# 2026-10-24 — kido-pl011 design: the standalone PL011 UART driver (builder crew)

**Piece:** a full PL011 UART driver — init (baud divisor from a
caller-supplied clock), polled TX, polled RX — as its own module
(`kido-pl011.h/.c`). One solid piece: the driver only. The HAL
wiring that could consume it is a future Gate item, not this
session's — the session-24/25 fence pattern (new files only, zero
Gate-approved files touched) holds.

**Why this piece now:** the named remains after session 25 were
"D1 KIDO_ERR_NO_TASKS (N8toriousAi's call — untouched), MMU call-site
wiring (future Gate item — untouched), HAL mailbox wiring (Gate
item — untouched), destroy bare-metal proof (queued on the
toolchain — absent a 9th time this session: `which` finds no
`aarch64-linux-gnu-gcc` and no `qemu-system-aarch64`), RPi4
execution proof (N8toriousAi's Pi4, his witness), PL011 as second
UART, BUBO peer (Phase 4)." The PL011 is the next unbuilt module
draftable without hardware: every register comes from the ARM
PrimeCell TRM, and the exchange is host-testable through a
scripted UART double (the session-22 MMU / session-24 HAL /
session-25 mbox precedent). It also gives session 25's mailbox
query its first real consumer shape: a Pi4 caller can one day feed
`kido_mbox_clock_rate()` output into this driver's `uartclk_hz`
parameter — without this session naming any Pi4 PL011 clock
constant (see C2).

**What already exists, and why this is not a duplicate:** the HAL
(`kido-hal-arm64.c`) carries a minimal PL011 TX helper: polled
TXFF-checked putc, firmware-configured, no init, no baud control,
no RX. That helper stays untouched (fence). This driver is the
full device: it owns the baud rate, the line format, and both
directions. A future Gate item may rewire the HAL's putc onto
this driver; this session does not move the HAL's furniture.

**Sources verified this session (not from memory alone):**
- ARM PrimeCell UART (PL011) TRM, DDI 0183 (register summary
  table): DR 0x000, RSR/ECR 0x004, FR 0x018, ILPR 0x020,
  IBRD 0x024, FBRD 0x028, LCR_H 0x02C, CR 0x030, IFLS 0x034,
  IMSC 0x038, RIS 0x03C, MIS 0x040, ICR 0x044, DMACR 0x048.
  Baud law: divisor = UARTCLK / (16 x baud) = IBRD + FBRD/64;
  FBRD = round(fraction x 64) (the TRM's "+0.5" rule).
- FR bit assignments used here (TRM flag register): BUSY bit 3,
  RXFE bit 4, TXFF bit 5, RXFF bit 6, TXFE bit 7. LCR_H: FEN
  bit 4, WLEN bits 6:5 (0b11 = 8 bits), STP2 bit 3, PEN bit 1.
  CR: UARTEN bit 0, TXE bit 8, RXE bit 9; reset value 0x0300
  (TXE+RXE) is consistent with those assignments.
- OSDev Raspberry Pi Bare Bones: Pi4 MMIO base 0xFE000000,
  UART0 at GPIO base + 0x1000 = **0xFE201000**; a Pi4 kernel log
  independently shows `uart-pl011 fe201000.serial: ttyAMA0 ...
  is a PL011 rev2`. QEMU virt: PL011 at **0x09000000** with a
  **24 MHz** clock (DTB `clock-frequency`, via the krinkinmu
  QEMU-virt writeup; the HAL already names the same base).
- One correction applied, not copied: a secondary writeup masks
  interrupts by writing 0x7FF to IMSC. In the PL011, IMSC bits
  SET unmask; 0x7FF would UNMASK everything. This driver writes
  IMSC = 0 (all masked) — the polled driver wants no IRQs.

## Positions

- **P1 standalone, not a HAL fold:** the PL011 is a device with
  its own register/baud contract, usable by callers that are not
  consoles (a second UART, a debug port, a future serial link).
  Session 25's D1 reasoning holds verbatim: one seam, two
  modules. The HAL stays the console table; the driver stays
  the device.
- **P2 polled only, no IRQ:** there is no GIC module yet, and
  inventing interrupt delivery without one would be a lie.
  IMSC = 0, DMACR = 0. Interrupt-driven RX is a named future
  unlocked by a future GIC module, not a silent absence.
- **P3 caller clock, never a guessed clock:** `init` takes
  `uartclk_hz` as a parameter. The QEMU virt clock (24 MHz)
  is verified and named as a constant. NO Pi4 PL011 clock
  constant is named this session (C2): the Pi4 UART clock was
  not verified from a source this session, and a wrong
  constant here would silently mistune every baud rate. A
  Pi4 caller supplies the clock — one day plausibly from
  `kido_mbox_clock_rate(KIDO_MBOX_CLOCK_UART)`, which is a
  candidate, not a claim, until a Pi4 run confirms it.
- **P4 bounded everywhere:** every poll (init BUSY wait, TX
  TXFF wait, RX RXFE wait) is bounded by `KIDO_PL011_POLL_MAX`
  (1 << 20, a loop count, no timer dependency — the mbox
  precedent). A wedged UART is a loud EARLY_ENV, never a hang.
  No new header code (N8toriousAi's call, sched-D1 precedent).
- **P5 stateless, idempotent init:** the driver keeps no
  per-port state; `base` is passed per call, like the HAL's
  putc. `putc` works on a firmware-configured UART without
  any init call — that is exactly the HAL's current QEMU use,
  preserved. `init` is required only when Kido owns the baud
  rate. Re-init recomputes and rewrites the same registers;
  it is safe on a firmware-owned UART (on QEMU virt, init
  with 24 MHz / 115200 reproduces the firmware's own setup).
- **P6 hosted-double keeper:** the hosted build replaces the
  MMIO registers with a scratch register set plus a scripted
  UART: a TX capture buffer, an RX FIFO with per-byte error
  flags, a TXFF-stuck scenario. The self-test pins the
  divisor table, the init register image, TX, RX, error-bit
  rejection, and every loud failure — not the silicon.

## Challenges

- **C1 — HAL duplication:** answered above. The HAL helper is
  TX-only and firmware-owned; this driver is the full device.
  Duplication is temporary and fenced: the HAL file is not
  touched, and the rewire is a Gate item, so N8toriousAi sees the
  seam before it moves.
- **C2 — Pi4 PL011 clock unknown:** answered by P3. No
  constant, no guess. The header names the gap and the
  candidate source (mbox UART clock id 2) in plain text. A
  Pi4 run must confirm the clock before any HAL init call
  uses this driver on uart0 — same burden as the mbox VPU
  id (session 25, C4).
- **C3 — RX error bits:** a DR read carries OE/BE/PE/FE in
  bits 11:8 alongside the byte. `getc` rejects a byte with
  any error bit set: it writes ECR (clearing the error),
  returns EARLY_ENV, and delivers nothing. A corrupt byte
  delivered as good data would be silent corruption; a
  rejected byte is a loud fact the caller can count.
- **C4 — getc timeout mapping:** `getc` is the WAITING path
  (bounded poll, then EARLY_ENV on expiry — a wedged UART,
  same mapping as the mbox timeout). The NON-waiting path is
  `poll()`: it reports RXFE as a flag, never an error. The
  split is the answer to "no data is normal": poll for
  presence, getc for a byte you intend to wait for. The
  -1-sentinel alternative is preserved as D3.
- **C5 — divisor rounding and range:** the divisor is
  computed in uint64 as total = round(UARTCLK x 4 / baud)
  (the TRM's +0.5 rule, integer form), then IBRD =
  total / 64, FBRD = total % 64 — so a fractional round-up
  past 63 carries into IBRD by construction, never overflows
  FBRD. IBRD == 0 (clock too slow for the baud) or
  IBRD > 0xFFFF (clock too fast) is EARLY_ENV, loud. Baud
  0, clock 0, base 0 are EARLY_ENV before any register is
  touched.
- **C6 — GPIO mux is not this module's job:** on real
  boards the pins must be muxed to the UART function before
  init (on Pi4, GPIO14/15 muxing selects between the PL011
  and the mini-UART). The driver never touches GPIO — the
  board layer owns muxing. Init on unmuxed pins would
  configure a UART nobody can hear; that failure mode
  belongs to the board layer's contract, stated here so no
  future builder blames the driver for silent pins.

## Preserved dissent

- **D1 — fold the PL011 into kido-hal-arm64:** overruled (P1,
  session-25 D1 precedent). The HAL file is already the
  console table plus the RPi4 AUX init; the PL011 protocol
  outgrows it. Preserved if a future builder finds the seam
  cost exceeds the separation benefit.
- **D2 — interrupt-driven RX now:** overruled (P2). No GIC
  module exists; an IMSC-unmasked driver with nowhere to
  route the IRQ would be a louder lie than a polled one.
  Preserved as the GIC module's first consumer.
- **D3 — getc returns -1 for no-data instead of a status:**
  overruled (C4). The poll/getc split gives both contracts
  without conflating "no byte" with "error" in one integer.
  Preserved as the alternative if a future debug-shell
  caller finds the two-call pattern awkward.
- **D4 — name the Pi4 PL011 clock (48 MHz, by lore):**
  overruled (C2/P3). Lore is not a source. No constant is
  named until a Pi4 run or a verified source supplies it.

## Named next

- HAL wiring (Gate item): HAL putc -> `kido_pl011_putc`;
  HAL init -> `kido_pl011_init` for RPi4 uart0 once pin mux
  + UART clock are confirmed on hardware.
- GIC module (unlocks D2: interrupt-driven RX).
- Pi4 hardware run (N8toriousAi's Pi4, his witness) — including
  the UART-clock confirmation (C2) and the VPU-rate sanity
  read (session 25, C4) in one run.
- kido-mmu call-site wiring (future Gate item, unchanged).
- Destroy bare-metal proof + PENDING #1 (toolchain, 9th
  data point recorded this session).
- 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)

- **Name overlap, legal but flagged:** the HAL already has a
  `static kido_pl011_putc` (its TX-only helper). The new driver
  exports a global `kido_pl011_putc`. Verified: a hosted
  `kido-hal-arm64.o` carries NO pl011 symbol at all (the hosted
  double path compiles the helper out), so no hosted collision.
  On bare metal the two can coexist by linkage law (static =
  internal, global = external, different translation units) —
  but that coexistence was NOT link-tested (no toolchain, 9th
  data point), and the future HAL rewire should delete the
  helper rather than live with two functions of one name.
- **Plain-compile fix:** the first draft's test-only helpers
  (`test_reset`/`test_feed`) broke a plain hosted `-c` build
  under `-Werror` (unused-function). Guarded behind
  `KIDO_PL011_SELFTEST`; plain hosted compile and the
  self-test build are now both clean. The mbox module's
  helpers have the same latent pattern (its builds in prior
  sessions always carried the self-test flag); noted, not
  changed — mbox is a Gate-adjacent file and this session
  touches no existing files.
