# Deliberation: kido-serial-irq — interrupt-driven PL011 RX (session 30)

Builder crew micro-agent circle. One solid piece: the RX side of the
interrupt chain becomes real. Sessions 26/27/28 built the three
links (PL011 polled driver, GICv2, exception vectors); this module
is the first consumer that ties them together — a GIC handler that
drains the UART RX FIFO into a ring the kernel can read without
polling. TX stays polled (kido_pl011_putc); the vec install + DAIF
unmask that would fire this handler for real remain Gate items, as
does every HAL wiring. Zero existing files touched (fence pattern).

## Positions

- P1 (integration realist): the handler must be registered BEFORE
  the IRQ is enabled, and the UART unmask must come LAST. Any other
  order lets an interrupt arrive with no handler or no drain path.
  Init order: register handler -> GIC config (level) -> GIC enable
  -> UART IMSC unmask + IFLS trigger + ICR clear. Stop reverses
  it: mask UART -> disable GIC -> unregister.
- P2 (ring keeper): the ring is static, 256 bytes, never allocates,
  never blocks. IRQ context cannot wait: the handler drains what is
  there (bounded by the 16-deep hardware FIFO) and counts what it
  cannot keep. A full ring drops bytes LOUDLY (dropped counter),
  never overwrites unread bytes — overwriting would corrupt the
  consumer's stream silently.
- P3 (PL011-boundary keeper): this module owns a narrow IRQ WINDOW
  into the UART (DR / FR / IMSC / IFLS / ICR / RSR), not the driver.
  kido-pl011 keeps init, baud, TX, and polled RX. The window's
  offsets come from the same source (DDI 0183) and are pinned by
  this module's own test; if the TRM reading ever changes, both
  files change together. See C1 for why the window is not a call
  into kido_pl011_poll/getc.
- P4 (honesty auditor): the hosted proof is the dispatch chain
  (GIC trigger -> dispatch -> handler -> ring), which is exactly
  what the vec stub will call on hardware. It is NOT a proof of
  SPI delivery through a real UART — that proof still needs the
  toolchain + QEMU (queued, unchanged). The module's PROOF STATUS
  says so.
- P5 (test keeper): the test drives the chain through PUBLIC GIC
  API only (init / trigger / dispatch / enable / disable). No
  GIC double internals are touched. The UART side uses this
  module's own hosted double (the per-module double pattern),
  because the pl011 double's feed function is static inside
  pl011.c's self-test TU and unreachable from another TU (see C1).
- P6 (fence keeper): new files only. No Gate-approved file moves.
  The HAL's static kido_pl011_putc helper, the vec install seam,
  and the MMU call-site seam are all untouched.

## Challenges, answered

- C1 (why not call kido_pl011_poll/getc in the handler?): two
  reasons, the second decisive. First, getc's bounded wait (1<<20
  spins) is the wrong shape for IRQ context — a handler must
  poll-then-read, never wait. Second and decisive: testability.
  The pl011 double's feed setter is static inside pl011.c and only
  exists under KIDO_PL011_SELFTEST, which also defines pl011.c's
  main() — a second TU's test cannot link it (main collision) or
  reach the setter (static). Breaking either the fence or the
  pl011 self-test to export a feed would cost more than the
  window: five registers, one TRM source, pinned by test. The
  window is declared as a window, not hidden as a fork.
- C2 (level vs edge trigger?): LEVEL. The PL011 asserts its RX
  interrupt while the RX FIFO sits at or above the trigger level
  (plus the RX-timeout case); an edge config would lose every
  byte that arrives while the handler is already running or
  while the line is already asserted. Level + drain-to-empty is
  the pair: the handler drains until RXFE, so the line drops
  before EOIR-equivalent return. kido_gic_set_config accepts
  SPI only, and 33 is an SPI — the config call is legal.
