Orderly shutdown: init's stop cascade into ring-3 S5 (M21.3)

The capstone. init becomes a real supervisor: it spawns its boot
services supervised against one endpoint that also carries its signals, a
re-arming heartbeat timer, and the power events it subscribes to. On the
power button (or a terminate signal — same path) it logs the shutdown,
runs the M17 stop sequence over its children in reverse spawn order
(vfs last), then asks the power service for S5.

The acpi service honors a shutdown request from a power subscriber — init
is the one subscriber, a soft gate that stands in for 'only the system
supervisor may power off' and, unlike a PID-1 check, survives the test
harness where the kernel's idle tasks take the early ids. The power
service is mechanism (write S5); deciding when to shut down and stopping
everything else first is init's policy — the microkernel split applied to
poweroff.

The orderly-shutdown scenario injects a real QMP power-button event and
watches the whole chain compose: button pressed -> init shutting down ->
entering S5 -> QEMU powers off. That single scenario proves the M17
lifecycle and the M21 event side compose into a clean shutdown. Suite
60/60.

docs/m21-plan.md

@@ -92,14 +92,15 @@ auto-merge to main when the branch is green; keep the branch; push everything.
       Host unit test with hand-encoded AML proves the queue; aml.zig joined the
       `zig build test` loop. QEMU raises no GPEs — suite is regression net,
       59/59).
-- [ ] **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.
+- [x] **M21.3** — orderly shutdown (init supervises its children on one
+      endpoint that also carries signals, power events, and a re-arming
+      heartbeat timer; on `power_button` or a `terminate` signal it logs
+      `init: shutting down`, runs `stop(child, 2000, endpoint)` in reverse
+      order, then requests `.power` shutdown; the acpi service honors shutdown
+      from a subscriber — init is the one subscriber, a soft gate that survives
+      testing where PID 1 isn't init — and writes SLP_TYP|SLP_EN from ring 3.
+      `orderly-shutdown` scenario proves button → shutting-down → S5 → QEMU
+      exit; suite 60/60).
 - [ ] **merge** `feat/power-events` → main, push, keep the branch — **loop
       ends here**.
 

system/kernel/tests.zig

@@ -154,6 +154,8 @@ pub fn run(case: []const u8, boot_information: *const BootInformation) void {
         acpiReportTest(boot_information); // same spawn; the harness regex differs
     } else if (eql(case, "power-button")) {
         acpiReportTest(boot_information); // boot the manager (spawns the acpi service); harness injects the button
+    } else if (eql(case, "orderly-shutdown")) {
+        orderlyShutdownTest(boot_information);
     } else if (eql(case, "initial-ramdisk")) {
         initialRamdiskTest(boot_information);
     } else if (eql(case, "vfs")) {
@@ -1926,6 +1928,27 @@ fn pciScanTest(boot_information: *const BootInformation) void {
     result();
 }
 
+/// M21.3 capstone: orderly shutdown. Boot init with the initial-ramdisk
+/// published, so init spawns the full service tree (vfs, input, device-manager
+/// -> discovery/acpi); the harness injects a real power-button event via QMP;
+/// the acpi service publishes it; init runs the stop sequence over its children
+/// and asks the power service for S5; the machine powers off (QEMU exits). The
+/// kernel test only spawns init — the ordered chain is the harness assertion.
+fn orderlyShutdownTest(boot_information: *const BootInformation) void {
+    log("DANOS-TEST-BEGIN: orderly-shutdown\n", .{});
+    if (boot_information.init_len == 0 or boot_information.initial_ramdisk_len == 0) {
+        check("bootloader handed over init and the initial_ramdisk", false);
+        result();
+        return;
+    }
+    const ramdisk = @as([*]const u8, @ptrFromInt(boot_handoff.physicalToVirtual(boot_information.initial_ramdisk_base)))[0..boot_information.initial_ramdisk_len];
+    process.setInitialRamdisk(ramdisk);
+    const image = @as([*]const u8, @ptrFromInt(boot_handoff.physicalToVirtual(boot_information.init_base)))[0..boot_information.init_len];
+    const spawned = if (process.spawnProcess(image, 4, &.{"/system/services/init"})) true else |_| false;
+    check("init spawned as PID root of user space", spawned);
+    result();
+}
+
 /// M20.2: the acpi service registers + reports its _HID devices. Boot normally
 /// (the manager spawns discovery); the harness's expect regex requires the two
 /// PS/2 nodes among the service's report lines, each with its _CRS resources —

system/services/acpi/acpi.zig

@@ -59,9 +59,14 @@ const sci_en_bit: u32 = 1 << 0;
 const slp_en: u32 = 1 << 13;
 
 // The `.power` subscribers: endpoints handed over as capabilities, each
-// receiving events as buffered messages. Dropped on a failed send.
+// receiving events as buffered messages. Dropped on a failed send. The
+// subscriber's task id is kept too — a shutdown request is honored only from a
+// subscriber (init subscribes; a stray process does not), the soft gate that
+// stands in for "only the system supervisor may power off" without hardcoding
+// a pid the kernel's idle tasks would have taken.
 const maximum_subscribers = 8;
 var subscribers: [maximum_subscribers]?runtime.ipc.Handle = .{null} ** maximum_subscribers;
+var subscriber_tasks: [maximum_subscribers]u32 = .{0} ** maximum_subscribers;
 
 // Pass-1 registration record (see main): what pass 2 reports.
 const Registered = struct { hid: [8]u8 = .{0} ** 8, hid_len: usize = 0, device_id: u64 = 0, resource_count: u64 = 0 };
@@ -390,6 +395,13 @@ fn publishEvent(bytes: []const u8) void {
     }
 }
 
