cleonos/docs/stage25.md

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.