cleonos/docs/stage3.md

CLeonOS Stage3

Stage Goal

• Add interrupt and exception foundation for x86_64 CLKS.
• Build and load IDT with exception vectors (0-31) and PIC IRQ vectors (32-47).
• Remap PIC and enable timer IRQ.
• Provide unified ISR stub + C dispatcher.

Acceptance Criteria

• Kernel boots and prints INT IDT + PIC INITIALIZED.
• CPU exceptions are captured and logged with vector/error/RIP.
• Timer IRQ increments internal tick counter without panic.
• Kernel reaches idle loop with interrupts enabled.

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

• Triple fault right after enabling interrupts:
  • Check IDT entry selector/type and verify lidt loaded valid base/limit.
• Exception panic with wrong vector/error layout:
  • Verify assembly stub push order matches struct clks_interrupt_frame.
• IRQ storm or hang:
  • Ensure PIC EOI is sent for IRQ vectors and IRQ masks are correct.
• Link failure for ISR symbols:
  • Confirm interrupt_stubs.S is included in Makefile and assembled to object file.
• Limine ELF panic on segment permissions:
  • Keep linker sections page-aligned to avoid mixed permission pages.