# 2026-10-31 — kido-cache deliberation (session 39, builder crew)

## The gap, stated first

Session 33 brought secondary CPUs up, 34 gave them a lock, 35 a
rendezvous, 36 a signal, 37 a work carrier, 38 a CPU identity.
Session 22's kido-mmu turns caches on (SCTLR M|C|I). Nothing in
the tree maintains a cache since. That is a live correctness
gap, not a wishlist item, and it has a concrete shape:

- The smp secondary mailbox lives in BSS. The primary writes it;
  a secondary reads it. With the D-cache on, the primary's write
  can sit in its own cache while the secondary reads stale
  memory — unless the writer cleans to the point of coherency
  and orders it with a DSB. Today no module offers that
  operation. The smp mailbox works only while caches are off,
  which is exactly the state mmu's enable sequence leaves
  behind.
- The phase-3 relocator writes GOT entries and code-adjacent
  data; any future code a CPU writes and another executes
  needs clean-to-PoU plus I-cache invalidation, in that
  order, or the executing CPU fetches stale instructions.

This session drafts kido-cache: the cache-maintenance leaf.
Zero existing files touched (the session-24/25/26/33 fence
pattern); the module-map row and the ledger entry are the
only other edits. No wiring into smp or mmu — consumers are
Gate items, as with every leaf since session 33.

## Circle

- **P1 coherence realist** — the mailbox problem above is the
  module's reason to exist. Clean-to-PoC + DSB SY is the
  writer-side contract; anything weaker is a hope.
- **P2 ordering auditor** — every op ends in its barrier, in
  the op, not in the caller. A barrier the caller must
  remember is a barrier that will be forgotten once.
