# Session 22 design — kido-mmu: the memory-management unit, drafted (builder crew)

## Pivot, stated first

This session opened as a verification session (deliberation
`2026-10-22-kido-session22-destroy-proof-design.md`): close PENDING
#1 (cross-compile) and put destroy's refusal gates on bare metal.
The toolchain was PRESENT at session start
(`aarch64-linux-gnu-gcc` resolved, `apt-get install` reported the
package newest) and ABSENT minutes later (binary gone, `apt-get
install` → "E: Unable to locate package", main pocket unreachable).
The hosted battery had already passed 12/12 before the toolchain
vanished. Per the destroy-proof deliberation's own C6, the session
degrades: PENDING #1 stays open with a 5th dated data point, the
QEMU halves cannot run, and the session picks up the next unbuilt
module instead. That module is **kido-mmu** — the last named item in
the ledger's standing remains ("UEFI/RPi4/MMU") that is draftable
without hardware: page-table construction is pure computation, fully
host-testable. (RPi4 UART init is register pokes with no observable
effect here; a UEFI memory-map parser is half a module without the
boot-services call. The MMU is the honest piece.)

D1 (`KIDO_ERR_NO_TASKS`) stays N8toriousAi's call. Phase 4 (real BUBO
peer + bare-metal transport) stays future. No bootable-kernel claim.

## The piece

