# 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](arch.md) boundary in
`src/arch/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.

`src/arch/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. `src/arch/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 (`src/arch/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 `src/arch/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](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.