# 2026-10-25 — kido-gic design: the GICv2 interrupt controller driver (builder crew)

**Piece:** a full GICv2 distributor + CPU-interface driver
(`kido-gic.h/.c`). One solid piece: the controller only. The
exception-vector module that could call it (VBAR table, DAIF
unmask, IRQ stub calling `kido_gic_dispatch()`) is a future
module, not this session's — the session-24/25/26 fence pattern
(new files only, zero Gate-approved files touched) holds.

**Why this piece now:** the named remains after session 26 were
"D1 KIDO_ERR_NO_TASKS (N8toriousAi's call — untouched), MMU call-site
wiring (future Gate item — untouched), HAL wiring (Gate items —
untouched), GIC module (unlocks interrupt-driven RX, PL011 D2),
RPi4 execution proof (N8toriousAi's Pi4, his witness), destroy
bare-metal proof (queued on the toolchain), real BUBO peer
(Phase 4), PENDING #1 cross-compile (9th data point: toolchain
absent)." The GIC is the next unbuilt module draftable without
hardware: every register comes from the ARM GIC architecture
specification, and the exchange is host-testable through a
scripted distributor/CPU-interface double (the session-22 MMU /
session-24 HAL / session-25 mbox / session-26 PL011 precedent).
It also changes the toolchain story: this session the cross
toolchain is PRESENT (aarch64-linux-gnu-gcc 13.3.0, qemu-system-
aarch64 8.2.2 — see the post-test note), so the GIC draft gets
a cross-compile check AND a QEMU SGI-delivery proof, not just a
hosted double. PENDING #1's 10th data point is "present," and
the destroy bare-metal proof design (session 22) stays queued
behind its own session — this session does not swallow it.

**Sources verified this session (not from memory alone):**
- ARM GIC Architecture Specification, IHI 0048B (GICv2),
  Table 4-1 distributor register map: GICD_CTLR 0x000,
  GICD_TYPER 0x004, GICD_IIDR 0x008, GICD_IGROUPR 0x080,
  GICD_ISENABLER 0x100, GICD_ICENABLER 0x180, GICD_ISPENDR
  0x200, GICD_ICPENDR 0x280, GICD_ISACTIVER 0x300,
  GICD_ICACTIVER 0x380, GICD_IPRIORITYR 0x400,
  GICD_ITARGETSR 0x800 (0x800-0x81C RO: SGI/PPI targets are
  fixed, only 0x820+ RW), GICD_ICFGR 0xC00, GICD_SGIR 0xF00.
- CPU interface register summary (IHI 0048B / Cortex-A32 TRM):
  GICC_CTLR 0x000, GICC_PMR 0x004, GICC_BPR 0x008,
  GICC_IAR 0x00C, GICC_EOIR 0x010, GICC_RPR 0x014,
  GICC_HPPIR 0x018, GICC_ABPR 0x01C, GICC_AIAR 0x020,
  GICC_AEOIR 0x024, GICC_AHPPIR 0x028, GICC_IIDR 0x0FC,
  GICC_DIR 0x1000.
- QEMU virt GICv2 bases (Arm Community DTB dump + axplat
  writeup): distributor 0x08000000, CPU interface 0x08010000,
  virtual interfaces 0x08030000/0x08040000 (not used here).
  QEMU virt PL011 UART is SPI 33 (same writeup).
- Interrupt ID classes (IHI 0048B): SGI 0-15, PPI 16-31,
  SPI 32+. Spurious ID 1023. ICFGR encoding: field 0b00 =
  level-sensitive, 0b10 = edge-triggered. SGIR: filter bits
  25:24, CPU target list bits 23:16, NSATT bit 15, SGIINTID
  bits 3:0. IAR bits 12:10 carry the SGI source CPUID; EOIR
  must echo the full IAR value, not just the ID.

## Positions

- **P1 GICv2 only, MMIO only:** QEMU virt with
  `gic-version=2` is the proven target, and its CPU interface
  is MMIO. GICv3 (system-register CPU interface, redistributors)
  is a different module, not a flag on this one.
- **P2 UP only:** one CPU interface, all SPI targets CPU0.
  No secondary-CPU bring-up, no per-CPU target tables. The
  single-CPU hosted double models exactly this.
