# 2026-10-27 — kido-psci design: the ARM PSCI conduit (builder crew)

**Piece:** the ARM Power State Coordination Interface conduit
(`kido-psci.h` + `kido-psci.c`). One solid piece: the
firmware call layer by which an EL1 kernel suspends, powers
down, or powers up CPUs, and shuts down or resets the
system. It is the tree's first power-management module —
every prior driver moves data or time, none moves power.

**Why this piece now:** session 31's remains are all blocked
or fenced. 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)
are Gate items by standing order, 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; the toolchain is absent a 15th time this session
(`which` finds no aarch64-linux-gnu-gcc, no
qemu-system-aarch64), so no assembly or QEMU proof can run.
The session-22 precedent applies: when the queued proof
cannot run, the session drafts the next module the tree
can actually carry. PSCI is that module — every function
ID and return code comes from DEN0022, it is host-testable
through a double like the GIC/PL011/mbox/timer drivers, and
it touches zero existing files (the session-24/25/26 fence
pattern).

**Sources verified this session (not from memory alone):**
- ARM DEN0022 (PSCI), via the public spec summary and
  vendor tables: PSCI_VERSION 0x84000000, CPU_SUSPEND
  0x84000001 (SMC32) / 0xC4000001 (SMC64), SYSTEM_OFF and
  SYSTEM_RESET as mandatory 0.2 functions, PSCI_FEATURES
  introduced in PSCI 1.0 and mandatory from 1.0 on, the
  mandatory/optional table (MIGRATE family optional,
  SYSTEM_RESET2 / CPU_FREEZE / SYSTEM_SUSPEND 1.1
  optional). The 0.2 IDs form the documented sequence
  VERSION 0x84000000, CPU_SUSPEND 0x84000001, CPU_OFF
  0x84000002, CPU_ON 0x84000003, AFFINITY_INFO 0x84000004,
  MIGRATE 0x84000005, MIGRATE_INFO_TYPE 0x84000006,
  MIGRATE_INFO_UP_CPU 0x84000007, SYSTEM_OFF 0x84000008,
  SYSTEM_RESET 0x84000009, FEATURES 0x8400000A; the
  module uses the SMC64 forms 0xC4000001/0xC4000003/
  0xC4000004 where the call carries a 64-bit argument,
  as an AArch64 caller must.
- PSCI_VERSION encoding: bits[31:16] major, bits[15:0]
  minor — so PSCI 0.2 encodes as 0x00000002, not
  0x00020000. The version gate is written against
  major/minor fields, never against a guessed constant,
  and the self-test pins both encodings (0.2 and 1.0).
- SMCCC conduit shape: function ID in x0, arguments in
  x1-x3, result back in x0; `smc #0` for the monitor
  conduit. PSCI functions can only be called from Normal
  or Realm EL1/EL2 — Kido's EL1 qualifies; the HVC form
  is the same format through a hypervisor instead.

## Positions

- **P1 SMC only, not HVC:** Kido runs EL1 under a secure
  monitor, so SMC is the conduit to EL3 firmware. HVC is
  the conduit for an EL1 kernel under a hypervisor with
  no EL3 — that is a hosted-Kido caller, a named future,
  not a flag on this driver. One conduit, one truth.
- **P2 Version-gated, not version-blind:** init() calls
  PSCI_VERSION first and records it. Below PSCI 0.2 the
  driver refuses: a pre-0.2 monitor is not a PSCI monitor
  this driver can speak to, and guessing at its dialect
  would be exactly BUBO's x86-assumption flaw in ARM
  dress. FEATURES is gated the same way at 1.0, by spec.
- **P3 Never-returning calls never pretend to return:**
  SYSTEM_OFF, SYSTEM_RESET, and CPU_OFF return only on
  firmware error; on success the machine stops, resets,
  or the CPU is off, and the function does not come
  back. The hosted double is the stated exception: it
  records the call and returns OK, because the host must
  not halt. The divergence is written in the header,
  not discovered by a surprised test.
- **P4 The firmware validates, Kido does not second-guess:**
  cpu_on() passes affinity and entry straight through.
  Entry == 0 (INVALID_ADDRESS) and unknown affinity
  (NOT_PRESENT) are firmware answers, carried by the
  mapping — a driver-side pre-check would split the
  contract between two validators and drift from the
  firmware's own rules. The double enforces the same
  validations so the mapping is tested, not assumed.
- **P5 Opaque platform data stays opaque:** CPU_SUSPEND's
  power_state encoding and MPIDR affinity format are
  platform firmware data. The driver carries them, it
  does not parse or invent them. Inventing a platform's
  power states would be the HAL's session-2 sin (a
  guessed UART address) in a new register.
- **P6 No new header code:** NOT_SUPPORTED maps to
  KIDO_ERR_STUB_REACHED (the firmware does not
  implement the function — the existing code's exact
  meaning); every other negative maps to EARLY_ENV;
  AFFINITY_INFO states are not errors at all. The
  sched-D1 precedent holds: a new code stays N8toriousAi's
  call.

