# 2026-10-29 — kido-ipi design deliberation (session 36, builder crew)

Session 35's remains are, again, all blocked or fenced: the QEMU
virt PSCI proof and the QEMU virt -smp proof need the toolchain
(absent a 19th 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, secondary entry
stub, first kido-sync consumer, first kido-barrier consumer) 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-ipi: the inter-processor interrupt discipline the
SMP line has been missing.

The arc so far: session 33 brought secondary CPUs up (kido-smp),
session 34 gave them exclusion (kido-sync), session 35 gave them
a rendezvous (kido-barrier). Nothing yet lets one CPU SIGNAL
another. The GIC driver (session 27) can send a software
interrupt (kido_gic_send_sgi), but an SGI number means nothing
without a discipline: which SGI ids are IPIs, what each one
asks for, who handles it, what gets counted. This module is
that discipline — not another transport.

## Positions

- P1 (signaling realist): a CPU that cannot interrupt another
  CPU cannot coordinate with it. Bring-up without signaling
  leaves secondaries reachable only by polling (smp's
  AFFINITY_INFO poll, wait_release spins) — polling is how
  you check on a CPU, not how you tell it something. The
  scheduler-tick broadcast the Gate wiring wants (GIC
  enable(30) + timer arm into the tick) has no vocabulary
  yet: "reschedule" must exist as an IPI type before any
  wiring can send it.
- P2 (transport injector): the module must NOT include
  kido-gic.h or call kido_gic_send_sgi directly. The fence
  pattern of sessions 24/25/26/33 holds: zero existing files
  touched, and a leaf module stays testable on the host.
  The transport arrives as a function-pointer ops table
  (the boot HAL table and the interop link table are the
  precedents). The Gate wiring binds kido_gic_send_sgi in
  one line — its signature (cpu_mask, sgi_id) -> status
  already matches the ops slot exactly, which is evidence
  the seam is the right shape, not a coincidence to lean on.
- P3 (IRQ-context auditor): an IPI handler runs in interrupt
  context, called from the future vector stub through
  kido_gic_dispatch. It must be short, non-blocking, and
  allocator-free — the same law as the GIC handler
  contract. dispatch() therefore owns counting even when no
  handler is registered (the GIC precedent: dispatch owns
  EOIR even with no handler). A delivery with nobody
  listening is a counted fact, not an error.
- P4 (SMP census keeper): the CPU mask is capped at the
  machine's CPU table — 8, the KIDO_SMP_MAX_CPUS census.
  Mask bits at or above 8 are refused EARLY_ENV, never
  silently truncated: truncating a mask would silently drop
  a CPU the caller meant to signal.
- P5 (minimal-types advocate): exactly two IPI types ship:
  RESCHED (please reschedule — the scheduler-tick
  vocabulary) and PING (diagnostic presence — the "are you
  there" that lets a future proof distinguish a live CPU
  from a silent one). Every further type anyone can name
  (CALL, STOP, TLB shootdown) needs machinery this module
  does not have; shipping them as bare enum values would
  be claiming a capability with no handler contract behind
  it. They are named futures with stated reasons, not
  cut features.
- P6 (test keeper): the hosted proof drives the layer
  through a scripted transport (a recorder, plus a
  fail-switch for the transport-error path) and calls
  dispatch() directly with invented source CPUs. No GIC,
  no QEMU, no secondary stub is needed to prove the
  discipline — the mapping, the masks, the counting, and
  every refusal. What the hosted proof cannot prove (the
  SGI actually arriving on another CPU) is stated, not
  implied.

## Challenges, answered

- C1 (why module-global state, not caller-embedded like
  barrier/sync?): SGI ids are a single system-wide
  namespace — one GIC, sixteen ids. Two IPI registries
  would double-claim ids and dispatch the same SGI twice.
  A caller-embedded IPI layer would be pretending at
  independence the hardware does not offer. The GIC's own
  static handler table is the precedent: system-wide
  resources get module-global registries, CPU-local
  primitives get caller-embedded structs.
- C2 (self-send — is signaling yourself legal?): yes, and
  the module does not special-case it. An SGI addressed to
  the sending CPU pends on that CPU by architecture; send()
  counts the handoff, dispatch() on receipt counts the
  arrival. The module never needs to know which CPU it
  runs on — smp keeps affinities opaque and never parses
  MPIDR, and this module does not break that law to learn
  its own identity.
