# 2026-10-30 — kido-call design deliberation (session 37, builder crew)

## Opening state

Session 36's remains are, again, all blocked or fenced: the QEMU
virt PSCI proof and the QEMU virt -smp proof need the toolchain
(absent a 20th time this session — `which` finds no
aarch64-linux-gnu-gcc, no qemu-system-aarch64; only the host gcc
13.3.0); 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, secondary entry stub, first sync/barrier/ipi
consumers) 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-call: the cross-CPU function mailbox.

The SMP line so far: session 33 brought CPUs up (kido-smp),
34 gave them a lock (kido-sync), 35 gave them a rendezvous
(kido-barrier), 36 gave them a signal (kido-ipi). Nothing yet
lets one CPU ask another CPU to DO something. The GIC can send
an SGI and the ipi discipline can name it, but a signal carries
no work. Session 36's deliberation D2 said it plainly: a CALL
type "needs a cross-CPU function mailbox/queue, a second
invention behind the scheduler." This session is that invention
— the mailbox itself, not the CALL type wired into ipi (that
binding is a Gate item: it needs the transport, the handler
registration, and the wakeup policy decided together).

## Circle

- P1 — work-queue realist. A mailbox, not an RPC framework.
  One slot per CPU, one call per slot, a function pointer and
  an argument. Anything fancier (queues, priorities, return
  values by copy) is a second invention.
- P2 — ordering auditor. The claim-run-store sequence must be
  exact: the lock orders the claim, the release orders the
  store, and the function must never run under the lock.
- P3 — IRQ-context auditor. A function pointer is arbitrary
  code. Arbitrary code never runs in interrupt context.
- P4 — census keeper. Eight slots, no more, no fewer: the
  smp table's census is the only CPU count the tree has.
- P5 — fence keeper. No ipi, no GIC, no scheduler, no MMIO in
  the leaf. The mailbox works polled; the wakeup is a Gate
  binding, not a dependency.
- P6 — test keeper. A single-threaded test proves the state
  machine and nothing about cross-CPU execution — the module's
  entire purpose. The pthread section is fenced to the test
  TU, the barrier precedent.

## Challenges, answered

- C1 — Module-global table, or caller-embedded struct?
  Module-global. The sync/barrier caller-embedded precedent
  was argued and distinguished, not ignored: a lock or a
  barrier is owned by its users, who hold it. A mailbox slot
  is owned by its TARGET CPU, which never "holds" it — the
  slot is an address in a system-wide address book, exactly
  like the ipi registry's SGI namespace and the GIC's handler
  table. Two mailbox tables would double-deliver calls. One
  table, eight slots, indexed by target CPU.
- C2 — One-deep slot, or a queue per CPU? One-deep. A queue
  is the second invention D2 warned about, and it needs a
  queue policy (drop? block? grow?) that no caller has asked
  for. A busy slot is a door, not an error: post() returns
  KIDO_OK with *accepted = 0 (the resonate-defer door and
  the sync try_lock precedent — contention is a fact, not a
  failure). The caller retries, or posts elsewhere, or
  decides the call can wait. The mailbox never silently
  drops work and never blocks a poster.
- C3 — Does the function run under the slot lock? NO — this
  is the decision the whole module turns on (P2). poll()
  claims the slot under the lock (POSTED -> RUNNING),
  unlocks, runs the function, relocks, stores the result
  (RUNNING -> DONE). Running under the lock would serialize
  every reap against an arbitrary function body, and would
  deadlock the day a function posts a call of its own: the
  poster would spin for a lock held by the CPU running its
  own function. The claim is the critical section, not the
  work. A second poll() during RUNNING is a no-op by the
  state check, so the claim is also the re-entrancy guard.
- C4 — Who may reap a result? Only the poster (P2/P4).
  The slot records the posting CPU; reap() by any other CPU
  refuses EARLY_ENV with the slot untouched — the sync
  stranger-unlock precedent, applied to results instead of
  locks. A stranger reading another CPU's result is silent
  corruption of the caller/callee contract, not a shortcut.
  The check applies whenever the slot is non-EMPTY, not only
  at DONE: a stranger polling for completion learns nothing
  about a call that is not theirs.
- C5 — What is the result channel? The function returns
  kido_status_t and the slot stores it (P1). No return-value
  copying, no output buffer: the argument is void*, its
  lifetime is the caller's, and the mailbox never copies,
  frees, or extends it — documented, not enforced, because
  enforcement would need an allocator the leaf refuses to
  touch. A function that needs to return data writes it
  through its argument before returning, the way a task body
  already does.
- C6 — Notification: does post() wake the target? NOT in
  this module (P5). The mailbox is poll-first: the target's
  idle loop calls kido_call_poll() for its own slot, and
  that loop is the execution engine. No ipi include, no
  transport injection, no GIC base — the leaf stays host-
  testable with zero MMIO. The Gate wiring that binds a
  wakeup (ipi PING, ipi RESCHED, or the future CALL type
  whose handler calls poll) is one line plus a policy
  decision, and it is named as the first-consumer Gate item
  below. Polling without wakeup is slower, not wrong: the
  call still executes, exactly once, in order.
