re-org docs

docs/os-development-guide/power.md

@@ -0,0 +1,130 @@
+# 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](../device-driver-development-guide/input.md), 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](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](discovery.md) 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](../../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_send`s 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](process-lifecycle.md), and [ACPI events](acpi.md) 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](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](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](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](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](discovery.md) — why the surface is domain-named, and the
+  firmware neutrality that makes a PSCI backend drop-in on ARM.
+- [process-lifecycle.md](process-lifecycle.md) — the stop sequence
+  (`terminate → deadline → kill`) and signals init composes into shutdown.
+- [device-manager.md](../device-driver-development-guide/device-manager.md) — the supervision model init mirrors for
+  its own children.