# 2026-10-25 — kido-vec design: the ARM64 exception-vector module (builder crew)

**Piece:** the exception-vector module (`kido-vec-arm64.S` +
`kido-vec-arm64.h`). One solid piece: the table, the IRQ stub,
and the DAIF/VBAR controls only. It turns session 27's GIC
driver from "controller programmed" into "interrupts delivered"
as a committed module — the scratch vector stub from the GIC
QEMU proof is the starting sketch, not the module, and this
session promotes it properly instead of copying it blindly:
the scratch stub saved nothing (its handler ran once and the
proof only needed the marker); the committed stub saves the
full frame, because a real IRQ can land mid-task.

**Why this piece now:** session 27's remains named it first:
"exception-vector module (VBAR + DAIF + IRQ stub ->
kido_gic_dispatch — the named next piece, with this session's
scratch stub as its starting sketch)." The other remains are
all fenced: D1 KIDO_ERR_NO_TASKS (N8toriousAi's call — untouched),
MMU call-site wiring (future Gate item — untouched), HAL
wiring (Gate items — untouched), destroy bare-metal proof
(its own design, session 22 — not swallowed here), SPI
delivery proof (this module's proof, queued below, not
claimed today), real BUBO peer (Phase 4). The vector module
is the next unbuilt piece draftable without hardware: every
rule comes from the ARM exception model, and the .S is
auditable instruction-for-instruction like the entry .S.

**Sources verified this session (not from memory alone):**
- ARM AArch64 exception model (ARM doc 102412): VBAR_ELx
  holds the table base and is UNDEFINED after reset — it
  must be configured before interrupts are enabled; each
  exception type has a defined offset from the base.
- The vector-table layout, confirmed by three independent
  writeups this session: table aligned to a 2 KiB boundary
  (`.align 11`); 16 entries of 128 bytes (`.align 7` each),
  in four groups of four — EL1t (SP_EL0), EL1h (SP_EL1),
  EL0 AArch64, EL0 AArch32 — each group ordered
  Sync / IRQ / FIQ / SError. Kido runs EL1h (the entry .S
  drops to EL1h, SPSR 0x3c5), so the live IRQ entry is
  entry 5 (EL1h group, second slot).
- The rpi4-osdev interrupt writeup's handler shape, adopted
  with attribution, not copied: a 256-byte frame saving
  x0-x30, dispatch to the C handler, restore, `eret`.
  (The scratch stub from session 27 saved nothing; this
  module does not inherit that shortcut.)
- Session 27's GIC proof log: exactly one IRQ taken, one
  clean exception return, through the scratch stub — the
  Group0 rung (distributor CTLR = 1) delivers on QEMU virt.

## Positions

- **P1 Table in .S, branches only:** the table is 16 `b`
  instructions, each padded to 128 bytes with `.balign 128`
  after a `.align 11` base. No handler code lives in the
  table (the 128-byte slot fits a branch, not a frame save),
  so the table is audit-clean: no literals, no absolute
  addresses, nothing for the phase-3 relocator to patch
  and nothing for the completeness audit to classify.
- **P2 Only EL1h IRQ is live:** entry 5 branches to the
  full stub. Every other entry branches to a tiny handler
  that records its vector index and ESR_EL1 into BSS slots
  and spins. Kido has no EL0, no EL1t stack, and no FIQ
  source (the GIC is configured Group0 -> IRQ only), so
  any other entry firing is a fault in the system's own
  assumptions — spinning with the evidence stashed is the
  loud response, not a silent return to a corrupted state.
- **P3 The IRQ stub saves everything, restores everything:**
  256-byte frame, x0-x30, on the interrupted stack (EL1h,
  so SP_EL1 — the interrupted task's stack or the boot
  stack, both real). `kido_gic_dispatch()` is a normal C
  call: it may clobber caller-saved registers, so the stub
  saves them all rather than trusting the ABI split. SPSR /
  ELR are banked by the hardware and untouched by the C
  call; `eret` restores PC and PSTATE from them. No
  register the interrupted code owned is spent.
- **P4 No nesting, by hardware default:** exception entry
  masks IRQ (PSTATE.I set on entry). The stub never
  unmasks, so a second IRQ cannot land inside the first
  handler's frame. Nested delivery is a named future for
  a module with a real IRQ stack, not a flag on this one.
  A handler that runs long therefore delays the next IRQ
  — stated, not hidden; GIC handlers are short by contract.
- **P5 Install is `adr`, not `ldr =`:** `kido_vec_install`
  loads the table address with `adr` (PC-relative, true
  wherever the image runs — including after the phase-3
  relocator, which runs before any C exists) and writes
  VBAR_EL1, then `isb`. No literal pool, no GOT, no
  relocation entry: the install cannot be the thing the
  audit has to excuse.
- **P6 DAIF controls are three small functions, no status
  codes:** `install`, `irq_enable` (`daifclr #2`),
  `irq_disable` (`daifset #2`), plus a `irq_masked` query
  (DAIF.I bit read back, 1 = masked). At EL1 these cannot
  fail — there is no failure mode to map to a header code,
  and inventing one would repeat the sched-D1 pattern for
  no reason. Calling them below EL1 faults by architecture;
  the caller contract is EL1, stated in the header.
- **P7 Wiring is a Gate item, not this session's:** the
  module ships uncalled, like the MMU module (session 22)
  and the mbox/pl011 drivers (sessions 25/26). Zero
  Gate-approved files touched: no entry .S change, no
  kido_main change, no boot.c change. The install order
  law is declared (C5) for the Gate session that wires it.

## Challenges

- **C1 — Which entries are real?** Answered by P2 + the
  entry .S's own SPSR: the kernel runs EL1h, tasks run
  EL1h, there is no EL0. EL1t entries would mean the core
  somehow selected SP_EL0, which no Kido code does; EL0
  entries would mean a lower EL exists, which it does not.
  Both go to the stash-and-spin handler, so if the
  assumption is ever wrong, the evidence (index + ESR)
  survives in BSS for a debugger instead of vanishing.
- **C2 — Why stash ESR instead of printing it?** There is
  no console contract at this layer: the HAL owns the
  UART, and the unhandled handler cannot assume a UART
  exists (it may fire before HAL init, or on a board
  whose UART is unwired). Printing would couple the
  vector module to the HAL. Stashing follows the reloc
  module's precedent (BSS report slots read by a later,
  console-owning layer) and costs two stores.
