danos/docs/os-development/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 architecture boundary in system/kernel/architecture/x86_64/. Only the 32 CPU-defined exception vectors were wired up at this stage; device interrupts (timer, keyboard, via the APIC) came later, on the same IDT — today it installs 48 gates (vectors 0-47) plus the ring-3 syscall gate at vector 128.

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 held three flat descriptors at this point — 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. (The table has since grown to seven entries: ring-3 user data and user code descriptors arrived with user mode, and the TSS descriptor — below — spans two slots.) 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 (since grown to gates 0-47, plus the ring-3 syscall gate at vector 128), 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.setTssFor), 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 (and later to seven, when user mode slotted the ring-3 user data/user code descriptors between the kernel data entry and the TSS pair).

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 interruptDispatch), 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 interruptDispatch, which forwards to a swappable on_fault hook. The generic kernel installs a reporter (onException in kernel.zig) that prints 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. What happens next depends on where the fault came from:

• User mode (CPL 3): kill the process, keep the machine. The kernel is intact (the CPU trapped onto the task's kernel stack), so the faulting process is killed — address space, IRQ bindings, and IPC handles reclaimed; a client it owed a reply to is failed with -EPEER — and the core reschedules. A crashing driver takes itself down, never the OS. This is fault recovery step 2 of resilience.md. NMI, double fault, and machine check are excluded: they report machine trouble regardless of what was running.
• Kernel mode: halt this core. The trusted base itself is broken, so there is nothing safe to kill; the fault is still contained to the core (an application-processor fault leaves the rest of the system running), and the report makes it 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 (since done)

Both items originally deferred here have landed:

• The IO-APIC: ioapic.zig routes external device lines onto vectors — discovered via ACPI's MADT, every input masked at init, lines unmasked one at a time as user-space drivers bind them (see device-interrupts.md). The keyboard followed exactly as predicted: the PS/2 bus driver (system/drivers/ps2-bus/) claims the 8042 controller and binds its IRQ 1 (and the aux mouse's IRQ 12) through this routing. USB HID keyboards arrive over xHCI instead, which interrupts via MSI, and the HPET's GSI routing exercises the same path.
• SSE state: isr_common (and the syscall entry) now fxsave/fxrstor the full SSE/x87 register file around dispatch. This stopped being optional the moment kernel code touched XMM — a 16-byte struct copy is a movdqu — and its absence was the root cause of a long-lived corruption Heisenbug; the comments in isr.s tell the story.

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