+fn isSubscriber(task: u32) bool {
+    for (&subscribers, 0..) |*slot, si| {
+        if (slot.* != null and subscriber_tasks[si] == task) return true;
+    }
+    return false;
+}
+
 /// Enter S5 (soft off): write SLP_TYP|SLP_EN to the PM1 control register(s).
 /// Mirrors the kernel's power.zig sleepValue. Only reached from a PID-1
 /// shutdown request (M21.3).
@@ -423,9 +435,10 @@ fn onMessage(message: []const u8, reply: []u8, sender: u32, capability: ?runtime
         @intFromEnum(power.Operation.subscribe) => {
             var status: i32 = -1;
             if (capability) |handle| {
-                for (&subscribers) |*slot| {
+                for (&subscribers, 0..) |*slot, si| {
                     if (slot.* == null) {
                         slot.* = handle;
+                        subscriber_tasks[si] = sender;
                         status = 0;
                         break;
                     }
@@ -436,11 +449,14 @@ fn onMessage(message: []const u8, reply: []u8, sender: u32, capability: ?runtime
             return @sizeOf(power.Reply);
         },
         @intFromEnum(power.Operation.shutdown) => {
-            // Only PID 1 (init), which has already stopped everything else.
-            const status: i32 = if (sender == 1) 0 else -1;
-            const r = power.Reply{ .status = status };
+            // Honored only from a power subscriber — init, which has already run
+            // the stop sequence over everything else. The power service is
+            // mechanism (write S5); deciding *when* to shut down and stopping
+            // the rest of the system first is init's policy.
+            const allowed = isSubscriber(sender);
+            const r = power.Reply{ .status = if (allowed) 0 else -1 };
             @memcpy(reply[0..@sizeOf(power.Reply)], std.mem.asBytes(&r));
-            if (sender == 1) enterS5();
+            if (allowed) enterS5();
             return @sizeOf(power.Reply);
         },
         else => return 0,

system/services/init/init.zig

@@ -6,12 +6,20 @@
 //!
 //! It proves the C-convention heap works, then — as PID 1 — acts as the system's
 //! **service supervisor**: it spawns the user-space services danos brings up at boot
-//! (the VFS server, the device manager), and settles into a heartbeat so it stays
-//! alive as the root of user space. Drivers are *not* its job: the device manager
-//! discovers the hardware and spawns those. This is the service half of the
-//! service/driver spawn split (docs/driver-model.md).
+//! (the VFS server, the device manager), and settles into an event loop as the root
+//! of user space. Drivers are *not* its job: the device manager discovers the
+//! hardware and spawns those. This is the service half of the service/driver spawn
+//! split (docs/driver-model.md).
+//!
+//! M21: init also owns **orderly shutdown**. It supervises its children (keeping
+//! their ids and an exit endpoint), subscribes to the power service, and on a
+//! power-button event runs the stop sequence over its children in reverse order
+//! before asking the power service to enter S5 — lifecycle (M17) and events (M21)
+//! composing into a clean poweroff.
 
+const std = @import("std");
 const runtime = @import("runtime");
+const power = runtime.power_protocol;
 
 /// The system services init brings up at boot, in order. This is init's policy — the
 /// microkernel keeps such choices in user space, not the kernel. Drivers are absent
@@ -19,6 +27,10 @@ const runtime = @import("runtime");
 /// manifest under /system/services instead of a hardcoded list.)
 const boot_services = [_][]const u8{ "vfs", "input", "device-manager" };
 
+var children: [boot_services.len]u32 = .{0} ** boot_services.len;
+var child_count: usize = 0;
+var supervision_endpoint: runtime.ipc.Handle = 0;
+
 pub fn main() void {
     // Prove the heap end to end: allocate through the runtime allocator (which
     // mmaps pages from the kernel and carves them with the free list), write into
@@ -34,19 +46,94 @@ pub fn main() void {
         gpa.free(buffer);
     } else |_| {}
 
-    // Bring up the boot services. Best-effort and silent: each service announces its
-    // own readiness (`vfs: ready`, ...), and in an isolation test that runs init with
-    // no initial-ramdisk the spawns simply no-op rather than deranging the heartbeat.
+    // One endpoint carries everything init waits on: children's exit
+    // notifications (they are spawned supervised against it), init's own
+    // signals, and power events it subscribes to. All arrive in the loop below.
+    supervision_endpoint = runtime.ipc.createIpcEndpoint() orelse {
+        _ = runtime.system.write("init: no endpoint\n");
+        return;
+    };
+    _ = runtime.process.bindSignals(supervision_endpoint);
+
+    // Bring up the boot services, supervised so init can stop them cleanly.
+    // Best-effort and silent: each service announces its own readiness, and in
+    // an isolation test with no initial-ramdisk the spawns simply no-op.
     for (boot_services) |service| {
-        _ = runtime.system.spawn(service);
+        if (runtime.system.spawnSupervised(service, &.{}, supervision_endpoint)) |id| {
+            children[child_count] = id;
+            child_count += 1;
+        }
     }
 
+    // Subscribe to power events (retry: the power service registers well after
+    // init starts). Best-effort — without it, a `terminate` signal still
+    // triggers the same shutdown path.
+    subscribePower();
+
+    // A re-arming timer drives the liveness heartbeat: proof PID 1 is alive
+    // (the init test's marker) while the loop stays free to receive signals,
+    // power events, and children's exit notifications.
+    _ = runtime.system.timerOnce(supervision_endpoint, 1000);
+
+    var receive: [power.message_maximum]u8 = undefined;
     while (true) {
-        _ = runtime.system.write("init: heartbeat\n");
-        runtime.system.sleep(1000);
+        const got = runtime.ipc.replyWait(supervision_endpoint, &.{}, &receive, null);
+        if (runtime.process.signalsFrom(got.badge)) |signals| {
+            if (signals.has(.terminate)) shutDown();
+            continue;
+        }
+        if (got.isTimer()) {
+            _ = runtime.system.write("init: heartbeat\n");
+            _ = runtime.system.timerOnce(supervision_endpoint, 1000);
+            continue;
+        }
+        if (got.isMessage() and got.len >= 2 and receive[0] == @intFromEnum(power.Operation.event)) {
+            // A power event (the only buffered messages init receives).
+            if (receive[1] == @intFromEnum(power.Event.power_button)) shutDown();
+            continue;
+        }
+        // Child-exit notifications and anything else: keep waiting.
+        if (got.isNotification()) continue;
     }
 }
 
+/// Look up the power service and subscribe our endpoint (handed over as the
+/// call's capability) so events arrive as buffered messages here.
+fn subscribePower() void {
+    var handle: ?runtime.ipc.Handle = null;
+    var tries: u32 = 0;
+    while (handle == null and tries < 200) : (tries += 1) {
+        handle = runtime.ipc.lookup(.power);
+        if (handle == null) runtime.system.sleep(20);
+    }
+    // A missing power service is not fatal — init proceeds to its heartbeat and
+    // a `terminate` signal still drives shutdown. Silent so the no-ramdisk init
+    // test's heartbeat marker is the next line written.
+    const h = handle orelse return;
+    const request = power.Subscribe{};
+    var reply: [power.message_maximum]u8 = undefined;
+    _ = runtime.ipc.callCap(h, std.mem.asBytes(&request), &reply, supervision_endpoint) catch {};
+}
+
+/// The stop sequence: terminate each child in reverse spawn order (vfs last —
+/// other services may flush through it), waiting up to a deadline for each to
+/// exit before killing it, then ask the power service to enter S5.
+fn shutDown() void {
+    _ = runtime.system.write("init: shutting down\n");
+    var i = child_count;
+    while (i > 0) {
+        i -= 1;
+        if (children[i] != 0) runtime.process.stop(children[i], 2000, supervision_endpoint);
+    }
+    if (runtime.ipc.lookup(.power)) |h| {
+        const request = power.Shutdown{};
+        var reply: [power.message_maximum]u8 = undefined;
+        _ = runtime.ipc.call(h, std.mem.asBytes(&request), &reply) catch {};
+    }
+    // If S5 did not take, init has nothing left to do but idle.
+    while (true) runtime.system.sleep(1000);
+}
+
 pub const panic = runtime.panic;
 comptime {
     _ = &runtime.start._start; // pull the runtime entry shim into the image

test/qemu_test.py

@@ -301,6 +301,19 @@ CASES = [
      "qmp_after": {"delay": 4, "command": "system_powerdown"},
      "expect": r"power: button pressed",
      "fail":   r"DANOS-TEST-RESULT: FAIL"},
+    # M21.3 capstone: orderly shutdown. Boot init (the full tree comes up);
+    # ~5s in, QMP system_powerdown raises the power button; the acpi service
+    # publishes it, init stops its children then requests S5, and QEMU exits.
+    # The ordered regex proves button -> shutting-down -> entering-S5; the case
+    # passes on QEMU's self-exit through S5 (docs/m21-plan.md).
+    {"name": "orderly-shutdown",
+     "smp":    4,
+     "timeout": 90,
+     "qmp_after": {"delay": 5, "command": "system_powerdown"},
+     "expect": r"power: button pressed[\s\S]*"
+               r"init: shutting down[\s\S]*"
+               r"power: entering S5",
+     "fail":   r"power: S5 write did not take|DANOS-TEST-RESULT: FAIL"},
     # M20.2: the acpi service evaluates _CRS/_STA in ring 3 and registers +
     # reports its _HID devices — the two PS/2 nodes must appear with resources
     # (keyboard: io 0x60/0x64 + IRQ = 3; mouse: IRQ = 1) (docs/m19-m20-plan.md).