Stage 25

docs/stage25.md

@@ -0,0 +1,64 @@
+# CLeonOS Stage25
+
+## Stage Goal
+- Make `tty2` (Alt+F2) enter a basic desktop environment.
+- Add first-step mouse support (PS/2 mouse IRQ and on-screen pointer).
+- Keep kernel shell on `tty1` (Alt+F1) unchanged.
+
+## What Was Implemented
+- New kernel modules:
+  - `clks/kernel/mouse.c`
+  - `clks/kernel/desktop.c`
+- New public headers:
+  - `clks/include/clks/mouse.h`
+  - `clks/include/clks/desktop.h`
+- Interrupt and PIC updates:
+  - Enable PIC cascade + mouse IRQ line.
+  - Route IRQ12 (`vector 44`) to mouse byte handler.
+- PS/2 mouse bring-up:
+  - Enable aux device.
+  - Set controller config for mouse IRQ.
+  - Send mouse commands (`F6`, `F4`) and verify ACK.
+  - Decode 3-byte PS/2 packets into X/Y/buttons.
+- Desktop on tty2:
+  - `clks_desktop_tick()` renders a simple graphical desktop scene.
+  - Draw software mouse cursor and button state indicator.
+  - Refresh when pointer changes and periodically to keep desktop clean.
+- TTY adjustments:
+  - Disable text cursor blinking on `tty2` to avoid desktop overlay artifacts.
+- Keyboard routing adjustment:
+  - Shell input queue only accepts character input while active TTY is `tty1` (index 0).
+  - Alt+F1..F4 switching remains available globally.
+- Framebuffer primitives:
+  - Added `clks_fb_draw_pixel()` and `clks_fb_fill_rect()` for desktop rendering.
+- Kernel flow integration:
+  - Stage banner -> `CLEONOS Stage25 START`.
+  - Initialize mouse + desktop during boot.
+  - Call desktop tick in `usrd` task.
+
+## Acceptance Criteria
+- Boot log shows `CLEONOS Stage25 START`.
+- Alt+F1 enters shell TTY; shell input works as before.
+- Alt+F2 switches to desktop view (non-text UI).
+- Mouse movement updates on-screen pointer in tty2.
+- Left mouse button changes pointer/indicator state.
+
+## Build Targets
+- `make setup`
+- `make userapps`
+- `make iso`
+- `make run`
+- `make debug`
+
+## QEMU Command
+- `qemu-system-x86_64 -M q35 -m 1024M -cdrom build/CLeonOS-x86_64.iso -serial stdio`
+
+## Common Bugs and Debugging
+- Desktop not visible after Alt+F2:
+  - Check `clks_desktop_init()` log lines and confirm framebuffer is ready.
+- Mouse pointer does not move:
+  - Check mouse init logs (`PS2 POINTER ONLINE`) and IRQ12 routing in `interrupts.c`.
+- Frequent text artifacts on desktop:
+  - Ensure desktop periodic redraw is active in `clks_desktop_tick()`.
+- Shell unexpectedly receives input while on desktop:
+  - Verify keyboard routing guard uses `clks_tty_active() == 0`.