cleonos/docs/stage14.md

CLeonOS Stage14

Stage Goal

• Pause risky ELF runtime expansion and prioritize non-ELF core capability.
• Expose virtual TTY manager controls through syscall ABI.
• Keep Stage13 boot flow stable while adding TTY observability and control hooks.

What Was Added

• New kernel syscalls:
  • CLKS_SYSCALL_TTY_COUNT (21)
  • CLKS_SYSCALL_TTY_ACTIVE (22)
  • CLKS_SYSCALL_TTY_SWITCH (23)
• New TTY kernel API exports:
  • clks_tty_count()
  • clks_tty_ready()
• New user C wrappers:
  • cleonos_sys_tty_count()
  • cleonos_sys_tty_active()
  • cleonos_sys_tty_switch(u64 tty_index)
• Boot probe now logs TTY syscall status (COUNT and ACTIVE).

Acceptance Criteria

• Kernel boots and prints CLEONOS STAGE14 START.
• Syscall framework remains online (INT80 FRAMEWORK ONLINE).
• Probe logs include:
  • [INFO][TTY] COUNT: 0X...
  • [INFO][TTY] ACTIVE: 0X...
• No regression in existing scheduler/service/FS/driver initialization sequence.

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

• TTY syscall value always -1:
  • Check kernel/user syscall ID tables are aligned.
• TTY_ACTIVE never changes after switch:
  • Validate clks_tty_switch() receives index < clks_tty_count().
• Missing TTY probe logs:
  • Ensure clks_stage14_syscall_probe() is still called after clks_syscall_init() and clks_interrupts_init().
• Build fails with undeclared syscall IDs:
  • Rebuild after syncing both headers:
    • clks/include/clks/syscall.h
    • cleonos/c/include/cleonos_syscall.h