- C3 (no send-to-all-but-self helper?): cut deliberately.
  "All but self" needs a current-CPU query the tree does
  not have (MPIDR parsing is a future, not a guess), and
  the caller always knows its own slot — smp hands it out
  as context_id. The caller computes the mask in one
  expression; a helper that guessed the caller's identity
  would be a worse API than no helper.
- C4 (dispatch receives an SGI outside the owned range):
  counted in stats.unknown and refused EARLY_ENV. This is
  a wiring bug made loud, not a tolerated case: the Gate
  wiring registers the IPI dispatch as the GIC handler for
  exactly base..base+1, so an out-of-range arrival means
  the wiring registered the wrong ids. Silent OK here
  would hide exactly that bug.
- C5 (dispatch with no handler registered): OK, counted,
  no call — the GIC precedent (C3/P3 above). RESCHED
  arriving before any scheduler exists must not error;
  it is a signal nobody consumed yet, and the count
  proves it arrived.
- C6 (re-init semantics): allowed, and it rebuilds the
  world — clears handlers, args, and stats, rebinds the
  ops table (the GIC init precedent). Init is a
  construction-time call, not a concurrent one: the
  caller initializes before sharing the layer, same law
  as barrier init.
- C7 (sgi_base range): base must satisfy base + 1 <= 15
  (two types, SGI ids 0-15 architectural), so base > 14
  refuses EARLY_ENV. The Gate wiring picks a base that
  does not collide with any other SGI user; this module
  validates the range, it does not police the namespace
  — policing would need a registry of all SGI users,
  which does not exist yet.
- C8 (what does send() returning OK actually claim?):
  handoff, never delivery. An SGI is fire-and-forget by
  architecture: it pends on the target, and the target's
  IRQ handler runs dispatch() later, or never if the
  target never unmasks. stats.sent counts handoffs to
  the transport; stats.received counts dispatch() calls.
  Any design that claimed delivery from send() would be
  lying about an asynchronous mechanism, so the two
  counters are kept separate and the distinction is
  stated in the header.

## Preserved dissent

- D1 (STOP type now — park a CPU): overruled. A STOP
  handler cannot spin inside IRQ context — the GIC
  dispatch writes EOIR only after the handler returns,
  so a spinning handler blocks completion of its own
  interrupt. Parking a CPU is scheduler/Gate policy at a
  safe point (flag + park at the next yield), not an IRQ
  handler action. Named future, with this reason.
- D2 (CALL type now — run a function on the target):
  overruled. A function pointer cannot cross CPUs by
  itself: it needs a mailbox/queue with ownership and
  lifetime rules — a second invention, and one that
  belongs behind the scheduler, not inside the signal
  layer. Named future.
- D3 (call kido_gic_send_sgi directly, skip the ops
  table): overruled (P2). It couples a leaf to an MMIO
  driver, makes the hosted proof need GIC bases, and
  breaks the fence pattern. The one-line Gate binding is
  cheaper than the coupling.
- D4 (acknowledged send — sender waits for receipt):
  overruled. An ack needs a reverse IPI plus a timeout
  policy, and a timeout on a rendezvous primitive is
  exactly what the barrier deliberation refused (a
  timeout releases a partial group). Send is async by
  architecture; rendezvous is the barrier's job, already
  built. Do not re-invent it inside IPI.

## Decisions

1. Module-global registry (C1): one IPI layer, one SGI
   range, handlers + stats held in static state.
2. Transport injected via ops table (P2/D3): the ops
   send slot matches kido_gic_send_sgi's signature
   exactly, so the Gate binding is one line.
3. Two types only (P5): RESCHED + PING. CALL, STOP, and
   TLB shootdown are named futures with stated blockers.
4. Mask is uint32_t, validated against the 8-CPU census
   (P4): zero mask refused, bits >= 8 refused, never
   truncated. (The GIC's uint8_t mask cannot even express
   the bit-8 refusal case; the IPI layer validates before
   narrowing to the transport's uint8_t.)
5. dispatch() maps sgi_id -> type by subtraction from
   base (C4/C7): in-range dispatches, out-of-range counts
   unknown and refuses loud.
6. No-handler delivery is OK + counted (C5); no new
   header codes (sched-D1 precedent): every failure is
   KIDO_ERR_EARLY_ENV or a propagated transport status.
7. kido_ipi_sgi_id() exposes base + type so the Gate
   wiring registers exactly the owned ids with the GIC
   — the wiring never recomputes the mapping.
8. Sent vs received are separate counters (C8): send()
   claims handoff only. The hosted test pins both sides
   through the scripted transport and direct dispatch().
