cleonos/docs/stage15.md

# CLeonOS Stage15

## Stage Goal
- Keep ELF path unchanged and continue non-ELF stability work.
- Add PS/2 keyboard IRQ handling in kernel interrupt path.
- Support virtual terminal hotkey switching with `Alt+F1`~`Alt+F4`.
- Keep scheduler, syscall, and existing Stage14 behavior stable.

## What Was Implemented
- New keyboard module:
  - `clks/include/clks/keyboard.h`
  - `clks/kernel/keyboard.c`
- Interrupt integration:
  - Enable IRQ1 (keyboard) alongside IRQ0 in PIC mask.
  - Read scancode from PS/2 data port `0x60`.
  - Dispatch scancode to keyboard hotkey handler.
- Hotkey behavior:
  - Hold `Alt` + press `F1/F2/F3/F4` to switch TTY 0/1/2/3.
  - On successful switch, kernel logs active TTY and switch counter.
- Boot stage update:
  - `CLEONOS STAGE15 START`.

## Acceptance Criteria
- Kernel boots and prints `CLEONOS STAGE15 START`.
- Boot logs include keyboard module online message:
  - `[INFO][KBD] ALT+F1..F4 TTY HOTKEY ONLINE`
- In QEMU runtime:
  - Press `Alt+F2` / `Alt+F3` / `Alt+F4` / `Alt+F1`.
  - Logs show:
    - `[INFO][TTY] HOTKEY SWITCH`
    - `[INFO][TTY] ACTIVE: 0X...`
    - `[INFO][TTY] HOTKEY_SWITCHES: 0X...`

## 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
- Hotkey has no effect:
  - Verify QEMU window is focused and keyboard input is captured.
  - Confirm logs show Stage15 keyboard online message.
- IRQ timer works but keyboard does not:
  - Re-check PIC mask includes IRQ1 (master mask should allow IRQ0 and IRQ1).
- Wrong function key mapping:
  - Current mapping is Set1 scancode: F1=0x3B, F2=0x3C, F3=0x3D, F4=0x3E.
- Excessive hotkey logs:
  - Holding key may repeat make scancode by keyboard auto-repeat; this is expected in current stage.