- **C3 — Does the IRQ stub need to save SP?** No: the
  stub allocates its frame with `sub sp, sp, #256` and
  frees it with the matching `add` before `eret`; the
  interrupted SP is never written, only moved and moved
  back. Saving SP into the frame would save a value the
  stub itself is about to change — the sched .S saves SP
  because a context switch CHANGES stacks; an IRQ return
  does not.
- **C4 — What if dispatch itself faults?** Then the fault
  lands on the sync-EL1h entry (entry 4) while already
  inside the IRQ frame: the sync handler stashes index 4
  + ESR and spins, on the same stack, below the IRQ frame.
  The stack has room (the boot stack is 16 KiB, a task
  stack is 16 KiB, the frame is 256 bytes) — but a fault
  inside dispatch with a nearly-full stack is a real
  overflow risk, stated here: handlers must stay short,
  and a future IRQ-stack module (separate SP for IRQ
  entry) is the named fix, not a claim made today.
- **C5 — Install order:** VBAR is undefined at reset, so
  the order is install FIRST, GIC init second, IRQ enable
  LAST. Enabling IRQ before install would vector an
  interrupt to address 0 (or stale VBAR) — a fault with
  no handler. The header states the order as law, and the
  QEMU proof (queued) asserts it: the harness reads VBAR
  back after install and checks it equals the table
  address before it ever unmasks.