- **P3 destructive-op auditor** — DC IVAC discards dirty
  lines. An invalidate API that cannot say what it destroys
  is a footgun with a header file. Its danger must be in
  the law, and its one preventable case (unaligned range
  spilling onto a neighbor's dirty line) must be refused,
  not warned about.
- **P4 sequence keeper** — clean-to-PoU + I-cache
  invalidate is one canonical sequence (CVAU, DSB, IVAU,
  DSB, ISB). Offered as pieces, a caller will reorder it;
  offered as one function, the order is unbreakable.
- **P5 fence keeper** — leaf, no coupling, no wiring. The
  smp mailbox clean and the mmu post-enable invalidate
  are named consumers, not this session's edits.
- **P6 test keeper** — the hosted double records every op
  (kind, first line, line count, barrier sequence) so the
  self-test pins alignment, counts, and order — the only
  things a host can pin about cache ops.

## Challenges, answered

- **C1 — PoC vs PoU, which op for which job.** DC CVAC /
  CIVAC / IVAC clean or invalidate to the point of
  coherency: the point where another CPU, or a DMA
  observer, sees the write. That is the inter-CPU job
  (mailbox, shared tables). DC CVAU cleans only to the
  point of unification: the point where the instruction
  cache sees the write. That is the code-writing job, and
  it is never a substitute for PoC work — a CVAU-cleaned
  mailbox is still invisible to another CPU's D-cache.
  The header states the split per function; no function
  is named "clean" without its point.
- **C2 — two line sizes, not one (the sharpest point).**
  CTR_EL0 carries two fields: DminLine [19:16] for the
  D-cache, IminLine [3:0] for the I-cache. Line bytes =
  4 << field in each case. DC ops must step by the D
  size; IC IVAU must step by the I size. A single
  line_size() stepped by the wrong field would skip lines
  on one side — silent stale data, or stale instructions,
  with no fault to announce it. So the leaf exposes two
  queries (dline, iline), each from its own field, and
  sync_icache_range() steps its CVAU walk by D and its
  IVAU walk by I. The hosted double injects both values
  independently so the test can make them differ (64 vs
  32) and pin both walks. A field value of 0 yields a
  4-byte line: over-maintenance, the safe direction,
  never refused.
- **C3 — unaligned ranges.** Clean-family ops (CVAC,
  CIVAC, CVAU) align the base down and the end up and
  maintain whole lines: cleaning a line writes a
  neighbor's dirty bytes back, which is harmless. IVAC
  is different: invalidating a line DISCARDS its dirty
  bytes, so an unaligned invalidate range would discard
  a neighbor's data the caller never named. Decision:
  invalidate_range() refuses EARLY_ENV on an unaligned
  addr or len (both must be line multiples); the
  clean-family ops round and proceed, stated in the
  header. One destructive op, one refusal — not a
  blanket rule the tree would then have to carve
  exceptions out of.
- **C4 — zero length.** Refused EARLY_ENV on every range
  op. A caller asking to maintain nothing has a bug, and
  the alternative (round a zero range up to one line)
  would maintain a line nobody asked about — the C3
  hazard wearing a no-op's clothes. The tree's
  loud-arg-guard pattern, applied uniformly.
- **C5 — DSB scope: SY, not ISH.** DSB SY orders to the
  full system; ISH orders only the inner shareable
  domain. On today's UP-then-SMP tree ISH would suffice
  for CPU-to-CPU visibility, but SY is the conservative
  correct scope for PoC visibility (a DMA observer, a
  future outer-shareable CPU, are not inner-shareable
  by promise), and the cost is one barrier per op, not
  per line. The barrier rides inside the op (P2), so no
  caller pays it twice by accident.
- **C6 — no set/way operations, ever in this leaf.**
  There is no "invalidate all D-cache by VA" — the
  set/way instructions (DC CISW etc.) address cache
  geometry, not memory, and would discard lines
  belonging to other agents' data. Offering them would
  be offering a weapon with no target. IC IALLU is the
  exception that proves the rule: invalidating the
  whole I-cache discards no data (instructions are
  re-fetched from memory), so icache_invalidate_all()
  is offered, with DSB + ISB after it. See D2.
- **C7 — who cleans the smp mailbox.** Not this leaf.
  The smp module owns its mailbox protocol; a Gate
  wiring (or a future smp revision) inserts
  clean_range + DSB at the writer side and documents
  it there. This leaf offers the op; inserting it into
  a proven file unilaterally would break the fence
  that kept sessions 33–38 honest.
- **C8 — what the hosted proof proves.** The double
  records op kind, first line address, line count, and
  barrier sequence. It proves alignment arithmetic,
  guard refusals, walk counts, and barrier order. It
  does not prove a real cache line moved — a host has
  no cache to move, and the ARM64 spellings await
  assemble + disassembly + a QEMU virt -smp 2 run with
  caches on. Stated, as with every leaf since session
  33.

## Convergence

One leaf, six range/all operations plus two line-size
queries, all VA-based, all barrier-closed, no new header
codes (EARLY_ENV for every guard, the sched-D1
precedent), no coupling beyond kido-boot.h, zero existing
files touched. The sequence that must not be reordered
(sync_icache_range) is one function. The op that can
destroy data (invalidate_range) is the only one that
refuses unaligned ranges. The two line sizes are two
queries, because C2 admits no safe single answer.

## Preserved dissent

- **D1 — bare dsb()/isb() API (overruled).** A caller
  with a bare barrier will use it to paper over an op
  that should have carried its own ordering, and the
  audit trail (which op ordered what) disappears. The
  barriers live inside the ops; a future consumer that
  genuinely needs a standalone barrier makes its own
  case to the Gate.
- **D2 — set/way maintenance (overruled, C6).** By
  geometry, not by address; discards unrelated lines.
  If a future platform truly needs a full D-cache
  invalidate, that is a platform operation with its own
  deliberation, not a leaf function.
- **D3 — unaligned invalidate with a warning
  (overruled, C3).** A warning is not a refusal: the
  neighbor's dirty line is discarded either way, and
  the caller learns about it from a log line instead
  of a status code. The tree refuses what it can
  detect; this it can detect.
- **D4 — one line size for both caches (overruled,
  C2).** Tempting (one query, one injector, simpler
  tests) and wrong on any core whose I and D lines
  differ. The test proves the difference is handled by
  making the two sizes differ.

## Honest limits

WRITTEN, NOT ASSEMBLED, NEVER EXECUTED — toolchain
absent a 22nd time (no aarch64-linux-gnu-gcc, no
qemu-system-aarch64; `which` finds neither). The ARM64
spellings (MRS CTR_EL0, DC CVAC/CIVAC/IVAC/CVAU,
IC IVAU/IALLU, DSB SY, ISB) await assemble +
disassembly + a QEMU virt -smp 2 run with caches
enabled, which also needs the Gate smp-mailbox wiring
(C7) before the mailbox proof means anything. The
hosted proof pins the arithmetic, the guards, and the
barrier order — not the silicon. EL law: cache
maintenance by VA traps from EL0 unless SCTLR_EL1.UCI
is set (it is not, anywhere in this tree); call at
EL1+, stated not enforced, the mpidr precedent.
CTR_EL0 itself is readable at any EL and needs no law.
