# 2026-10-28 — kido-smp design deliberation (builder crew)

Goal: the next module the tree can actually carry. Session 32's
remains were all blocked or fenced: the QEMU virt PSCI proof needs
the toolchain (absent a 16th time this session — `which` finds no
aarch64-linux-gnu-gcc, no qemu-system-aarch64); the Gate wirings
(vec into the boot path, GIC enable(30) + timer arm into the
scheduler tick, serial-irq init into the boot path, HAL wiring,
MMU call-site wiring, psci-init gating policy) are Gate items, not
things a scaffold session takes unilaterally; the destroy
bare-metal proof has its own design (session 22, not swallowed
here); D1 KIDO_ERR_NO_TASKS is N8toriousAi's call; the BUBO peer is
Phase 4. Per the session-22 precedent (degrade honestly to the
next draftable module), this session drafts kido-smp: secondary
CPU bring-up policy on top of the session-32 PSCI conduit — the
exact future the psci header named ("SMP bring-up policy on top
of CPU_ON"). Zero existing files touched (the session-24/25/26
fence pattern); the module-map row and the ledger entry are the
only other edits.

## Positions

- P1 (coordinator, not conduit): smp owns POLICY — which CPU, which
  stack, what state it is in. The PSCI driver owns the call. smp
  never issues `smc` itself and never re-implements the return-code
  map; every psci status propagates unchanged.
- P2 (firmware-truth keeper): a CPU's firmware state comes from
  AFFINITY_INFO, never from smp's optimism. bring_up polls the
  firmware until it reports ON; smp's STARTED means "firmware says
  ON", nothing more.
- P3 (fence keeper): no scheduler, entry, boot, or HAL file moves.
  The secondary entry stub is a future Gate item (psci header's own
  words); this module declares its contract and stops there.
- P4 (static-tables keeper): 8 slots, static BSS, no allocator.
  Stacks are caller-supplied carves, not allocator products —
  smp must work before any allocator policy exists for secondaries.
- P5 (honesty auditor): PSCI has no "power down another CPU" call.
  CPU_OFF powers down the CALLER. Any smp API that claimed to off
  a secondary from the primary would be fiction, so none exists.
- P6 (test keeper): the hosted proof drives the REAL psci API
  against psci.c's scripted firmware double (linked without
  KIDO_PSCI_SELFTEST, so no main collision). No smp-side firmware
  double is invented; the double's limits are stated, not hidden.

## Challenges, answered

- C1 (ON is not ARRIVED): CPU_ON returning OK plus firmware ON
  proves the CPU started, not that it reached Kido code. Two
  phases, two facts: STARTED = firmware reports ON after the
  poll; ARRIVED = the secondary stub called
  kido_smp_secondary_arrived(ctx) from real Kido code. The
  scheduler/Gate wiring consumes ARRIVED, never STARTED.
- C2 (context_id is the slot index): CPU_ON's context_id is
  passed to the secondary entry (DEN0022: the entry receives it).
  smp passes the slot index, so the stub knows its slot without
  parsing MPIDR and without a table lookup before it has a stack.
- C3 (the stub needs a stack before it has a stack): a C accessor
  cannot serve a stub with no SP. So the primary writes the
  stack top into a per-slot BSS mailbox word
  (kido_smp_secondary_stack_top[slot]) BEFORE cpu_on, and the
  stub loads SP from that word with a PC-relative read (the
  entry .S pattern). The mailbox is pinned by test after every
  bring_up. The stub itself is still the Gate item; the mailbox
  is this module's half of its contract.
- C4 (failed bring_up, two kinds): a REFUSED cpu_on changes no
  firmware state, so the slot returns to EMPTY and retry with
  corrected arguments is allowed (pinned by test: entry 0
  fails, then the same affinity succeeds). A poll that times
  out or errors AFTER a successful cpu_on is different — the
  firmware state is genuinely unknown — so that slot goes
  FAILED and is terminal for its affinity (no re-bring; see D1).