- **P3 Group0-only routing as primary:** distributor CTLR = 1
  and CPU-interface CTLR = 1, FIQEn = 0, so Group0 signals
  IRQ. This is the classic QEMU-virt recipe, and the QEMU
  SGI proof in this session adjudicates it (C1). Group1
  classification is deferred, not denied (D2).
- **P4 dispatch owns EOIR, always:** `kido_gic_dispatch()`
  reads IAR, calls the registered handler if any, then writes
  EOIR with the full IAR value. A handlerless interrupt is
  still completed — otherwise it stays active forever and the
  CPU interface never signals again. The one exception is
  the spurious ID (C5): nothing to complete, no EOIR write.
- **P5 init guarantees routability only:** distributor off,
  all SPI targets set to CPU0, all enables cleared, all
  pending cleared, CPU interface PMR = 0xFF (accept all) and
  BPR = 0 (any higher priority preempts), distributor on.
  Priorities stay at reset (0) and trigger config stays at
  reset (level) — assigning them is the caller's job through
  `set_priority` / `set_config`, not init's silent policy.
- **P6 static handler table, sized by the architecture:**
  1020 slots (the GICv2 source maximum), fn + arg per slot.
  No allocator dependency: the GIC must be usable before
  any init order is assumed, and a table that cannot grow
  cannot surprise. The BSS cost (~16 KiB on AArch64) is
  stated in the header.
- **P7 the core is not this module's job:** programming the
  GIC does NOT deliver interrupts to a CPU whose PSTATE I bit
  is masked and whose VBAR points nowhere. DAIF unmask +
  vector table + the IRQ stub that calls `dispatch()` belong
  to the future exception-vector module. This driver programs
  the controller; claiming "interrupts work" from it alone
  would be the exact lie the scaffold's honesty law forbids.
  The QEMU proof in this session uses a SCRATCH vector stub
  in /tmp, never committed, to adjudicate delivery — the
  committed module stays honest about its boundary.

## Challenges

- **C1 — Group0 vs Group1 routing:** on a GIC with security
  extensions, Non-secure writes to the Group0 enable bit are
  restricted, and Group1 interrupts signal FIQ unless
  configured otherwise. Answered by P3 + empirical ladder:
  the QEMU proof tries Group0-only first; if SGI delivery
  fails, the scratch harness tries CTLR = 3 (both groups)
  and then Group1-only with IGROUPR classification, and the
  session records which rung worked. The committed init
  ships the rung the proof validated — no rung is claimed
  without the run.
- **C2 — ITARGETSR read-only for SGI/PPI:** the spec table
  shows 0x800-0x81C RO. Answered: `set_target` accepts SPI
  (>= 32) only; SGI/PPI targets return EARLY_ENV loud. A
  caller routing a PPI to another CPU is asking for
  something the hardware does not offer.
- **C3 — ICFGR for SGI/PPI:** SGI trigger is fixed edge;
  PPI trigger is IMPLEMENTATION DEFINED. Answered the same
  way: `set_config` accepts SPI only, loud otherwise.
  The PL011 UART (SPI 33, level-triggered) is the honest
  first consumer: reset config (level) already suits it.
- **C4 — IAR CPUID bits for SGI:** EOIR must carry the
  source CPUID (bits 12:10) for SGIs, or the deactivate
  targets the wrong source. Answered: dispatch writes the
  full IAR value to EOIR. The hosted double returns a
  CPUID-bearing IAR for SGIs and the test pins the EOIR
  capture byte-for-byte.
- **C5 — spurious 1023:** not an error, not a handler call,
  and no EOIR write (there is no active interrupt to
  complete). Answered: dispatch returns OK, handler counts
  unchanged, EOIR capture unchanged — all three pinned.
- **C6 — TYPER-derived bound, never hardcoded:** the maximum
  IRQ comes from GICD_TYPER ITLinesNumber: (lines + 1) * 32,
  capped at the architectural 1020 sources. The hosted
  double scripts TYPER with lines = 4 (160 IRQs); the
  driver refuses IRQ 160 and IRQ 1020 alike on that double.
  No QEMU TYPER value is named — the driver reads the
  hardware it is given.