- C3 (IFLS trigger level?): RXIFLSEL = 001, i.e. interrupt at
  1/4 full (4 bytes of the 16-deep FIFO). 1/8 (1 byte) would
  interrupt per byte — the polling it replaces, with worse
  latency guarantees; 1/2+ risks the 16-deep FIFO overrunning
  on a burst before the handler runs. 1/4 is the middle that
  keeps both bounds comfortable. It is a constant with a reason,
  not a tuned value — a Pi4 run may revisit it.
- C4 (one port or many?): ONE port, module-global state. Kido
  has one console UART and the HAL has one putc path; a
  multi-port table would be generality with no caller. The
  handler's arg is ignored (NULL at registration) and the
  stored IRQ is checked on entry, so a mis-registration is
  counted spurious, not silently served. Multi-port is a named
  future, not a flag.
- C5 (error bytes in IRQ context?): rejected exactly as the
  polled law requires — DR error bits OE/BE/PE/FE mean the byte
  is discarded, ECR cleared, and the error counter incremented.
  Nothing corrupt is ever delivered to the ring. The handler
  continues draining after an error byte; one bad byte does
  not stall the FIFO.
- C6 (stop() keeps the ring?): YES. Bytes already received are
  facts; stop() stops NEW delivery (mask + disable +
  unregister), it does not erase history. The consumer may
  still drain after stop. Destroying the ring would need a
  separate, named API — and a reason.
- C7 (priority?): UNTOUCHED. GIC init leaves priorities at
  reset (0); assigning this IRQ a priority is caller policy
  (kido_gic_set_priority exists for it), not something this
  module smuggles in. Stated, not defaulted.
- C8 (what about TX IRQ?): NOT this module. TX stays polled
  through kido_pl011_putc. A TX-empty interrupt would need a
  second ring (TX queue) and a second handler policy; that is
  a named future, and folding it in would double this piece.

## Convergence

Init order (P1) + static ring with counted drops (P2) + the
declared 5-register IRQ window (P3/C1) + dispatch-chain proof
only (P4) + public-GIC test driving (P5) + zero existing files
(P6). Consumer API mirrors the pl011 split in non-blocking form:
available() is the flag, getc() is the drain — but unlike the
polled getc, an empty ring is EARLY_ENV immediately, never a
wait. The caller checks available() first; that contract is in
the header, not implied.

## Preserved dissent

- D1 (single-owner purist, overruled): the IRQ window should live
  inside kido-pl011.c, not a second module — one UART, one file.
  Overruled on testability (C1) and on the fence: moving the
  window into pl011.c this session would touch a Gate-adjacent
  file for a module whose hardware proof cannot run anyway. The
  sync rule is stated in both headers: the window's offsets
  track DDI 0183, and any TRM re-reading changes both files.
- D2 (edge trigger, overruled): edge config would fire once per
  assertion and let the handler drain fully — fewer GIC
  interactions. Overruled (C2): bytes arriving during the drain
  re-assert nothing on an edge config, and the level line is
  what the hardware actually provides.
- D3 (blocking consumer getc, overruled): a getc that waits for
  the next IRQ would match the polled driver's shape. Overruled:
  IRQ context cannot be waited on from a consumer without a
  scheduler hook, and the scheduler is fenced — the courier
  pattern (resonate) is the shape for "wait for delivery", not
  a blocking read. available()+getc is the honest pair.

## Proof posture (stated, not hand-waved)

- Hosted self-test: real kido-gic.c + real kido-serial-irq.c,
  public GIC API driving, module's own UART double. Proves the
  dispatch chain and every counter.
- NOT proven: SPI delivery through a real UART (needs the
  toolchain + QEMU virt + vec install + DAIF unmask — all
  queued, unchanged); Pi4 UART0 IRQ identity (unnamed, same
  discipline as the PL011 clock and the GIC bases).
- Toolchain this session: 13th data point — aarch64-linux-gnu-gcc
  absent; apt locked by the system updater (process 2998), so
  even an install attempt could not run. The vec/timer/SPI
  QEMU proofs stay queued; this session degraded honestly to
  the next draftable module per the session-22 precedent.
