cleonos/docs/stage4.md

CLeonOS Stage4

Stage Goal

• Add process/task scheduling foundation in CLKS.
• Introduce task control blocks and kernel task registry.
• Implement timer-driven round-robin time-slice scheduling logic.
• Connect scheduler tick updates to IRQ0 interrupt path.

Acceptance Criteria

• Kernel boots and prints CLEONOS STAGE4 START.
• Scheduler initializes and logs task count.
• At least 3 kernel tasks exist (idle, klogd, kworker).
• Timer IRQ invokes scheduler tick handler without panic/reboot.
• System stays in idle loop with interrupts and scheduler active.

Build Targets

• make setup
• 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

• Immediate reboot after enabling interrupts:
  • Verify IDT selector uses runtime CS and ISR stubs are linked.
• Scheduler task count is 0:
  • Confirm clks_scheduler_init() is called before idle loop.
• Build failure on ISR symbols:
  • Ensure interrupt_stubs.S is included and .S build rule exists.
• Build failure on scheduler symbols:
  • Ensure scheduler.c is in C_SOURCES and scheduler.h is included where needed.
• No periodic scheduling activity:
  • Verify IRQ0 is unmasked and timer vector 32 path calls scheduler tick handler.