- C7 — Re-init over a busy table? Refused (barrier
  in-flight precedent). init() rebuilds the world only when
  every slot is EMPTY; a POSTED, RUNNING, or DONE slot
  refuses EARLY_ENV with the table untouched. Rebuilding
  over a posted call would silently lose work in flight.
  Re-init on an empty table clears handlers, stats, and
  slots — the ipi re-init precedent.
- C8 — CPU identity without MPIDR parsing? The caller passes
  both indices explicitly (P4). ipi deliberation C6 already
  settled this: the caller knows its smp slot, and MPIDR
  parsing is a named future, not a guess — ipi C3 refused to
  parse MPIDR for the source CPU, and this module refuses
  to parse it for the poster. post() and reap() validate
  both indices against the 8-CPU census (bits >= 8 are
  EARLY_ENV, never truncated — the ipi mask law, applied to
  indices). No hosted injector is needed: the self-test
  plays two CPUs by passing two indices.
- C9 — May a CPU poll another CPU's slot? The contract says
  no: the idle loop services its own slot (P3). The module
  cannot enforce this without a current-CPU query it
  refuses to invent (C8), so it is stated, not detected —
  the barrier one-call-per-round precedent. Servicing
  another CPU's slot would execute the function on the
  wrong CPU, defeating the module; the contract is in the
  header in plain words, and the Gate wiring (which knows
  its own slot) is the enforcement point.
- C10 — Self-post (source == target)? Allowed, no special
  case (P1). Posting to your own slot and polling it is the
  UP-degenerate form and the single-threaded test's shape.
  A rule against it would be decoration: the state machine
  handles it identically, and forbidding it would break
  the hosted proof without protecting anything real.

## Preserved dissent

- D1 — Blocking post / blocking wait with a timeout.
  Overruled (sync dead-holder law, barrier no-timeout law):
  a timeout on post would convert a busy callee into a lost
  call, and a timeout on reap would convert an unfinished
  call into a wrong answer. The caller loops post/reap;
  the bounded doors are try-shaped by design.
- D2 — A queue of N calls per CPU. Overruled (C2): the queue
  policy is unasked-for invention. If a caller needs queue
  depth, that caller builds it on top of the busy door and
  brings the policy with it.
- D3 — Running the function in the IPI handler. Overruled
  (P3, ipi IRQ law): handlers must be short, non-blocking,
  allocator-free. An arbitrary function pointer satisfies
  none of those. The handler's job, when the Gate wiring
  gives it one, is to call poll() — from task context, at a
  safe point — never to BE the execution.
- D4 — Injecting an ipi notify transport now. Overruled
  (P5/C6): a notify slot would couple the leaf to ipi's
  send signature and make the hosted proof carry a fake
  transport for a feature the module does not need. The
  binding is one Gate line when the wiring lands; coupling
  now buys nothing.

## Design, as built

- Table: 8 static slots, one per CPU. Slot = { spinlock
  (sync public API), state, poster, fn, arg, result }.
  State machine: EMPTY -> POSTED -> RUNNING -> DONE ->
  EMPTY (reap). No other transitions exist.
- API: kido_call_init() / kido_call_post(src, dst, fn,
  arg, &accepted) / kido_call_poll(cpu) / kido_call_reap
  (src, dst, &done, &result) / kido_call_state(dst, &state)
  (diagnostic snapshot, sync snapshot law) /
  kido_call_stats(&out) (posted, busy, completed, reaped,
  stranger).
- Ordering chain (P2): post's lock release orders the
  POSTED store before any poller's claim; the claim's
  release orders RUNNING before the function body; the
  store's release orders the result before DONE; the
  reap's lock acquisition orders DONE before the result
  read. No DMB claimed beyond what the spinlock's
  acquire/release pair already provides (sync header law).
- No new header codes (sched-D1 precedent): every failure
  is KIDO_ERR_EARLY_ENV; busy is KIDO_OK + accepted 0;
  not-done is KIDO_OK + done 0.
- 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.
- First consumer (Gate item): the scheduler-tick RESCHED
  broadcast's work half, or a Gate wiring binding ipi
  transport + a CALL-type handler that polls. The mailbox
  does not choose its consumer; the Gate does.
- Proof status: WRITTEN, NOT ASSEMBLED, NEVER EXECUTED on
  bare metal (toolchain absent, 20th data point). The
  module has no asm at all — unlike sessions 33-35 there
  is no ARM64 spelling awaiting disassembly — only the
  cross-CPU execution itself, which awaits the Gate
  secondary stub + a QEMU virt -smp 2 run. The hosted
  proof uses real spinlocks and real threads but proves
  the mailbox discipline, not delivery across silicon.

## Outcome note (post-hoc)

The session-36 remains list is unchanged except for one
addition at its tail: kido-call now exists, and the ipi D2
blocker ("needs a cross-CPU function mailbox") is closed
as a module. The CALL type itself stays a named future in
ipi until the Gate wiring binds transport + handler +
wakeup policy together. Nothing in this record authorizes
that binding from a scaffold session.