- **C7 — byte/field RMW preserves neighbors:** priority is
  one byte per IRQ, target one byte per IRQ, config two
  bits per IRQ, all inside 32-bit registers. Answered: the
  driver reads the word, replaces only its field, writes
  it back. Tests pin the neighbor byte/field unchanged
  after every write (priority neighbor still 0x00, target
  neighbor still the init 0x01, config neighbor still 0).
- **C8 — SGI filter scope:** only filter = 0 (explicit CPU
  target list) this version. Broadcast filters (1 = all but
  self, 2 = self) are a named future, not a silent
  default — a broadcast SGI from a UP kernel would be
  theater with one CPU anyway.
- **C9 — init order:** distributor CTLR = 0 first, then
  targets/enables/pending, then CPU interface, then
  distributor CTLR = 1 last. Configuring a live distributor
  risks delivering a half-configured interrupt; the order
  is the guard.

## Preserved dissent

- **D1 — GICv3 now:** overruled (P1). The virt target runs
  gic-version=2; a v3 driver shares almost no register
  interface (redistributors, ICC system registers). Preserved
  as its own module when a v3 target is named.
- **D2 — Group1 + IGROUPR classification now:** overruled
  (P3/C1). The Group0 recipe is what the proof validates
  first; classifying SPIs into Group1 before any secure-
  world need exists would add a second routing story with
  no consumer. Preserved if a secure-world caller appears.
- **D3 — allocator-backed handler table:** overruled (P6).
  The static table costs BSS but no init order. Preserved
  if 1020 slots ever prove too small — the architecture
  caps sources at 1020, so it cannot.
- **D4 — dispatch inside the vector stub (.S):** overruled
  (P7). Dispatch is plain C so the future vector module
  can call it from its stub; putting C logic in the stub
  would duplicate the trampoline lesson the scheduler
  already learned (context switch lives in .S because the
  compiler cannot see the caller's registers — dispatch
  needs no such privilege).
- **D5 — broadcast SGI filters now:** overruled (C8).
  Preserved for the SMP module, where a target list with
  more than CPU0 exists.

## Named next

- Exception-vector module (VBAR table, DAIF unmask, IRQ
  stub -> `kido_gic_dispatch()`): turns this driver from
  "controller programmed" into "interrupts delivered" as a
  committed module. The scratch stub from this session's
  proof is the starting sketch, not the module.
- SPI delivery proof on QEMU (UART RX IRQ 33 with serial
  input): the SGI proof covers distributor + CPU interface
  + dispatch; SPI delivery through a real device is still
  unproven and is the vector module's natural proof.
- Destroy bare-metal proof (design ready, session 22) +
  PENDING #1 re-check on the next tooled VM (this session
  flips the data point to "present" — see post-test note).
- kido-mmu call-site wiring (future Gate item, unchanged).
- HAL wiring (Gate items, unchanged — HAL putc ->
  kido_pl011_putc, HAL init -> kido_pl011_init, HAL mailbox
  adoption after the Pi4 VPU-rate read).
- Real BUBO peer + bare-metal transport (Phase 4);
  D1 KIDO_ERR_NO_TASKS header code (N8toriousAi's call).

## Post-test note (found during this session's verification)

- **Toolchain present, 10th data point:** `which` finds
  `aarch64-linux-gnu-gcc` 13.3.0 AND `qemu-system-aarch64`
  8.2.2 this session. PENDING #1 (cross-compile) is no
  longer blocked on this VM — the GIC cross-compile check
  below ran for real. The destroy bare-metal proof was NOT
  swallowed into this session: it has its own design and
  its own proof bar, and it stays queued.
- **QEMU SGI proof — what it proves and what it does not:**
  the scratch harness (see the ledger entry) proves SGI
  delivery through the committed `kido_gic_*` functions on
  QEMU virt: init -> enable SGI 0 -> unmask IRQ -> SGI to
  CPU0 -> handler runs -> EOIR -> exactly one marker, zero
  exceptions. It proves the Group0 rung (CTLR = 1) on this
  QEMU build. It does NOT prove SPI delivery (no device
  asserted IRQ 33), does NOT prove the Pi4 GIC (different
  GIC, different bases), and does NOT bless the scratch
  vector stub as a module — that stub lives in /tmp and
  dies with this session.
- **Plain-compile guard, same lesson as PL011:** the
  test-only helpers are guarded behind KIDO_GIC_SELFTEST
  so a plain hosted `-c` build stays clean under -Werror.