## Challenges, answered

- **C1 (why not MIGRATE?):** MIGRATE exists for a
  uniprocessor Trusted OS to move its context between
  CPUs. Kido has no Trusted OS to migrate. Offering a
  MIGRATE wrapper would be API theater; the FEATURES
  probe can still be asked about MIGRATE's ID, and the
  firmware answers for itself. Omission is declared in
  the header, not silent.
- **C2 (why SMC64 for CPU_ON but SMC32 for SYSTEM_OFF?):**
  the 64-bit form exists where the call carries a
  64-bit argument (entry point, affinity). SYSTEM_OFF,
  SYSTEM_RESET, VERSION, and CPU_OFF carry no such
  argument, so they have only the SMC32 ID. Using
  SMC64 IDs where they exist is the AArch64 caller's
  correct form, not a style choice.
- **C3 (can init detect a missing monitor?):** no. An
  SMC with no monitor present faults at the instruction,
  and there is no PSCI call that probes for a monitor
  without making one. That is why init is a caller-gated
  call and is NOT wired into the boot path: the boot
  path must never fault on a platform whose firmware
  never installed a monitor. The Gate item is the
  gating policy, not the conduit.
- **C4 (is CPU_ON an SMP claim?):** no. The scheduler
  is UP by law, and this module starts no second CPU
  on its own — it is the conduit a future SMP policy
  would call, with a second CPU's entry stub and stack
  as a scheduler/Gate item. A conduit is not a policy.
- **C5 (why does the double return from SYSTEM_OFF?):**
  because the alternative is halting the dev machine.
  The double records the call (the flag is the evidence)
  and returns OK; the header states the divergence in
  the same paragraph as the never-return law, so no
  reader can mistake the hosted behavior for the
  bare-metal one.
- **C6 (affinity format in the double?):** the double's
  table uses values 0..3 as a stand-in, stated in the
  header's test-setter comment. Real MPIDRs come from
  the caller (DTB/MPIDR reader, future). A test double
  that pretended its integers were MPIDRs would teach
  the wrong format to the next reader.
- **C7 (why is CPU_OFF's hosted return not a state?):**
  CPU_OFF has no target CPU — it powers down the
  caller. There is nothing to mark off in the table,
  and marking the host thread off would be a lie the
  test then had to work around. Returning SUCCESS with
  no state change is the honest hosted shape.

## Convergence

SMC conduit + version-gated init + the 0.2 core (VERSION,
CPU_SUSPEND, CPU_OFF, CPU_ON, AFFINITY_INFO, SYSTEM_OFF,
SYSTEM_RESET) + the 1.0 FEATURES probe, all through one
shared error mapping, with the never-return law and the
hosted divergence both written in the header. Zero
existing files touched; the module-map row and the
ledger entry are the only other edits, per the fence
pattern.

## Preserved dissent

- **D1 (HVC conduit, overruled):** a dual-conduit driver
  (SMC or HVC selected at init) would serve a hosted
  Kido under a hypervisor. Overruled for this piece:
  Kido's target is EL1 under a monitor, and a conduit
  flag chosen without a hypervisor to test against is
  an untestable branch. HVC stays a named future.
- **D2 (driver-side entry validation, overruled):**
  refusing entry == 0 before the SMC would fail faster
  and never issue a bogus call. Overruled (P4): the
  firmware is the validator, and the double enforces
  the same rule, so the mapping is proven without
  splitting the contract.
- **D3 (PSCI 1.1 functions now, overruled):**
  SYSTEM_RESET2, CPU_FREEZE, and SYSTEM_SUSPEND are
  optional 1.1 functions a complete driver would offer.
  Overruled as scope: they are optional, firmware-gated,
  and untestable without a 1.1 monitor; the FEATURES
  probe is the honest way a caller discovers them.
  They stay named futures.
- **D4 (CPU_OFF state record, overruled):** recording
  the calling CPU as OFF in the double would make the
  hosted table reflect the call. Overruled (C7): the
  caller is the host thread, and the table has no
  "host CPU" row; a fake row would be worse than no
  row.

## Proof posture (stated before running)

- Hosted self-test FIRST (gcc 13.3.0, -Wall -Wextra
  -Werror, zero warnings required). A module whose
  hosted battery is red proves nothing on bare metal.
- Plain hosted `-c` must pass with the test setters
  guarded (the PL011 lesson: unguarded helpers break
  a plain build).
- Queued proof gate (toolchain return): assemble the
  bare-metal path (the `smc #0` string is text until
  then) + QEMU virt PSCI proof (VERSION readback,
  CPU_ON record, SYSTEM_OFF exit) through a scratch
  harness, per the session-31 pattern. Nothing about
  bare-metal behavior is claimed from the hosted run.