- C5 (hosted double sets ON immediately): after a successful
  cpu_on the double reports ON on the first poll, so the hosted
  test proves the ON path and the poll loop's shape, but NOT
  the ON_PENDING-transient path and NOT the timeout path. Both
  are code-reviewed, stated here, and queued for the QEMU PSCI
  proof, where real firmware timing exists. No hosted test
  pretends otherwise.
- C6 (the primary's affinity is unknown): smp does not reserve
  slot 0 for the primary and does not guess it. The table holds
  secondaries only; bringing up an already-ON affinity fails
  loud at the firmware (ALREADY_ON -> EARLY_ENV), and the
  duplicate-affinity scan refuses a second bring_up of any
  affinity already in STARTED/ARRIVED/FAILED.
- C7 (park without a timer): the secondary's wait for release
  takes a caller spin bound, not a time bound — smp has no
  timer dependency by design (the timer driver is a separate
  module with its own Gate wiring). Unreleased within the
  bound is EARLY_ENV, never an infinite spin. A bare-metal
  caller passes a large bound; the bound is a loop count,
  stated as one.
- C8 (affinities stay opaque): smp never parses MPIDR, same law
  as psci. The hosted double's 0..3 stand-in affinities are
  the test's, not a claim about real MPIDR format.

## Convergence

- bring_up order is fixed: guards -> duplicate scan -> reserve
  slot + write mailbox -> cpu_on -> bounded affinity poll ->
  STARTED. Validation precedes reservation (a refused guard
  leaves the table empty); reservation precedes cpu_on (the
  slot index IS the context_id, so it must exist first).
- secondary_off marks nothing: on bare metal a successful
  CPU_OFF never returns, so any marking code after the call
  would run only on the error path and would lie. The API
  propagates the psci status and nothing else; the primary
  learns a secondary went OFF through kido_smp_query, which
  re-reads AFFINITY_INFO and moves ARRIVED/STARTED -> OFF
  only on a firmware OFF report (a firmware ON report leaves
  smp state alone — arrival is smp-level, not firmware-level).
- No new header codes (sched-D1 precedent, psci P6): every
  failure is EARLY_ENV or a propagated psci status
  (STUB_REACHED for NOT_SUPPORTED).
- Re-init refuses while any secondary is live (STARTED or
  ARRIVED) — resetting the table under a running CPU would
  orphan it. OFF/FAILED/EMPTY allow re-init.

## Preserved dissent

- D1 (retry a FAILED bring_up): overruled for this version.
  After a successful cpu_on, a CPU that never reports ON may
  be starting slowly, wedged, or powered off by firmware
  policy — re-issuing cpu_on into that unknown state risks a
  double-start. A Gate policy may add an explicit, audited
  retry (affinity re-check + re-issue) later; this module
  refuses instead.
- D2 (smp owns secondary stacks via kido-alloc): overruled.
  Allocator coupling would tie bring-up to allocator init
  order and raise the free-ownership question (who frees a
  secondary's stack, and when, if the CPU never arrives?).
  Caller-supplied stacks keep that question with the caller,
  where the scheduler/Gate wiring will answer it.
- D3 (write the secondary .S stub now): overruled. The psci
  header names the stub a scheduler/Gate item, and a stub
  without its scheduler consumer is untestable shape. The
  mailbox + context_id contract is declared here so the stub
  has a fixed target when the Gate commissions it.
- D4 (single-phase bring_up that waits for arrival): overruled.
  Arrival happens on another CPU at an unknown time; a
  synchronous wait on the primary would hang it (and on
  hosted it could never complete). Two phases — STARTED
  now, ARRIVED later — is the honest shape.

## Proof gate (queued, toolchain)

- Hosted self-test this session (real psci API, scripted
  double); plain hosted -c clean; full hosted battery
  re-run; collision check (zero kido_smp references outside
  the two new files before writing).
- QEMU virt proof (queued with the PSCI proof): -smp 2+,
  bring_up of CPU 1 through the future stub, STARTED then
  ARRIVED observed on the console, zero exceptions. The
  stub does not exist yet, so this proof waits for the Gate
  item, not just the toolchain — stated, not hidden.
