# 2026-10-23 — kido-hal RPi4 UART init design (builder crew)

**Piece:** make the RPi4 board entry in `kido-hal-arm64` REAL — AUX
mini-UART (uart1) init sequence + polled TX, closing the session-2
(2026-10-14) loud stub (`fill(RPI4) -> KIDO_ERR_STUB_REACHED`). The
oldest open draftable item in the scaffold.

**Why this piece now:** the named remains were "UEFI/RPi4/MMU".
kido-mmu drafted session 22; UEFI discovery closed session 23. RPi4
UART is the last of the three and is draftable without hardware:
every address comes from the public spec, and the sequence is
host-testable through a scratch-register double (the session-22 MMU
"records order+values" precedent). The destroy bare-metal proof and
PENDING #1 stay queued on the toolchain — absent again this session
(7th data point: apt lock held by the system updater twice in a row,
`which` finds no cross gcc; nothing to compile against).

**Sources verified this session (not from memory alone):**
- BCM2835 ARM Peripherals doc: AUX block at bus `0x7E215000`
  (`AUX_MU_IO_REG` at `0x7E215040`), baud law
  `baud = sysclock / (8 * (baud_reg + 1))`, 8x oversampling.
- OSDev "Raspberry Pi 4" (`/proc/iomem` dump): `fe215000` = aux,
  `fe200000` = gpio — ARM-physical base `0xFE000000`
  (Low Peripheral Mode).
- Ultibo BCM2711: UART1 TXD = GPIO14, RXD = GPIO15, both ALT5.
- rpi4os.com "bare metal OS for Raspberry Pi 4, Part 4" (the
  canonical Pi4 bare-metal reference): `PERIPHERAL_BASE 0xFE000000`,
  GPIO14/15 -> ALT5 maps the mini UART, `AUX_UART_CLOCK 500000000`
  paired with `core_freq_min=500` in config.txt.
- azat.cc serial summary (Foundation behavior): on the Pi 4 the
  **mini UART is the PRIMARY UART** on the header pins and the
  PL011 goes to Bluetooth — the reverse of the Pi 1/2 layout.

## Positions

- **P1 spec realist:** no guessed addresses. Every constant names
  its source above. The one firmware-dependent value (VPU clock)
  is a NAMED constant with its config.txt pairing documented, not
  a buried magic number.
- **P2 TX-only minimalist:** the HAL console contract is putc/puts
  — transmit only. The mini UART is the right UART for it: no
  mailbox clock query needed, no fight with Bluetooth for the
  PL011 (on the Pi 4 the PL011 is the BT UART by default), and
  the init is 8 register writes.
- **P3 baud-math auditor:** `KIDO_RPI4_VPU_HZ = 500000000`,
  `BAUD = 5e8/(8*115200) - 1 = 541` (actual 115315, +0.1% —
  inside UART tolerance). The rpi4os reference runs exactly this
  pairing (`core_freq_min=500`). The failure mode of a wrong bet
  is baud skew, never a crash — stated in the source.
- **P4 fence keeper:** only `kido-hal-arm64.h/.c` change. The board
  table gains `init` + `putc` hooks; qemu-virt's init stays NULL
  (firmware owns the PL011). Zero Gate-approved files touched;
  the entry shim's board reporting is unchanged.
- **P5 hosted-double keeper:** the double gets a scratch register
  file + a write log. The self-test pins the 8-write sequence
  order and values exactly (MMU precedent), including a
  read-modify-write preservation check on GPFSEL1.
- **P6 test keeper:** self-test check 3 flips (RPi4 was
  STUB_REACHED, now OK). Twelve new checks pin the sequence, the
  putc path, and re-init idempotence. 19 checks total.

## Challenges

- **C1 — the VPU clock bet:** answered with the rpi4os pairing.
  `core_freq_min=500` in config.txt pins the VPU clock; the draft
  documents the pairing next to the constant. A mailbox clock
  query is the named future that removes the bet (D2).
- **C2 — mini-UART vs PL011 on the Pi 4:** answered. Pi 4 default
  puts the mini UART on the header (primary) and the PL011 on BT
  — the mini UART is not the consolation prize here, it IS the
  header UART. PL011 stays a named future (D1).
- **C3 — GPIO pulls:** answered by omission, deliberately. The
  rpi4os reference sets pull-none, but pulls cannot affect TX
  (the pin is driven), and a TX-only console never reads. The
  draft does not touch the pull registers; firmware owns them.
  Documented, not forgotten.
- **C4 — execution proof:** answered honestly. WRITTEN, NOT
  EXECUTED ON HARDWARE — stated in the source's PROOF STATUS
  block. The hosted double pins the sequence; a real Pi4 run is
  N8toriousAi's to witness.
- **C5 — the old table law dies:** `uart_base == 0 -> STUB` was
  the declared-but-unwritten encoding. It is replaced by the
  hook table: every row is now a real board; unknown board is
  still NO_CONSOLE, loud. No declared-but-unwritten rows remain
  in the HAL.
- **C6 — re-init safety:** answered by construction. All writes
  are absolute except `AUX_ENABLES |= 1`, which is idempotent.
  Re-fill replays the sequence; the test pins the replay.
- **C7 — LSR vs STAT for TX-ready:** answered. LSR bit 5
  (transmitter empty) is the documented polled-TX bit (BCM2835
  §2.2.2, 16550 convention). STAT bit 1 exists too; one bit is
  enough and LSR is the canonical one.
- **C8 — puts newline handling:** unchanged. The shared
  `kido_arm64_puts` (`\n` -> `\r\n`) sits above the per-board
  putc hook.

## Preserved dissent

- **D1 — PL011 instead of mini-UART:** overruled. The PL011 needs
  its UARTCLK characterized (firmware-dependent divider, BT
  contention on the Pi 4 default mapping); the mini UART needs one
  named constant. Preserved as the named future second UART.
- **D2 — mailbox VPU-clock query:** overruled. No mailbox driver
  exists in the scaffold; inventing the query here would be a
  bigger piece than the UART. Named future; the constant documents
  the seam.
- **D3 — RX / console input:** overruled. The `kido_hal_t` table
  has no read entry; the console is TX-only by interface. A read
  path is a HAL-interface change — N8toriousAi's call.

## Named next

- RPi4 execution proof on real hardware (N8toriousAi's Pi4, his witness).
- Mailbox driver -> VPU clock query removes the C1 bet.
- PL011 as second UART (BT coexistence story).
- kido-mmu call-site wiring (future Gate item, unchanged).
- Destroy bare-metal proof + PENDING #1 (toolchain, 7th data
  point recorded).