`modules/kido-mmu.h` + `modules/kido-mmu.c`: ARM64 stage-1
translation for EL1 — static identity-mapped page tables
(VA == PA, so enabling is transparent to the running image),
constructed in portable C over a caller-supplied map, enabled by a
short audited register sequence. Hosted self-test
(`KIDO_MMU_SELFTEST`) walks the built tables and pins every
descriptor bit. The ARM64 register writes are real inline asm with
a hosted double (the HAL's syntax-test precedent); they are
WRITTEN, NOT ASSEMBLED and NEVER EXECUTED this session — stated in
the module header and here, per the session-16 precedent. The
call-site seam is DECLARED, not wired (session-4 precedent): after
`kido_reloc_verify()` OK, before `kido_boot()` — a future Gate
item; zero approved files touched.

## Positions

- **P1 table-builder.** 4 KiB granule, 39-bit VA (T0SZ=25), walk
  starts at L1: L1 1 GiB blocks where a whole GiB is mapped,
  otherwise L1 table → L2 2 MiB blocks, L3 4 KiB pages only for
  sub-2 MiB fragments. Largest-fitting-block rule, computed in
  portable C. 39-bit over 48-bit: 2 table levels instead of 3,
  512 GiB of VA — every real map (128 MiB RAM + UART windows)
  fits with room for ten lifetimes. Fewer levels, fewer pages,
  auditable by eye.
- **P2 static-tables keeper.** The tables are a bounded static
  array in BSS (`KIDO_MMU_MAX_TABLE_PAGES`, sized for the worst
  honest map + margin, declared). No allocator involvement — the
  MMU comes up before anyone should depend on it, and the
  allocator's regions are the MMU's INPUT, not its backing. The
  map itself is caller-supplied (`kido_mmu_map_entry_t[]`):
  bare metal passes kido-mem regions + the UART window; hosted
  passes synthetic entries. No kido-mem coupling, no HAL
  coupling — the one-query pattern (kido-image precedent).
- **P3 attribute realist.** Two MAIR entries only: 0x00
  Device-nGnRnE (UART), 0xFF Normal WBWA (RAM). Block
  descriptors: AF=1 (no access-flag faults — we run no fault
  handler), AP=0b00 (EL1 RW, EL0 none), UXN=1/PXN=0 (kernel
  executes; nothing else exists), nG=0, SH=ISH (normal) /
  OSH (device). Every bit chosen is stated with its reason;
  nothing copied from a tutorial without asking why.
- **P4 enable-order purist.** Sequence: `TLBI VMALLE1` → DSB →
  TTBR0_EL1 → TCR_EL1 → MAIR_EL1 → DSB → ISB → SCTLR_EL1 |=
  M|C|I → ISB. Tables/TTBR/TCR/MAIR fully programmed BEFORE the
  M bit flips — enabling with half-programmed controls is how
  kernels die mysteriously. TCR and MAIR values come from pure C
  functions (`kido_mmu_tcr_el1()`, `kido_mmu_mair_el1()`), so the
  hosted test pins the exact register values bit-for-bit.
- **P5 seam declarer.** The relocator (phase 3) runs with the MMU
  OFF — it fixes physical addresses; enabling first would be
  circular (tables would need relocating before the relocator
  runs). The identity map makes the later enable transparent.
  Declared seam: after `kido_reloc_verify()` returns OK in the
  entry chain, before `kido_boot()`. Wiring waits for the Gate;
  the draft touches nothing.
- **P6 test keeper.** The hosted self-test walks the constructed
  tables with an independent test walker (not the builder's own
  accessors): descriptor types, OA bases, AttrIndx, SH, AF, AP,
  UXN/PXN on sampled entries; unmapped VA walks to a zero
  descriptor; overlap/NULL/misaligned inputs fail LOUD;
  table-exhaustion fails `KIDO_ERR_NO_MEMORY` LOUD; rebuild is
  idempotent; the enable double records the register sequence
  and values.

## Challenges

- **C1 — Why identity map? Isn't the MMU's point virtual memory?**
  Answered (P1/P5): this kernel's honesty law is "no fake
  anything." A fancy higher-half map with nothing to put in it
  would be decoration. The MMU's REAL job here: turn on the
  caches (M+C+I) and give the kernel memory attributes — device
  vs normal — which bare metal currently lacks. Identity keeps
  every existing address valid across the enable; a higher-half
  design is a future module with a future reason.
- **C2 — 1 GiB L1 blocks would map 896 MiB of nonexistent RAM
  around the 128 MiB region. Why not just do that (simpler)?**
  Overruled: the MMU saying "mapped" over nonexistent RAM turns
  a wild pointer into a bus abort instead of a translation
  fault — strictly worse diagnostics. The largest-fitting rule
  (P1) maps exactly the described regions: 64× 2 MiB blocks for
  128 MiB RAM. Precision is cheap here.
- **C3 — The UART window: why a whole 2 MiB device block for a
  4 KiB PL011?** Alignment honesty: 0x09000000 is 2 MiB-aligned,
  the PL011 lives at its base, and a 2 MiB device block is one
  descriptor instead of a 512-entry L3 table for 4 KiB of
  registers. Device-nGnRnE is strict; the extra mapped-but-empty
  device space faults on access like the registers would. One
  descriptor, stated.
- **C4 — Who provides the map on bare metal, and when?**
  The caller — the future wiring composes it from kido-mem's
  region list (NORMAL) plus the board's UART base (DEVICE, from
  the HAL's board table, passed as data). The module never calls
  kido-mem or the HAL (P2). Until the Gate wires it, the map is
  the integrator's job; the module's contract is "map in, tables
  out."
- **C5 — Caches on: does anything in the tree assume caches off?**
  The phase-3 relocator and the entry `.S` run BEFORE the
  declared seam (P5), so they never see the MMU. Post-enable,
  device memory is nGnRnE (ordered, uncached) — the UART path is
  unaffected. Normal memory becomes cached: the only
  cache-coherence subtlety is DMA, which doesn't exist yet.
  Stated, not hidden.
- **C6 — TCR_EL1.EPD1=1 (disable TTBR1 walks): why not just set
  T1SZ=64?** EPD1 is explicit — "the upper VA region is disabled"
  reads as intent; T1SZ=64 reads as a magic number achieving the
  same by arithmetic. Explicit wins in a scaffold.
- **C7 — The enable asm is written but unassembled and unexecuted.
  Is that session-16 theater?** No — session 16's rule was
  "stated in every file that carries it, not hand-waved." The
  module header carries PROOF STATUS: construction REAL
  (host-tested), register sequence WRITTEN/NOT ASSEMBLED/NEVER
  EXECUTED, call site DECLARED/NOT WIRED. The hosted double
  proves the sequence logic and values; the encoding waits for
  the toolchain like everything else in PENDING #1's shadow.

## Convergence

Draft `kido-mmu.h`/`kido-mmu.c` per P1–P6; self-test per the
module's TESTING line (`-Wall -Wextra -Werror`, zero warnings);
update `architecture/module-map.md` (new row, DRAFT); ledger entry
records the pivot, the 5th toolchain data point, the design, the
tests, and the remains. The destroy-proof deliberation keeps its
outcome note (recorded post-hoc, marked as such).

## Preserved dissent

- **D1 (overruled):** 48-bit VA / 4-level tables "for
  future-proofing." Overruled: 39 bits already covers 512 GiB;
  the fourth level buys nothing but pages and audit surface.
  If a map ever needs it, that's a new deliberation.
- **D2 (overruled):** have the module read kido-mem regions
  directly ("one less caller burden"). Overruled: the
  one-query/no-coupling pattern is load-bearing scaffold law
  (kido-image P1); the MMU must not know where maps come from.
- **D3 (overruled):** wire the seam now (one line in
  `kido_entry_c_main`) since the design is settled. Overruled:
  session-4 precedent — boot-chain wiring waits for the Gate.
  N8toriousAi is away; the seam is declared, not taken.
