danos/docs/interrupts.md

Interrupts and exceptions

When something goes wrong on the CPU — a bad pointer, a divide by zero, a malformed page table — the processor raises an exception. If nothing is set up to catch it, the fault escalates: the CPU tries to invoke a handler, finds none, faults again trying to handle that, and on the third strike triple-faults, which on real hardware and in QEMU means a silent reset. Debugging by spontaneous reboot is miserable.

This is the machinery that catches those faults and prints what happened instead. It's all x86_64-specific, so it lives behind the arch boundary in system/kernel/architecture/x86_64/. Only the 32 CPU-defined exception vectors are wired up so far; device interrupts (timer, keyboard, via the APIC) come later, on the same IDT.

First the GDT

In 64-bit long mode, segmentation is mostly switched off — but the CPU still requires valid segment descriptors for code and data, and, crucially, every IDT gate names a code-segment selector that must resolve in the current GDT. The firmware left a GDT in place, but we don't control it, so we install our own with known selectors: 0x08 kernel code, 0x10 kernel data.

system/kernel/architecture/x86_64/gdt.zig holds three flat descriptors — a required null entry, plus code and data — where the only bits that matter in long mode are the access byte and the code segment's long-mode (L) flag. Loading it (gdt_flush in isr.s) does two things: lgdt, then reload the segment registers. The data registers take a plain mov, but CS can't — so we reload it with a far return, pushing the new selector and a return address and letting lretq pop them into CS:RIP.

Then the IDT

The Interrupt Descriptor Table maps each of 256 vectors to a handler. Each entry is a 16-byte gate holding the handler's address (split across three fields, a quirk of the format), the code selector (0x08), and flags: 0x8E means present, ring 0, 64-bit interrupt gate. system/kernel/architecture/x86_64/idt.zig builds the table, points the first 32 vectors at their stubs, and loads it with lidt (idt_flush).

The TSS and the double-fault stack

There's one more table, the Task State Segment. In long mode its main remaining job is the Interrupt Stack Table (IST): an IDT gate can name an IST slot, and when that vector fires the CPU switches to the stack recorded there — regardless of what the interrupted stack looked like.

This matters most for the double fault (#DF, vector 8). A #DF means the CPU hit a fault while trying to deliver another fault — very often because the current stack pointer is bad, so pushing the exception frame itself faulted. If the #DF handler then tried to push onto that same bad stack, it would fault a third time and triple-fault — an instant reset. So the #DF gate is pointed at IST1, a small dedicated stack (system/kernel/architecture/x86_64/tss.zig) that's always valid.

Bringing it up: fill in the TSS's IST1 pointer, publish the TSS through a descriptor in the GDT (gdt.setTss), and load it into the task register with ltr. The TSS descriptor is a 16-byte system descriptor spanning two GDT slots, which is why the GDT grew from three entries to five.

The stubs and the trap frame

On an exception the CPU pushes a small frame (SS, RSP, RFLAGS, CS, RIP) and, for some vectors, an error code. That inconsistency is a nuisance, so each stub in system/kernel/architecture/x86_64/isr.s normalises it: vectors that don't get a hardware error code push a dummy 0, then every stub pushes its vector number and jumps to a shared tail, isr_common. The tail pushes all the general registers and calls the Zig handler with a pointer to the whole thing.

The result on the stack is a uniform CpuState — register block, then vector and error code, then the CPU's frame. Its field order in idt.zig is exactly the push order in isr.s; the two must stay in sync.

Why a separate .s file

The stubs and table-loads are real assembly rather than Zig inline asm because they need things inline asm on this toolchain can't express: cross-symbol jmp/call (a stub jumping to isr_common, which calls the exported exceptionHandler), and the lgdt/lidt memory operands (which LLVM rejects inline). build.zig adds isr.s to the arch module.

Reporting a fault

isr_common calls exceptionHandler, which forwards to a swappable on_fault hook. The generic kernel installs a reporter (onException in main.zig) that prints, in red, the exception name and vector, the error code, the faulting RIP and RSP, and — for a page fault (#PF, vector 14) — the faulting address from CR2. Then it halts. There's no fault recovery yet, so every exception is terminal; the point is that it's now visible instead of a silent reset.

The hook is set before arch.init() in kmain, so a fault during setup is still caught.

Verifying it

A temporary ud2 (unconditional invalid-opcode instruction) in kmain produced, in red:

CPU EXCEPTION: invalid opcode (vector 6)
  error code : 0x0
  RIP        : 0x000000000010dadd   <- the ud2, in the kernel image at 0x100000+
  RSP        : 0x0000000007e8aed0

Vector 6 with no error code, a RIP inside the loaded kernel, and a sane RSP together confirm the whole path: the GDT is active (we're still executing), the IDT vectored to the right stub, the stub built a correct CpuState, and the Zig handler read it and reported instead of triple-faulting.

Separately, pointing RSP at an unmapped address and faulting forced a double fault — reported cleanly (double fault (vector 8)) rather than triple-faulting into a reset, which only works because #DF ran on IST1. That's the proof the TSS/IST is wired up: the handler survived a completely broken stack.

What's next (not done here)

• The IO-APIC and the keyboard: the timer (a local-APIC device interrupt) is covered in device-interrupts.md; external devices like the keyboard also need the IO-APIC to route their lines onto vectors.
• SSE state: the stubs save general registers but not the vector registers, so a returning interrupt whose handler uses SSE will need that added. Fine for now, since our handlers don't.

With faults now debuggable, the paging work that follows — where a wrong page-table entry means an instant #PF — is far less painful.