# 2026-10-24 — kido-mbox design: the VideoCore mailbox driver (builder crew)

**Piece:** the mailbox driver that removes session 24's named C1 bet —
the RPi4 AUX mini-UART baud register today is computed from a NAMED
constant (`KIDO_RPI4_VPU_HZ = 500 MHz`, paired with config.txt
`core_freq_min=500`) instead of a measured clock. The driver queries
the VideoCore firmware for the real clock rate over the property-tags
mailbox, so a future HAL init can compute the baud divisor from
measurement instead of from a bet. One solid piece: the driver only.
The HAL wiring that consumes it is a future Gate item, not this
session's — the session-24 fence pattern (new files only, zero
Gate-approved files touched) holds.

**Why this piece now:** the named remains after session 24 were
"D1 KIDO_ERR_NO_TASKS (N8toriousAi's call — untouched), MMU call-site
wiring (future Gate item — untouched), destroy bare-metal proof
(queued on the toolchain — absent an 8th time this session: `which`
finds no `aarch64-linux-gnu-gcc` and no `qemu-system-aarch64`),
RPi4 execution proof (N8toriousAi's Pi4, his witness), mailbox driver,
PL011 second UART, BUBO peer (Phase 4)." The mailbox is the next
unbuilt module draftable without hardware: every register comes from
public spec, and the exchange is host-testable through a scripted
VideoCore double (the session-22 MMU / session-24 HAL precedent).

**Sources verified this session (not from memory alone):**
- OSDev "Raspberry Pi 4" `/proc/iomem` dump: `fe00b880-fe00b8bf`
  = `mailbox@7e00b880` — ARM-physical base `0xFE00B880` on the Pi 4
  (Low Peripheral Mode, peripheral base `0xFE000000`).
- rpi4os Part 5 (framebuffer/mailbox): channel 8 is the ARM->VideoCore
  property-tags channel; the message buffer MUST be 16-byte aligned
  because only the upper 28 bits of its address travel in the mail
  value and the low 4 bits carry the channel.
- Raspberry Pi forum mailbox example + DeepWiki mailbox writeup:
  register layout READ `0x00`, STATUS0 `0x18` (EMPTY `0x40000000`),
  WRITE1 `0x20`, STATUS1 `0x38` (FULL `0x80000000`); write value =
  `(buffer_address & ~0xF) | 8`; success = response code `0x80000000`.
- Linux `rpi_firmware_property` driver (spinics patch): the get-clock-
  rate request is tag `0x00030002` (confirmed as a real firmware
  request id by a kernel log line, "Request 0x00030002"); packet =
  `[clock_id, rate_hz]`; the firmware returns rate 0 on an unknown
  clock — so 0 is a LOUD failure here, never a divisor input.
- The VPU clock id (5) is carried from the firmware's clock table
  (EMMC 1, UART 2, ARM 3, CORE 4, VPU 5, ...). It was NOT re-fetched
  from the firmware wiki this session — stated plainly, not dressed
  as verified. The module takes `clock_id` as a parameter, so the
  id table is a caller fact, not module logic; and the first Pi4 run
  must show a sane VPU rate (near 500 MHz under `core_freq_min=500`)
  before the HAL adopts the query. A wrong id fails loud (rate 0),
  never silently.

## Positions

- **P1 protocol realist:** the driver implements exactly one
  exchange shape — build the tag buffer, write the mail, read the
  echo, validate the response. No framebuffer tags, no clock-setting
  tags, no batching. The mailbox is a firmware door, not a bus to
  build a stack on.
- **P2 timeout keeper:** every poll is bounded (`KIDO_MBOX_POLL_MAX`
  spins), never an infinite wait. A wedged mailbox or an absent
  VideoCore returns `KIDO_ERR_EARLY_ENV` loud. Pre-console there is
  no louder, and a spin-forever here would be a silent hang wearing
  a halo. The timeout maps to EARLY_ENV (firmware unresponsive =
  environment not sane); no new header code — that stays N8toriousAi's
  call per the sched-D1 precedent.
- **P3 static-buffer keeper:** one static 16-byte-aligned BSS buffer,
  one in-flight call, no allocator, no HAL dependency, no timer
  dependency. The mailbox must work at HAL-init time, before the
  allocator exists and before any timer is trusted. UP-only matches
  the scheduler's UP law; reentrancy is refused by construction
  (there is no lock to get wrong — a second caller would corrupt
  the single buffer, so the API is documented single-flight).
- **P4 validation purist:** five checks, all loud: mail echo
  (read value == written value), response-code success bit,
  tag-id echo, response-length == 8, clock-id echo, rate != 0.
  Any failure is EARLY_ENV with `*hz` untouched (never a partial
  or zero rate handed to a baud computation).
- **P5 fence keeper:** new files only (`kido-mbox.h/.c`). The HAL
  keeps its named constant this session; the seam is DECLARED:
  a future HAL init calls `kido_mbox_vpu_hz()` and computes
  `BAUD = hz / (8 * 115200) - 1`. Zero Gate-approved files touched.
- **P6 hosted-double keeper:** the hosted build replaces the MMIO
  registers with a scratch file plus a scripted VideoCore: on
  WRITE1 the double decodes the buffer, fabricates the response
  words in place (the firmware's real behavior — it writes the
  caller's buffer), and arms the READ echo. Scenarios: OK, stale
  mail first, wrong echo, no reply (timeout), bad response code,
  zero rate, wrong tag/clock echo, short length, FULL-stuck write
  side. The self-test pins the exchange, not the firmware.

## Challenges

- **C1 — bus address vs ARM physical address:** the VideoCore
  reconstructs the buffer address from the mail's upper 28 bits.
  rpi4os writes the ARM physical address directly and it works on
  real hardware; Kido runs MMU-off (or identity-mapped, per the
  kido-mmu design) at HAL-init time, so virtual == physical for
  the low-RAM BSS buffer. The module guards what it can: the
  buffer address must fit 32 bits and be 16-byte aligned, else
  EARLY_ENV before any write. The residual alias risk is covered
  by the echo + timeout: if the firmware wrote elsewhere, the
  echo never matches and the call fails loud — never a baud
  divisor computed from garbage.
- **C2 — stale mail:** another agent (or a previous crashed call)
  could leave mail in the VC->ARM box. The read loop discards
  any value that is not this call's echo, bounded by the same
  poll budget, instead of accepting the first word it sees.
  A stale flood therefore degrades to a timeout, loud.
- **C3 — why not fold this into kido-hal-arm64:** overruled (D1
  below). The mailbox is a firmware protocol with its own
  register/buffer contract, usable by future callers (board
  revision, temperature, clock-setting) that are not consoles.
  The HAL stays the console table; the mailbox stays the
  firmware door. One seam, two modules.
- **C4 — VPU id trust:** answered in the sources note. The id is
  a parameter; the convenience wrapper `kido_mbox_vpu_hz()` names
  the HAL's need. First-hardware-run confirmation is a stated
  burden, not a footnote.
- **C5 — poll bound sizing:** `1 << 20` volatile reads. On
  hardware the firmware answers in microseconds; on the hosted
  double the timeout path runs the same bound in well under a
  second. The bound is a loop count, not time — no timer
  dependency, by design (P2).
- **C6 — what the driver does NOT do:** no IRQ, no channel other
  than 8, no multi-tag batching, no clock setting. Each is a
  named future, not a silent absence — the header says so.

## Preserved dissent

- **D1 — fold the mailbox into kido-hal-arm64:** overruled (C3).
  The HAL file is already the console table; the mailbox protocol
  outgrows it. Preserved as the alternative if a future builder
  finds the seam cost exceeds the separation benefit.
- **D2 — infinite poll like the PL011 putc:** overruled. The
  PL011 spin is defensible (nowhere to report without a console);
  the mailbox HAS a reporter — its caller — and a return code.
  A wedged firmware must be a loud error, not a hang.
- **D3 — HAL adopts the query this session:** overruled. The
  query is WRITTEN NOT EXECUTED ON HARDWARE; wiring it into the
  console path before any hardware run would move the VPU bet
  from a named constant to an unproven query. The HAL keeps the
  constant until the Pi4 run confirms the query. Gate item.

## Named next

- RPi4 execution proof on real hardware (N8toriousAi's Pi4, his witness)
  — including the VPU-rate sanity read (C4).
- HAL wiring: `kido_mbox_vpu_hz()` -> baud divisor (Gate item).
- kido-mmu call-site wiring (future Gate item, unchanged).
- Destroy bare-metal proof + PENDING #1 (toolchain, 8th data point
  recorded this session).
- PL011 as second UART; real BUBO peer + bare-metal transport
  (Phase 4); D1 KIDO_ERR_NO_TASKS header code (N8toriousAi's call).