- **C6 — Relocation interaction:** the table holds only
  branches (relative, relocation-free) and `install` uses
  `adr` (PC-relative). The unhandled handler's BSS stores
  use `adrp` (PC-relative, the reloc module's own idiom).
  Consequence: the vector module adds ZERO entries to
  .rela.dyn and needs ZERO carve-outs from the phase-3
  walk. This is a design property to be confirmed by
  disassembly when the toolchain returns (proof gate
  below), not a claim made today — the .S is unassembled
  this session (see Proof posture).
- **C7 — FIQ goes to spin, not to dispatch:** the GIC
  driver routes Group0 to IRQ and never enables FIQ
  routing; a FIQ firing means the controller was
  misconfigured or the core took a spurious FIQ. Routing
  it to dispatch would let a misconfiguration masquerade
  as a handled interrupt. Spinning with the evidence
  stashed is the honest response (P2).

## Preserved dissent

- **D1 — Route FIQ to dispatch too:** overruled (C7).
  Preserved for a future secure-world caller that actually
  configures FIQ routing; until then FIQ has no producer.
- **D2 — Save only caller-saved registers in the IRQ
  stub:** overruled (P3). The saving is 31 registers either
  way in practice (the callee-saved set is saved by the C
  call's own prologue if it uses them — but the stub
  cannot see that), and a full frame is auditable at a
  glance. Preserved if frame size ever matters (it does
  not: 256 bytes against a 16 KiB stack).
- **D3 — A C-level `kido_vec_handle_sync` dispatcher:**
  overruled (P2). Sync exceptions in Kido today are faults,
  not syscalls — there is no EL0 to serve and no syscall
  table to dispatch to. A dispatcher would be scaffolding
  for a userspace that does not exist. Preserved for the
  EL0 module, if one is ever named.
- **D4 — Wire install into the entry .S now:** overruled
  (P7). The entry .S is a proven path (phase-3 QEMU proofs);
  touching it for a module whose own QEMU proof cannot run
  this session (no toolchain) would couple an unproven
  module to a proven path. The Gate session wires it with
  the proof in hand.

## Proof posture (honest, stated first)

- **Toolchain absent, 11th data point:** `which` finds no
  `aarch64-linux-gnu-gcc` and no `qemu-system-aarch64`
  this session (sessions 13/17/20/21/23/24/25/26 pattern;
  session 27's "present" did not survive the VM cycle).
  So this module is WRITTEN, NOT ASSEMBLED, and its QEMU
  proof is QUEUED — exactly the session-13/17 posture, not
  hand-waved.
- **What was checked for real this session:** a source-
  text check on the .S (not an assembly): 16 vector
  entries counted, each entry's branch target named; the
  IRQ frame's store list and load list compared pair by
  pair (16 pairs + x30, identical offsets both ways);
  the frame size (256) is a multiple of 16 (SP alignment
  law); no `kido_vec` symbol collides with an existing
  module (grep, zero hits before writing); the header's
  vector-index constants match the table order (0-15).
  These check the text, not the machine code — stated.
- **Queued proof gate (toolchain return):** assemble both
  .S files in the tree + this one, zero warnings;
  disassembly check — table base 2048-aligned, each entry
  exactly 128 bytes apart, IRQ stub save/restore lists
  match, `install` is `adr`+`msr vbar_el1`+`isb`, no
  absolute literal in the file (C6 confirmation, audit
  counts unchanged); QEMU virt / cortex-a57 / gic-version
  = 2, committed module only (no scratch stub): install
  -> VBAR readback equals the table address -> GIC init
  -> SGI 0 handler registered + enabled -> IRQ unmask ->
  SGI to CPU0 -> handler marker -> control flow resumes
  past the send (the `eret` proof) -> one IRQ taken, one
  clean return, zero fault entries in `-d int`. SPI
  delivery (UART RX IRQ 33) stays the proof after that,
  not this gate.

## Named next

- QEMU proof of this module (gate above) + SPI delivery
  proof (UART RX IRQ 33 with serial input): the vector
  module's natural proofs, queued on the toolchain.
- Gate item: wire `kido_vec_install` into the boot path
  (after `kido_reloc_verify` OK, before GIC enable) and
  retire the session-27 scratch stub from all records.
- Destroy bare-metal proof (design ready, session 22);
  kido-mmu call-site wiring (future Gate item); HAL
  wiring (Gate items); real BUBO peer + bare-metal
  transport (Phase 4); D1 KIDO_ERR_NO_TASKS (N8toriousAi's
  call); PENDING #1 cross-compile (11th data point:
  toolchain absent again).
- First boot is N8toriousAi's to witness.
