danos/docs/os-development/power.md

The power service: events and shutdown

A laptop lid closes, a battery drains, someone presses the power button — and several parts of the system might care: a session manager dims the screen, a logger notes it, and ultimately something has to turn the machine off. None of them owns the hardware that reported the event, and the reporter should not know who is listening. So system power is a service: an event source publishes button/lid/battery/AC events, interested processes subscribe, and one privileged caller — init — can ask it to power the machine off. It is the same publish/subscribe shape as the input service, applied to power.

Why a service, and why it is named for the domain, not the firmware

Where the events come from is firmware-specific — on x86 they ride the ACPI SCI (acpi.md); on a Raspberry Pi they would come from PSCI or a mailbox. What subscribers want is not: the lid closed means the same thing regardless of who noticed. So the surface is domain-named. There is a power-protocol module and a well-known ServiceId.power = 5; on x86 the acpi service registers it, and on ARM a PSCI/mailbox service will register the same id. Subscribers call ipc.lookup(.power) and never learn which firmware they are on — the neutrality the whole discovery migration exists to preserve, carried one layer up into a running-system surface.

This is why the protocol is power, not "ACPI events": naming a cross-firmware surface after one firmware would leak x86 into code the ARM port must reuse unchanged.

The protocol

The power-protocol module (library/protocol/power/power-protocol.zig) follows the vfs-protocol pattern — extern-struct messages, a version, reserved fields. Three operations:

Direction	Operation	Purpose
subscriber → service	subscribe	receive published events; the subscriber's endpoint rides as the call's capability (the input/device-manager pattern)
init → service	shutdown	orderly shutdown's last step: enter S5 (soft off)
service → subscriber	event	a published EventMessage, delivered as a buffered message (never sent to the service)

Events are published, not polled: like the input service, the service holds subscriber endpoints as capabilities and ipc_sends each event as a buffered message, so a slow or dead subscriber can never wedge the source. The event vocabulary is hardware-neutral:

• power_button — the button was pressed (a fixed ACPI event on x86).
• lid, ac, battery — the named GPE-driven events.
• notify — a device notification that maps to none of the above; its code (the ACPI Notify argument) and the notifying device's hid say which device and what happened.

An EventMessage carries the event tag plus code and an 8-byte hid, so a generic notify is fully described without a second round trip.

shutdown is authority, not information. It is the only operation that does something irreversible, so it is gated: the contract is that only init (PID 1) may request it, because init is the process that has already run the stop sequence over everything else. The acpi service implements this as a soft gate — it honors shutdown only from a process that is a subscriber, and init is the one subscriber. That stands in for "only the system supervisor may power off" without hard-coding a pid, so it still holds under tests where PID 1 is not init.

Orderly shutdown

Powering off cleanly is where the power service, the process lifecycle, and ACPI events compose. init already supervises the services it starts; for shutdown it runs one event loop over one endpoint that carries three things at once: its children's exit notifications, the lifecycle signals it can receive (terminate), and the power events it subscribes to — plus a re-arming heartbeat timer proving PID 1 is alive. (init subscribes with retries, because the power service registers .power well after init starts; a missing power service is not fatal — a terminate signal drives the same path.)

On a power_button event or a terminate signal, init:

1. logs that it is shutting down,
2. runs the standard stop sequence — process.stop(child, deadline, endpoint) — over its children in reverse spawn order, so the VFS stops last (other services may flush through it), each child getting the terminate → deadline → kill escalation from process-lifecycle.md, and
3. requests .power shutdown.

The service then enters S5 (soft off) by writing SLP_TYP | SLP_EN to the PM1 control register(s) from ring 3, with the SLP_TYP values taken from its own AML parse of the _S5 object — the kernel has no S5 path of its own. If the write returns instead of powering the machine off, it logs loudly so a test fails rather than hangs.

No new system call was needed for S5. The broad io_port grant on the acpi-tables node (discovery.md) already put the PM1 control ports in the acpi service's hands, so writing S5 from ring 3 is something it could physically already do; formalizing it as a protocol operation added a contract, not authority. The kernel keeps only reboot (acpi.reboot in system/kernel/acpi.zig — the FADT reset register plus the legacy fallbacks, which need no AML); it has no poweroff path at all — S5 is not a kernel operation.

Verifying it

Two QEMU scenarios exercise the path, both injecting a real ACPI power-button press via QMP system_powerdown (there is no other deterministic power event on this config):

• power-button proves the source: the acpi service's SCI handler logs the press and publishes power_button (the ACPI half is in acpi.md).
• orderly-shutdown proves the whole composition: button → init logs shutting down → children stopped → the service enters S5 → QEMU exits. The ordered regex is the proof, and QEMU's self-exit through S5 is the pass.

Scope

Interface-complete but validated on real hardware (the author's laptop) later, because QEMU does not emulate them: battery _BST/_BIF evaluation beyond the interface stubs, lid and AC events, and the embedded controller's _Qxx queries. Deliberately out of scope for now: reboot over the power protocol, S3 sleep, per-device D-states (a future lifecycle-vocabulary extension, since "suspend" has the shape of a signal every driver must answer and has no consumer until laptop sleep), and thermal zones.

See also

• acpi.md — where the events come from on x86: the SCI, the power button fixed event, and GPE/Notify dispatch in the acpi service.
• discovery.md — why the surface is domain-named, and the firmware neutrality that makes a PSCI backend drop-in on ARM.
• process-lifecycle.md — the stop sequence (terminate → deadline → kill) and signals init composes into shutdown.
• device-manager.md — the supervision model init mirrors for its own children.