danos/docs/m21-plan.md

M21 execution plan: ACPI events + system power

The operational plan for the event side of the acpi service and orderly shutdown — the capstone m19-m20-plan.md previewed. Same rules as its predecessors: one phase at a time, each green before the next; this file is the build order and the checklist.

Definition of green, every phase: zig build clean, zig build test clean, python3 test/qemu_test.py passes (existing scenarios plus the phase's new one), and the relevant design doc updated. Commit per green phase (no co-author trailers). Failing cases preserve their serial logs (<case>-failed-serial.log).

Workflow: dedicated worktree; branch feat/power-events off main; auto-merge to main when the branch is green; keep the branch; push everything.

Settled decisions (2026-07-13, approved)

1. S5 is executed by the acpi service from ring 3. No new syscall: the broad port grant (M20 decision 5) already made this physically possible — the service holds the PM1 control ports in its io grant and derives _S5 from its own namespace (aml.sleepState). Formalizing it adds no authority. The kernel keeps power.zig for its own test paths and panic-time use.
2. The power surface is domain-named (decision 7 of the last plan): a power-protocol module + ServiceId.power = 5, registered by the acpi service — on ARM, a PSCI/mailbox service registers the same id and subscribers never know the difference. Messages: subscribe (endpoint as the call's capability, the input/manager pattern), shutdown (accepted only from PID 1 — init), and events published as buffered messages: power_button, lid, ac, battery, generic notify with a code.
3. The service learns event ports from its own FADT copy: the kernel adds the FADT as one more memory resource on the acpi-tables node; the service tells it apart from the AML blobs by signature ("FACP" header — the blob resources are header-stripped bytecode and start with no signature). The kernel's own FADT parse is untouched.
4. The acpi service converts to the harness (runtime.service.run): protocol messages (subscribe/shutdown), the SCI notification, and the existing report flow fold into one loop — the shape it was always meant to have.
5. GPE/Notify correctness is proven by host unit tests (synthetic AML with a Notify inside a method body; aml.zig joins the zig build test loop). The QEMU scenario proves the power button — a fixed event, deterministically injectable via QMP system_powerdown — because QEMU cannot raise GPEs deterministically on this config. Battery/AC/lid and the embedded controller (_Qxx) are interface-complete here and validated on real hardware (the laptop) later.

Ground truth the phases build on (verified 2026-07-13)

• system/devices/power.zig shutdown() is the kernel's S5 write (SLP_TYP|SLP_EN to PM1a/PM1b control); there is no power syscall.
• init (system/services/init/init.zig) spawns vfs/input/device-manager fire-and-forget — no child ids kept, no signals, no event loop. The whole stop toolkit exists in runtime.process (stop/sendSignal/bindSignals).
• test/qemu_test.py has no QMP channel (serial is a one-way file).
• The kernel parses PM1 control blocks and SCI_INT from the FADT; the PM1 event blocks (offsets 56/60, len at 88) and GPE0/GPE1 blocks (offsets 80/84, lens 92/93) are unparsed — the service reads them from its FADT copy (decision 3).
• The acpi-tables node carries the SCI as its only len == 1 irq resource (the broad window is len 256) — that is how the service finds it to irqBind.
• notify_opcode = 0x86 exists in system/devices/aml/opcodes.zig but the interpreter never handles it — a GPE _Lxx body containing Notify fails evaluation today. Everything else a GPE handler needs (field access, control flow, method calls) is proven by the ring-3 _STA/_CRS work.
• The dead-code sweep (spawned task) also edits system/devices/acpi.zig; M21.0 checks whether it landed and rebases before touching that file.

Status

• M21.0 — baseline: rebase over anything newly merged (the dead-code sweep touches acpi.zig); cut feat/power-events; add the QMP channel to the harness (-qmp unix:.../qmp.sock,server,nowait, a small client with the qmp_capabilities handshake, a per-case qmp_after hook that sends a command N seconds after boot); existing suite stays green.
• M21.1 — SCI + the power button: kernel appends the FADT as an acpi-tables memory resource; new power-protocol module + ServiceId.power; the acpi service converts to the harness, registers .power, parses the event/GPE blocks from its FADT copy, enables ACPI mode if needed (SMI dance, spin on SCI_EN), binds the SCI, sets PWRBTN_EN; on SCI reads/clears PM1_STS and publishes power_button (log: power: button pressed), always irqAck. Scenario power-button: qmp_after system_powerdown → expect the log line.
• M21.2 — Notify + GPE dispatch: interpreter handles notify_opcode into a bounded queue drained after evaluate(); on GPE status bits the service evaluates \_GPE._Lxx/_Exx, maps notified nodes to events (PNP0C0A→battery, ACPI0003→ac, PNP0C0D→lid, else generic), clears GPE_STS, acks. EC _Qxx explicitly out (hardware track). Host unit tests for Notify in aml.zig; aml.zig joins the zig build test loop.
• M21.3 — orderly shutdown: init keeps child ids (spawnSupervised + exit endpoint), binds signals, subscribes to .power; on power_button logs init: shutting down, runs stop(child, 2000, endpoint) in reverse spawn order, then sends shutdown to .power; the acpi service (sender PID 1 only) logs power: entering S5 and writes SLP_TYP|SLP_EN from ring 3. Scenario orderly-shutdown: boot via init, qmp_after system_powerdown, ordered regex button→shutting-down→entering-S5, pass on QEMU exit. Docs + memory updated.
• merge feat/power-events → main, push, keep the branch — loop ends here.

---

Phase notes

M21.0 QMP: open the unix socket after Popen, complete the qmp_capabilities handshake, then send the hook's command (for these scenarios: {"execute": "system_powerdown"}). The socket is additive — no existing case may notice it. Note e3fe3f3 recently reworked how the harness boots; adapt to its current shape rather than the pre-rework description.

M21.1 SCI details: PM1_STS is at the event block base (write-1-to-clear); PM1_EN at base + block_len/2; PWRBTN bit is 8 in both. If PM1b exists, mirror reads/writes to both blocks. Enable ACPI mode only when SCI_EN (PM1 control bit 0) is clear — OVMF boots may already have it set. The publish path reuses the manager's subscriber table pattern (bounded, drop-on-failed-send).

M21.2 GPE walk: GPE0_STS bytes live at the GPE0 block base, GPE0_EN in the block's upper half; for a set+enabled bit n, the handler method is _L%02X (level) or _E%02X (edge) under \_GPE. Evaluate, drain the notify queue, clear the status bit, ack. A missing handler method is clear-and-log, not an error.

M21.3 ordering: init subscribes with retries — the acpi service registers .power well after init starts. The stop sequence runs vfs last (other services may flush through it). The S5 write mirrors power.zig's sleepValue (SLP_TYP bits [12:10], SLP_EN bit 13); if the write returns, log power: S5 write did not take so the scenario fails loudly instead of hanging.

Explicitly out of scope: the embedded controller and _Qxx queries, battery _BST/_BIF evaluation beyond the interface stubs, lid/AC on QEMU (no emulation), reboot over the power protocol, S3 sleep, per-device D-states (a future lifecycle-vocabulary extension), thermal zones.