display-demo: stop drawing a cursor and stop blocking on the mouse

Two real bugs visible in a normal `zig build run-x86-64` boot (but not in the
display-demo test, which spawns no input service):

  - Two cursors. The demo drew its own cursor layer while the display service
    now draws one too (its mouse-listener thread). The demo's went through the
    client IPC protocol and lagged; the service's is in-process and tracks
    tightly — "one responds better than the other."

  - Animation frozen until the mouse moves. The demo called a *blocking*
    `mouse.next()` (ipc_reply_wait) inside its animation loop, so the sliding
    box advanced only one frame per mouse event. In the display-demo test
    there is no input service, so subscribeMouse() returned null and the loop
    ran free on its 30ms timer — which is exactly why the test passed while
    the real boot was broken.

The compositor now owns the cursor (docs/display.md), so the demo should draw
none and read no input: it becomes a pure client-animation proof whose loop is
independent of the mouse. Removes its cursor layer, mouse subscription, and the
blocking read.

Also harden displayDemoTest to spawn the `input` service alongside the demo
(matching real boot): a client that blocks its animation loop on a mouse read
would now stall before `display-demo: ok` and fail the test, instead of
passing because no input service happened to be present.

Verified: display / display-service / display-demo / display-cursor all green.

.editorconfig

@@ -0,0 +1,16 @@
+# EditorConfig: https://editorconfig.org/
+# Follows the Zig style guide: https://ziglang.org/documentation/0.16.0/#Style-Guide
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.zig]
+# "Line length: aim for 100; use common sense."
+max_line_length = 100

.gitattributes

@@ -0,0 +1 @@
+*.zig text eol=lf

.zig-version

@@ -1 +0,0 @@
-0.16.0

README.md

@@ -1,13 +1,32 @@
 # DanOS
-Codename: Shodan
-Version: 1
 
-A small operating system, written from scratch in Zig — a bootloader (`boot/`)
-and a microkernel (`system/kernel/`), sharing a neutral handoff contract (`system/boot-handoff.zig`).
-It boots x86-64 via UEFI, and so far has a framebuffer console, a physical frame
-allocator, its own paging with W^X permissions, interrupt/exception handling, a
-LAPIC timer, a kernel heap, a fixed-priority preemptive scheduler, and in-kernel IPC
-channels. See [`docs/`](docs/README.md) for how each piece works.
+**Codename: Shodan**
+
+A very small resilient operating system.
+
+## Zen of DanOS:
+
+- Resilient Micro-Kernel Architecture.
+    - Every process run in an isolated user space not kernel space.
+    - Processes cannot take down the entire OS with it when they die or is killed
+- Stable public runtime library, private OS ABI.
+    - Keeps a stable runtime for user space processes between OS versions (great for backwards compatibility)
+    - Allows the underlying OS to be changed without effecting applications
+    - Provides a boundary to enable compatibility between OS's e.g. POSIX, MUSL etc
+- Drivers are just isolated processes in user space.
+    - Thin binaries that can be restarted like applications.
+    - Useful during driver development.
+    - Drivers can claim MMIO / ports
+    - Driver resources (e.g. IRQ/Port/MMIO) claims are automatically cleaned up if the driver dies or is killed
+    - Drivers can also hook into the process lifecycle to clean up or reset hardware
+- No legacy to deal with
+    - Zig code uses a clean coding style (Zen of Zig)
+    - Favor reading code over writing code.
+    - No magic numbers.
+    - No shortened names unless its for ABI compatibility or acronyms
+- Inter-Process Communication (IPC)
+  - Publish and subscribe to Asynchronous Messages
+  - Talk to services and processes synchronously
 
 ## Prerequisites
 
@@ -35,6 +54,17 @@ the UEFI bootloader at `zig-out/EFI/BOOT/BOOTX64.efi`, the kernel at
 `zig-out/system/kernel`, init at `zig-out/system/services/init`, drivers under
 `zig-out/system/drivers/`, and the initial-ramdisk at `zig-out/boot/`.
 
+## Release media
+
+```sh
+zig build release-x86-64
+```
+
+Produces `zig-out/danos-x86-64.iso`, a hybrid ISO that boots flashed raw to a
+USB stick (balenaEtcher, dd) or burned to optical media — see
+[docs/release-iso.md](docs/release-iso.md). `zig build check-iso-image`
+validates it without booting.
+
 ## Run
 
 Boot it in QEMU with OVMF (opens a display window):
@@ -60,9 +90,13 @@ straight into CI.
 
 ## Documentation
 
-Design notes explaining the *why* behind the code live in
+Design notes explaining *why* behind the code live in
 [`docs/`](docs/README.md) — start with [`docs/README.md`](docs/README.md).
 
+For the hardware needed to run DanOS — minimum specs plus a plain-language guide
+matching Intel/AMD CPU generations by name — see
+[`docs/system-requirements.md`](docs/system-requirements.md).
+
 ## Logo
 
 San Serif Text "Dan OS" with a black karate belt around it.

boot/efi.zig

@@ -2,6 +2,7 @@ const std = @import("std");
 const uefi = std.os.uefi;
 const elf = std.elf;
 const boot_handoff = @import("boot-handoff");
+const build_options = @import("build_options");
 const BootInformation = boot_handoff.BootInformation;
 const GraphicsOutput = uefi.protocol.GraphicsOutput;
 const EdidActive = uefi.protocol.edid.Active;
@@ -29,7 +30,7 @@ pub fn main() uefi.Status {
     // report the reason (boot services are still up) and park the machine so the
     // message stays on screen.
     boot() catch |err| {
-        log("\r\ndanos: boot failed: ");
+        log("\r\nEFI: boot failed: ");
         logBytes(@errorName(err));
         log("\r\n");
         while (true) asm volatile ("hlt");
@@ -65,14 +66,14 @@ fn boot() !noreturn {
 
     // Best effort: a volume without /system/services/init still boots (kernel-only).
     loadInit(bs, &boot_information) catch |err| {
-        log("danos: no /system/services/init (");
+        log("EFI: no /system/services/init (");
         logBytes(@errorName(err));
         log(") - booting without user space\r\n");
     };
 
     // Best effort: the initial_ramdisk (VFS server + drivers) is optional too.
     loadInitialRamdisk(bs, &boot_information) catch |err| {
-        log("danos: no initial_ramdisk (");
+        log("EFI: no initial_ramdisk (");
         logBytes(@errorName(err));
         log(")\r\n");
     };
@@ -84,7 +85,7 @@ fn boot() !noreturn {
     // the map and exiting would invalidate the map key.
     const cr3 = try buildBootstrapTables(bs, &boot_information);
 
-    log("danos: kernel loaded, exiting boot services\r\n");
+    progress("EFI: kernel loaded, exiting boot services\r\n");
     boot_information.memory_map = try exitBootServices(bs);
 
     // Switch onto our tables and jump to the kernel in one uninterruptible step.
@@ -395,7 +396,7 @@ fn loadInit(bs: *uefi.tables.BootServices, boot_information: *BootInformation) !
     const image = try loadFile(bs, init_file_name);
     boot_information.init_base = @intFromPtr(image.ptr);
     boot_information.init_len = image.len;
-    log("danos: /system/services/init loaded\r\n");
+    progress("EFI: /system/services/init loaded\r\n");
 }
 
 /// Ferry the initial_ramdisk (the VFS server + drivers) to the kernel, same as init.
@@ -403,7 +404,7 @@ fn loadInitialRamdisk(bs: *uefi.tables.BootServices, boot_information: *BootInfo
     const image = try loadFile(bs, initial_ramdisk_file_name);
     boot_information.initial_ramdisk_base = @intFromPtr(image.ptr);
     boot_information.initial_ramdisk_len = image.len;
-    log("danos: initial_ramdisk loaded\r\n");
+    progress("EFI: initial_ramdisk loaded\r\n");
 }
 
 /// Validate the ELF, copy every PT_LOAD segment to its physical address, and
@@ -561,6 +562,14 @@ fn log(comptime message: []const u8) void {
     _ = out.outputString(std.unicode.utf8ToUtf16LeStringLiteral(message)) catch {};
 }
 
+/// A boot-progress breadcrumb: like `log`, but compiled out unless `-Dserial`
+/// (off by default), so a real-hardware boot stays silent. Fatal errors use
+/// `log` directly and always show, so a failed boot still explains itself.
+fn progress(comptime message: []const u8) void {
+    if (!build_options.serial) return;
+    log(message);
+}
+
 /// Write a runtime ASCII byte string (e.g. an @errorName) by widening to UTF-16.
 fn logBytes(bytes: []const u8) void {
     const out = uefi.system_table.con_out orelse return;

build.zig

@@ -54,33 +54,82 @@ fn timestamp(b: *std.Build) []const u8 {
 /// can't reach), linked against the `runtime` runtime library with the shared user
 /// link script. Pinned to LLVM + LLD so the script's PHDRS (segment permissions)
 /// are authoritative — the kernel's W^X user-ELF loader requires exact perms.
+///
+/// The compilation root is not the program's own file but the shared shim
+/// library/runtime/root.zig, which supplies the root declarations (`main`
+/// re-export, panic handler, `_start` pull) so a program only defines
+/// `pub fn main`. The program's file becomes the `program` module the shim
+/// imports; reach it through `programModule` to add per-binary imports.
 fn addUserBinary(
     b: *std.Build,
     target: std.Build.ResolvedTarget,
     runtime_module: *std.Build.Module,
-    posix_module: *std.Build.Module,
     mmio_module: *std.Build.Module,
+    xkeyboard_config_module: *std.Build.Module,
+    acpi_ids_module: *std.Build.Module,
     name: []const u8,
     root: []const u8,
 ) *std.Build.Step.Compile {
+    return addUserBinaryImpl(b, target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, name, root, false);
+}
+
+/// As `addUserBinary`, but built multi-threaded (`single_threaded = false`) so real
+/// atomics/TLS work — required before a binary may call `runtime.Thread.spawn`
+/// (docs/threading.md). Threads are a deliberate per-binary opt-in.
+fn addThreadedUserBinary(
+    b: *std.Build,
+    target: std.Build.ResolvedTarget,
+    runtime_module: *std.Build.Module,
+    mmio_module: *std.Build.Module,
+    xkeyboard_config_module: *std.Build.Module,
+    acpi_ids_module: *std.Build.Module,
+    name: []const u8,
+    root: []const u8,
+) *std.Build.Step.Compile {
+    return addUserBinaryImpl(b, target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, name, root, true);
+}
+
+fn addUserBinaryImpl(
+    b: *std.Build,
+    target: std.Build.ResolvedTarget,
+    runtime_module: *std.Build.Module,
+    mmio_module: *std.Build.Module,
+    xkeyboard_config_module: *std.Build.Module,
+    acpi_ids_module: *std.Build.Module,
+    name: []const u8,
+    root: []const u8,
+    threaded: bool,
+) *std.Build.Step.Compile {
+    // Settings (target, optimize, code model, ...) live on the root module only;
+    // the program and runtime modules leave theirs null and inherit them.
+    const program_module = b.createModule(.{
+        .root_source_file = b.path(root),
+        .imports = &.{
+            .{ .name = "runtime", .module = runtime_module },
+            // Typed volatile MMIO + memory barriers, for drivers. See library/mmio/.
+            .{ .name = "mmio", .module = mmio_module },
+            // Keyboard layouts (keycode + modifiers -> keysym/character), available
+            // to any program that wants it. See library/xkeyboard-config/.
+            .{ .name = "xkeyboard-config", .module = xkeyboard_config_module },
+            // ACPI/PnP hardware-ID registry, so drivers name devices
+            // (HardwareId.ps2_keyboard) instead of magic "_HID" strings.
+            .{ .name = "acpi-ids", .module = acpi_ids_module },
+        },
+    });
     const exe = b.addExecutable(.{
         .name = name,
         .root_module = b.createModule(.{
-            .root_source_file = b.path(root),
+            .root_source_file = b.path("library/runtime/root.zig"),
             .target = target,
             .optimize = .ReleaseSmall,
             .code_model = .large,
-            .single_threaded = true,
+            .single_threaded = !threaded, // a threaded binary needs real atomics/TLS
             .sanitize_c = .off,
             .stack_check = false,
             .stack_protector = false,
             .imports = &.{
                 .{ .name = "runtime", .module = runtime_module },
-                // POSIX/C compatibility layer, available to any program that wants it
-                // (danos-native code uses `runtime` directly). See library/posix/.
-                .{ .name = "posix", .module = posix_module },
-                // Typed volatile MMIO + memory barriers, for drivers. See library/mmio/.
-                .{ .name = "mmio", .module = mmio_module },
+                .{ .name = "program", .module = program_module },
             },
         }),
     });
@@ -92,6 +141,114 @@ fn addUserBinary(
     return exe;
 }
 
+/// The `program` module of a binary built by `addUserBinary` — the module rooted
+/// at the program's own source file. Per-binary imports (protocol modules, bus
+/// ABIs) go here, not on the root shim: module imports are not transitive, so an
+/// import added to the root would be invisible to the program's code.
+fn programModule(exe: *std.Build.Step.Compile) *std.Build.Module {
+    return exe.root_module.import_table.get("program").?;
+}
+
+/// The modules the kernel imports, gathered once so both kernel variants (the
+/// installed one and the serial-enabled one `run-x86-64` boots) are built from
+/// the same set. `build_options` is *not* here — it carries `serial`/`test_case`,
+/// which differ per variant, so `addKernel` builds it fresh each time.
+const KernelModules = struct {
+    boot_handoff: *std.Build.Module,
+    abi: *std.Build.Module,
+    device_abi: *std.Build.Module,
+    architecture: *std.Build.Module,
+    platform: *std.Build.Module,
+    parameters: *std.Build.Module,
+    initial_ramdisk: *std.Build.Module,
+};
+
+/// Build the freestanding x86_64 kernel ELF. Factored so we can build it twice
+/// from one recipe: the installed/flashable image (serial off by default) and the
+/// serial-enabled variant `run-x86-64` boots — they differ only in the `serial`
+/// build option baked into `build_options`.
+fn addKernel(
+    b: *std.Build,
+    kernel_target: std.Build.ResolvedTarget,
+    optimize: std.builtin.OptimizeMode,
+    modules: KernelModules,
+    test_case: ?[]const u8,
+    serial: bool,
+) *std.Build.Step.Compile {
+    // Compile-time configuration the kernel reads as `@import("build_options")`:
+    // the QEMU harness's -Dtest-case, and whether the serial log sink is compiled
+    // in (see the -Dserial option). Built per variant since `serial` differs.
+    const build_options = b.addOptions();
+    build_options.addOption(?[]const u8, "test_case", test_case);
+    build_options.addOption(bool, "serial", serial);
+    const build_options_module = build_options.createModule();
+
+    const exe = b.addExecutable(.{
+        .name = "kernel",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("system/kernel/kernel.zig"),
+            .target = kernel_target,
+            .optimize = optimize,
+            .code_model = .kernel, // kernel runs in the top 2 GiB (higher half)
+            .red_zone = false, // interrupts would corrupt the SystemV red zone
+            .single_threaded = false, // SMP: the big kernel lock's atomics must be real across cores
+            .sanitize_c = .off, // the UBSan runtime needs f128/SSE support we don't provide
+            .stack_check = false, // stack-probe calls have no runtime to land in
+            .stack_protector = false,
+            .imports = &.{
+                .{ .name = "boot-handoff", .module = modules.boot_handoff },
+                .{ .name = "abi", .module = modules.abi },
+                .{ .name = "device-abi", .module = modules.device_abi },
+                .{ .name = "architecture", .module = modules.architecture },
+                .{ .name = "platform", .module = modules.platform },
+                .{ .name = "parameters", .module = modules.parameters },
+                .{ .name = "build_options", .module = build_options_module },
+                .{ .name = "initial-ramdisk", .module = modules.initial_ramdisk },
+            },
+        }),
+    });
+    exe.setLinkerScript(b.path("system/kernel/architecture/x86_64/linker.ld"));
+    exe.entry = .{ .symbol_name = "_start" };
+    // The self-hosted linker ignores parts of the linker script (PHDRS,
+    // /DISCARD/, AT(), section order); the higher-half layout depends on the
+    // script being authoritative, so pin the kernel to LLVM + LLD.
+    exe.use_llvm = true;
+    exe.use_lld = true;
+    // Higher-half virtual base (matches KERNEL_VIRT_BASE in linker.ld); the
+    // linker's AT() clauses give each segment a low physical load address
+    // (.text at 1 MiB), which the loader allocates and copies into.
+    exe.image_base = 0xFFFFFFFF80100000;
+    return exe;
+}
+
+/// Assemble the bootable FAT32 image (the in-repo Python builder) holding what
+/// the firmware and loader need off the ESP: the EFI stub, `kernel`, `init`, and
+/// the initial-ramdisk. Factored so the serial-enabled `run-x86-64` variant can
+/// bundle its own serial kernel while sharing the loader, init, and ramdisk — all
+/// built once per invocation (the loader's boot breadcrumbs and init's heartbeat
+/// both follow the top-level -Dserial). Returns the image's LazyPath.
+fn addBootImage(
+    b: *std.Build,
+    kernel_bin: std.Build.LazyPath,
+    efi_bin: std.Build.LazyPath,
+    init_bin: std.Build.LazyPath,
+    initial_ramdisk_img: std.Build.LazyPath,
+) std.Build.LazyPath {
+    const mk_fat = b.addSystemCommand(&.{"python3"});
+    mk_fat.addFileArg(b.path("tools/make-fat-image.py"));
+    const fat_image = mk_fat.addOutputFileArg("danos-usb.img");
+    mk_fat.addArg("64"); // MiB
+    mk_fat.addArg("EFI/BOOT/BOOTX64.efi");
+    mk_fat.addFileArg(efi_bin);
+    mk_fat.addArg("system/kernel");
+    mk_fat.addFileArg(kernel_bin);
+    mk_fat.addArg("system/services/init");
+    mk_fat.addFileArg(init_bin);
+    mk_fat.addArg("boot/initial-ramdisk.img");
+    mk_fat.addFileArg(initial_ramdisk_img);
+    return fat_image;
+}
+
 pub fn build(b: *std.Build) void {
     ensureZigVersion();
 
@@ -123,10 +280,39 @@ pub fn build(b: *std.Build) void {
     });
     // ACPI/PnP hardware-ID (_HID) names — the flat analog of pci-class for acpi_device
     // nodes. Also shared reference data.
+    // The AML interpreter, a build module so the ring-3 acpi service can run the
+    // same parser the kernel does (docs/discovery.md — the shared AML module).
+    // Pure Zig, no kernel imports — one source, two builds.
+    const aml_module = b.addModule("aml", .{
+        .root_source_file = b.path("system/devices/aml/aml.zig"),
+    });
+
     const acpi_ids_module = b.addModule("acpi-ids", .{
         .root_source_file = b.path("system/devices/acpi-ids.zig"),
     });
 
+    // The USB device-framework wire ABI (chapter-9 set-up packets, standard +
+    // class requests, descriptors) and the USB class-code taxonomy — the flat
+    // reference the xHCI bus driver, the USB class drivers, and the device
+    // manager's identity matcher all share. Pure data, like pci-class/acpi-ids.
+    const usb_abi_module = b.addModule("usb-abi", .{
+        .root_source_file = b.path("system/devices/usb-abi.zig"),
+    });
+    const usb_ids_module = b.addModule("usb-ids", .{
+        .root_source_file = b.path("system/devices/usb-ids.zig"),
+    });
+    // The USB transfer protocol: what a USB class driver says to the xHCI bus
+    // driver to drive its device (open / control / interrupt / bulk). A protocol
+    // module like vfs-protocol, shared by the bus driver and every class driver.
+    const usb_transfer_protocol_module = b.addModule("usb-transfer-protocol", .{
+        .root_source_file = b.path("system/drivers/usb-xhci-bus/usb-transfer-protocol.zig"),
+    });
+    // The block-device protocol: read/write of fixed-size blocks, spoken between a
+    // filesystem and a block driver (usb-storage). A protocol module like the rest.
+    const block_protocol_module = b.addModule("block-protocol", .{
+        .root_source_file = b.path("system/services/block/protocol.zig"),
+    });
+
     // Kernel tunables (maximum_cpus, stack sizes, tick rate). A dependency-free module of
     // compile-time constants, imported wherever a knob is read; keeps the trade-offs
     // in one place instead of scattered across the tree. See system/parameters.zig.
@@ -178,6 +364,13 @@ pub fn build(b: *std.Build) void {
         .root_source_file = b.path("system/services/vfs/protocol.zig"),
     });
 
+    // The input wire protocol: the input service's public interface, exposed as its own
+    // module the same way vfs-protocol is. Shared by the input service, the runtime's
+    // `input` helper (subscribe/publish), and every source and subscriber.
+    const input_protocol_module = b.addModule("input-protocol", .{
+        .root_source_file = b.path("system/services/input/protocol.zig"),
+    });
+
     // The danos-native user-space runtime: system_call wrappers, the C-convention
     // heap, IPC helpers, the process start shim, device access. This is the stable
     // application ABI; POSIX compatibility is a separate library on top (see below).
@@ -193,9 +386,42 @@ pub fn build(b: *std.Build) void {
             .{ .name = "abi", .module = abi_module },
             .{ .name = "device-abi", .module = device_abi_module },
             .{ .name = "vfs-protocol", .module = vfs_protocol_module },
+            .{ .name = "input-protocol", .module = input_protocol_module },
         },
     });
 
+    // The device-manager protocol: hello + (M18.2) tree reports, exposed as its
+    // own module like the other protocol modules. Imported through the runtime.
+    const device_manager_protocol_module = b.addModule("device-manager-protocol", .{
+        .root_source_file = b.path("system/services/device-manager/device-manager-protocol.zig"),
+    });
+    runtime_module.addImport("device-manager-protocol", device_manager_protocol_module);
+    // The USB transfer protocol, so runtime.usb (the class-driver client) can speak
+    // it, the way runtime.input speaks the input protocol.
+    runtime_module.addImport("usb-transfer-protocol", usb_transfer_protocol_module);
+    // The block protocol, so runtime.block (the block-device client) can speak it.
+    runtime_module.addImport("block-protocol", block_protocol_module);
+
+    // The display protocol, so runtime.display (the compositor client) and the display
+    // service both speak it through the runtime, like the other protocol modules.
+    const display_protocol_module = b.addModule("display-protocol", .{
+        .root_source_file = b.path("system/services/display/protocol.zig"),
+    });
+    runtime_module.addImport("display-protocol", display_protocol_module);
+
+    // The scanout protocol: the compositor's outbound present channel to a native scanout
+    // driver (virtio-gpu), separate from the client-facing display protocol (docs/display-v2.md).
+    const scanout_protocol_module = b.addModule("scanout-protocol", .{
+        .root_source_file = b.path("system/services/display/scanout-protocol.zig"),
+    });
+    runtime_module.addImport("scanout-protocol", scanout_protocol_module);
+
+    // The power protocol: system power's domain-named surface (docs/power.md).
+    const power_protocol_module = b.addModule("power-protocol", .{
+        .root_source_file = b.path("system/services/power/protocol.zig"),
+    });
+    runtime_module.addImport("power-protocol", power_protocol_module);
+
     // Typed volatile MMIO register access + memory-ordering barriers, for drivers on
     // top of an mmio_map grant. Depends only on `builtin` (arch-conditional barriers);
     // no target set, so it inherits each driver's. See library/mmio/mmio.zig.
@@ -203,15 +429,17 @@ pub fn build(b: *std.Build) void {
         .root_source_file = b.path("library/mmio/mmio.zig"),
     });
 
-    // The POSIX / C compatibility layer, a separate library layered strictly over the
-    // runtime (it calls the runtime's IPC/heap, never system calls directly). This is
-    // the one place POSIX/C spellings are allowed verbatim — see docs/coding-standards.md
-    // and library/posix/posix.zig.
-    const posix_module = b.addModule("posix", .{
-        .root_source_file = b.path("library/posix/posix.zig"),
+    // Keyboard layouts compiled from the X11 xkeyboard-config database into native Zig
+    // (keycode + modifiers -> keysym/character). The `layouts` tables are generated by
+    // tools/make-xkeyboard-config.py; `xkeyboard-config` is the hand-written API over them.
+    // No target set, so each inherits its importer's. See library/xkeyboard-config/.
+    const xkb_layouts_module = b.addModule("layouts", .{
+        .root_source_file = b.path("library/xkeyboard-config/generated/layouts.zig"),
+    });
+    const xkeyboard_config_module = b.addModule("xkeyboard-config", .{
+        .root_source_file = b.path("library/xkeyboard-config/xkeyboard-config.zig"),
         .imports = &.{
-            .{ .name = "runtime", .module = runtime_module },
-            .{ .name = "vfs-protocol", .module = vfs_protocol_module },
+            .{ .name = "layouts", .module = xkb_layouts_module },
         },
     });
 
@@ -224,9 +452,12 @@ pub fn build(b: *std.Build) void {
     // Compile-time configuration the kernel reads as `@import("build_options")`. The
     // QEMU test harness sets -Dtest-case=<name> to run one self-test at boot.
     const test_case = b.option([]const u8, "test-case", "Kernel self-test case to run at boot (see system/kernel/tests.zig)");
-    const build_options = b.addOptions();
-    build_options.addOption(?[]const u8, "test_case", test_case);
-    const build_options_module = build_options.createModule();
+    // The serial-console log sink. Off by default: a real machine often has no
+    // working legacy COM1, and the boot log is kept in RAM (klog) and flushed to
+    // disk instead — serial is now only a QEMU convenience. `run-x86-64` and the
+    // QEMU test harness (test/qemu_test.py, which asserts on serial markers) turn
+    // it on; a flashable `zig build` image leaves it out. See serial.zig.
+    const serial = b.option(bool, "serial", "Compile the serial-console log sink into the kernel (default: off; run-x86-64 and the test harness enable it)") orelse false;
 
     // --- Kernel: freestanding x86_64 ELF, jumped to by the bootloader ---
     // SSE2 is part of the x86_64 baseline and UEFI leaves it enabled at handoff,
@@ -238,41 +469,17 @@ pub fn build(b: *std.Build) void {
         .abi = .none,
     });
 
-    const exe = b.addExecutable(.{
-        .name = "kernel",
-        .root_module = b.createModule(.{
-            .root_source_file = b.path("system/kernel/kernel.zig"),
-            .target = kernel_target,
-            .optimize = optimize,
-            .code_model = .kernel, // kernel runs in the top 2 GiB (higher half)
-            .red_zone = false, // interrupts would corrupt the SystemV red zone
-            .single_threaded = false, // SMP: the big kernel lock's atomics must be real across cores
-            .sanitize_c = .off, // the UBSan runtime needs f128/SSE support we don't provide
-            .stack_check = false, // stack-probe calls have no runtime to land in
-            .stack_protector = false,
-            .imports = &.{
-                .{ .name = "boot-handoff", .module = boot_handoff_module },
-                .{ .name = "abi", .module = abi_module },
-                .{ .name = "device-abi", .module = device_abi_module },
-                .{ .name = "architecture", .module = architecture_module },
-                .{ .name = "platform", .module = platform_module },
-                .{ .name = "parameters", .module = parameters_module },
-                .{ .name = "build_options", .module = build_options_module },
-                .{ .name = "initial-ramdisk", .module = initial_ramdisk_module },
-            },
-        }),
-    });
-    exe.setLinkerScript(b.path("system/kernel/architecture/x86_64/linker.ld"));
-    exe.entry = .{ .symbol_name = "_start" };
-    // The self-hosted linker ignores parts of the linker script (PHDRS,
-    // /DISCARD/, AT(), section order); the higher-half layout depends on the
-    // script being authoritative, so pin the kernel to LLVM + LLD.
-    exe.use_llvm = true;
-    exe.use_lld = true;
-    // Higher-half virtual base (matches KERNEL_VIRT_BASE in linker.ld); the
-    // linker's AT() clauses give each segment a low physical load address
-    // (.text at 1 MiB), which the loader allocates and copies into.
-    exe.image_base = 0xFFFFFFFF80100000;
+    const kernel_modules = KernelModules{
+        .boot_handoff = boot_handoff_module,
+        .abi = abi_module,
+        .device_abi = device_abi_module,
+        .architecture = architecture_module,
+        .platform = platform_module,
+        .parameters = parameters_module,
+        .initial_ramdisk = initial_ramdisk_module,
+    };
+    // The installed/flashable kernel: serial follows -Dserial (off by default).
+    const exe = addKernel(b, kernel_target, optimize, kernel_modules, test_case, serial);
 
     // Everything installs into a FHS-shaped zig-out: it IS the danos filesystem *and*
     // the boot volume. Each binary lands at its addressed, leaf-collapsed path — the
@@ -286,7 +493,15 @@ pub fn build(b: *std.Build) void {
     // Built by the shared user-binary recipe (see addUserBinary): freestanding,
     // linked into the kernel's user region against the `runtime` runtime library, and
     // started in ring 3 by the kernel's user-ELF loader.
-    const init_exe = addUserBinary(b, kernel_target, runtime_module, posix_module, mmio_module, "init", "system/services/init/init.zig");
+    const init_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "init", "system/services/init/init.zig");
+    // init reads the same `serial` flag the kernel does: its liveness heartbeat is a
+    // serial/test-build diagnostic (the QEMU harness's init tests assert on it, and
+    // -Dserial images emit it), so a flashable image runs a purely event-driven PID 1
+    // that wakes only for real work. The test harness builds with -Dserial=true, so
+    // the heartbeat stays present under test.
+    const init_options = b.addOptions();
+    init_options.addOption(bool, "serial", serial);
+    programModule(init_exe).addImport("build_options", init_options.createModule());
     const init_install = b.addInstallArtifact(init_exe, .{ .dest_dir = .{ .override = .{ .custom = "system/services" } } });
     b.getInstallStep().dependOn(&init_install.step);
 
@@ -294,12 +509,80 @@ pub fn build(b: *std.Build) void {
     // Each is built by the same user-binary recipe, then packed into one image by
     // the host-side make-initial-ramdisk tool. The bootloader ferries the image to the kernel,
     // which unpacks it and spawns each program (system/initial-ramdisk.zig).
-    const vfs_exe = addUserBinary(b, kernel_target, runtime_module, posix_module, mmio_module, "vfs", "system/services/vfs/vfs.zig");
-    const vfstest_exe = addUserBinary(b, kernel_target, runtime_module, posix_module, mmio_module, "vfs-test", "system/services/vfs/vfs-test.zig");
-    const hpet_exe = addUserBinary(b, kernel_target, runtime_module, posix_module, mmio_module, "hpet", "system/drivers/hpet/hpet.zig");
-    const bus_exe = addUserBinary(b, kernel_target, runtime_module, posix_module, mmio_module, "bus", "system/drivers/bus/bus.zig");
-    const device_manager_exe = addUserBinary(b, kernel_target, runtime_module, posix_module, mmio_module, "device-manager", "system/services/device-manager/device-manager.zig");
-    const args_echo_exe = addUserBinary(b, kernel_target, runtime_module, posix_module, mmio_module, "args-echo", "system/services/args-echo/args-echo.zig");
+    const vfs_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "vfs", "system/services/vfs/vfs.zig");
+    const vfstest_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "vfs-test", "system/services/vfs/vfs-test.zig");
+    const ps2_bus_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "ps2-bus", "system/drivers/ps2-bus/ps2-bus.zig");
+    const ps2_keyboard_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "ps2-keyboard", "system/drivers/ps2-bus/keyboard.zig");
+    const ps2_mouse_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "ps2-mouse", "system/drivers/ps2-bus/mouse.zig");
+    const usb_xhci_bus_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "usb-xhci-bus", "system/drivers/usb-xhci-bus/usb-xhci-bus.zig");
+    // The xHCI bus driver builds chapter-9 requests and decodes descriptors from
+    // usb-abi, and reports each interface's (class,subclass,protocol) identity via
+    // usb-ids.packTriple.
+    programModule(usb_xhci_bus_exe).addImport("usb-abi", usb_abi_module);
+    programModule(usb_xhci_bus_exe).addImport("usb-ids", usb_ids_module);
+    programModule(usb_xhci_bus_exe).addImport("usb-transfer-protocol", usb_transfer_protocol_module);
+    // The USB HID class drivers: keyboard and mouse. They own no hardware — each
+    // opens its device through runtime.usb (the transfer protocol) and publishes to
+    // the input service. They build chapter-9 class requests from usb-abi.
+    const usb_hid_keyboard_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "usb-hid-keyboard", "system/drivers/usb-hid/keyboard.zig");
+    programModule(usb_hid_keyboard_exe).addImport("usb-abi", usb_abi_module);
+    const usb_hid_mouse_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "usb-hid-mouse", "system/drivers/usb-hid/mouse.zig");
+    programModule(usb_hid_mouse_exe).addImport("usb-abi", usb_abi_module);
+    // The USB mass-storage class driver: opens its device via runtime.usb, drives it
+    // with Bulk-Only Transport + SCSI, and serves the block protocol under `.block`.
+    const usb_storage_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "usb-storage", "system/drivers/usb-storage/usb-storage.zig");
+    programModule(usb_storage_exe).addImport("block-protocol", block_protocol_module);
+    // The FAT filesystem server: mounts the block device and serves it into the VFS
+    // at /mnt/usb. Its engine (engine.zig / on-disk.zig) is imported relatively.
+    const fat_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "fat", "system/services/fat/fat.zig");
+    // Threaded: the display runs a mouse-listener thread alongside its compositor loop
+    // (docs/threading.md, docs/display.md), so it opts into real atomics/TLS.
+    const display_exe = addThreadedUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "display", "system/services/display/display.zig");
+    const display_demo_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "display-demo", "system/services/display-demo/display-demo.zig");
+    const virtio_gpu_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "virtio-gpu", "system/drivers/virtio-gpu/virtio-gpu.zig");
+    const shm_server_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "shm-server", "system/services/shm-server/shm-server.zig");
+    const shm_client_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "shm-client", "system/services/shm-client/shm-client.zig");
+    const fat_test_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "fat-test", "system/services/fat/fat-test.zig");
+    const pci_bus_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "pci-bus", "system/drivers/pci-bus/pci-bus.zig");
+    // The PCI bus driver decodes each function's class triple to human names in its
+    // boot log (class/subclass/prog-IF), so pull in the shared pci-class reference.
+    programModule(pci_bus_exe).addImport("pci-class", pci_class_module);
+    // A test fixture, not a real driver: hellos to the device manager, then faults —
+    // what the driver-restart scenario drives the crash-loop cap with.
+    const crash_test_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "crash-test", "system/services/crash-test/crash-test.zig");
+    const device_list_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "device-list", "system/services/device-list/device-list.zig");
+    // The discovery service: one swappable process per firmware
+    // (docs/discovery.md), bundled under the neutral ramdisk name
+    // "discovery" so the device manager never learns which firmware it is on.
+    // x86 boots describe hardware with ACPI; the Raspberry Pis hand over a
+    // flattened device tree — the aarch64 target flips the default when it
+    // lands (docs/arm.md). Both are placeholders until M20.1 (acpi) and the
+    // ARM bring-up (fdt).
+    const Discovery = enum { acpi, fdt };
+    const discovery = b.option(Discovery, "discovery", "Which discovery service fills the ramdisk's 'discovery' slot (default: acpi)") orelse Discovery.acpi;
+    const discovery_source: []const u8 = switch (discovery) {
+        .acpi => "system/services/acpi/acpi.zig",
+        .fdt => "system/services/fdt/fdt.zig",
+    };
+    const discovery_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "discovery", discovery_source);
+    if (discovery == .acpi) programModule(discovery_exe).addImport("aml", aml_module);
+    const device_manager_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "device-manager", "system/services/device-manager/device-manager.zig");
+    // Names the xHCI PCI class triple from the shared taxonomy instead of a bare 0x0C0330.
+    programModule(device_manager_exe).addImport("pci-class", pci_class_module);
+    // The manager matches reported USB interfaces by their (class,subclass,protocol)
+    // triple (usbDriverForIdentity), built from the named usb-ids codes.
+    programModule(device_manager_exe).addImport("usb-ids", usb_ids_module);
+    // The input service and its exercisers: the fan-out server, a hardware-free synthetic
+    // source, and a subscriber that doubles as the `input` test's oracle. See docs/input.md.
+    const input_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "input", "system/services/input/input.zig");
+    const input_source_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "input-source", "system/services/input-source/input-source.zig");
+    const input_test_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "input-test", "system/services/input-test/input-test.zig");
+    const args_echo_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "args-echo", "system/services/args-echo/args-echo.zig");
+    const process_test_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "process-test", "system/services/process-test/process-test.zig");
+    const log_flush_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "log-flush", "system/services/log-flush/log-flush.zig");
+    // The first multi-threaded binary: exercises runtime.Thread over the thread ABI
+    // (docs/threading.md). Built threaded so its shared-memory poll is real.
+    const thread_test_exe = addThreadedUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "thread-test", "system/services/thread-test/thread-test.zig");
 
     // Pack the user binaries into the initial_ramdisk image with the host-side Python tool
     // (the container format is trivial, and Python sidesteps std API churn). Args:
@@ -311,22 +594,75 @@ pub fn build(b: *std.Build) void {
     mk_run.addFileArg(vfs_exe.getEmittedBin());
     mk_run.addArg("vfs-test");
     mk_run.addFileArg(vfstest_exe.getEmittedBin());
-    mk_run.addArg("hpet");
-    mk_run.addFileArg(hpet_exe.getEmittedBin());
-    mk_run.addArg("bus");
-    mk_run.addFileArg(bus_exe.getEmittedBin());
+    mk_run.addArg("ps2-bus");
+    mk_run.addFileArg(ps2_bus_exe.getEmittedBin());
+    mk_run.addArg("ps2-keyboard");
+    mk_run.addFileArg(ps2_keyboard_exe.getEmittedBin());
+    mk_run.addArg("ps2-mouse");
+    mk_run.addFileArg(ps2_mouse_exe.getEmittedBin());
+    mk_run.addArg("usb-xhci-bus");
+    mk_run.addFileArg(usb_xhci_bus_exe.getEmittedBin());
+    mk_run.addArg("usb-hid-keyboard");
+    mk_run.addFileArg(usb_hid_keyboard_exe.getEmittedBin());
+    mk_run.addArg("usb-hid-mouse");
+    mk_run.addFileArg(usb_hid_mouse_exe.getEmittedBin());
+    mk_run.addArg("usb-storage");
+    mk_run.addFileArg(usb_storage_exe.getEmittedBin());
+    mk_run.addArg("fat");
+    mk_run.addFileArg(fat_exe.getEmittedBin());
+    mk_run.addArg("fat-test");
+    mk_run.addFileArg(fat_test_exe.getEmittedBin());
+    mk_run.addArg("display");
+    mk_run.addFileArg(display_exe.getEmittedBin());
+    mk_run.addArg("display-demo");
+    mk_run.addFileArg(display_demo_exe.getEmittedBin());
+    mk_run.addArg("virtio-gpu");
+    mk_run.addFileArg(virtio_gpu_exe.getEmittedBin());
+    mk_run.addArg("shm-server");
+    mk_run.addFileArg(shm_server_exe.getEmittedBin());
+    mk_run.addArg("shm-client");
+    mk_run.addFileArg(shm_client_exe.getEmittedBin());
+    mk_run.addArg("pci-bus");
+    mk_run.addFileArg(pci_bus_exe.getEmittedBin());
+    mk_run.addArg("crash-test");
+    mk_run.addFileArg(crash_test_exe.getEmittedBin());
+    mk_run.addArg("thread-test");
+    mk_run.addFileArg(thread_test_exe.getEmittedBin());
+    mk_run.addArg("device-list");
+    mk_run.addFileArg(device_list_exe.getEmittedBin());
+    mk_run.addArg("discovery");
+    mk_run.addFileArg(discovery_exe.getEmittedBin());
     mk_run.addArg("device-manager");
     mk_run.addFileArg(device_manager_exe.getEmittedBin());
+    mk_run.addArg("input");
+    mk_run.addFileArg(input_exe.getEmittedBin());
+    mk_run.addArg("input-source");
+    mk_run.addFileArg(input_source_exe.getEmittedBin());
+    mk_run.addArg("input-test");
+    mk_run.addFileArg(input_test_exe.getEmittedBin());
     mk_run.addArg("args-echo");
     mk_run.addFileArg(args_echo_exe.getEmittedBin());
+    mk_run.addArg("process-test");
+    mk_run.addFileArg(process_test_exe.getEmittedBin());
+    mk_run.addArg("log-flush");
+    mk_run.addFileArg(log_flush_exe.getEmittedBin());
 
     // Also install the packed binaries to their FHS homes, so zig-out is a true image
     // of the filesystem — even though at boot they arrive inside the initial-ramdisk.
     for ([_]struct { *std.Build.Step.Compile, []const u8 }{
         .{ vfs_exe, "system/services" },
         .{ device_manager_exe, "system/services" },
-        .{ hpet_exe, "system/drivers" },
-        .{ bus_exe, "system/drivers" },
+        .{ input_exe, "system/services" },
+        .{ ps2_bus_exe, "system/drivers" },
+        .{ ps2_keyboard_exe, "system/drivers" },
+        .{ ps2_mouse_exe, "system/drivers" },
+        .{ usb_xhci_bus_exe, "system/drivers" },
+        .{ usb_hid_keyboard_exe, "system/drivers" },
+        .{ usb_hid_mouse_exe, "system/drivers" },
+        .{ usb_storage_exe, "system/drivers" },
+        .{ fat_exe, "system/services" },
+        .{ display_exe, "system/services" },
+        .{ log_flush_exe, "system/services" },
     }) |entry| {
         const step = b.addInstallArtifact(entry[0], .{ .dest_dir = .{ .override = .{ .custom = entry[1] } } });
         b.getInstallStep().dependOn(&step.step);
@@ -339,6 +675,13 @@ pub fn build(b: *std.Build) void {
     // Boot methods live in boot/, one per way of getting the kernel running.
     // Each is its own binary/entry (a loader is built for its own target); today
     // that's UEFI for x86-64, with room for e.g. a device-tree path for the Pis.
+    // The loader reads -Dserial too, so its boot-progress breadcrumbs (con_out,
+    // which firmware may mirror to a serial console) are silenced by default — a
+    // real-hardware boot stays quiet. Fatal-error messages ignore this and always
+    // show, so a failed boot still explains itself on screen. See boot/efi.zig.
+    const loader_options = b.addOptions();
+    loader_options.addOption(bool, "serial", serial);
+    const loader_options_module = loader_options.createModule();
     const efiexe = b.addExecutable(.{
         .name = "BOOTX64",
         .root_module = b.createModule(.{
@@ -351,6 +694,7 @@ pub fn build(b: *std.Build) void {
             .imports = &.{
                 // The bootloader speaks only the handoff contract — never the user ABI.
                 .{ .name = "boot-handoff", .module = boot_handoff_module },
+                .{ .name = "build_options", .module = loader_options_module },
             },
         }),
     });
@@ -360,6 +704,57 @@ pub fn build(b: *std.Build) void {
     const efi_install = b.addInstallArtifact(efiexe, .{ .dest_dir = .{ .override = .{ .custom = "EFI/BOOT" } } });
     b.getInstallStep().dependOn(&efi_install.step);
 
+    // --- danos-usb.img: the bootable FAT32 USB image ---
+    // Format a real FAT32 image (the in-repo Python builder, no external tools)
+    // holding exactly what the firmware and bootloader need off the ESP: the EFI
+    // stub, the kernel, init, and the initial-ramdisk. QEMU presents this image as
+    // a USB mass-storage device the guest boots from (see run-x86-64 and the test
+    // harness), and the danos fat driver mounts the same image at /mnt/usb.
+    const fat_image = addBootImage(b, exe.getEmittedBin(), efiexe.getEmittedBin(), init_exe.getEmittedBin(), initial_ramdisk_img);
+    const fat_image_install = b.addInstallFile(fat_image, "danos-usb.img");
+    b.getInstallStep().dependOn(&fat_image_install.step);
+
+    // The image `run-x86-64` boots: identical to the flashable one but with the
+    // serial log sink compiled in, so a developer always gets the machine-readable
+    // log captured to serial0 — without baking serial into the image users flash.
+    // Built lazily (only when `run-x86-64` is requested), and never installed.
+    const exe_serial = addKernel(b, kernel_target, optimize, kernel_modules, test_case, true);
+    const fat_image_serial = addBootImage(b, exe_serial.getEmittedBin(), efiexe.getEmittedBin(), init_exe.getEmittedBin(), initial_ramdisk_img);
+
+    // `zig build check-fat-image` — validate the produced image is a real FAT32
+    // with the EFI stub present (the builder's own --verify, no external tools).
+    const check_fat = b.addSystemCommand(&.{"python3"});
+    check_fat.addFileArg(b.path("tools/make-fat-image.py"));
+    check_fat.addArg("--verify");
+    check_fat.addFileArg(fat_image);
+    const check_fat_step = b.step("check-fat-image", "Verify the FAT32 USB image is valid and bootable");
+    check_fat_step.dependOn(&check_fat.step);
+
+    // --- release-x86-64: danos-x86-64.iso, the flashable release image ---
+    // Wrap the FAT32 boot volume in a hybrid ISO (the in-repo Python builder
+    // again, no xorriso/isohybrid): an ISO9660 whose El Torito EFI boot entry
+    // and MBR ESP partition entry both point at the embedded FAT image. One
+    // file then boots every way release media is consumed — flashed raw to a
+    // USB stick with Etcher or dd, or burned to optical media — while
+    // danos-usb.img stays the raw superfloppy QEMU and the test harness boot.
+    const mk_iso = b.addSystemCommand(&.{"python3"});
+    mk_iso.addFileArg(b.path("tools/make-iso-image.py"));
+    const iso_image = mk_iso.addOutputFileArg("danos-x86-64.iso");
+    mk_iso.addFileArg(fat_image);
+    const iso_install = b.addInstallFile(iso_image, "danos-x86-64.iso");
+    const release_step = b.step("release-x86-64", "Build the flashable x86-64 release ISO (zig-out/danos-x86-64.iso; flash with Etcher or dd)");
+    release_step.dependOn(&iso_install.step);
+
+    // `zig build check-iso-image` — the ISO builder's own --verify (mirroring
+    // check-fat-image): the MBR partition, the El Torito catalog, and the
+    // embedded FAT32 image must all agree.
+    const check_iso = b.addSystemCommand(&.{"python3"});
+    check_iso.addFileArg(b.path("tools/make-iso-image.py"));
+    check_iso.addArg("--verify");
+    check_iso.addFileArg(iso_image);
+    const check_iso_step = b.step("check-iso-image", "Verify the release ISO is a valid hybrid (MBR ESP partition + El Torito EFI entry)");
+    check_iso_step.dependOn(&check_iso.step);
+
     // --- run-x86-64: boot the x86-64 kernel in QEMU via UEFI/OVMF ---
     // Firmware lives in different places per OS/distro, so probe the known
     // layouts (Architecture, Debian/Ubuntu, Fedora, macOS Homebrew) and use the first
@@ -398,6 +793,19 @@ pub fn build(b: *std.Build) void {
 
     const run_efi = b.addSystemCommand(&.{
         "qemu-system-x86_64",
+        "-device",
+        "qemu-xhci,id=xhci",
+        "-device",
+        "usb-mouse,bus=xhci.0",
+        "-device",
+        "usb-kbd,bus=xhci.0",
+        // "-usb",
+        // "-device",
+        // "usb-ehci,id=ehci",
+        // "-device",
+        // "usb-tablet,bus=usb-bus.0",
+        // "-device",
+        // "usb-mouse,bus=ehci.0",
         "-machine",
         "q35",
         "-m",
@@ -407,10 +815,14 @@ pub fn build(b: *std.Build) void {
     });
     run_efi.addArg("-drive");
     run_efi.addPrefixedFileArg("if=pflash,format=raw,file=", vars_out);
-    // Present the FHS zig-out to the guest as a FAT drive — it is the boot volume.
+    // Boot off the FAT32 USB image: a mass-storage device on the same xHCI bus as
+    // the keyboard and mouse. OVMF finds \EFI\BOOT\BOOTX64.efi on it and boots.
+    // The serial-enabled variant, so serial0 carries the log for this dev boot.
+    run_efi.addArg("-drive");
+    run_efi.addPrefixedFileArg("if=none,id=bootusb,format=raw,file=", fat_image_serial);
     run_efi.addArgs(&.{
-        "-drive",
-        b.fmt("format=raw,file=fat:rw:{s}", .{b.install_path}),
+        "-device",
+        "usb-storage,bus=xhci.0,drive=bootusb,removable=on,bootindex=0",
         "-net",
         "none",
         // Emulated display advertising 1280x720 as its native (EDID preferred)
@@ -429,8 +841,10 @@ pub fn build(b: *std.Build) void {
     const make_log_dir = b.addSystemCommand(&.{ "mkdir", "-p", log_dir });
     const serial_log = b.fmt("{s}/run-x86-64-serial0-{s}.log", .{ log_dir, timestamp(b) });
     run_efi.addArgs(&.{ "-serial", b.fmt("file:{s}", .{serial_log}) });
-    // The whole FHS zig-out must be installed (and the scratch dir created) before we mount it.
-    run_efi.step.dependOn(b.getInstallStep());
+    // We boot the self-contained `fat_image_serial` (added as a file arg above, so
+    // it's already a dependency) — not the installed FHS zig-out — so `run-x86-64`
+    // builds only the serial kernel, never the flashable one. Just make the serial
+    // scratch dir first.
     run_efi.step.dependOn(&make_log_dir.step);
 
     const run_efi_step = b.step("run-x86-64", "Boot the x86-64 kernel in QEMU (UEFI/OVMF); serial0 is logged to zig-out/qemu-test/run-x86-64-serial0-<timestamp>.log");
@@ -456,7 +870,23 @@ pub fn build(b: *std.Build) void {
         "system/devices/device-abi.zig",
         "system/devices/pci-class.zig", // class/subclass/prog-IF name decoding
         "system/devices/acpi-ids.zig", // _HID name decoding
+        "system/devices/aml/aml.zig", // AML parse + interpret, incl. Notify dispatch (M21)
+        "system/devices/usb-abi.zig", // wire sizes + bit packings + set-up packet encodings
+        "system/devices/usb-ids.zig", // class/subclass/protocol code assignments
         "library/mmio/mmio.zig", // barriers assemble + registers round-trip
+        "system/drivers/ps2-bus/scancode.zig", // set-2 decode + keyboard state machine
+        "system/drivers/ps2-bus/mouse-packet.zig", // 3-byte mouse packet assembly
+        "system/drivers/usb-hid/hid-report.zig", // HID boot-report keyboard/mouse decode
+        "system/drivers/usb-storage/bulk-only-transport.zig", // CBW/CSW wrapper sizes
+        "system/drivers/usb-storage/scsi.zig", // SCSI CDB encodings (big-endian)
+        "system/services/vfs/path.zig", // mount-prefix path matching
+        "system/services/vfs/protocol.zig", // NodeKind / DirectoryEntry sizes + op values
+        "system/services/fat/on-disk.zig", // FAT on-disk struct sizes + type detection
+        "system/services/fat/engine.zig", // FAT read/write over a RAM-backed image
+        "system/services/display/compositor.zig", // Rect math + fill/composite/blit-tile
+        "system/services/display/protocol.zig", // pack(): native pixel encoding per format
+        "system/drivers/virtio-gpu/virtio-gpu-protocol.zig", // virtio-gpu command struct sizes
+        "system/drivers/virtio-gpu/virtio-pci.zig", // virtio 1.0 PCI transport struct sizes
     }) |root| {
         const mod_tests = b.addTest(.{
             .root_module = b.createModule(.{
@@ -467,4 +897,56 @@ pub fn build(b: *std.Build) void {
         });
         test_step.dependOn(&b.addRunArtifact(mod_tests).step);
     }
+
+    // The xkeyboard-config keymap tests need its generated `layouts` import wired, so they
+    // don't fit the plain loop above. Its keycode->character assertions are the end-to-end
+    // proof that the xkb-data -> generator -> Zig-lookup pipeline is correct.
+    const xkb_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("library/xkeyboard-config/xkeyboard-config.zig"),
+            .target = target,
+            .optimize = optimize,
+            .imports = &.{
+                .{ .name = "layouts", .module = xkb_layouts_module },
+            },
+        }),
+    });
+    test_step.dependOn(&b.addRunArtifact(xkb_tests).step);
+
+    // runtime.time's Instant/Duration arithmetic. time.zig pulls in system.zig (the
+    // syscall wrappers), which needs the `abi` module, so it doesn't fit the plain
+    // loop above.
+    const time_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("library/runtime/time.zig"),
+            .target = target,
+            .optimize = optimize,
+            .imports = &.{
+                .{ .name = "abi", .module = abi_module },
+            },
+        }),
+    });
+    test_step.dependOn(&b.addRunArtifact(time_tests).step);
+
+    // runtime.Thread's lock/condvar state machines (Mutex/Condition/RwLock/WaitGroup). Its
+    // Futex seam falls back to std.Thread.Futex off the danos target, so the tests exercise
+    // them with real host threads (docs/threading-plan.md M11). Like time.zig it pulls in
+    // system.zig (syscall wrappers), which needs the `abi` module.
+    const thread_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("library/runtime/thread.zig"),
+            .target = target,
+            .optimize = optimize,
+            .imports = &.{
+                .{ .name = "abi", .module = abi_module },
+            },
+        }),
+    });
+    test_step.dependOn(&b.addRunArtifact(thread_tests).step);
+
+    // Convenience: `zig build gen-xkeyboard-config` regenerates the layout tables from the
+    // vendored data (offline). `fetch` (the network step) stays a manual script run.
+    const gen_xkb = b.addSystemCommand(&.{ "python3", "tools/make-xkeyboard-config.py", "generate" });
+    const gen_xkb_step = b.step("gen-xkeyboard-config", "Regenerate library/xkeyboard-config/generated from the vendored data");
+    gen_xkb_step.dependOn(&gen_xkb.step);
 }

docs/README.md

@@ -39,16 +39,53 @@ rather than restate it. Roughly in the order things happen at runtime:
     endpoints — the backbone the microkernel's isolated servers talk over.
 12. **[syscall.md](syscall.md) — system calls.** How ring 3 asks the kernel for
     something: the `syscall`/`sysret` fast path, the trap frame, and why the table is
-    deliberately tiny.
-13. **[drivers.md](drivers.md) — writing a driver.** The payoff: a driver is an
+    deliberately tiny. The numbers are a **private** ABI — [vdso.md](vdso.md) designs
+    the public boundary that will hide them.
+13. **[vfs-protocol.md](vfs-protocol.md) — the VFS wire protocol.** The language-neutral
+    byte-level spec of the file protocol spoken over IPC: request/reply headers,
+    the operation table, mount routing, and the append-only evolution rules — the
+    first IPC protocol documented as public ABI.
+14. **[drivers.md](drivers.md) — writing a driver.** The payoff: a driver is an
     ordinary ring-3 process that claims a device, maps its registers, and **sleeps
     until its hardware interrupts it**. The claim is the capability; `irq_ack` is the
     unmask.
-14. **[driver-model.md](driver-model.md) — buses, classes and host controllers.** How
-    real driver stacks factor into three shapes, how families share code, and the
-    proposed ABI for the three primitives still missing (capability passing, DMA +
-    memory barriers, MSI).
-15. **[halting.md](halting.md) — halting.** Why a kernel can't just "exit", and
+15. **[driver-model.md](driver-model.md) — buses, classes and host controllers.** How
+    real driver stacks factor into three shapes and how families share code. The
+    three primitives it proposed are long since built (M13 capability passing,
+    M14 DMA + barriers, M15 MSI), and the driver *contract* on top of them —
+    hello, supervision, restart — is built too (device-manager.md, M18).
+16. **[process-management.md](process-management.md) — process management.** The
+    microkernel's `ps`/`kill`/SIGCHLD: enumerate as a table snapshot, the
+    supervision link as the kill authority, and child-exit notifications over the
+    same endpoints IRQs arrive on.
+17. **[process-lifecycle.md](process-lifecycle.md) — the process lifecycle.** Built
+    (M17): signals over IPC as the one lifecycle vocabulary every process speaks — the
+    POSIX.1-1990 words with message delivery instead of stack hijack, the stable
+    `runtime.process` interface, exit reasons, published exit events any stateful
+    service can subscribe to (the VFS releasing dead clients' handles), and the two
+    iron rules (cleanup is the kernel's job; kill is not a signal).
+18. **[device-manager.md](device-manager.md) — the device manager.** Built (M18,
+    through the app surface): the
+    tree, the matcher, and the supervisor. Tree structure lives in the manager,
+    authority stays in the kernel; bus drivers report what they see; drivers are
+    restarted through the lifecycle vocabulary — the plan that turns
+    [resilience.md](resilience.md)'s restart goal into increments.
+19. **[input.md](input.md) — the input module.** Broadcasting input events (keyboard,
+    mouse, joystick): why a synchronous rendezvous can't fan out to many listeners, the
+    asynchronous `ipc_send` primitive built to fix it, and the per-device subscribe/publish
+    service layered on top.
+20. **[display.md](display.md) — the display service.** The display half of the GUI
+    track: a user-space compositor that owns the framebuffer, composes a layer stack into
+    a double buffer, and presents it. Why GOP and the PCI display device are two views of
+    one controller, the device-node + write-combining handoff, and what flicker-free buys
+    that tear-free doesn't. Plan: [display-plan.md](display-plan.md). **v2** (complete) makes
+    scanout a pluggable backend — GOP floor + a native virtio-gpu driver, hot-attached, with
+    runtime mode-set, EDID, fenced vsync presents, and restart re-attach:
+    [display-v2.md](display-v2.md), plan [display-v2-plan.md](display-v2-plan.md). Looking
+    further out, two research snapshots survey what a *native* driver for real GPU silicon
+    would take as another `.scanout` backend: [nvidia-gpus.md](nvidia-gpus.md) (RTX 3060 /
+    Ampere) and [intel-igpu.md](intel-igpu.md) (Intel iGPU).
+21. **[halting.md](halting.md) — halting.** Why a kernel can't just "exit", and
     how `while (true) hlt` parks the CPU safely once there's nothing left to do.
 
 Start with the north star:
@@ -61,9 +98,37 @@ Start with the north star:
 - **[resilience.md](resilience.md) — resilience.** A design note (not built yet) on
   fault isolation + live restart — the reincarnation-server + capability model that
   makes "if I break it, I can restart it" real. danos's core motivation.
+- **[zig-self-hosting.md](zig-self-hosting.md) — running Zig on danos.** A design note
+  (not built yet) on making danos a real Zig target (`-target x86_64-danos`) and
+  eventually running the compiler on it. The key realisation: Zig 0.16 reduces an OS
+  port to **one seam** (`std.os.danos`), so we build `runtime.os` (→ that seam) plus a
+  thin `runtime.fs`, retire the `posix` shim, and follow a phased path to
+  `zig build-exe hello.zig` running on danos — **not** Linux-ABI emulation.
+- **[threading.md](threading.md) — threads, the std-shaped way.** **Built** (M1–M6):
+  `runtime.Thread` mirrors `std.Thread`'s API (spawn/join/detach, Mutex/Condition/
+  Semaphore) over a **private** thread ABI — several tasks sharing one address space via
+  a `thread_spawn` syscall, futex-backed blocking, address-space refcounting. Why it's the
+  native type and not literal `std.Thread` (the [private ABI](syscall.md)), and why
+  threads stay a narrow opt-in against the [resilience](resilience.md) default. Build
+  plan + gates: [threading-plan.md](threading-plan.md).
+- **[vdso.md](vdso.md) — the vDSO, the public system-call boundary.** A design note
+  (not built yet) on keeping `abi.zig` genuinely private: a kernel-supplied, C-ABI
+  entry blob mapped into every process as the *only* way into the kernel — so the
+  syscall numbers can be renumbered or randomised at will, and Rust/C binaries get a
+  stable boundary without danos growing a dynamic linker. danos's public ABI = the
+  vDSO + the documented IPC wire protocols ([vfs-protocol.md](vfs-protocol.md) first).
 
 Cutting across all of these:
 
+- **[system-requirements.md](system-requirements.md) — system requirements.** The
+  hardware needed to run danos: minimum specs (UEFI x86-64, ACPI, PCIe ECAM,
+  xHCI, ~128 MiB RAM) grounded in what the boot path actually assumes, plus a
+  plain-language guide matching Intel/AMD CPU generations by name.
+- **[release-iso.md](release-iso.md) — the release ISO.** The flashable boot
+  media: `zig build release-x86-64` wraps the FAT32 boot volume in a hybrid ISO
+  (MBR ESP partition + El Torito EFI entry, one embedded image) that Etcher/dd
+  flash to USB or a burner writes to disc — built by an in-repo pure-Python
+  tool, like the FAT image itself.
 - **[arch.md](arch.md) — the architecture split.** How CPU-specific code is kept
   behind a build-time `arch` module so the generic kernel never names x86_64,
   leaving room for other systems (e.g. an AArch64 Raspberry Pi) later.
@@ -75,7 +140,16 @@ Cutting across all of these:
   when to build it, and how to keep it architecture-agnostic.
 - **[acpi.md](acpi.md) — finding the ACPI tables.** The concrete x86 locator chain:
   how the loader captures the **RSDP**, hands its physical address across in `BootInfo`,
-  and how the platform derives the **RSDT/XSDT** from it and walks the SDTs.
+  and how the platform derives the **RSDT/XSDT** from it and walks the SDTs — plus the
+  live event side (the SCI, the power button, GPE/Notify) the ring-3 acpi service runs.
+- **[power.md](power.md) — the power service.** System power as a domain-named
+  service: button/lid/battery events published to subscribers, and init's orderly
+  shutdown composing the [lifecycle](process-lifecycle.md) stop sequence with an ACPI
+  S5 write. Firmware-neutral — a PSCI backend drops in on ARM.
+- **[timers.md](timers.md) — timers and time.** The ring-3 surface for reading the
+  clock and waiting: why `now()` is a syscall rather than a service, and the one-shot
+  timer notification (`timer_bind`) that gives supervisors a timed wait — built on the
+  LAPIC heartbeat and calibrated TSC of [device-interrupts.md](device-interrupts.md).
 - **[smp.md](smp.md) — multiple cores.** A design/research note on how microkernels
   (L4, seL4) handle SMP — big kernel lock vs per-CPU vs multikernel — and how the
   right choice depends on whether danos is chasing real-time or resilience.
@@ -132,7 +206,7 @@ addressed as **`system/services/init`** — the repeated leaf resolves away:
 | Source (root file)                     | Addressed as (module / binary / FHS path) |
 |----------------------------------------|--------------------------------------------|
 | `system/services/init/init.zig`        | `system/services/init` → `/system/services/init` |
-| `system/drivers/hpet/hpet.zig`         | `system/drivers/hpet` → `/system/drivers/hpet`   |
+| `system/drivers/ps2-bus/ps2-bus.zig`   | `system/drivers/ps2-bus` → `/system/drivers/ps2-bus` |
 | `library/runtime/runtime.zig`          | `library/runtime` (the `runtime` module)         |
 
 In **source**, a sub-project is a directory so it can hold many files — the entry is
@@ -157,21 +231,22 @@ system/          → /system   danos's own internals (the self-representation)
   services/    init/ vfs/ device-manager/   system servers → /system/services (vfs/ holds
                               vfs.zig, vfs-test.zig, protocol.zig)
 library/         → /lib       libraries, one sub-directory each
-  runtime/                    the danos-native runtime — the stable application ABI
-  posix/                      POSIX/C compatibility, layered over runtime
+  runtime/                    the danos-native runtime + file API (fs) — the stable application ABI
 boot/            → /boot      the loaders
 tools/  test/                 host-side build + QEMU test harness
 ```
 
 A sub-project exposes its **public interface as a module**: `system/services/vfs/` owns
-the VFS wire protocol (`protocol.zig`, the `vfs-protocol` module), which the POSIX
-layer imports by name. `usb`/`block` drivers will expose their protocols the same way.
+the VFS wire protocol (`protocol.zig`, the `vfs-protocol` module), which the runtime's
+file API (`runtime.fs`) imports by name. `usb`/`block` drivers expose their protocols the
+same way.
 
-`library/posix/` is special: it is the **one place** POSIX/C spellings are allowed
-verbatim (`stat`, `O_CREAT`, `fopen`, `errno`). Everywhere else follows the danos
-naming rule with no exception — see [coding-standards.md](coding-standards.md). The
-POSIX layer calls the runtime, never the kernel's system calls directly, so it never
-appears in the private-ABI path.
+There is **no POSIX/C compatibility layer today**: danos programs do file I/O through the
+danos-native `runtime.fs` (open/read/write/list over the VFS). A hand-rolled POSIX shim
+(`library/posix/`) was retired as premature — the real POSIX/C surface will come later
+from the `std.os.danos` seam (and, eventually, musl) when danos becomes a Zig target (see
+[zig-self-hosting.md](zig-self-hosting.md)). When it does, the foreign-ABI naming
+exception in [coding-standards.md](coding-standards.md) applies to that seam.
 
 ## Source map
 
@@ -195,9 +270,8 @@ appears in the private-ABI path.
 | Framebuffer text console (mirrors to serial) | `system/kernel/console.zig` |
 | In-kernel test cases | `system/kernel/tests.zig` |
 | Arch-specific kernel code (`halt`, GDT/IDT/TSS, exception + interrupt stubs, page tables, APIC/IO-APIC/timer, serial, linker script) | `system/kernel/architecture/x86_64/` |
-| danos-native runtime (`runtime`): syscall wrappers, heap, IPC, device access — the stable application ABI | `library/runtime/` |
-| POSIX/C compatibility (`posix`): unistd, stdio — the one place POSIX names are allowed | `library/posix/` |
+| danos-native runtime (`runtime`): syscall wrappers, heap, IPC, device access, the file API (`fs`) — the stable application ABI | `library/runtime/` |
 | System services (init, the VFS server + `protocol`, the device-manager) | `system/services/` |
-| Device drivers, one sub-project each (`hpet` leaf driver, `bus` bus driver) | `system/drivers/` |
-| Build + `run-x86-64` (QEMU/OVMF) | `build.zig` |
+| Device drivers, one sub-project each (`pci-bus`, `ps2-bus`, `usb-xhci-bus` bus drivers) | `system/drivers/` |
+| Build + `run-x86-64` (QEMU/OVMF) + `release-x86-64` (the flashable ISO) | `build.zig` |
 | QEMU integration test harness | `test/qemu_test.py` |

docs/acpi.md

@@ -107,12 +107,66 @@ firmware-agnostic [device model](discovery.md) gets populated; this note stops a
 part that answers "where are the tables?" — everything past the RSDP is just following
 more pointers the tables themselves provide.
 
+## ACPI events: the SCI, the power button, and GPEs (M21)
+
+The tables above are static description; ACPI is also a *live* channel. Hardware
+raises the **SCI** (System Control Interrupt) — one shared, level-triggered line
+whose vector the FADT names — and the OS reads status registers to learn what
+happened: a fixed event like the power button, or a **General-Purpose Event**
+(GPE) whose handler is an AML method. Since [discovery](discovery.md) moved AML
+to ring 3, the event side lives there too, in the same **acpi service** — the
+device discoverer and the event source are one process, because both need the
+namespace and the port grant.
+
+**The kernel hands the service what it needs and no more.** Reading PM1 event
+blocks and GPE blocks requires the FADT, which the kernel already parses for its
+own `\_S5` poweroff. Rather than re-parse, the kernel appends the **FADT as one
+more memory resource** on the `acpi-tables` node; the service tells it apart
+from the AML blob resources by signature — the FADT keeps its intact `"FACP"`
+header, while the blob resources are header-stripped bytecode that starts with
+no signature. The kernel's own FADT parse is untouched; the service reads the
+PM1 *event* blocks (which the kernel never parsed — it only needs PM1 *control*
+for `\_S5`) and the GPE0/GPE1 blocks straight from its copy. The **SCI itself**
+arrives as the node's one `len == 1` irq resource (distinct from the broad
+`[0, 256)` window that covers children's legacy lines), which is how the service
+finds the line to `irq_bind`.
+
+With those in hand the service enables ACPI mode (only if `SCI_EN` is clear —
+some firmwares boot with it already set), sets `PWRBTN_EN`, and on each SCI:
+
+- **The power button** is a *fixed* event: a set `PWRBTN_STS` bit in PM1 status.
+  The handler clears it (write-1-to-clear), logs the press, and publishes a
+  [`power`](power.md) `power_button` event to subscribers.
+- **GPEs** are the general path: for each set-and-enabled GPE bit `n`, the
+  service evaluates its `\_GPE._L%02X` (level) or `_E%02X` (edge) handler
+  method, drains the **Notify** queue that method produced, maps each notified
+  device to an event (battery, AC, lid, or a generic `notify` with its code),
+  and clears the status bit. A missing handler method is clear-and-log, not an
+  error. Making GPEs work required teaching the interpreter one opcode it never
+  handled — `Notify` (`0x86`) — which it now folds into a bounded queue drained
+  per evaluation; everything else a handler needs (field access, control flow,
+  method calls) was already proven by the ring-3 `_STA`/`_CRS` work.
+
+**How this is tested.** QEMU cannot raise GPEs deterministically on this config,
+so GPE/Notify correctness is proven by **host unit tests** — hand-encoded AML
+with a `Notify` inside a method body, run under `zig build test`. The QEMU
+`power-button` scenario proves the fixed-event path end to end: a QMP
+`system_powerdown` injects a real ACPI power-button press, and the service's SCI
+handler must log it. Battery/AC/lid and the embedded controller's `_Qxx` queries
+are interface-complete but validated on real hardware later.
+
+The service surface these events are *published on* — subscription, the event
+vocabulary, and orderly shutdown — is the power service, [power.md](power.md).
+
 ## Related
 
 - [efi.md](efi.md) — the loader that captures the RSDP before `ExitBootServices`.
 - [memory-map.md](memory-map.md) — the same loader-captures / kernel-consumes seam, and
   the ACPI-reclaim memory the RSDP lives in.
 - [discovery.md](discovery.md) — the broader (still-evolving) plan for turning these
-  tables into one neutral device model shared with the ARM device-tree path.
+  tables into one neutral device model shared with the ARM device-tree path, and how
+  ACPI enumeration and events moved to the ring-3 acpi service.
+- [power.md](power.md) — the domain-named power service the ACPI event side publishes
+  to (button, lid, battery) and its orderly-shutdown path into S5.
 - [arch.md](arch.md) — why the kernel reaches the device code through a `platform`
   module and never names ACPI directly.

docs/coding-standards.md

@@ -65,15 +65,18 @@ Three, and only three.
    `errno`, `O_CREAT`. We don't get to rename `fwrite` to `fileWrite` — it wouldn't be
    `fwrite` any more.
 
-   **This exception is scoped to one place: `library/posix/`.** A file under
-   `library/posix/` *is* the foreign ABI, so it keeps the ABI's spellings — that is the
-   whole rule for that directory. **Everywhere else, Zig/danos naming applies with no
-   POSIX exception**, so there is nothing to get wrong: if you're not in
-   `library/posix/`, expand it. A concept POSIX also has gets a danos name outside that
-   layer — the VFS wire protocol carries a `FileStatus`, not a `Stat`, and a `create`
-   flag, not `O_CREAT`; `library/posix/` is what maps `stat`→`status` and
-   `O_CREAT`→`create` at the boundary. (The `syscall` *wrappers* elsewhere are not an
-   exception to this — they wrap the private danos ABI, so they use danos names.)
+   **This exception is scoped to a file that *is* a foreign ABI, and nothing else.**
+   danos has no such file today: the old `library/posix/` compatibility shim was retired
+   once its callers moved to the danos-native `runtime.fs`, since a hand-rolled POSIX
+   layer is premature until danos actually needs it (see
+   [zig-self-hosting.md](zig-self-hosting.md)). The exception will apply again to the
+   `std.os.danos` seam when danos becomes a real Zig target — that module *is* the C-ABI
+   `system` interface, so it keeps `open`/`read`/`errno`/`O_CREAT`. **Everywhere else,
+   Zig/danos naming applies with no exception**: a concept POSIX also has gets a danos
+   name — the VFS wire protocol carries a `FileStatus`, not a `Stat`, and a `create`
+   flag, not `O_CREAT`; the boundary is where `stat`→`status` and `O_CREAT`→`create` get
+   mapped. (The `syscall` *wrappers* elsewhere are not an exception — they wrap the
+   private danos ABI, so they use danos names.)
 
 2. **Zig idioms are spelled the way Zig spells them.** Three names are the language's,
    not ours, and are left alone:
@@ -96,7 +99,7 @@ That's all — no Unix-abbreviation exception. The source directories are full w
 (`system`, `library`, not `src`/`lib`), and there is no daemon `d` suffix: a driver
 lives in `system/drivers/` and a service in `system/services/`, so the *location*
 already says what it is. Encoding the role in the name too (`busd`, `vfsd`) is
-redundant — the program is just `bus`, `vfs`. Don't put in a name what its directory
+redundant — the program is just `ps2-bus`, `vfs`. Don't put in a name what its directory
 already tells you.
 
 ## A note on collisions
@@ -138,10 +141,36 @@ single word or acronym needs no hyphen: `scheduler.zig`, `paging.zig`, `apic.zig
 conventions above — `snake_case` — because it's an identifier, not a filename.)
 
 **A sub-project's entry point repeats its directory's name** — `init/init.zig`,
-`runtime/runtime.zig`, `hpet/hpet.zig` — and the sub-project is addressed by the
+`runtime/runtime.zig`, `ps2-bus/ps2-bus.zig` — and the sub-project is addressed by the
 *directory* (`system/services/init`, `library/runtime`), with the repeated leaf
 resolving away. See the repository-layout section of [README.md](README.md).
 
+## Named values, not magic numbers
+
+The naming rule has a twin: **a value with meaning gets a name, too.** The same
+principle drives both — a reader should never have to leave the code to understand it.
+An abbreviated *name* forces a reader to guess; a bare *number* forces them worse, out
+to a spec or a header or a comment three files away, to learn what the value even *is*.
+If `0x0C` is the PCI serial-bus class, the code says `BaseClass.serial_bus`, not `0x0C`;
+if `0x04` is the ACPI IRQ resource descriptor, it says `SmallResourceType.irq`, not
+`0x04`. The number is an implementation detail of the name — recorded once, where the
+name is defined, and never spelled again at a use site.
+
+**Prefer an `enum`** when the values form a set (device classes, AML opcodes, resource
+descriptor types, states): the type then also says *which* set a value belongs to, and
+the compiler rejects a value from the wrong one. A lone `pub const` with a descriptive
+name suffices for a one-off (`const large_descriptor_bit = 0x80`). Reach for the enum
+the moment code elsewhere compares against, packs, or produces the value — a packed PCI
+class triple is written from named parts (`.serial_bus`, `.usb`, `.xhci`), never as
+`0x0C_03_30` under a comment that decodes the bytes.
+
+The exceptions are the numbers that carry no hidden meaning: `0` and `1` as plain zero
+and one, an index step, a field width, a bit shift. `x + 1`, `buffer[0]`, and `<< 8`
+need no christening — there is nothing to look up. The test is exactly the naming test:
+*would a reader have to look this up to know what it means?* If yes, name it. This is
+what `opcodes.zig`'s `*_opcode` constants, `acpi-ids`'s `HardwareId`, and `pci-class`'s
+class enums already are — reference data defined once and named everywhere it is used.
+
 ## Why acronyms are the line
 
 Because an acronym has no letters to restore. `MMIO` doesn't become "memory mapped
@@ -150,3 +179,19 @@ input output" in code — that expansion is what the acronym *is for*. But `msg`
 test for "is this an abbreviation I must expand" is simply: *is there a longer word this
 is a clipped form of?* If yes, write the word. If it's an initialism standing in for a
 phrase, leave it.
+
+## Zen of Zig
+
+* Communicate intent precisely.
+* Edge cases matter.
+* Favor reading code over writing code.
+* Only one obvious way to do things.
+* Runtime crashes are better than bugs.
+* Compile errors are better than runtime crashes.
+* Incremental improvements.
+* Avoid local maximums.
+* Reduce the amount one must remember.
+* Focus on code rather than style.
+* Resource allocation may fail; resource deallocation must succeed.
+* Memory is a resource.
+* Together we serve the users.

docs/danos-file-system-hierarchy-FSH.md

@@ -17,7 +17,7 @@ Most modern Unix and Unix-like operating systems follow the FHS. DanOS has its o
 | /srv             | Site-specific data served by this system, such as data and scripts for web servers, data offered by FTP servers, and repositories for version control systems       |
 | /system          | DanOS operating system files (similar idea to C:\Windows). A true representation of danos — its layout mirrors the source tree, so `/system` is what danos *is*.    |
 | /system/devices  | danos virtual device tree e.g. similar to /sys on linux but with danos device tree conventions (the structures in the devices module)                               |
-| /system/drivers  | driver binaries, one sub-project each (e.g. /system/drivers/hpet)                                                                                                   |
+| /system/drivers  | driver binaries, one sub-project each (e.g. /system/drivers/pci-bus, /system/drivers/ps2-bus)                                                                       |
 | /system/services | system-service binaries — the VFS server, init, and other user-mode servers (e.g. /system/services/vfs, /system/services/init)                                      |
 | /system/kernel   | the kernel image                                                                                                                                                    |
 | /tmp             | Directory for temporary files (see also /var/tmp). Often not preserved between system reboots and may be severely size-restricted.                                  |
@@ -61,8 +61,8 @@ to the driver in the order written, and a read consumes what is there. Terminals
 serial lines, keyboards and mice are all of this shape. These are the natural first
 device nodes in danos, because a character driver needs nothing the kernel doesn't
 already provide — it claims its device, maps its registers with `mmio_map`, and blocks
-on `replyWait` for either an interrupt or a client request. `system/drivers/hpet/hpet.zig` is already
-that program, minus the client half.
+on `replyWait` for either an interrupt or a client request. `system/drivers/ps2-bus/ps2-bus.zig`
+is already that program, minus the file-node client half.
 
 The obstacle was never the file type; it is which hardware a ring-3 driver can reach.
 Direct `in`/`out` from user space is still a #GP (no TSS I/O bitmap, IOPL never raised),

docs/device-interrupts.md

@@ -78,6 +78,40 @@ preemption and wakeups (1 ms granularity); the **TSC** is the resolution you rea
 time at. Making `sleep` itself sub-millisecond would take a tickless one-shot
 timer — a later step.
 
+### Is the TSC trustworthy? Invariant, and synchronized
+
+A cycle counter is only a valid *clock* if two things hold, and danos checks both,
+because they decide whether we read time with a cheap `rdtsc` or fall back to the HPET.
+
+**Invariant.** An old TSC counted core clock cycles, so it sped up and slowed down with
+frequency scaling — useless as wall time. Modern CPUs (all of danos's targets) provide an
+**invariant TSC**: a constant rate across P/C-states that never stops. The guarantee is a
+CPUID bit — leaf `0x80000007`, EDX bit 8 — on both Intel *and* AMD. danos reads it in
+`calibrate`, and a TSC that doesn't advertise it is not used as the clocksource. AMD is
+why this matters in practice: it doesn't populate the Intel leaf `0x15` that enumerates
+the TSC *frequency*, so danos already measures AMD's rate against the HPET — but a
+measured frequency without the invariance guarantee is not enough.
+
+**Synchronized.** Each core has its own TSC. Even invariant ones can start at different
+values (a second socket, some firmware), so a thread migrating from a core reading
+`1_000_000` to one reading `999_000` would see time jump *backward*. danos runs a **warp
+check** as each application processor comes online (`checkWarpSource`, adapted from
+Linux's): the waking core and the BSP hammer a shared "highest seen" TSC under a lock,
+and if either ever reads below it, the cores' TSCs are skewed. It's pairwise because APs
+come up one at a time ([smp.md](smp.md)).
+
+**The fallback.** When the TSC fails either test — non-invariant (a bare VM such as the
+default qemu64), or warped between cores — danos moves the monotonic clock onto the
+**HPET** main counter: one fixed-rate counter, so it can neither skew between cores nor
+drift with frequency. It costs a memory-mapped read instead of a register read, but it
+keeps time *accurate*, which is the whole point. The switch preserves the current value,
+so the clock never jumps. The boot log names the outcome:
+
+```
+/system/kernel: clocksource tsc  (TSC invariant: yes, synchronized: yes)   # real Intel/AMD
+/system/kernel: clocksource hpet (TSC invariant: no,  synchronized: yes)   # a bare VM (TCG)
+```
+
 ## Two kinds of vector, one dispatch
 
 The IDT now installs gates `0-47`: the 32 exceptions plus the device range. Every

docs/device-manager.md

@@ -0,0 +1,172 @@
+# The device manager
+
+**Status: the protocol and supervision are built** (M18.1, 2026-07-13): `hello`
+with its deadline, supervised spawn, restart with backoff, and the crash-loop
+cap are in — usb-xhci-bus is the first conforming driver, and the
+`driver-restart` scenario proves fault → backoff → re-claim → cap end to end.
+Tree reports are built too (M18.2, 2026-07-13): the xHCI driver scans its
+root-hub ports and reports each connected device (`child_added`); the manager
+mirrors them and prunes a dead reporter's children, and the `usb-report`
+scenario proves report → prune → respawn → re-report. The application surface is built (M18.3, 2026-07-13):
+`enumerate` and `subscribe` over IPC, with `device-list` as the first client —
+the manager is now the one answer to "what devices exist" for applications.
+The primitives underneath are real ([process-management.md](process-management.md):
+spawn/supervise/kill/exit-notification; [driver-model.md](driver-model.md): the device
+table as a capability system; [drivers.md](drivers.md): claim/map/IRQ), and the first
+per-device driver spawn works (the device manager matches the xHCI controller by PCI
+class and spawns `usb-xhci-bus` with the device id as argv[1]). This document designs
+the rest: the device manager as **the tree, the matcher, and the supervisor** — the
+policy process that turns [resilience.md](resilience.md)'s restart goal into practice
+for drivers.
+
+How processes stop, reload, and report their deaths is deliberately **not** in this
+document: that is the universal lifecycle every danos process speaks —
+[process-lifecycle.md](process-lifecycle.md), signals over IPC and the stable
+`runtime.process` interface. The device manager is that design's first serious
+customer, not its owner. Its own protocol contains nothing lifecycle-shaped; a
+driver is stopped, health-checked, and buried exactly like any other process.
+
+## The tree: structure in the manager, authority in the kernel
+
+The device tree is two things fused: *information* (what exists, how it nests) and
+*authority* (a descriptor is a licence to map physical memory). They separate:
+
+- The **kernel keeps the capability system** — device, I/O-port, and interrupt
+  claims, resource containment on `device_register`, the
+  `mmio_map`/`irq_bind`/`msi_bind` gates — and **cleans all of it up when a process
+  dies** (settled; it is increment 1 of
+  [process-lifecycle.md](process-lifecycle.md)). The three invariants in
+  [driver-model.md](driver-model.md) stay exactly where they are. A device manager
+  that could mint MMIO mappings by its own say-so would be a second kernel, and a
+  buggy one would un-earn everything the microkernel bought.
+- The **device manager owns the tree as data** — identity, topology, naming, driver
+  matching, hotplug events, and being the one process everything else asks about
+  devices. Firmware discovery seeds it (today via the kernel's snapshot); **bus
+  drivers grow it** by reporting what they see; applications query and watch it.
+  `device_enumerate` fades to a manager-internal (then deleted) seam.
+
+Long-term, discovery itself leaves the kernel — but not *into* the manager. PCI
+enumeration is a **pci-bus driver**: the manager spawns it against the host bridge
+(already a device with the ECAM window as a resource), it scans, it reports functions
+like any bus reports children. ACPI becomes an **acpi service** that interprets the
+tables and reports the namespace. The manager only orchestrates and merges. Moving
+AML interpretation out of ring 0 is its own project on its own track; nothing here
+depends on when it lands. (It landed: [discovery.md](discovery.md), M19–M20.)
+
+`device_register` is **idempotent on exact match**: a re-registration with an
+identical (parent, class, identity, resources) tuple returns the existing id
+instead of appending a duplicate. The kernel table has no unregister, so without
+this a restarted registering bus would re-report its children as fresh nodes on
+every respawn. Idempotence is what makes restart-and-re-report sound for *every*
+reporting bus — pci-bus, the acpi service, a future fdt service — not just one,
+and it is why supervision (below) can prune a dead bus's subtree and trust the
+restarted instance to rebuild exactly the same ids.
+
+## The protocol
+
+A `device-manager-protocol` module (the vfs-protocol pattern): extern-struct
+messages, a version in the handshake, reserved fields everywhere. The manager is a
+well-known endpoint (`ipc.register(.device_manager)`); the badge tells it who is
+talking; the same endpoint receives its children's exit notifications — one loop,
+one world.
+
+| Direction | Message | Purpose |
+|---|---|---|
+| driver → manager | `hello { version, role, device_id }` | confirms the argv assignment, starts the deadline clock |
+| bus → manager | `child_added { parent, identity, resources }` | one node the bus discovered |
+| bus → manager | `child_removed { id }` | unplug, or the bus lost it |
+| app → manager | `enumerate` | snapshot of the tree (read-only) |
+| app → manager | `subscribe` | receive published add/remove events |
+
+`hello` is the one deadline the manager enforces itself: spawned and silent past the
+deadline means wrong binary, wrong protocol version, or wedged before main — apply
+the stop sequence and the restart policy. Everything else lifecycle-shaped
+(terminate, the common `ping` liveness call, exit reasons) arrives through
+[process-lifecycle.md](process-lifecycle.md)'s vocabulary, not this protocol.
+
+Assignment stays argv (`usb-xhci-bus <device id>`) for now — simple, and it works.
+The step after `hello` exists is delegation: the manager claims (or is granted) the
+devices and passes the claim to the driver over IPC (the M13 capability-transfer
+mechanism), replacing first-come-first-served `device_claim` with policy. Identity in
+`child_added` is per-bus: PCI children carry the class triple (`pci_class`, as the
+xHCI match already uses); USB children carry the (class, subclass, protocol) triple
+from usb-ids.zig — each bus's native language, decoded by the shared ids modules.
+
+## Supervision and restart
+
+Every driver is spawned with the manager's exit endpoint (`spawnSupervised` — built).
+On a death notification:
+
+1. **Read the reason** ([process-lifecycle.md](process-lifecycle.md) increment 2).
+   Clean exit → it meant to; don't restart. Fault or missed `hello` deadline →
+   restart with **backoff**, and a crash-loop cap (three fast deaths → mark failed,
+   stop respawning, log loudly; a later `reload` to the manager can retry).
+2. **Prune the subtree** the dead bus driver reported. Its children describe
+   protocol state (xHCI slot ids, transfer rings) that died with the process;
+   keeping the nodes would be keeping a lie. Watchers receive `child_removed` — the
+   input service losing, then regaining, a keyboard is the *honest* description of
+   what happened. The restarted instance rediscovers and re-reports.
+3. **The claim is already free** because the kernel released it at death — the
+   restarted instance claims the same controller and comes up.
+
+Who supervises the supervisor: **init** (PID 1), which already supervises the
+services it starts. If the manager dies, drivers keep running (they hold their
+claims; the kernel doesn't care who their supervisor was — though their exit
+notifications now dangle harmlessly). The restarted manager re-learns the world:
+kernel snapshot, then a re-`hello` round — drivers answer a broadcast or are stopped
+and respawned. Full state handoff is deliberately not attempted.
+
+## Thin drivers, class protocols
+
+The [driver-model.md](driver-model.md) three-shape split, restated as processes:
+
+- A **bus driver** (usb-xhci-bus) owns its controller — claim, MMIO, IRQ/MSI, DMA
+  rings — and offers a *transfer* protocol ("submit a control transfer to device N",
+  built from the usb-abi request constructors) plus tree reports to the manager.
+- A **class driver** (usb-hid, usb-storage) owns nothing: it is matched to a reported
+  child by its identity triple, speaks the bus's transfer protocol downward and its
+  service's protocol upward — HID reports to the input service, blocks to the block
+  service. It works unchanged over any controller.
+- **Services** (input, display, block) aggregate class drivers and face applications.
+
+Each arrow is a protocol module. The manager routes none of the data plane — it
+introduces the parties (matching), supervises them (lifecycle), and gets out of the
+way.
+
+## Increments
+
+Increments 1–4 are the lifecycle prerequisites and live in
+[process-lifecycle.md](process-lifecycle.md) (claim cleanup on death, exit reasons,
+published exit events, signals + `runtime.process`). On top of those:
+
+5. **device-manager-protocol**: `hello`, supervised spawn with restart policy;
+   usb-xhci-bus becomes the first conforming driver.
+6. **Tree reports**: `child_added`/`child_removed`; the manager mirrors; xHCI reports
+   the mouse and keyboard QEMU already hangs off it.
+7. **App surface**: `enumerate`/`subscribe` over IPC; `device_enumerate` retreats
+   to a manager-internal seam.
+8. **Discovery migration** — DONE (M19–M20, 2026-07-13): enumeration moved to
+   ring 3 as swappable per-firmware discoverers — the pci-bus driver (M19) then
+   the acpi service (M20), see [discovery.md](discovery.md); the kernel seeds
+   only the host bridge and the acpi-tables node. Matching moved with it:
+   `child_added` grew a `device_id` (the kernel-registered id, `no_device` for
+   unregistered leaves like USB ports) and a firmware `hid`, and the manager now
+   matches drivers from those **reports** rather than its boot-time snapshot. The
+   PCI arm flipped in M19.3, the ACPI arm (ps2-bus matched from `_HID`) in M20.3
+   — each in a single phase so no device is ever matched from both sources at
+   once. The acpi service reports only the non-PCI `_HID` devices, since pci-bus
+   already reports PCI functions (M20.2).
+
+## Settled questions (2026-07-12)
+
+- **Stateful buses**: pruning the subtree on bus-driver death is right for USB. A
+  future storage bus with in-flight writes wants drain-before-terminate — which is
+  exactly the `deadline_ms` parameter `stop()` already has; a per-driver deadline
+  is one value in the manager's policy table when such a bus arrives. No design
+  change.
+- **Manager death**: drivers survive the manager; the restarted manager re-learns
+  the world (above). Checkpointing driver state with the manager is deferred until
+  something demonstrates the need.
+- **Matching stays code until the third bus.** `driverFor`/`pciDriverFor` are
+  honest at two bus types; the third triggers the manifest (a driver declares what
+  it binds: a PCI class triple, a USB class triple, an ACPI `_HID`).

docs/discovery.md

@@ -167,3 +167,81 @@ free; discovery on x86 is partly about *finding* what ARM just tells you.
 - [ipc.md](ipc.md) — the channels that interrupts-as-messages and the device manager
   will ride on.
 - [vision.md](vision.md) — why drivers belong in isolated user space at all.
+
+## Update (M19.3, 2026-07-13): PCI enumeration left the kernel
+
+The kernel now seeds only the `pci_host_bridge` node (ECAM window, MMIO
+apertures derived from the memory map's holes, bus range, and the 16-bit I/O
+window). The per-function walk moved to the ring-3 `pci-bus` driver
+([device-manager.md](device-manager.md)): it claims the bridge, repeats the
+ECAM scan through its mmio grant, and `device_register`s what it finds, which
+the device manager mirrors and matches. The ACPI namespace walk follows in M20;
+the static tables (MADT, HPET, MCFG, FADT + `\\_S5`) stay kernel-side.
+
+## Update (M20.3, 2026-07-13): ACPI enumeration left the kernel too
+
+The kernel no longer folds the AML namespace's Device objects into the device
+tree. It still parses the *static* tables (MADT for SMP, HPET for the tick, MCFG
+for the host bridge, FADT) and still builds the AML namespace — but only to read
+the `\\_S5` sleep type for poweroff. Device discovery is the ring-3 **acpi
+service** ([device-manager.md](device-manager.md)): it claims the `acpi-tables`
+node the kernel publishes (the AML blobs, a broad io_port grant, the SCI),
+re-parses the same blobs with the shared AML module, evaluates `_STA`/`_CRS`,
+and registers + reports each `_HID` device — the device manager matches drivers
+(ps2-bus) from those reports. With M19's pci-bus driver, discovery now runs
+entirely in user space; the kernel seeds only the host bridge and the
+acpi-tables node.
+
+## Discovery is a swappable process per firmware (M19–M20)
+
+Moving PCI and ACPI enumeration out of ring 0 was not just a relocation — it
+made discovery **firmware-neutral by construction**, which is the whole reason
+to do it before the second architecture rather than after. Everything at and
+above the [device-manager](device-manager.md) protocol — descriptors,
+containment, reports, matching, supervision — is generic and may never become
+x86-specific. Discovery is the single firmware-specific piece, and it is
+isolated as **one swappable process per firmware**:
+
+- **x86** boots describe hardware with ACPI, so the discoverer is the **acpi
+  service** ([acpi.md](acpi.md)): it claims the `acpi-tables` node and runs AML.
+- **The Raspberry Pis** hand over a flattened device tree, so the discoverer is
+  an **fdt service**: it claims a `devicetree-blob` node and walks the tree —
+  pure data, no bytecode, so it needs neither a port grant nor an interpreter,
+  strictly simpler than ACPI. (A placeholder until the [aarch64](arm.md)
+  bring-up fills it in.)
+
+The device manager spawns the discoverer under the **neutral ramdisk name
+`discovery`** and never learns which firmware it is on; the build's
+`-Ddiscovery=acpi|fdt` option fills that slot (x86 defaults to `acpi`, the
+aarch64 target flips the default when it lands). The manager owns the device
+tree as *data* and touches no hardware, ever — firmware bytecode runs only
+inside the crashable, supervised discoverer, so an AML fault can never take
+down the supervisor.
+
+Two consequences of neutrality bind on later work:
+
+- **Cross-firmware surfaces are named by domain, not firmware.** System power is
+  a [`power`](power.md) protocol, not an "ACPI events" protocol: on x86 the acpi
+  service registers it, on ARM a PSCI/mailbox service registers the same
+  `ServiceId.power`, and subscribers never learn the difference.
+- **Identity must widen before the fdt service exists.** `DeviceDescriptor`'s
+  8-byte `hid` holds an EISA id but cannot hold an FDT `compatible` string
+  (`"brcm,bcm2835-aux-uart"`); the identity field grows before the ARM path can
+  report a real node.
+
+Two supporting decisions keep the kernel's remaining slice honest:
+
+- **The AML interpreter is a shared build module**, compiled into both the
+  kernel and the acpi service — one source, two builds, no fork. The kernel
+  links it for the `\_S5` poweroff evaluation, the service links it for
+  everything else, and the `acpi-parse` test asserts the two produce the same
+  device count across the ring-3 move.
+- **Bridge apertures come from the firmware memory map, not AML.** Registered
+  PCI functions carry BAR resources, and `device_register` containment demands
+  the bridge own windows that cover them. Those apertures are derived
+  kernel-side from the boot memory map's MMIO holes (regions that are neither
+  RAM nor tables) — mechanical, AML-free, and available at boot regardless of
+  what later moved to user space. The acpi service's authority is likewise
+  exactly one node: the `acpi-tables` node, whose broad io_port grant is the
+  documented trust boundary for the one process allowed to run firmware
+  bytecode.

docs/display-plan.md

@@ -0,0 +1,181 @@
+# Display service — build plan (v1: the dumb-framebuffer compositor)
+
+The ordered, checkpointable build-out for [display.md](display.md). Each milestone is
+small, lands on its own, and ends in a **verifiable gate** — shaped for a `/loop` run.
+Read [display.md](display.md) first for the *why*; this is the *what* and the *order*.
+
+## Locked decisions (do not relitigate)
+
+- **Handoff = device node + write-combining `mmio_map`.** The kernel seeds a synthetic
+  `display0` node from `BootInformation.framebuffer`; the service claims + WC-maps it.
+  (Not a bespoke `framebuffer_map` syscall — the device route inherits ownership,
+  release-on-death, and re-claim-on-restart.)
+- **v1 = the full compositor pipeline on the dumb framebuffer.** One `display` service
+  owns the LFB + a cacheable back buffer + a layer stack; double-buffer + damage-driven
+  present; clients draw via server-side commands. **No** runtime mode-setting, **no**
+  shared-memory surfaces — both deferred (see display.md, "What v1 does not do").
+
+## Conventions
+
+Follow [coding-standards.md](coding-standards.md): spell out non-acronym abbreviations in
+full, kebab-case file names, no `Co-Authored-By` trailers on commits. New user binaries
+go through `addUserBinary` in [build.zig](../build.zig) and get packed into the
+initial-ramdisk; protocols are `b.addModule("…-protocol", …)` and imported into the
+`runtime` module.
+
+## How to verify along the way
+
+- `zig build test` — host unit tests (compositor math: layer clipping, damage merge,
+  pitch/format blits are all host-testable with a fake framebuffer).
+- `python3 test/qemu_test.py <case>` — boots the real kernel in QEMU; assert on the
+  serial log ([tests.zig](../system/kernel/tests.zig) is the registry).
+- The `run-efi` target renders to QEMU's display (`-device VGA,edid=on,xres=1280,yres=720`)
+  — a screenshot confirms pixels for the milestones whose gate is visual.
+
+---
+
+## D1 — The handoff primitive (kernel) ✅
+
+Make the boot framebuffer reachable and mappable **write-combining** from user space.
+
+- [x] [device-abi.zig](../system/devices/device-abi.zig): added `DeviceClass.display`; a
+      `DisplayInfo{ width, height, pitch, format }` carried on the descriptor; a
+      `flags` field on `ResourceDescriptor` + `resource_flag_write_combining`.
+- [x] [devices-broker.zig](../system/kernel/devices-broker.zig): `seedDisplay(base, w, h,
+      pitch, format)` publishes a root-level `display` node with one WC-flagged `memory`
+      resource `[base, height*pitch]` + the `DisplayInfo`; `displayDevice()` /
+      `displayClaimed()`. Seeded from `kmain` after `devices_broker.init`.
+- [x] [process.zig](../system/kernel/process.zig) `systemMmioMap` + paging
+      (`mapUserDeviceInto` gains a `write_combining` bool): a resource's WC flag maps it
+      through the WC PAT slot (`setupPat`) instead of strong-uncacheable.
+- [x] [console.zig](../system/kernel/console.zig): `setSuppressed` quiesces `write` while
+      the display device is claimed (driven from `systemDeviceClaim` / release); the
+      terminal panic + exception paths clear it first so a dying machine still draws.
+
+**Gate (met, automated):** the `display` kernel test (`python3 test/qemu_test.py display`,
+`displayTest` in [tests.zig](../system/kernel/tests.zig)) asserts the seeded node's shape
+and geometry, then walks the real claim + `mmio_map` path into a throwaway address space
+and verifies the leaf is **write-combining** (PAT entry 4: PAT bit set, PCD/PWT clear) —
+with an uncacheable-still-uncacheable regression guard. Chosen over the original
+screenshot-of-a-fill gate because it proves the *actual* WC property headlessly; the
+visible fill folds into D2's gate (the service clears the screen through the back buffer).
+Regression-checked: `discovery`, `ioport`, `claim-release`, `supervision`, `device-list`,
+`device-manager` all still pass with the +1 device in the table.
+
+## D2 — Service skeleton, protocol, runtime module ✅
+
+Stand up the named service and the double-buffer, no layers yet.
+
+- [x] `system/services/display/protocol.zig`: `Operation{ info, create_layer,
+      configure_layer, destroy_layer, fill_rect, blit_tile, damage, present }`; `extern`
+      `Request`/`Reply`; size + `maximum_payload` consts. (Model: block/protocol.zig.)
+- [x] [abi.zig](../system/abi.zig): `ServiceId.display = 9`.
+- [x] `system/services/display/display.zig`: `main` → enumerate + claim + WC-map the LFB
+      (front) → `mmap` a cacheable back buffer of `height*pitch` → `runtime.service.run`.
+      `info` and a whole-screen `present` (back → front) are live; layer ops fail-stub
+      until D3. Init clears the back buffer and presents it — the double-buffer path.
+- [x] [library/runtime/display.zig](../library/runtime/runtime.zig) (+ barrel export of
+      `display` and `display_protocol`): `info()` and `present()`, cached `.display`
+      lookup with retry (model: block.zig).
+- [x] [init.zig](../system/services/init/init.zig): `"display"` added to `boot_services`.
+- [x] [build.zig](../build.zig): `display-protocol` module on the runtime; `display` exe
+      via `addUserBinary`; packed into the initial-ramdisk; installed to
+      `/system/services/display`.
+- [x] **Kernel fix the back buffer surfaced:** `mmap` was capped at 256 pages (1 MiB) by
+      a fixed kernel-stack `frames` array. Rewrote `systemMmap` to map page-by-page with
+      rollback (no scratch array) and raised the cap to 8192 pages (32 MiB) — enough for a
+      4K back buffer. A real limitation met, exactly the kind this project chases.
+
+**Gate (met, automated):** `python3 test/qemu_test.py display-service` spawns the
+compositor and matches its own serial heartbeats — `display: online {w}x{h} pitch …`
+followed by `display: presented frame 0` — which it prints only after the whole
+claim → WC-map → back-buffer → clear → present chain succeeds (matched on serial like the
+fault cases, since a lone blocking service can't reschedule the in-kernel test context to
+poll). Regression-checked: `usermem`, `heap` (the `mmap` rewrite), `init` (the boot-list
+addition), and D1's `display` all still pass.
+
+## D3 — Layer stack + compositor + damage present ✅
+
+The heart: composite an ordered layer stack, present only what changed.
+
+- [x] A layer table (16 slots): each `Layer` = position, z, visible, a server-owned
+      `mmap`'d surface (freed on `destroy_layer`). `damage` accumulates the dirty screen
+      region since the last present.
+- [x] `create_layer` / `configure_layer` (damages old + new footprints) / `destroy_layer`,
+      `fill_rect`, `blit_tile` (reads the inline tile from the IPC payload, unaligned-safe),
+      `damage`, `present`.
+- [x] Pure, host-tested [compositor.zig](../system/services/display/compositor.zig): `Rect`
+      (intersect/unite), `Surface`, `fillRect`, `composite` (opaque, clipped to a damage
+      rect), `blitTile`. `present` clears the damaged region to the wallpaper, paints the
+      visible layers bottom-to-top (z-sorted), and flushes just that rect back → front (WC).
+      Colour packing (rgbx/bgrx) is `protocol.pack`, also host-tested.
+- [x] Host tests (`zig build test`, green): rect intersect/unite, `fillRect` clipping +
+      `stride > width` padding, `composite` overlap-shows-top + damage clipping, `blitTile`
+      unaligned read + clipping, and `pack` for both pixel formats.
+
+**Gate (met):** `zig build test` green for the compositor + pack unit tests, **and** the
+`display-service` case's startup self-check composites two overlapping layers on the real
+framebuffer and reads back the composited pixels — overlap = top layer, outside = bottom
+layer — logging `display: compositor self-check ok` (matched by the harness).
+
+## D4 — Client API + the demo client ✅
+
+Prove the pipeline end-to-end from a separate process.
+
+- [x] Finished [runtime/display.zig](../library/runtime/runtime.zig): a `Layer` handle with
+      `fill` / `blitTile` (inline tile) / `configure` (move/restack/show) / `damage` /
+      `destroy`, `createLayer`, and a `color(r,g,b)` helper (caches the mode, packs via
+      `protocol.pack`). Coordinates are signed over the wire (`@bitCast` both ways).
+- [x] `system/services/display-demo/`: a hardware-free client (the `input-source` analog)
+      — a full-screen wallpaper layer, a rectangle that slides back and forth (moved by
+      `configure` each frame, so the compositor repaints old + new), and a cursor layer;
+      presents in a loop paced by `runtime.time`. Wired into build + initial-ramdisk.
+- [x] **Bug this surfaced:** `protocol.message_maximum` was 4096, but the kernel caps
+      every IPC message at `MESSAGE_MAXIMUM` = 256 — so `replyWait` rejected the oversized
+      receive buffer with `-E2BIG` and the serve loop had been *spinning* since D2 (unseen,
+      as D2/D3 matched init-time heartbeats). Set it to 256; `blit_tile` is now explicitly
+      a small-tile path (≤ 54 px inline), larger bitmaps being the deferred shm surface.
+
+**Gate (met):** `python3 test/qemu_test.py display-demo` spawns the service + `display-demo`;
+the demo drives a run of frames of motion through the layer client API and logs
+`display-demo: ok` (the visible motion is a screenshot via `zig build run-x86-64`).
+Regression-checked: `zig build test`, `display` (D1), and `display-service` (D2/D3) all
+still pass, and the default `zig build` is clean.
+
+## D5 — Test cases + docs ✅
+
+- [x] The three integration cases exist and pass: `display` (D1 handoff, kernel),
+      `display-service` (D2/D3 compositor + self-check), and `display-demo` (D4 full
+      pipeline: spawn `display` + `display-demo`, match `display-demo: ok`) —
+      [tests.zig](../system/kernel/tests.zig) + [qemu_test.py](../test/qemu_test.py). Plus
+      the pure host tests (`zig build test`).
+- [x] [display.md](display.md) updated to the built state (the "Verifying it" section names
+      the real cases); [README index](README.md) entry present (#19); the `display-track`
+      memory marked DONE with the commits.
+
+**Gate (met):** `python3 test/qemu_test.py display display-service display-demo` all pass,
+`zig build test` is green, and the default `zig build` is clean.
+
+---
+
+## v1 status: complete
+
+D1–D5 done. The display service is a working framebuffer compositor: it owns the
+framebuffer (write-combining), composites a z-ordered layer stack into a cacheable back
+buffer, presents only the damaged region, and is driven over IPC by the `runtime.display`
+client — proven end-to-end by a separate demo process. Two limitations are deliberate and
+documented (docs/display.md): no runtime mode-setting (native backend) and no true vsync
+(no vblank on a dumb framebuffer). Next steps are the Deferred items below.
+
+---
+
+## Deferred (explicitly not in this plan)
+
+- **Shared-memory surfaces** — generalize M13 capability passing to memory objects
+  (`shm_create`/`shm_map`), so bitmap clients hand the compositor a rendered surface
+  instead of drawing commands. The compositor's layer model already anticipates it.
+- **Native backend (Bochs DISPI, then virtio-gpu)** — behind the same internal backend
+  interface as the dumb framebuffer: EDID mode list + runtime resolution/bpp change +
+  (eventually) a vblank/flip path for true vsync.
+- **Driver/compositor process split** — only when a second backend or a second head makes
+  the abstraction pay for itself.

docs/display-v2-plan.md

@@ -0,0 +1,173 @@
+# Display v2 — build plan (pluggable scanout: GOP floor + virtio-gpu native)
+
+The ordered, checkpointable build-out for [display-v2.md](display-v2.md). Each milestone
+lands on its own and ends in a **verifiable gate** — shaped for a `/loop` run, like
+[display-plan.md](display-plan.md). Read display-v2.md first for the *why*.
+
+## Locked decisions (do not relitigate)
+
+- **First native backend = virtio-gpu** (VM standard: mode-set + present/flush + vsync).
+- **Dynamic hot-attach**: boot on GOP, upgrade to native when the driver **announces**
+  (push, not polling); re-attach across driver restarts; GOP is the floor for "no driver
+  ever," not a live fall-back after a reprogram.
+- **v2 builds the `shm` capability** (endpoints → memory objects), shared with the future
+  client-surface path.
+- The compositor's layers/back-buffer/damage are **unchanged**; only scanout is pluggable.
+
+## Conventions
+
+Follow [coding-standards.md](coding-standards.md): spell out non-acronym abbreviations,
+kebab-case file names, no `Co-Authored-By` trailers. New user binaries go through
+`addUserBinary` and get packed into the initial-ramdisk; protocols are
+`b.addModule("…-protocol", …)` imported into `runtime`; new syscalls extend
+[abi.zig](../system/abi.zig) `SystemCall` + a `library/runtime` wrapper.
+
+## How to verify along the way
+
+**Every gate is serial-checkable — no screenshots** (this plan is built to run unattended).
+Where "does it actually display" would otherwise need a human eyeball, the code **reads its
+own pixels back**: the scanout resource is CPU-visible RAM (shm-backed) and the back buffer
+is cacheable, so a driver/compositor can write a known value, read it back, and log a
+pass/fail — and a virtio `resource_flush` is confirmed by the device **acking it on the
+used ring**. Those two together (pixel-readback + flush-ack) are the automated stand-in for
+"it's on screen."
+
+- `zig build test` — host unit tests (backend selection, virtio struct sizes/encodings,
+  pixel-check helpers).
+- `python3 test/qemu_test.py <case>` — boots the kernel in QEMU; asserts on serial markers.
+  The virtio cases boot with `-device virtio-gpu` (a per-case `qemu_extra`).
+- `run-x86-64` renders to a window — for the human's own satisfaction, **not** a gate.
+
+---
+
+## V1 — The scanout backend seam (refactor, no behaviour change) ✅
+
+Extract scanout from the compositor so today's path becomes one backend among future ones.
+
+- [x] `system/services/display/backend.zig`: a `Backend` tagged union with `info()`,
+      `surface()` (the cacheable compose target), `present(damage)`, and capability flags
+      (`canModeSet`/`hasVsync`, both false for GOP).
+- [x] The v1 GOP path is now `backend.Gop` (claims the `display` node, WC-maps the LFB,
+      keeps the cacheable back buffer, `present` = the damage-rect WC copy). display.zig
+      composes into `backend.surface()` and calls `backend.present(damage)` — no LFB or
+      framebuffer geometry left in the compositor core.
+- [x] The selection decision is the pure `chooseKind(native_available)` (gop unless a
+      native driver announced), split from the syscall-bound `select()`/`Gop.init()`.
+
+**Gate (met):** `display-service` + `display-demo` pass **unchanged** (pure refactor; GOP
+is the only backend), and `zig build test` stays green.
+
+## V2 — The `shm` cross-process memory capability (kernel) ✅
+
+- [x] [abi.zig](../system/abi.zig): `shm_create` (34) / `shm_map` (35) syscalls + a
+      `shm_test` service id. Handlers in process.zig: `shm_create(len)` allocates contiguous,
+      zeroed, **cacheable** frames, wraps them in a refcounted object, installs a capability
+      handle, maps them into the caller's shm arena → returns virtual_address + handle; `shm_map(cap)`
+      maps the same physical pages into the receiver. Reclaimed on death (see below).
+- [x] The capability core (ipc-synchronous.zig) is now **kind-tagged**: `scheduler.Task`'s
+      handle table holds `HandleObject{kind, ptr}`; `closeHandles` and `shareCapability`
+      dispatch by kind, so an `ShmObject` rides an `ipc_call` `send_cap` exactly like an
+      endpoint and frees only when its last capability drops. `mapUserSharedInto` (paging)
+      maps WB-cacheable + `device_grant`, so a sharer's teardown never frees the shared
+      frames — the object owns them.
+- [x] `library/runtime/shm.zig` (+ barrel export): `create(len) -> Region{ptr, handle, len}`,
+      `map(handle) -> ptr`.
+
+**Gate (met):** `python3 test/qemu_test.py shm` — `shm-client` creates a region, writes a
+pattern, and passes its capability to `shm-server` as an `ipc_call` send_cap; the server
+`shm_map`s it and reads the **same bytes** back → `shm: shared 4096 bytes ok`. Guardrail:
+`ipc`/`ipc-call`/`ipc-cap`, `supervision`, `dma`, `usermem`, `display-service`, and host
+tests all still pass — the handle-table change broke no existing IPC.
+
+## V3 — The virtio-gpu driver: bring-up + a frame on screen ✅
+
+- [x] `system/drivers/virtio-gpu/`: claim the virtio-gpu PCI function (device-manager
+      match on the display/other class triple, driver self-confirms vendor 0x1AF4/device
+      0x1050 from config space), enable memory-space + bus-master, walk the vendor
+      capabilities in config space to find common-config + notify, map the BAR, negotiate
+      VERSION_1, and stand up the control virtqueue in coherent DMA. `virtio-gpu-protocol.zig`
+      + `virtio-pci.zig` for the control/transport structs (host-tested sizes).
+- [x] Create a 2D scanout resource backed by a coherent DMA region (V4 swaps this for the
+      shm-shared surface), `attach_backing`, `set_scanout` to scanout 0, `transfer_to_host_2d`
+      + `resource_flush` of a test pattern, and wait on the used ring.
+- [x] Register a `scanout` service (`ServiceId.scanout` = 11).
+
+**Gate (met):** the `virtio-gpu` case (QEMU `-device virtio-gpu-pci`) boots the
+device-manager stack, which discovers the function and spawns the driver; the driver writes
+a known test pattern into the scanout backing, `transfer_to_host_2d` + `resource_flush`es
+it, and **waits for the device's used-ring ack**, then reads the backing back and checks the
+pattern — logging `virtio-gpu: scanout 640x480 online` and `virtio-gpu: flush acked, pixel
+check ok`. That proves virtqueue + resource + attach + set_scanout + transfer + flush end to
+end without a screenshot (the used-ring ack is the device confirming it consumed the frame).
+
+## V4 — The native backend + hot-attach ✅
+
+- [x] `backend.VirtioGpu` in the compositor: `surface()` = the shared `shm` scanout surface
+      (the compositor composes straight into the device's resource backing; x86 DMA is
+      coherent, so the cacheable shared pages need no flush), `present(damage)` = a `present`
+      request over the driver's `.scanout` endpoint (→ transfer-to-host + resource flush).
+- [x] The driver **announces** to `.display` after bring-up (looks it up with a bounded retry,
+      sends `attach_scanout` with the geometry + the shared surface as an `ipc_call` send_cap).
+      The compositor maps it, looks up `.scanout` itself (no need to pass the endpoint — the
+      driver registered it), switches backend, and re-composites the current frame full-screen.
+      The present is deferred to a one-shot timer so it runs *after* the reply unblocks the
+      driver and it serves `.scanout` — presenting inline would deadlock.
+- [x] Boot still starts on `backend.Gop`; the upgrade happens on announce. `shm_physical` (a
+      new syscall) gives the driver the guest-physical of the shared surface for `attach_backing`.
+
+**Gate (met):** the `display-native` case (QEMU `-device virtio-gpu-pci`, `mem` bumped since it
+boots the whole system) starts the compositor + `display-demo` + device-manager; the driver
+announces, the compositor logs `display: scanout upgraded to virtio-gpu`, drives frames through
+the native backend, and **reads a pixel back** from the shared surface after a present to
+confirm the composited frame landed (`display: native present verified`), while `display-demo:
+ok` still fires — checked order-independently. Without `-device virtio-gpu-pci` nothing is
+announced and it stays on GOP: the v1 `display-service`/`display-demo` gates pass unchanged.
+
+## V5 — Mode-setting, EDID, and vsync ✅
+
+- [x] The driver negotiates `VIRTIO_GPU_F_EDID` (when offered) and reads the monitor's EDID,
+      logging its preferred mode; it offers a small mode list over `.scanout` `get_modes`. The
+      resource + shared surface are sized to the largest mode, so `set_mode` just re-points the
+      scanout rectangle (no resource/surface churn) — a runtime resolution change. `runtime.display`
+      gains `modes()` / `setMode()` (display-protocol `get_modes`/`set_mode`, forwarded to the backend).
+- [x] Every `resource_flush` is issued fenced (`VIRTIO_GPU_FLAG_FENCE`); the device signals the
+      fence when the frame is on screen, which the used-ring ack the synchronous present waits on
+      already gates — a tear-free present.
+- [x] `backend.VirtioGpu` reports `canModeSet` / `hasVsync` = true.
+
+**Gate (met):** the `display-modeset` case (reusing the display-native boot) upgrades to
+virtio-gpu, queries the driver's modes, `setMode`s to a different resolution, and confirms the
+change by reading the backend's geometry back (`display: mode set to {w}x{h}, verified`); the
+fenced present path is exercised and confirmed (`display: vsync present ok`) — both from serial,
+passing 3/3. The driver also logs the EDID preferred mode (`virtio-gpu: EDID preferred mode …`).
+
+## V6 — Resilience (restart + re-attach) + tests + docs ✅
+
+- [x] The virtio-gpu driver now **hellos** the device manager (role: bus) so it is properly
+      supervised — no longer stopped at the hello deadline — and is restarted on death. On
+      driver loss the compositor keeps the last frame (its `.scanout` calls now return
+      `-EPEER` instead of hanging — a kernel fix: an endpoint is marked dead when its owner
+      dies) and **re-attaches** when the restarted driver re-announces. A permanent give-up
+      (crash-loop cap) leaves the frozen frame; GOP is not re-taken.
+- [x] `test/qemu_test.py`: the `virtio-gpu`, `display-native` (hot-attach), `display-modeset`,
+      and `display-reattach` (driver-kill/re-attach) cases. display-v2.md status updated.
+
+**Gate (met):** the `display-reattach` case — device-manager (in `test-scanout-restart` mode)
+kills the virtio-gpu driver once after it hellos; the restart policy respawns it, it
+re-announces, and the compositor logs `display: scanout re-attached` after the initial
+`display: scanout upgraded to virtio-gpu`, with no CPU exception / panic (the compositor
+survives) — passing 3/3. All v1 + v2 cases (host tests, `ipc`/`ipc-call`/`ipc-cap`,
+`supervision`, `shm`, `display-service`, `display-demo`, `virtio-gpu`, `display-native`,
+`display-modeset`) pass; default `zig build` is clean.
+
+---
+
+## Deferred (explicitly not in this plan)
+
+- **Client-rendered surfaces** — now unblocked by the `shm` capability (V2): an app renders
+  its own bitmap and hands the compositor a reference. A natural follow-on.
+- **Bochs DISPI backend** — a simpler second native backend (mode-set only, dumb scanout);
+  slots behind the same interface if wanted.
+- **Real-GPU (NVIDIA/AMD/Intel) drivers** — out of scope; those devices stay on the GOP
+  floor by design.
+- **Hardware-accelerated compositing / multiple heads** — future.

docs/display-v2.md

@@ -0,0 +1,131 @@
+# The display service v2: a pluggable scanout backend
+
+**Status: complete (V1–V6).** The compositor boots on the GOP framebuffer and, when a
+virtio-gpu driver announces itself, hot-attaches a native backend over the shared `shm`
+scanout surface — with runtime mode-setting, EDID, and fenced (vsync) presents, and it
+re-attaches across driver restarts. All serial-gated (see [display-v2-plan.md](display-v2-plan.md)).
+
+v1 ([display.md](display.md)) is a compositor that owns the **GOP framebuffer** — it
+composites a layer stack into a cacheable back buffer and streams damage to the linear
+framebuffer the firmware handed over. That path is portable and good: it drives any GPU,
+including a real NVIDIA card at an ultrawide's native resolution, with zero GPU-specific
+code. v2 keeps it as the **floor** and makes *scanout* — how a finished frame reaches the
+panel — a **pluggable backend**, so the compositor can **upgrade to a real GPU driver when
+one is present** and fall back to the framebuffer when it isn't.
+
+The compositor itself (layers, back buffer, damage) does not change. Only the last step —
+"put this frame on screen" — becomes swappable.
+
+## The shape
+
+```
+   compositor (display service)  ── layer stack + back buffer + damage   (unchanged)
+        │  composites a frame, then: backend.present(damage)
+        ▼
+   scanout backend  (selected at runtime — GOP by default, native when it appears)
+        │
+        ├─ GopBackend        the v1 path: WC copy back→front to the firmware LFB.
+        │                    Always available. No mode-set, no vsync. THE FLOOR.
+        │
+        └─ VirtioGpuBackend  talks to a virtio-gpu driver process over a `scanout`
+                             service: present via a shared resource + flush (real vsync),
+                             EDID mode list, runtime mode-set.
+```
+
+A **backend** is a small interface the compositor calls:
+
+- `surface()` → the pixels to compose into and their geometry `{ptr, pitch, format, w, h}`
+  (the LFB for GOP; a shared scanout resource for virtio-gpu),
+- `present(damage: Rect)` → make the damaged region visible (a no-op-ish WC copy for GOP;
+  a virtio flush, optionally vsync-fenced, for the native path),
+- capability queries — `canModeSet`, `hasVsync` — and, when supported, `modes()` /
+  `setMode(m)`.
+
+The compositor composes into `surface()` and calls `present(damage)` exactly as it does
+today; everything device-specific lives behind the interface.
+
+## Selection and hot-attach
+
+The choice is **dynamic**, because a GPU driver is spawned asynchronously (the device
+manager brings it up after boot), and because danos is meant to be resilient:
+
+1. **Boot on GOP.** The compositor starts on `GopBackend` immediately, so there is never a
+   blank screen while drivers load — the exact v1 behaviour.
+2. **Upgrade on announce.** When the virtio-gpu driver has claimed its device and set up a
+   scanout, it **announces itself to the display service** (a `push`: the driver looks up
+   `.display` and sends an *attach-scanout* message carrying its `scanout` endpoint as a
+   capability). The compositor switches to `VirtioGpuBackend` and re-presents the current
+   frame full-screen. Push beats polling — the compositor doesn't know a priori which
+   driver, if any, exists, and danos has no service-registration pub/sub.
+3. **Native is restartable, not fallback-on-crash.** Once a native driver has reprogrammed
+   the device, the firmware's GOP framebuffer is **stale** — "native → GOP" is not a clean
+   fall-back. So a native driver that **crashes** is *restarted* by its supervisor (the
+   resilience work already merged), re-announces, and the compositor **re-attaches**
+   (native → native). The screen freezes on the last frame during the gap — acceptable.
+4. **GOP is the floor for "no driver was ever there."** On a real GPU (NVIDIA/AMD/Intel)
+   the class-0x03 device matches nothing in the driver table, no `scanout` is ever
+   announced, and the compositor stays on GOP forever — no special-casing. Only if a
+   native driver *permanently* gives up (crash-loop cap) does the compositor attempt GOP
+   again, and even then only if the LFB is still mappable.
+
+## The shared-memory primitive this needs
+
+virtio-gpu's scanout resource is **guest RAM** — the driver allocates it and attaches it
+to a virtio resource, and the compositor composes into it. That means the compositor
+writing into the driver's buffer is **cross-process memory sharing**, the primitive v1
+deferred (docs/display.md, "What v1 does not do"). v2 builds it: the natural generalization
+of M13 capability-passing from *endpoints* to *memory objects* —
+
+```
+shm_create(len) -> {handle, virtual_address}     // a shareable, page-aligned RAM region
+… pass `handle` as the send_cap on an ipc_call …
+shm_map(cap)    -> virtual_address                // the receiver maps the same physical pages
+```
+
+The payoff is leverage: the **same** primitive unlocks **both** native GPU drivers *and*
+client-rendered surfaces (an app composing its own bitmap and handing the compositor a
+reference instead of drawing by command). One piece of kernel work, two features.
+
+## The virtio-gpu driver
+
+A new ring-3 driver process (the topology v1 anticipated — "split the driver from the
+compositor when a second backend arrives"). It claims the virtio-gpu PCI function, and:
+
+- sets up the **virtqueues** (control + cursor) and the device's config space,
+- creates a **2D scanout resource** backed by an `shm` region, `attach_backing`s it,
+  `set_scanout`s it to a CRTC, and `resource_flush`es damaged rectangles,
+- reads **EDID** (the `GET_EDID` control command) for the mode list, and `set_scanout`
+  at a chosen mode for **runtime mode-setting**,
+- registers a `scanout` service and announces to the display service.
+
+Its `resource_flush` is the real **present** — and gives a genuine **vsync/tear-free**
+path a dumb GOP framebuffer can't.
+
+## What v2 unlocks — and its honest scope
+
+Behind the abstraction, a native backend gives runtime **mode-setting** (resolution /
+refresh / bpp), **EDID** enumeration, and **vsync**. But only on devices we have a driver
+for — realistically **VMs** (virtio-gpu, and later maybe Bochs DISPI). Real discrete GPUs
+need per-vendor KMS-class drivers that aren't getting written, so they **stay on GOP** —
+which is genuinely fine (v1 on the NVIDIA box is smooth). So v2's real value is twofold:
+the **pluggable architecture** (a driver slots in when one exists) and a **rich, vsync'd
+path in VMs**, where danos development happens. The framebuffer floor never goes away.
+
+## Locked decisions
+
+- **First native backend: virtio-gpu** — the VM standard; gives mode-set + a real
+  present/flush (and vsync), and exercises the whole pluggable design. Tested with QEMU
+  `-device virtio-gpu`.
+- **Dynamic hot-attach** — boot on GOP, upgrade to native on the driver's announce,
+  re-attach across driver restarts; GOP is the floor for "no driver ever," not a live
+  fall-back after a reprogram.
+- **Detection = push** (the driver announces to `.display`), not compositor polling.
+- **v2 builds the `shm` capability** (endpoints → memory objects), shared with the future
+  client-surface path.
+
+## See also
+
+- [display.md](display.md) — v1: the compositor, the GOP-vs-device split, the WC discipline.
+- [display-v2-plan.md](display-v2-plan.md) — the ordered build-out.
+- [driver-model.md](driver-model.md) — claim / `mmio_map` / MSI / capability passing (M13).
+- [resilience.md](resilience.md) — the restart machinery the hot-attach leans on.

docs/display.md

@@ -0,0 +1,305 @@
+# The display service: a framebuffer compositor
+
+The [framebuffer](framebuffer.md) the loader hands over is a flat block of pixel
+memory, and the kernel's [bootstrap console](../system/kernel/console.zig) draws text
+into it directly. That console is a stop-gap. The **display service**
+(`system/services/display/`) is the real thing: an ordinary ring-3 process that *owns*
+the framebuffer, composes a stack of **layers** into an off-screen back buffer, and
+**presents** finished frames to the screen — the display half of the GUI track
+([vision.md](vision.md)), the sibling of the [input service](input.md).
+
+This note is the architecture and the reasoning behind it. The concrete build order
+lives in [display-plan.md](display-plan.md).
+
+## First, a distinction that shapes everything: GOP vs. the PCI device
+
+It is tempting to think "the GOP framebuffer" and "the VGA-compatible display
+controller in the PCIe tree" are two different things. They are not — they are **two
+interfaces to the same silicon, at different times and different levels**, and knowing
+which one you're holding decides what you can do.
+
+- **GOP is firmware's *temporary* driver** for the display controller. It gives you a
+  linear framebuffer pointer and can set video modes — but only until
+  `ExitBootServices`. The loader already leans on this: [`queryFramebuffer`](../boot/efi.zig)
+  reads the monitor's EDID, picks the native mode, and calls `set_mode` **before**
+  exiting ([gop.md](gop.md)). Once the kernel runs, GOP is **gone** — no `set_mode`, no
+  mode list, no EDID. What survives is the frozen snapshot in
+  [`BootInformation.framebuffer`](../system/boot-handoff.zig): `{base, width, height,
+  pitch, format}`, and nothing more.
+
+- **The PCI class-0x03 device is the raw controller** — BARs, config space, registers,
+  IO ports. It is what you actually *own* after boot. On QEMU's emulated adapter
+  ([`-device VGA,edid=on`](../build.zig), the Bochs VBE/DISPI model) the `base` GOP handed
+  you *is* that device's linear-framebuffer BAR — the same physical memory, seen through
+  a different door. On a real discrete GPU, GOP's `base` is an aperture inside the GPU's
+  VRAM BAR. danos already decodes this device
+  ([pci-class.zig](../system/devices/pci-class.zig) has the full `display` namespace, and
+  `pci-bus` already reports it to the [device manager](device-manager.md) with its class
+  triple) — but nothing binds it yet.
+
+What that difference costs you, concretely:
+
+| You want to…                              | Dumb GOP framebuffer (boot handoff) | Native device driver (PCI 0x03)          |
+|-------------------------------------------|-------------------------------------|------------------------------------------|
+| **Report** the current mode              | ✅ from the handoff                 | ✅                                        |
+| **Change resolution / bpp at runtime**   | ❌ GOP is gone                      | ✅ program DISPI regs / virtio-gpu queue  |
+| **Re-read EDID, enumerate monitor modes** | ❌                                  | ✅ the device exposes an EDID block       |
+| **Refresh rate**                         | ❌ (virtual anyway)                 | only a real KMS driver — far future       |
+| **vblank / tear-free present**           | ❌ no vblank signal                 | ✅ vblank IRQ + page-flip (real GPUs)     |
+| **Works on the Pi (no PCI VGA)**         | ✅ VideoCore hands a simple FB      | ✗ per-device                              |
+
+The lesson: the **portable base for the whole GUI stack is the GOP / boot-handoff linear
+framebuffer**. Runtime mode-setting is a *per-device upgrade* layered on top — and on
+the Raspberry Pis there is no PCI VGA at all, so the neutral framebuffer is the only
+thing all three target machines share. That is why the display service is built on the
+dumb framebuffer first, with the native backend as an optional module behind the same
+interface.
+
+## Two constraints this service exists to meet
+
+Like the input service — which existed partly to motivate the asynchronous
+[`ipc_send`](ipc.md) primitive — the display service runs straight into two limits the
+rest of the system hasn't had to face:
+
+1. **The framebuffer is kernel-only today.** It arrives through the boot handoff, is
+   mapped into the kernel's physmap, and is touched only by
+   [`console.zig`](../system/kernel/console.zig). It is *not* a
+   [devices-broker](../system/kernel/devices-broker.zig) node, so
+   `device.claim`/`mmio_map` cannot reach it, and there is no framebuffer
+   [syscall](syscall.md). A user-space display service needs a **new mechanism just to
+   touch the pixels**. (See "The handoff" below — this is built.)
+
+2. **danos has no cross-process shared memory.** The memory syscalls are `mmap`
+   (private, zeroed), `mmio_map` (a *claimed device's* MMIO), and `dma_alloc` (new
+   pinned physical). The block driver's "pass a buffer by physical address" trick
+   ([block/protocol.zig](../system/services/block/protocol.zig)) works *only because its
+   consumer is DMA hardware*. A compositor that CPU-reads and blends client layers can't
+   use it — it would have to *map* another process's memory, which nothing allows. This
+   is deferred (see "What v1 does not do"), because v1 sidesteps it entirely.
+
+## Architecture
+
+```
+  kernel  ── owns the boot framebuffer; bootstrap console only
+     │   seeds a "display0" device node from BootInformation.framebuffer
+     │   (ResourceKind.memory = [base, height*pitch], write-combining hint,
+     │    plus DisplayInfo{width, height, pitch, format})
+     ▼
+  display service   (system/services/display/, ServiceId.display)      ← the compositor
+     │   device.claim(display0) → mmio_map(WRITE-COMBINING) = FRONT buffer (the LFB)
+     │   mmap(cacheable) a BACK buffer of the same geometry
+     │   owns:  an ordered LAYER STACK  +  a per-frame DAMAGE list
+     │   loop:  composite dirty layers → back buffer → present dirty rects → front
+     │   backend is an INTERNAL interface: {gop-fb} today; {bochs-dispi, virtio-gpu} later
+     ▼   reached by name (ipc_lookup); clients drive it over the display protocol
+  ┌────────────────────────────────────┬──────────────────────────────────────┐
+  drawing clients (v1)                  surface clients (deferred)
+  runtime.display commands:             runtime.display surfaces:
+    create_layer / configure_layer        shm_create → pass as a capability →
+    fill_rect / blit_tile / damage         the compositor maps & composites the
+    present                                client-rendered bitmap directly
+```
+
+The bring-up sequence mirrors a hardware driver's — it is the
+[`usb-xhci-bus` `initialise`](../system/drivers/usb-xhci-bus/usb-xhci-bus.zig) shape
+(claim → `mmio_map` → run loop) — and the request/reply service shell is the
+[FAT](../system/services/fat/fat.zig) / [input](../system/services/input/input.zig) shape
+([`runtime.service.run`](../library/runtime/service.zig) with a `protocol.zig` of
+`extern struct` messages and an `Operation` tag).
+
+**One process, for now.** v1 is a *single* service that both owns the framebuffer and
+composites — it does not split a "framebuffer driver" from a "compositor" the way input
+splits `ps2-bus` from the input service. The backend (dumb FB vs. a native GPU) is an
+*internal* interface, not a process boundary. That boundary earns its keep only when a
+second backend or a second monitor appears; until then it is complexity with no payoff.
+
+## The handoff: a device node + a write-combining map
+
+The framebuffer crosses into user space through the machinery that already exists for
+every other device, rather than a bespoke syscall — so it inherits ownership,
+release-on-death, and re-claim-on-restart for free (the [resilience](resilience.md)
+story: a crashed display service returns the LFB to the kernel, and its restart
+re-claims it).
+
+- The kernel seeds a synthetic **`display0`** node into the
+  [devices-broker](../system/kernel/devices-broker.zig) at init, from
+  `BootInformation.framebuffer`: one `ResourceKind.memory` resource spanning
+  `[base, height*pitch]`, tagged **write-combining**, plus a small
+  `DisplayInfo{width, height, pitch, format}` (the memory resource says *where* and *how
+  big*; `DisplayInfo` says how to *interpret* the bytes).
+- The service `device.claim`s it and `mmio_map`s the resource. The map is
+  **write-combining**, not the strong-uncacheable that `mmio_map` uses for register
+  MMIO. The kernel already programs a WC PAT slot for its own console
+  ([`setupPat`](../system/kernel/architecture/x86_64/paging.zig)); this reaches it from
+  the user mapping path. **This matters:** an uncacheable framebuffer makes the
+  back→front blit unusably slow.
+- On `claim`, the kernel's bootstrap console goes quiet, so the two never fight over the
+  LFB. A panic is the one exception — by then the service is likely dead anyway, and a
+  panic on screen wins.
+
+The display service is a **named boot service**: `init` spawns it by name alongside
+`vfs`/`input`/`device-manager` ([init.zig](../system/services/init/init.zig)), and it
+self-discovers `display0` with `device.enumerate`. The [device manager](device-manager.md)
+matching path (PCI class 0x03 → a driver) is reserved for the future *native* backend, not
+this singleton synthetic node.
+
+## Double buffering and the write-combining discipline
+
+Two buffers, with deliberately different memory types:
+
+- The **front buffer** is the LFB — **write-combining**: fast to *write*, slow to
+  *read*. The rule is therefore **never read the front buffer**. Only ever stream into
+  it, sequentially.
+- The **back buffer** is ordinary **cacheable** RAM (`mmap`), the same geometry. All
+  compositing happens here, where reads and read-modify-write blends are cheap.
+
+So a frame is: compose every dirty layer into the cacheable back buffer, then **present**
+— copy the changed regions back→front in sequential, WC-friendly writes. Two details the
+[framebuffer](framebuffer.md) note already establishes carry over: step rows by `pitch`,
+not `width*4`; and handle both `rgbx` and `bgrx` [pixel formats](gop.md).
+
+## Flicker vs. tearing — what double buffering does and doesn't buy
+
+These are two different artifacts, and the dumb framebuffer fixes exactly one of them:
+
+- **Flicker** is the user seeing intermediate, half-drawn states (a clear-then-redraw
+  flash). Double buffering **eliminates it completely** — the screen only ever receives
+  whole, finished frames.
+- **Tearing** is a present landing while the display's scanout beam is mid-frame, so the
+  top of the screen shows the new frame and the bottom the old. Avoiding it requires
+  presenting during the vertical blank (**vsync**) — which needs a vblank signal. **A
+  dumb GOP framebuffer has no vblank.**
+
+So v1 is **flicker-free**, and it *minimizes* the tear window by presenting only damaged
+rectangles (less to copy → a smaller window in which the beam can catch a half-updated
+frame), but it is **not tear-free**. Genuine vsync waits for a backend with a vblank IRQ
+or a flush/flip path — a native-device capability, not something the firmware
+framebuffer can offer. Stated plainly here so the limitation is understood, not
+discovered.
+
+## Layers and the client protocol
+
+The compositor holds an **ordered stack of layers**. Each layer has a rectangle, a
+z-order, a visibility flag, and a surface. Presenting walks the stack bottom-to-top,
+painting each dirty layer into the back buffer, then flushes the damage to the front.
+
+In v1 the surfaces are **server-owned**, and clients draw into them with a small
+immediate-mode command protocol — essentially the model early X used, and enough for a
+shell, a terminal, a cursor, and a wallpaper:
+
+| Operation          | Meaning                                                        |
+|--------------------|---------------------------------------------------------------|
+| `info`             | report `{width, height, pitch, format}` of the display        |
+| `create_layer`     | allocate a server-owned surface, return a layer handle        |
+| `configure_layer`  | set a layer's rect, z-order, visibility                       |
+| `destroy_layer`    | release a layer                                               |
+| `fill_rect`        | fill a rectangle of a layer with a colour                     |
+| `blit_tile`        | copy a small client-supplied pixel tile into a layer (inline) |
+| `damage`           | mark a region of a layer dirty                                |
+| `present`          | composite dirty layers and flush to the screen                |
+
+Text is intentionally *not* an operation — a client renders glyphs by blitting tiles
+(the [PSF font](../system/kernel/font.psf) path the console already uses can move into a
+client). Keeping the protocol to rectangles and tiles keeps the compositor small and the
+policy in the client.
+
+## `runtime.display`
+
+Clients speak the protocol through a new [`library/runtime/display.zig`](../library/runtime/runtime.zig),
+the [`runtime.block`](../library/runtime/block.zig) shape (a cached `.display` lookup
+with a boot-race retry): `display.info()`, a `Layer` handle with `fill` / `blitTile` /
+`damage`, and `present()`. Application code never issues the raw syscalls — it calls the
+runtime, as with every other danos service.
+
+## The cursor: a mouse-listener thread feeding the compositor
+
+The compositor is the single owner of the framebuffer — only the main `service.run` loop
+touches the backend and the layer stack. Tracking the mouse without breaking that
+ownership is the display's first use of [threads](threading.md): the service is built
+multi-threaded (`addThreadedUserBinary`) and, at startup, spawns a **mouse-listener
+thread** beside the compositor loop.
+
+- **Listener thread.** Blocks on the input service's mouse stream
+  (`input.subscribeMouse()`), accumulates the relative `dx`/`dy` motion into an absolute
+  cursor position clamped to the screen, and hands it to the compositor. It never touches
+  the compositor — so no lock guards the framebuffer. A parked `next()` leaves its core
+  free to halt ([halting.md](halting.md)).
+- **The channel.** A single-slot *latest-value* cell (`CursorChannel`) guarded by a
+  `runtime.Thread.Mutex`: the renderer wants where the cursor *is now*, not a replay of
+  every delta, so a new position overwrites the old. The listener also **pokes** the
+  compositor awake — the main loop is parked in `replyWait`, so the listener posts a
+  zero-payload `ipc.send` to the compositor's endpoint, which arrives as a
+  message-notification ([ipc.md](ipc.md)). The poke is *coalesced*: at most one is queued
+  while the main loop has not drained the last, so a fast mouse cannot flood the endpoint.
+- **Render.** On the poke, the main loop takes the latest position and moves the cursor —
+  which is just a top-z compositor layer — with the existing `configure` + `present` path
+  (it damages the old and new footprints, so only those two rectangles repaint).
+
+Two threading facts shape this (both in [threading.md](threading.md)). IPC **handles do
+not cross threads**, so the listener can't reuse the main loop's endpoint handle — it
+`ipc.lookup(.display)`s its *own* handle to the same endpoint to poke through. And a
+multi-threaded service doing concurrent IPC is why the kernel's endpoint-create / register
+/ lookup syscalls now serialize under the big kernel lock. Shared fate applies: a fault in
+the listener takes the whole display down, and the supervisor restarts the process
+([resilience.md](resilience.md)).
+
+## What v1 does not do (and why that's fine)
+
+Two capabilities are deliberately out of the first cut. Neither reshapes anything above;
+both are clean additions behind the interfaces v1 establishes.
+
+- **Client-rendered surfaces (shared memory).** The fast path for a bitmap-heavy app is
+  to render into its *own* buffer and hand the compositor a *reference*, not a stream of
+  commands. That needs the missing cross-process shared-memory primitive — best built as
+  the natural generalization of the existing M13 [capability passing](driver-model.md)
+  from *endpoints* to *memory objects* (`shm_create(len) → {cap, virtual_address}`, pass `cap` on
+  an `ipc_call`, receiver `shm_map(cap) → virtual_address`). v1 avoids it because server-owned
+  surfaces already prove the whole pipeline.
+
+- **Runtime mode-setting (a native backend).** Detecting the EDID mode list and changing
+  resolution / bpp at runtime needs the raw PCI device. The first native backend is
+  Bochs DISPI — the register interface QEMU's `-device VGA` exposes — behind the same
+  internal backend interface the dumb framebuffer sits behind. Refresh-rate and colour
+  management (a gamma LUT) are real-GPU-KMS territory, far beyond this.
+
+## Verifying it
+
+Four QEMU test cases ([tests.zig](../system/kernel/tests.zig), `python3
+test/qemu_test.py <case>`), each layering on the last:
+
+- **`display`** — the kernel handoff: the seeded `display` device is shaped correctly and
+  the claim → `mmio_map` leaf is genuinely **write-combining** (PAT entry 4), asserted at
+  the page-table level.
+- **`display-service`** — the compositor comes up: it claims the framebuffer, allocates
+  the cacheable back buffer, presents a cleared frame through the double-buffer path
+  (`display: online … / presented frame 0`), and a startup **self-check** composites two
+  overlapping layers on the real framebuffer and reads them back — overlap = the top
+  layer — logging `display: compositor self-check ok`.
+- **`display-demo`** — the full pipeline from a separate process: the hardware-free
+  [`display-demo`](../system/services/display-demo/) client (the
+  [`input-source`](../system/services/input-source/) analog) drives layers — a wallpaper and
+  a sliding rectangle — through the layer client API and heartbeats
+  `display-demo: ok`, proving a frame travelled client → compositor → screen, exactly as
+  the [input test](input.md) proves an event travels source → service → subscriber. It draws
+  no cursor and reads no input — the cursor is the service's own (below), and the demo
+  animates on its own frame timer, independent of the mouse (the test spawns `input`
+  alongside it to keep that independence honest). The visible motion itself is a screenshot
+  away via `zig build run-x86-64`.
+- **`display-cursor`** — the mouse-listener thread end to end: with the `input` service up,
+  `input-source mouse` publishes pure motion, and the display's listener thread accumulates
+  it into a cursor position handed to the render loop over the `CursorChannel`. Once the
+  cursor has tracked a run of that motion, the service logs
+  `display: cursor tracking mouse ok`. Runs `smp: 4` — the compositor and listener threads
+  execute on different cores, which is what surfaced the IPC-under-lock requirement above.
+
+The compositor's pixel math (rectangle clipping, fill, composite, tile blit) and colour
+packing are additionally covered by pure host unit tests under `zig build test`.
+
+## See also
+
+- [framebuffer.md](framebuffer.md) — the linear framebuffer, pitch vs. width, `volatile`.
+- [gop.md](gop.md) — GOP, and why only linear RGBX/BGRX modes are paintable.
+- [input.md](input.md) — the sibling service; the async `ipc_send` fan-out.
+- [driver-model.md](driver-model.md) — claim / `mmio_map`, capability passing, the trust model.
+- [device-manager.md](device-manager.md) — matching and supervision (the native backend's route).
+- [display-plan.md](display-plan.md) — the ordered build-out.

docs/driver-model.md

@@ -57,8 +57,9 @@ is not an address window. Discovery is trusted; user space is not.
 
 ### What a bus driver looks like
 
-`system/drivers/bus/bus.zig` is the smallest honest one. Its "bus" is the HPET's register block and
-its "devices" are the block's comparators:
+danos ships no demo bus driver — the real ones are `pci-bus`, `ps2-bus`, and
+`usb-xhci-bus`. The smallest *honest* shape, illustrated here with an HPET register block
+as the "bus" and its comparators as the "devices", is:
 
 ```zig
 _ = dev.claim(bus.id);                       // 1. own the bus
@@ -78,8 +79,8 @@ for (0..n) |i| {                             // 3. publish each child
 
 Each child is left **unclaimed**, which is the handoff: a comparator driver can now
 `device_claim` one and `mmio_map` it, and will see only its own 0x20-byte window. A child
-whose window escapes the bus is refused — `bus` asserts that, and the `bus` test
-asserts the kernel's table upholds it.
+whose window escapes the bus is refused; the in-kernel `containment` test asserts the
+kernel's table upholds that ([drivers.md](drivers.md)).
 
 A USB device has *no* resources at all: `resource_count = 0`, because it's addressed
 through its controller, not by MMIO. That case is allowed and is the common one.
@@ -143,7 +144,7 @@ If a class driver needs `mmio`, it has become an HCD and should be one.
   physically-contiguous, pinned, uncacheable, reclaim-on-teardown buffers with the
   physical address exposed (`pmm.allocContiguous`, a DMA arena, `mapUserDmaInto`).
   `dma_below_4g` caps the address for legacy engines; `dma_write_combining` is accepted
-  but falls back to coherent until PAT is programmed. hpet is refactored onto `/lib/mmio`;
+  but falls back to coherent until PAT is programmed. The bus drivers use `/lib/mmio`;
   no DMA driver consumes `dma_alloc` yet.
 - **M15** — interrupts for PCI devices, the MSI half. Discovery now gives every PCI
   function its 4 KiB ECAM config space as resource 0 (unblocking the capability walk
@@ -239,8 +240,8 @@ once per page, maps writeback-cached, and never reveals a physical address.
 **The fix.**
 
 ```
-dma_alloc(len, flags) -> vaddr (rax), paddr (rdx)
-dma_free(vaddr, len)  -> 0
+dma_alloc(len, flags) -> virtual_address (rax), physical_address (rdx)
+dma_free(virtual_address, len)  -> 0
 
 flags:  dma_coherent  (1)  uncacheable; the default and the only one that's portable
         dma_wc        (2)  write-combining — needs PAT programmed; for framebuffers
@@ -302,8 +303,8 @@ rather than an out-struct. The rest of this section is the original design note.
 
 **The blocker, and it's a hard one.** No PCI device can take an interrupt today.
 [`addBars`](system/devices/acpi.zig) records `.memory` and `.io_port` BARs and never an
-`.irq`; there is no `_PRT` parsing anywhere in the tree. `hpet` only works because the
-HPET advertises its own routing options in its own registers — a privilege no ordinary
+`.irq`; there is no `_PRT` parsing anywhere in the tree. The HPET is the one exception —
+it advertises its own interrupt routing in its own registers, a privilege no ordinary
 device has.
 
 **The fix, in two halves.**
@@ -326,7 +327,7 @@ which means **discovery should give each `pci_device` a `.memory` resource for i
 4 KiB ECAM slot**. That's a small change to `parseMcfg` and it unblocks the whole
 capability walk (MSI, MSI-X, PCIe extended caps) without any new syscall.
 
-Note QEMU's HPET reports `Tn_FSB_INT_DEL_CAP = 0` — no MSI — so `hpet` can never
+Note QEMU's HPET reports `Tn_FSB_INT_DEL_CAP = 0` — no MSI — so an HPET timer could never
 exercise this path. The first MSI driver will be the first PCI driver.
 
 ## M16 — the IOMMU, and the honest caveat  ◑ detection done, enforcement pending
@@ -353,7 +354,7 @@ gap should be named rather than implied.
 
 `M13` (capability passing) is independent of `M14`/`M15` and is the cheapest. It
 unlocks class drivers, which are the shape with no hardware requirements at all — you
-could write a real one against `bus`'s comparators tomorrow.
+could write a real one against any device a bus driver publishes tomorrow.
 
 `M14` and `M15` together unlock the first HCD. `M14`'s barrier layer is worth landing
 on its own regardless: it's small, obviously correct, and stops every future driver

docs/drivers.md

@@ -22,12 +22,12 @@ say.*
 
 ## How a driver gets started: discover, match, spawn
 
-Nothing in the kernel decides that the HPET needs the `hpet` driver — that is policy,
-and policy lives in user space. Boot brings user space up as a three-level supervision
-hierarchy, each level owning one job:
+Nothing in the kernel decides that the PCI host bridge needs the `pci-bus` driver — that
+is policy, and policy lives in user space. Boot brings user space up as a three-level
+supervision hierarchy, each level owning one job:
 
 ```
-kernel  ──spawns──►  init (PID 1)  ──spawns──►  device-manager  ──spawns──►  hpet
+kernel  ──spawns──►  init (PID 1)  ──spawns──►  device-manager  ──spawns──►  pci-bus
   |                     |                          |
   spawns only init,     the service supervisor:    the driver supervisor: enumerates
   publishes the         starts the system          /system/devices, matches each device
@@ -74,7 +74,7 @@ The driver syscall numbers (`system/abi.zig`) with the device types they carry
 |---|------|---------|
 | 11 | `device_enumerate(buf, max) -> total` | Snapshot the device table |
 | 12 | `device_claim(id) -> ok` | Take **exclusive** ownership |
-| 13 | `mmio_map(id, res_idx) -> vaddr` | Map a claimed device's register window |
+| 13 | `mmio_map(id, res_idx) -> virtual_address` | Map a claimed device's register window |
 | 14 | `irq_bind(id, res_idx, endpoint)` | Deliver that device's IRQ as a notification |
 | 15 | `irq_ack(id, res_idx)` | Re-arm the IRQ after servicing the device |
 | 16 | `device_register(parent_id, desc) -> id` | Publish a child of a device you claimed |
@@ -184,7 +184,11 @@ Two properties worth knowing:
 
 ## A whole driver
 
-`system/drivers/hpet/hpet.zig` is ~150 lines and does all of it. The shape:
+A minimal leaf driver is only ~150 lines and does all of it. danos ships **no such
+example binary** — the driver model is proven by the real drivers (`pci-bus`, `ps2-bus`,
+`usb-xhci-bus`), and a teaching example belongs here, in the docs, rather than as a
+compiled program nobody runs. Illustrated with a hypothetical HPET timer driver, the
+shape is:
 
 ```zig
 const hpet = findHpet(buf) orelse return;      // device_enumerate, look for
@@ -209,8 +213,8 @@ while (...) {
 }
 ```
 
-The HPET is a good first driver for a reason that isn't obvious. Its *counter* is a
-clocksource — the only way to use it is to read it, so it proved `mmio_map` without
+The HPET makes a good illustration for a reason that isn't obvious. Its *counter* is a
+clocksource — the only way to use it is to read it, so it exercises `mmio_map` without
 needing interrupts at all. Its *comparators* are a clockevent, and can be configured
 **level-triggered** (`Tn_INT_TYPE_CNF`), which asserts a bit in `GENERAL_INT_STATUS`
 that the driver must write-1-to-clear. That's a genuine deassert step, so the full
@@ -252,9 +256,10 @@ bus driver may only ever subdivide what it already owns.
 A device with **no resources** is legal and common. A USB device is reached through its
 controller, not by MMIO, so it gets `resource_count = 0`.
 
-See [`system/drivers/bus/bus.zig`](../system/drivers/bus/bus.zig) for a complete one, and
-[driver-model.md](driver-model.md) for how bus drivers, class drivers and host
-controller drivers fit together.
+See [`system/drivers/pci-bus/pci-bus.zig`](../system/drivers/pci-bus/pci-bus.zig) for a
+real one — it claims a PCI host bridge, maps its ECAM window, and publishes each function
+it finds as a child — and [driver-model.md](driver-model.md) for how bus drivers, class
+drivers and host controller drivers fit together.
 
 ## What the kernel does not do for you
 
@@ -313,32 +318,38 @@ uncacheable, physical address exposed), and **memory barriers** (`/lib/mmio`'s
 
 ## Verifying it
 
-The `hpet` test spawns `hpet` from the initial ramdisk and watches the serial log. The driver
-prints `hpet: ok` only after being woken five times, and its loop's only exit is
-through `replyWait` returning a notification — it cannot reach that line by polling.
+No demo driver ships to prove this end to end; the *real* drivers do, so the tests
+target them and the kernel primitives directly:
 
-The last check doesn't trust the driver's self-report at all: the kernel reads the I/O
-APIC redirection entry back and asserts the line really is routed to a device vector,
-really is level-triggered, and really was left unmasked by the driver's final
-`irq_ack`.
+- **`device-manager`** — boots only the device manager, which discovers the PCI host
+  bridge, matches `pci-bus`, and `system_spawn`s it. The test reads kernel state — the
+  process table and the device tree — to confirm pci-bus came up and registered the
+  functions it enumerated: the whole discover → match → spawn → driver-up chain.
+- **`acpi-ps2`** — a user-space driver (`ps2-bus`) is woken by its device's IRQ,
+  delivered as an IPC notification, and attaches the keyboard: IRQ-as-IPC, end to end.
+- **`pci-scan`** — a user-space driver (`pci-bus`) maps its device's MMIO (the ECAM
+  window) and walks it: `mmio_map`, end to end.
+- **`containment`** — the kernel refuses a `device_register` whose child window escapes
+  the parent's grant (else it would be a syscall for mapping arbitrary memory), while an
+  identical re-register stays idempotent. Asserted in-kernel, straight against the broker.
+- **`irqfree`** — the teardown path. Binds two owners to one shared endpoint, releases
+  one, and reads the I/O APIC back: the departing owner's line is masked, the sibling's
+  is not. That second half is why bindings are keyed on the owning *task* and not on the
+  endpoint pointer — endpoints are shared, so releasing "everything pointing at this
+  endpoint" would silently mask a live driver's device.
+- **`iopass`** — the `device_grant` teardown rule, so destroying a driver's address
+  space never returns MMIO frames to the RAM pool.
 
 ```
-$ python3 test/qemu_test.py hpet irqfree iopass
-  hpet         ... PASS  (matched 'DANOS-TEST-RESULT: PASS')
+$ python3 test/qemu_test.py device-manager acpi-ps2 pci-scan containment irqfree iopass
+  device-manager ... PASS  (matched 'DANOS-TEST-RESULT: PASS')
+  acpi-ps2     ... PASS
+  pci-scan     ... PASS  (matched 'DANOS-TEST-RESULT: PASS')
+  containment  ... PASS  (matched 'DANOS-TEST-RESULT: PASS')
   irqfree      ... PASS  (matched 'DANOS-TEST-RESULT: PASS')
   iopass       ... PASS  (matched 'DANOS-TEST-RESULT: PASS')
 ```
 
-Two companions cover what `hpet` can't, because it never exits:
-
-- **`irqfree`** — the teardown path. Binds two owners to one shared endpoint, releases
-  one, and reads the I/O APIC back: the departing owner's line is masked, the sibling's
-  is not. That second half is why bindings are keyed on the owning *task* and not on
-  the endpoint pointer — endpoints are shared, so releasing "everything pointing at
-  this endpoint" would silently mask a live driver's device.
-- **`iopass`** — the `device_grant` teardown rule, so destroying a driver's address
-  space never returns MMIO frames to the RAM pool.
-
 ## What's next (not done here)
 
 The big driver-model pieces — capability passing (class drivers), DMA + barriers, MSI,
@@ -362,3 +373,23 @@ the first DMA driver to protect and test against) and these smaller items:
 - **Interrupt priority / threaded IRQ latency.** `notifyFromIsr` enqueues the woken
   driver but doesn't preempt (`wakeLocked` deliberately leaves that to the caller), so
   a woken driver waits for the next scheduling point.
+
+## The driver contract (M17–M18)
+
+Claiming and mapping is half of being a danos driver; the other half is the
+**lifecycle and protocol contract**, and the runtime makes it nearly free:
+
+- Build on `runtime.service.run` — one replyWait loop folding protocol
+  requests, signals, and notifications into callbacks. The harness answers the
+  universal zero-length ping and turns `terminate` into a clean exit for you
+  ([process-lifecycle.md](process-lifecycle.md)).
+- A driver spawned with an assignment (its device id as argv[1]) sends the
+  versioned `hello` to the device manager inside the deadline, and a **bus**
+  driver reports what it discovers with `child_added`
+  ([device-manager.md](device-manager.md); usb-xhci-bus is the reference
+  implementation).
+- Crash freely — that is the design. The kernel releases your claims, IRQ
+  bindings, and MSI vectors at death; the manager reads your exit reason,
+  prunes what you reported, restarts you with backoff, and your fresh instance
+  re-claims and re-reports. Never depend on your own cleanup running
+  (iron rule 1).

docs/input.md

@@ -0,0 +1,161 @@
+# The input module: broadcasting input events
+
+A keyboard driver has one keystroke and *many* programs that might want it — a shell, a
+window server, a logger. None of them owns the hardware, and the driver should not know
+who is listening. So between the drivers and the listeners sits the **input service**
+(`system/services/input/`): drivers **publish** events to it, programs **subscribe**, and
+it fans each event out to every interested subscriber. It is an ordinary ring-3 process
+reached over IPC, like the [VFS server](../system/services/vfs/vfs.zig) — no kernel knows
+what a key is.
+
+## One service, several device classes
+
+The service carries three device classes today — **keyboard**, **mouse**, and
+**joystick/gamepad** — and is built to take more
+([protocol.zig](../system/services/input/protocol.zig)). Each class has its own typed
+event:
+
+- `KeyEvent` — `key_down`/`key_up` (physical make/break) and `key_press` (a character was
+  produced, carrying the Unicode scalar); plus a layout-independent `keycode` and a
+  `modifiers` bitmask.
+- `MouseEvent` — relative `motion` (`dx`/`dy`), `button_down`/`button_up`, and `scroll`.
+- `JoystickEvent` — `axis` moves (a signed value on a `control` index) and
+  `button_down`/`button_up`.
+
+All three travel in one **`InputEvent` envelope** tagged with a `DeviceKind`, so the
+fan-out is a single code path and a subscriber can take a mix of classes on one stream.
+Decode an envelope with `asKeyboard()` / `asMouse()` / `asJoystick()` (each returns null
+unless the tag matches). A subscriber names the classes it wants with a **`device_mask`**,
+and the service routes each event only to subscribers whose mask includes its class — so a
+mouse-only listener never wakes for keystrokes.
+
+## Why this needed a new kernel primitive
+
+The interesting part is delivery, and it runs straight into the shape of danos IPC.
+[ipc.md](ipc.md) describes a **synchronous rendezvous**: a server holds exactly one
+pending reply (`Task.ipc_client`) and *must* answer it on its next `replyWait`. Two
+consequences decide the whole design:
+
+1. **You cannot block N subscribers waiting for "the next event".** A server can hold only
+   one caller at a time, so the natural "subscriber calls `next_event()` and blocks" API
+   is impossible for more than one subscriber. Delivery therefore has to be **push** — the
+   service reaching out to subscribers — not pull.
+
+2. **A synchronous push can hang the whole service.** If the service delivered with
+   `ipc_call`, it would block until each subscriber replied. `ipc_call` has no timeout, and
+   the kernel does **not** wake a caller parked on a *dead* peer's endpoint (it only fails a
+   peer that was mid-reply — see [process.zig](../system/kernel/process.zig)
+   `releaseTaskResourcesLocked`). One subscriber that exits mid-delivery would wedge input
+   for everyone. That is the opposite of the resilience the microkernel is for.
+
+The fix is the asynchronous send that [ipc.md](ipc.md) had already earmarked as future
+work ("asynchronous / buffered send … for notifications between servers"):
+
+```
+ipc_send(handle, message_ptr, message_len) -> 0 / -errno
+```
+
+`ipc_send` copies a small payload into the endpoint's **bounded queue** and wakes a
+receiver, then returns immediately — it never blocks and so can never hang on a dead or
+slow subscriber. The receiver picks it up through the same `replyWait` it already runs:
+the wake arrives as a **buffered message** — `notify_badge_bit | notify_message_bit` set in
+the badge (distinguishing it from a bare IRQ/child-exit notification), the sender's task id
+in the low bits, and the payload in the receive buffer, with no reply owed. The queue holds
+16 messages per endpoint; a full queue **drops the oldest**, because a buffered message is
+discrete data, not a coalescing "level" like an interrupt. See
+[ipc-synchronous.zig](../system/kernel/ipc-synchronous.zig) (`sendLocked`, `popPost`, and
+the `replyWait` receive loop).
+
+This is the async counterpart of `ipc_call`, and the input service is its first consumer.
+
+## How the pieces fit
+
+```
+  keyboard/mouse driver, input-source       input service               subscriber(s)
+  -----------------------------------       -------------               -------------
+  connectSource(); loop:                    replyWait:                  subscribeKeyboard()/…All:
+    publishKeyboardEvent(k) ─ ipc_call ─▶  publish → broadcast:            createIpcEndpoint()
+    publishMouseEvent(m)                     for each sub whose            callCap(subscribe,
+    publishJoystickEvent(j)                   mask matches event.device:     send_cap = ep,
+                                               ipc_send(sub_ep) ──────▶       device_mask)
+                                       reply ok                          loop: next()
+                                     subscribe → store {ep cap,          └─ replyWait(ep)
+                                       task id, device_mask}                → InputEvent
+```
+
+- A **subscriber** calls `input.subscribe(mask)` — or a typed helper: `subscribeKeyboard()`,
+  `subscribeMouse()`, `subscribeJoystick()` (one class, `next()` returns the decoded event),
+  or `subscribeAll()` (every class, `next()` returns a tagged `InputEvent`)
+  ([library/runtime/input.zig](../library/runtime/input.zig)). It creates its own endpoint
+  and hands it to the service as a **capability** (M13 capability passing — the input
+  service is that feature's first real user), along with its `device_mask`. Then it loops on
+  `next()`, a `replyWait` on that endpoint returning each pushed event.
+- A **source** (a keyboard, mouse, or joystick driver) calls `input.connectSource()` and the
+  method for its class: `publishKeyboardEvent`, `publishMouseEvent`, or
+  `publishJoystickEvent`. Publishing is a short synchronous `ipc_call` the service answers at
+  once; the service's own fan-out is asynchronous, so publishing never blocks on a slow
+  subscriber.
+- The **service** ([input.zig](../system/services/input/input.zig)) keeps a small subscriber
+  table (endpoint handle + owning task id + `device_mask`). On `publish` it `ipc_send`s the
+  event to every subscriber whose mask includes the event's device class. On `subscribe` it
+  stores the passed capability and mask and, as housekeeping, prunes any slot whose owning
+  process has exited (checked against `process_enumerate`) — not for correctness (an async
+  send to an orphaned endpoint is harmless) but to reclaim the slot.
+
+Publisher and subscriber must be **separate processes**: a single thread that both
+published and serviced its own subscription would deadlock (its `publish` call blocks until
+the service delivers to its endpoint, which only the same thread could receive).
+
+## Status and follow-ups
+
+- **The keyboard is real.** The `ps2-bus` driver owns PNP0303, which carries *both* the
+  0x60/0x64 ports and IRQ1, so reading the hardware lives in the bus, not in
+  [keyboard.zig](../system/drivers/ps2-bus/keyboard.zig): the bus binds IRQ1 and, on each
+  interrupt, drains port 0x60, routing every byte by the status register's
+  auxiliary-output bit to whichever child driver **attached** for that device (an
+  `AttachRequest` to the well-known `ps2_bus` service, carrying the child's endpoint as a
+  capability; the bytes then arrive as asynchronous `ForwardedByte` messages, so the IRQ
+  path never blocks on a child). The keyboard driver decodes the stream — scancode **set 2**,
+  what the keyboard sends with the 8042's legacy translation off, decoded by
+  [scancode.zig](../system/drivers/ps2-bus/scancode.zig) into USB HID usage keycodes with
+  make/break, typematic-repeat, and modifier tracking (host-tested under `zig build test`) —
+  and publishes real `key_down`/`key_press`/`key_up` events.
+- **Keycode → character** is wired in: the keyboard driver fills a `key_press` event's
+  `character` through [`library/xkeyboard-config`](../library/xkeyboard-config/README.md)
+  (`xkb.map(layout, keycode, mods)` → keysym + Unicode character), synthesizing the ASCII
+  control characters for Enter/Tab/Backspace/Escape, whose keysyms map to no Unicode. The
+  layout defaults to `us`; the bus can pass another as the driver's argv[2] — the seam for
+  a future settings source.
+- **The mouse is real too.** IRQ12 is enumerated on the auxiliary device's own ACPI node
+  (PNP0F13), so the bus claims that node alongside the controller and routes both IRQs to
+  its one endpoint, acking whichever line the notification's badge names.
+  [mouse.zig](../system/drivers/ps2-bus/mouse.zig) attaches the way the keyboard does and
+  assembles the forwarded bytes with
+  [mouse-packet.zig](../system/drivers/ps2-bus/mouse-packet.zig) (three-byte stream-mode
+  packets: sync/overflow handling, nine-bit movement, screen-convention `dy` — host-tested
+  under `zig build test`) into `button_down`/`button_up` transitions and `motion` events.
+  **Follow-up:** the IntelliMouse magic-knock for a scroll wheel (four-byte packets) and
+  `scroll` events. The hardware-free `input-source` still rotates through all three classes
+  synthetically (including a joystick, which has no driver yet) via the
+  `input.synthetic*Event` helpers.
+- **Drop-oldest under overflow** is a defined loss; the 16-slot ring absorbs normal bursts.
+  Real backpressure/flow-control is future work.
+- **`publish` is unauthenticated** — any process may publish, consistent with the current
+  bring-up trust model (see [driver-model.md](driver-model.md)). A source capability is
+  future work.
+
+## Verifying it
+
+The `input` case (`python3 test/qemu_test.py input`, in
+[tests.zig](../system/kernel/tests.zig) `inputTest`) boots the real kernel and spawns the
+service, the synthetic source (which cycles keyboard, mouse, and joystick events), and a
+subscriber that took all three classes. It passes only when the subscriber heartbeats
+`input-test: ok` — proof that an event travelled source → service → subscriber over IPC,
+exercising `ipc_send`, capability-passing subscription, and per-device routing. Each
+serial line names the class received, so the log shows all three arriving on one stream.
+
+## See also
+
+- [ipc.md](ipc.md) — the synchronous rendezvous and the notification path `ipc_send` extends.
+- [syscall.md](syscall.md) — the system-call surface, including `ipc_send`.
+- [driver-model.md](driver-model.md) — class drivers, capability passing (M13), the trust model.

docs/intel-igpu.md

@@ -0,0 +1,556 @@
+# Native Intel iGPU display support — feasibility and roadmap
+
+**Status: research snapshot, not implemented.** This records what a *minimal, display-only*
+native driver for an **Intel integrated GPU** — EDID read + mode-set + framebuffer scanout, with
+**no** 3D/media/compute — would take, and how it slots into danos's pluggable scanout
+architecture. It is a survey of primary sources (Intel's open-source
+[Programmer's Reference Manuals](https://www.intel.com/content/www/us/en/docs/graphics-for-linux/developer-reference/1-0/overview.html),
+coreboot's [libgfxinit](https://doc.coreboot.org/gfx/libgfxinit.html), the Linux
+[i915 display](https://github.com/torvalds/linux/tree/master/drivers/gpu/drm/i915/display) driver,
+and Haiku's [intel_extreme](https://github.com/haiku/haiku/tree/master/src/add-ons/kernel/drivers/graphics/intel_extreme/)),
+not an implementation. It is the companion to [nvidia-gpus.md](nvidia-gpus.md) and should be read
+against it — the two answer the same question for opposite silicon.
+
+Read [display.md](display.md) and [display-v2.md](display-v2.md) first — this doc assumes the v2
+model where scanout is a **pluggable backend** and a native driver is just another `.scanout`
+service (like the virtio-gpu one), announcing to the compositor over `attach_scanout`.
+
+## TL;DR
+
+- **Intel is a materially easier, lower-tier target than the NVIDIA RTX 3060 — and the reason is
+  documentation, not silicon.** Intel publishes official, register-level, per-platform **Display
+  Engine** PRMs with named registers, bitfields, and numbered enable sequences; NVIDIA publishes
+  no display PRM and forces reverse-engineering against GPL nouveau. A minimal Intel display-only
+  driver is roughly **tier 2 to low-tier 3** for well-covered generations (Skylake / Kaby Lake /
+  Coffee Lake), versus NVIDIA's **tier 4** for GA106. This is the load-bearing conclusion.
+- **The display block is a genuinely separable register domain.** Mode-set + scanout touch only
+  display registers (pipes, planes, transcoders, DDI buffers, PLLs, power wells, GMBUS/AUX) — **no
+  render engine, no command streamer, no GEM/3D, no signed microcode.** Two small carve-outs, both
+  trivial pokes that do *not* pull in the render engine: a real CDCLK frequency change writes the
+  shared GT PCODE mailbox, and the plane's surface register is a GGTT (memory-interface) address.
+- **There is no firmware wall on the display path.** The only display microcontroller (DMC / "CSR",
+  Skylake+) is **optional** — its sole job is saving/restoring display state across DC5/DC6
+  low-power idle. Without it, i915 prints "Disabling runtime power management" and mode-sets and
+  scans out normally. GuC/HuC are render/media coprocessors, never touched by a display driver.
+  Pre-Skylake parts have no display microcontroller at all yet mode-set fine. There is **nothing
+  analogous to NVIDIA's GSP**.
+- **The scanout memory model is dramatically simpler than a discrete GPU.** Intel iGPUs have **no
+  VRAM**: the display scans out of ordinary system RAM addressed through the Global GTT (GGTT), a
+  flat single-level page table. Linear (untiled) framebuffers are first-class. You need **no
+  GEM/TTM, no VMM, no VRAM allocator, no BAR1 aperture juggling** — the exact machinery the NVIDIA
+  path forces on you.
+- **coreboot libgfxinit is a compact, complete, display-only reference** doing precisely this scope
+  (EDID + PLL/mode-set + scanout, zero 3D) in ~22k lines of formally-analysed SPARK/Ada — versus
+  i915's ~400k lines. It is a *read-and-reimplement* reference, not drop-in code (GPL-2.0-or-later,
+  and Ada, not Zig).
+- **The clean-room, permissively-licensed path is real** — you can implement from the PRM without
+  reading GPL code, and Haiku's MIT `intel_extreme` is a permissive precedent. This is the decisive
+  contrast with NVIDIA, where no vendor register spec exists.
+- **The practical catch is hardware, not software.** On a desktop with an RTX 3060, the monitor is
+  almost certainly cabled to the *card*, so an iGPU driver would light a dark motherboard port; the
+  CPU may be an **F-SKU with the iGPU fused off entirely**; and every clean-room reference targets
+  *older* Intel. Intel is the right target to **learn** display bring-up — "run it on my machine"
+  is a separate, machine-dependent question that may not resolve in the reader's favour.
+- **Recommendation:** as with the NVIDIA doc, GOP already gives native-resolution scanout with zero
+  GPU code. A native Intel driver buys runtime mode changes, hardware vsync, and multihead — and it
+  reaches "first pixel" far faster than the NVIDIA path *if* the target machine actually has a
+  usable, cable-attached iGPU of a documented generation.
+
+## Display engine architecture, and why it's separable
+
+For the common single-display path (SST DisplayPort / HDMI / eDP), the Intel display data flow is a
+small, fully documented, essentially fixed sequence:
+
+```
+memory surface → PLANE(s) → PIPE → TRANSCODER → DDI (drives IO/PHY) → connector
+```
+
+The Tiger Lake PRM Vol 12 states it verbatim: *"The front end of the display contains the pipes.
+The pipes connect to the transcoders. The transcoders, except for wireless, connect to the DDIs to
+drive the IO/PHY."* A **pipe** blends planes (primary/sprite/cursor) into one raster stream; the
+**transcoder** wraps it in port-protocol timing (DP/HDMI/eDP/DSI); the **DDI** is the physical port
+and PHY. Pipe, Planes, Transcoder, and Digital Display Interface are each first-class PRM chapters
+with per-object files in libgfxinit
+([TGL PRM Vol 12](https://cdrdv2-public.intel.com/705833/intel-gfx-prm-osrc-tgl-vol-12-display-engine.pdf)).
+
+**Two honest qualifications** the raw research overstated (per verification):
+
+- The pipeline is *not* strictly linear in all cases — the same PRM pages document optional branches
+  a minimal driver simply ignores (wireless writeback to memory, MIPI DSI, DisplayPort multistream
+  many-to-one, DSC/tiled pipe-joining). Ignoring them does not weaken feasibility.
+- The four-object model *as named* is **Haswell-onward** (DDI introduced ~2013), not "every gen."
+  Pre-Haswell used FDI + PCH transcoders + port-specific encoders. Within the modern iGPU range
+  danos would realistically target (Skylake → Meteor/Lunar Lake) the model is stable.
+
+**The DPLL/clock block is a separate, per-port programmable clock source** and is one of the harder,
+most gen-specific pieces: pick/enable a PLL, route its output to the DDI, then bring up the port.
+The register layout and divider math change substantially per generation — pre-SKL SPLL/WRPLL/LCPLL,
+Skylake+ shared DPLL0–3, Gen11+ combo-PHY plus Type-C MG/DKL PLLs. Pixel-clock computation is a
+classic per-gen rewrite.
+
+### Separable from render — the single most important enabler
+
+The display is a distinct register domain from render/media, and this is confirmed at the primary
+level: the TGL PRM ships display as its own volume (Vol 12), separate from Render Engine (Vol 9) and
+Media (Vol 11); Linux's KMS "is provided by Intel Display Driver, and **shared with drm/xe**"
+([kernel.org i915](https://docs.kernel.org/gpu/i915.html)) — i.e. the display module is
+reused across two different GPU drivers. A full mode-set lights a display end-to-end using only power
+wells, PLL/port-clock, DDI-buffer/PHY, transcoder and pipe registers — **zero render commands, zero
+GEM objects, zero command-streamer.** libgfxinit is decisive proof: complete EDID + modeset +
+framebuffer with no render/3D code at all.
+
+Two carve-outs the "touches ONLY display registers" phrasing needs (per verification), **neither of
+which drags in the render engine**:
+
+1. A mode-set that changes the **Core Display Clock (CDCLK)** frequency/voltage pokes the shared **GT
+   Driver Mailbox** (PCODE/PCU power-controller interface), per Vol 12's own "Display Voltage
+   Frequency Switching" step. A trivial register handshake, documented alongside the display sequence.
+2. The primary plane's surface register (`PLANE_SURF`) holds a **GGTT graphics address** (a
+   memory-interface concept, not covered in Vol 12). Using pre-mapped stolen memory — as libgfxinit
+   does — sidesteps any active GGTT programming. See [Memory and scanout](#memory-and-scanout).
+
+### Per-gen churn: what's stable, what you rewrite
+
+The **object model** (pipes/planes/transcoders/DDIs, GMBUS-for-EDID, double-buffered plane registers
+armed atomically) is conceptually stable from Ironlake/Haswell through Tiger Lake. What you rewrite
+per generation is:
+
+1. the **CPU-vs-PCH split and interconnect**,
+2. the **port/PHY + DPLL** programming,
+3. **register offsets + power-well / CDCLK topology**, and
+4. the **mode-set enable sequence itself** (power-well ordering, PLL lock, DDI-buffer enable,
+   transcoder clock-select) — an effective fourth axis the raw research folded into (1)/(2).
+
+Interconnect eras, with the timeline **corrected** (the cited Haiku doc was chronologically loose):
+
+- **Gen5 Ironlake (2010) → Ivy Bridge:** FDI (Flexible Display Interface) links the CPU display
+  engine to PCH-resident ports. The FDI/PCH-split era begins at **Ironlake**, not Gen7.
+- **Haswell (Gen7.5):** the main digital outputs come **back onto the CPU die as DDIs** (DDI A = eDP)
+  — the *opposite* of "moving output to the PCH," and it collapses the FDI/PCH dance **for the
+  digital ports only**. FDI is **retained** for the legacy VGA/CRT path (DDI E → PCH CRT DAC), so a
+  driver gets the single DDI code path only by omitting analog VGA (which a minimal driver does).
+- **Skylake (Gen9):** reworks clock/PLL, CDCLK, and the power-well model; introduces the optional DMC.
+- **Gen11 Ice Lake / Gen12 Tiger Lake:** add combo-PHY + USB-Type-C/Thunderbolt MG/DKL PHYs — the
+  single biggest cost increase, and the reason "newest silicon" is *not* the easiest target. (DSC is
+  documented per-**pipe**; MSO is an eDP feature — not "per-transcoder" as the raw research said.)
+
+### The tractable sweet spot
+
+The documented, tractable sweet spot for a from-scratch display-only driver is the
+**Haswell (Gen7.5) / Broadwell (Gen8) DDI family, with Skylake (Gen9) as the modern-hardware pick**
+since it shares the same DDI object model. Rationale:
+
+- Broadwell has a complete, freely downloadable
+  [PRM Vol 11 Display](https://cdrdv2-public.intel.com/690828/intel-gfx-prm-osrc-bdw-vol-11-display.pdf);
+  its engine (3 pipes A/B/C, 4 transcoders incl. transcoder-EDP that floats onto any pipe, DDI A–E,
+  WRPLL/SPLL/LCPLL) is the classic "DDI + transcoder + WRPLL" model.
+- It predates the combo-PHY / Type-C / MG-DKL complexity of Ice Lake / Tiger Lake.
+- libgfxinit's DDI **connector/EDID/DP layer is uniform from Haswell through Coffee Lake**, so the
+  hardest-to-get-right port logic generalises widely.
+
+Two supporting claims from the raw research are **wrong and corrected here (verification):**
+
+- **The BDW and SKL PRMs are NOT 0BSD-licensed.** Both carry a Creative Commons
+  **Attribution-NoDerivatives** notice. Only the *newer* OSRC PRMs (Tiger Lake 2021 onward) put their
+  embedded code samples under **Zero-Clause BSD**. So for the recommended Haswell/Broadwell/Skylake
+  generations there are no "copy-pasteable 0BSD code samples" — the legal basis is *reimplementation
+  from a CC-BY-ND spec* (register facts are not copyrightable), not copying.
+- **FDI+PCH is not fully eliminated on Haswell/Broadwell.** The BDW PRM keeps FDI for the DDI E → PCH
+  CRT DAC. The "one DDI code path" holds only for the digital outputs a minimal driver targets.
+
+Sandy/Ivy Bridge (Gen6/7) is where the hobby-doc walkthroughs concentrate (the OSDev GMBUS/EDID
+material) but carries the FDI+PCH split cost. *(Low confidence on the OSDev specifics — the wiki
+returns 403 to automated fetches and its "guaranteed to work" phrasing is a hobby assertion, not a
+silicon guarantee.)*
+
+## Documentation — and the clean-room question
+
+This is the crux of the whole comparison. **Intel hands you the register spec that NVIDIA withholds.**
+
+- The Tiger Lake **"Vol 12: Display Engine"** PRM is a real, first-party, open-source document —
+  **433 pages, verified by direct download** — with named registers + addresses + bitfield tables
+  (`TRANS_DDI_FUNC_CTL`, `DDI_BUF_CTL`, `DP_TP_CTL`, `PLANE_STRIDE`, `DPLL_CFGCR0/1`, `CDCLK_CTL`,
+  `PWR_WELL_CTL_DDI`, …) and **numbered, step-by-step enable sequences** with explicit writes, wait
+  conditions, and microsecond timeouts. It even includes the "magic value" tables older PRMs deferred
+  to the driver (DisplayPort PLL DCO/divider values; voltage-swing/de-emphasis in mV). *"A spec you
+  could write a driver from directly"* is well-supported, not hyperbole
+  ([TGL Vol 12](https://cdrdv2-public.intel.com/705833/intel-gfx-prm-osrc-tgl-vol-12-display-engine.pdf)).
+- **Clean-room, permissively-licensed implementation is legally and practically feasible from the
+  PRM alone.** CC-BY-ND governs redistribution of the *document*; register addresses and bit
+  definitions are functional facts, and original code implementing a described hardware interface is
+  not a derivative of the PDF. *(This is standard copyright reasoning, not adjudicated case law —
+  treat it as well-grounded, not settled.)* Two independent implementations already exist built
+  essentially from these docs (libgfxinit, Haiku), so the spec is demonstrably sufficient.
+
+**The documentation ceiling — corrected.** The raw research said public PRMs stop "roughly at Ice
+Lake / Tiger Lake." Verification refuted this: full public **"Vol 12 Display Engine"** PRMs exist for
+Ice Lake, Lakefield, Tiger Lake, Rocket Lake, DG1, **and DG2/Arc "Alchemist" (Gen12.5, 2022)** —
+[the ACM display PRM is public](https://www.x.org/docs/intel/ACM/intel-gfx-prm-osrc-acm-vol12-displayengine.pdf).
+The genuine cliff is **Meteor Lake (2023) and newer**: those have only a high-level architecture
+overview, no register-level display PRM, and i915 references their display registers by opaque
+internal **Bspec numeric IDs**. Alder Lake and Raptor Lake iGPUs are Gen12 Xe-LP display — the same
+IP as Tiger Lake — so despite lacking a dedicated PRM they are effectively covered by the TGL PRM.
+
+Net: a from-docs driver can confidently target **Skylake through DG2/Arc**, which is essentially the
+entire current laptop/NUC installed base; only Meteor Lake and later slide back toward the NVIDIA
+situation (reverse-engineering or reading GPL i915). The PRMs also survived 01.org's shutdown and are
+mirrored in several stable places (Intel's cdrdv2 host, the
+[Igalia CC-BY-ND archive](https://github.com/Igalia/intel-osrc-gfx-prm) for Gen4–Gen9.5,
+[kiwitree](https://kiwitree.net/~lina/intel-gfx-docs/prm/), x.org) — not a single point of failure.
+*(Note: the Igalia archive stops at Kaby Lake and contains no Display Engine volume; the TGL/DG2
+display PRMs are separate Intel/x.org downloads.)*
+
+## coreboot libgfxinit — the native reference
+
+[libgfxinit](https://doc.coreboot.org/gfx/libgfxinit.html) is the closest thing to a template danos
+could ask for: a self-contained **native modeset library** (no VBIOS/int10, no firmware blobs) that
+probes displays via EDID over DDC/I²C and DP AUX, and drives LVDS, eDP, DP1–3, HDMI1–3, analog VGA,
+plus USB-C DP/HDMI alt-mode on Tiger Lake. It sets up pipes (Primary/Secondary/Tertiary), planes,
+transcoders, PLLs, panel power/backlight, the GTT, and framebuffer scanout — **display-only, zero
+3D/media/compute**, which is exactly danos's scope. Its public entry is essentially
+`Initialize()` then `Update_Outputs(Pipe_Configs)`, where each `Pipe_Config` carries
+`{Port, Framebuffer, Cursor, Mode}` — a near-perfect fit for a pluggable scanout backend.
+
+Why it beats i915 as a reference (**verified by measurement**): **131 Ada source files, ~818 KB,
+~22k code lines** across *all* generations, factored precisely along the axes you care about (`edid`,
+`dp_aux`, `dp_training`, `pipe_setup`, `transcoder`, `plls`, `connectors`, `port_detect`), with
+**none** of the DRM/KMS/GEM/TTM, GT/3D, RC6/RPS, or GuC/HuC machinery that makes
+`drivers/gpu/drm/i915` **~419k lines / 900 files / 12 MB**. (A grep confirms *zero* gem/ttm/guc/huc/
+execbuf identifiers in the tree.) It depends only on a small HW-access shim, `libhwbase`
+(`HW.PCI`, `HW.Port_IO`, `HW.MMIO`, `HW.Time`), which maps naturally onto danos's MMIO-grant + IPC
+primitives — you provide Zig equivalents and the modeset logic sits on top. *(Correction to the raw
+research: the widely-quoted "~13–14k LOC" is only the generic `common/` layer; the eight
+per-generation subdirs roughly double it.)*
+
+**It is a read-and-reimplement reference, not drop-in code.** Two hard constraints:
+
+- **License is GPL-2.0-or-later** (the COPYING file is GPLv2; per-file headers add "or any later
+  version"). The CC-BY-4.0 on the docs *site* is a footer, not the source license. Copyleft applies
+  to ported code.
+- **It is SPARK/Ada, and designed to run as coreboot boot-firmware**, not a runtime OS driver. A
+  danos port means either an Ada/GNAT toolchain in the build or hand-transliteration into Zig; the
+  SPARK "absence of runtime errors" proof does **not** carry over to your reimplementation (and note
+  it proves absence of runtime errors, **not** functional modeset correctness).
+
+Two more caveats worth knowing: its **error handling is limited** — "only the case that no display
+could be found counts as failure"; a later DP link-training failure is *not* propagated. And its
+**verified-in-coreboot** hardware list stops at **Coffee Lake + Apollo Lake**, even though the tree
+contains a `tigerlake/` directory (Ice Lake has no directory at all, and Alder Lake support is only
+"begun"). So treat Haswell..Coffee Lake as the trustworthy transliteration window and TGL as
+present-but-less-proven.
+
+The orchestration reads as a clean state machine (`hw-gfx-gma.adb` `Enable_Output`):
+`Fill_Port_Config → Preferred_Link_Setting → PLLs.Alloc → [retry] Connectors.Pre_On →
+Display_Controller.On → Connectors.Post_On`, with a literal *"try each DP-lane configuration twice"*
+inner retry and an outer link-setting step-down. `hw-gfx-dp_training.adb` (398 lines) is a complete,
+generic DP link-training implementation (TP1/TP2/TP3, CR + EQ loops, swing/pre-emphasis adjust from
+sink status). Per-generation buffer translations plug in underneath via
+`Program_Buffer_Translations`, gated on `Config.Has_DDI_Buffer_Trans`. All of this was confirmed
+against the source line-by-line.
+
+## The EDID + mode-set path (Haswell/Broadwell target)
+
+The whole path is memory-mapped register programming with polled status bits — no command ring, no
+microcode, no DMA channel.
+
+**EDID over DDC (GMBUS).** Pure MMIO poking of the GMBUS I²C controller (`GMBUS0`–`GMBUS5`): `GMBUS0`
+selects pin-pair/port + clock; `GMBUS1` carries slave address (`0x50` for EDID), byte count,
+direction, SW-ready; `GMBUS2` exposes HW-ready/NAK/ACTIVE to poll; `GMBUS3` is a 4-byte data FIFO;
+`GMBUS5` gives the 2-byte segment index for E-DDC. A read is: write `GMBUS0`, write `GMBUS1`
+(`CYCLE_WAIT | count | SLAVE_READ | SW_RDY | slave<<addr`), loop {poll `HW_RDY`, read 4 bytes}, then
+STOP ([i915 intel_gmbus.c](https://github.com/torvalds/linux/blob/master/drivers/gpu/drm/i915/display/intel_gmbus.c)).
+
+**EDID + DPCD over DP AUX.** For DisplayPort/eDP, EDID (as I²C-over-AUX to `0x50`) and all DPCD
+capability/link-status registers are read over the AUX channel: per-DDI `DDI_AUX_CTL` + 5×
+`DDI_AUX_DATA`. Build a 3–5 byte header + payload, set SEND_BUSY, poll it clear, read
+DONE/TIMEOUT/RECEIVE_ERROR. Message size 1–20 bytes; spec requires ≥3 retries. On Haswell/BDW the AUX
+clock divider is programmed explicitly; SKL+ derive it automatically
+([i915 intel_dp_aux.c](https://github.com/torvalds/linux/blob/master/drivers/gpu/drm/i915/display/intel_dp_aux.c)).
+Both GMBUS and DP-AUX live in libgfxinit's shared `common/` — cheap and nearly gen-invariant.
+
+**The mode-set is a fixed, documented register sequence.** The Broadwell DisplayPort enable order
+(verbatim from BDW PRM Vol 11, pp.98–99): (1) DDI lane capability; (2) panel power sequencing if
+needed; (3) enable the CPU display PLL (WRPLL/SPLL) and wait ~20 µs; (4) Port Clock Select → DDI,
+enable `DP_TP_CTL` with training pattern 1, configure `DDI_BUF_TRANS`, enable `DDI_BUF_CTL`, wait
+>518 µs, run link training, set `DP_TP_CTL` to Normal (Idle first for eDP); (5) Transcoder Clock
+Select, enable the plane, panel fitter if needed, program transcoder timings + M/N/TU, enable
+`TRANS_DDI_FUNC_CTL`, enable `TRANS_CONF`, then backlight. Disable is the exact reverse — a bounded
+checklist.
+
+**DisplayPort/eDP link training is driver-driven in software over AUX** — the CPU runs the
+clock-recovery and channel-equalization state machines by hand; it is **not** offloaded to a hardware
+sequencer or firmware. The source side exposes only primitives: `DP_TP_CTL` selects the training
+pattern the port emits; `DDI_BUF_CTL`/`DDI_BUF_TRANS` set voltage-swing/pre-emphasis. The driver
+loops: emit pattern + set source levels → write `TRAINING_PATTERN_SET` (DPCD 0x102) + `TRAINING_LANEx_SET`
+(0x103) over AUX → delay (100 µs CR / 400 µs EQ) → read `LANE_STATUS` → on failure adjust to the
+sink's `ADJUST_REQUEST` values and retry. A few hundred lines of ordinary CPU/AUX code (libgfxinit
+`Train_DP`: CR loop 1..32, EQ loop 1..6). **This is the single fiddliest, most fragile piece** — a
+TMDS/HDMI panel avoids it entirely, and targeting an already-lit eDP panel avoids most of it.
+
+**The clock (WRPLL) is documented divider math, not a magic table.** On Haswell/BDW the WRPLL derives
+the symbol clock from a 2700 MHz LCPLL reference through R2/N2/P dividers with VCO 2400–4800 MHz —
+small integer arithmetic. DP is *easier* than HDMI because it runs at a few fixed link rates (1.62 /
+2.7 / 5.4 GHz), so a DP/eDP-only minimal driver can often use fixed rates and skip most of the search.
+
+**Plane/scanout programming is trivial for a compositor.** The primary plane is `PRI_CTL`
+(enable + pixel format), `PRI_STRIDE`, `PRI_SURF` (surface base — writing it triggers the atomic
+update), `PRI_OFFSET`; formats include 32-bit BGRX 8:8:8 and 16-bit BGRX 5:6:5 — a direct match for a
+linear XRGB compositor buffer. Plane registers are double-buffered and latch at vblank via an
+**arming** write — so a page-flip is "write base + stride + size, then the arming write." This is
+*exactly* the primitive danos's damage-driven compositor already expresses over GOP/virtio-gpu; the
+incremental work is "program these display-domain registers," not a new scanout model. The panel
+fitter (`PF_WIN_POS`/`PF_WIN_SZ`/`PF_CTRL`) can be left disabled for native-resolution scanout;
+Skylake+ replaces it with a shared pipe-scaler (`PS_CTRL`).
+
+**Smallest useful target:** eDP (DDI A / transcoder-EDP) or a single DP output at native resolution,
+panel fitter off, plane in 32bpp XRGB. That is: GMBUS + I²C-over-AUX EDID/DPCD, one fixed-rate or
+WRPLL config, the ~20-step enable sequence, the software CR/EQ loop, and `PRI_*` plane setup with
+`PRI_SURF`-write flips. Out of scope: 3D, media, tiling, RC6/power-gating, PSR, audio.
+
+## Memory and scanout
+
+This is where Intel's *architecture* — not just its docs — makes the job smaller, and it is the
+biggest single simplification versus a discrete GPU.
+
+- **No VRAM.** Intel iGPUs have a unified memory architecture; the display scans out of ordinary
+  **system RAM** addressed through the **Global GTT (GGTT)**. The only way to give the GPU memory is
+  to bind system pages into the GGTT
+  ([i915/GEM crashcourse](https://blog.ffwll.ch/2012/10/i915gem-crashcourse.html)).
+- **The plane surface register is a GGTT offset**, not a raw physical address — the display walks the
+  GGTT to fetch pixels, so a scanout buffer must be GGTT-mapped (global, not per-process). libgfxinit
+  writes the framebuffer offset straight into `DSPSURF`/`PLANE_SURF` masked to 4 KB.
+- **Linear (untiled) scanout is a first-class supported mode** — the plane's tiling field value 0 is
+  Linear. No X/Y/Yf tiling engine is needed for a display-only driver. (UEFI GOP itself hands off a
+  linear framebuffer the plane is already scanning.)
+- **No memory manager.** You need only (1) some contiguous-ish system pages and (2) GGTT PTEs
+  pointing at them (`physical_addr | valid_bit` — the GGTT is a flat single-level array of PTEs in
+  the `GTTMMADR` MMIO BAR), then program the plane. **No GEM/TTM/PPGTT/GuC.** coreboot's native-init
+  literally does `for(i…) WRITE32(base + i*inc | 1, (i*4) | 1)`.
+- **"Stolen memory"** (GSM/DSM) is firmware-reserved system RAM where the firmware places the GGTT
+  itself and the boot framebuffer. A driver is not obligated to keep scanout there — it can rebind
+  GGTT entries to its own pages. Stolen memory matters mainly for *inheriting* the GOP framebuffer at
+  handoff.
+
+**The contrast with NVIDIA is stark.** On a discrete GPU the scanout surface must live in **VRAM**
+(nouveau always pins scanout to VRAM), CPU access goes through the **BAR1** aperture (which on
+consumer cards can be far smaller than total VRAM unless Resizable BAR is on), and you need a
+contiguous aligned VRAM allocator plus a BAR1 mapping. The Intel iGPU path **eliminates all of that**
+— scanout is plain system RAM, and a userspace compositor can write the framebuffer pages directly
+(as danos already does with the GOP WC framebuffer).
+
+Because danos boots via GOP, an Intel driver attaches to a display whose **GGTT is already populated
+and whose plane is already scanning a linear framebuffer at native resolution.** A minimal driver can
+reuse that live mapping and reprogram the running plane rather than come up from cold — the same
+"attach to a live display" advantage the NVIDIA doc identifies, but with a far smaller register
+surface and no firmware wall. *(Low-confidence, per-target details to pin from the specific gen's
+PRM: GGTT PTE size — 4-byte pre-gen8 vs 8-byte gen8+ — the `GTTMMADR`/aperture BAR layout, surface
+alignment — 4 KB floor but some gens/tilings want 256 KB — and whether the display's GGTT-mediated
+DMA sits before or after danos's M16 IOMMU on the target platform.)*
+
+## Firmware
+
+A minimal display-only Intel driver is **effectively firmware-free — more so than NVIDIA.**
+
+- **DMC (Display Microcontroller, "CSR", Skylake+) is NOT required for mode-set or scanout.** Its
+  sole job is saving/restoring display-engine registers across DC5/DC6 low-power idle. Absent, i915
+  prints *"Failed to load DMC firmware … Disabling runtime power management"* and the display
+  mode-sets and scans out normally — you lose only the deep display idle states, not output
+  ([intel_dmc.c](https://github.com/torvalds/linux/blob/master/drivers/gpu/drm/i915/display/intel_dmc.c);
+  corroborated by multiple distro bug threads). *(A source-level `HAS_DMC` early-return citation would
+  strengthen this beyond distro testimony, but the conclusion is well-supported.)*
+- **Pre-Skylake parts have no display microcontroller at all** yet perform full mode-set (and even
+  Panel Self Refresh). This confirms the display engine is fundamentally CPU/MMIO-driven; the
+  microcontroller is an add-on for autonomous idling, not a prerequisite for lighting a panel.
+  Targeting a pre-Skylake or DMC-optional generation sidesteps the question entirely.
+- **GuC and HuC are render/media microcontrollers on the GT side** — GuC schedules the render engines,
+  HuC assists HEVC/H.265 codec (plus later HDCP/PXP/GSC). Neither is in the scanout path; a
+  display-only driver never loads them
+  ([kernel.org microcontrollers](https://docs.kernel.org/gpu/i915.html)).
+- **PSR firmware lives on the panel**, not in the OS — a minimal driver simply doesn't enable PSR.
+- **Type-C/TCSS (Ice Lake+) firmware** (PMC/IOM/PHY) is part of platform BIOS/coreboot init and the
+  hardware, *not* a signed blob the display driver loads at runtime. A driver attaching to an
+  already-lit GOP connector, or targeting classic DDI ports, avoids it. *(Cold DP-alt-mode changes
+  from a userspace driver on modern TCSS platforms were not traced to primary source — flagged.)*
+
+There is **no signed-firmware wall over the Intel GPU at all** on the display path. This is the
+architectural opposite of NVIDIA's mandatory, unsignable, ABI-unstable GSP — which even on the
+near-side "direct" display path is a permanent maintenance liability for anything beyond scanout.
+
+## Licensing
+
+The situation is *better* than NVIDIA's but still nuanced.
+
+- **The two best code references are both GPL** — Linux i915 (GPL-2.0) and coreboot libgfxinit
+  (GPL-2.0-or-later). You cannot copy either into a permissively-licensed danos. libgfxinit's WRPLL
+  divider math is itself copied from i915, so it carries the same encumbrance.
+- **But you don't need to copy code.** The Intel PRM is a *specification*, and a clean-room Zig
+  implementation written from the PRM (using libgfxinit/i915 only to understand behaviour, never to
+  copy) is legitimate — register numbers and bit definitions are functional facts, not copyrightable
+  expression. This is the exact inverse of the NVIDIA case, where no such spec exists and the only
+  guide is the GPL/RE'd code itself.
+- **A permissive precedent exists: Haiku's `intel_extreme` is MIT-licensed** and was built from
+  Intel's public docs. So if danos wants a permissive license, the model is: implement from the PRM,
+  optionally read MIT Haiku for structure, treat GPL libgfxinit/i915 as documentation-of-last-resort.
+- **A licensing nuance on the recommended generations:** the "copy the 0BSD PRM code samples" shortcut
+  only applies to Tiger-Lake-era (2021+) PRMs. The Haswell/Broadwell/Skylake PRMs are CC-BY-ND, so
+  their register *facts* are free to implement but there are no code samples to lift.
+
+As with the NVIDIA doc: danos's userspace-driver-over-IPC model (a driver is a separate process behind
+a defined protocol) is the cleanest possible license boundary if the project ever chooses to ship a
+GPL display-driver binary and keep the rest of danos permissive — but that is a boundary judgement
+wanting real diligence, not a settled fact. The clean-room-from-PRM route avoids the question.
+
+## Prior art outside Linux
+
+This is a **real contrast with NVIDIA**, where no one has built a from-scratch native driver outside
+Linux. For Intel there are **multiple independent, non-Linux, clean-room native modeset
+implementations** to learn from:
+
+- **coreboot libgfxinit** — SPARK/Ada, G45/GM45 and Arrandale → Coffee Lake + Apollo Lake (TGL
+  in-tree), the strongest structural reference.
+- **Haiku `intel_extreme`** — modeset-only (no 2D/3D accel), **MIT-licensed**, i845 through Sandy
+  Bridge solid, newer Gemini/Ice/Tiger Lake in progress but "hit or miss, as the driver lags behind
+  the specs" ([Haiku generations](https://www.haiku-os.org/docs/develop/drivers/intel_extreme/generations.html),
+  [Phoronix Sept 2024](https://www.phoronix.com/news/Haiku-OS-September-2024)).
+- **SerenityOS** — added basic native Intel graphics ([PR #6277](https://github.com/SerenityOS/serenity/pull/6277)),
+  though only for very old ICH7-class hardware.
+- **managarm** — native Intel G45 support.
+
+The catch: **every clean-room non-Linux implementation targets old hardware.** A modern Gen12 "Xe"
+desktop iGPU is beyond all of them; for the very newest parts only GPL i915 covers the registers. So
+the wealth of prior art is real but concentrated below Tiger Lake.
+
+## The practical desktop caveat
+
+Before any effort estimate is trusted, three hardware realities — the honest reason "Intel is easier"
+does **not** automatically mean "it'll light up the reader's monitor":
+
+1. **Muxing / cabling.** On a desktop with a discrete RTX 3060, the monitor is almost certainly
+   plugged into the *card's* outputs, not the motherboard's. An iGPU driver would light a
+   **different, currently-dark** output. To see danos on Intel the reader would have to physically
+   move the cable to a motherboard video port **and** likely enable the iGPU / "IGD Multi-Monitor" in
+   BIOS. Intel-first probably does **not** light the current display without re-cabling.
+2. **No iGPU at all.** Intel **F-SKU** desktop chips (i5-9400F, i5-12400F, i5-13400F, i7-13700KF, …)
+   ship the graphics **fused off** and cannot be re-enabled. These are extremely common in
+   budget/mid gaming builds paired with an RTX 3060. On an F-SKU (or an X-series HEDT part) the
+   Intel-iGPU path is a **non-starter** regardless of cabling.
+3. **Generation coverage.** If the CPU *is* a recent non-F part, its iGPU may be Gen12 Xe (Alder/
+   Raptor Lake), beyond libgfxinit's verified set and beyond most non-Linux prior art — leaving GPL
+   i915 (or the TGL-class PRM, which covers Alder/Raptor display IP) as the only reference.
+
+A cleaner path for *learning* without the hardware lottery: an older bare-metal Intel box (Haswell/
+Skylake NUC or laptop) whose panel is natively on the iGPU. Note QEMU does **not** emulate an Intel
+iGPU display engine, so a VM cannot exercise a real Intel modeset path — virtio-gpu (already working)
+is the VM answer.
+
+## Alternatives, and the honest Intel-vs-NVIDIA verdict
+
+| Option | What you get | The tradeoff |
+|---|---|---|
+| **Stay on GOP** (working today) | Native-res scanout, zero GPU code/firmware/maintenance | Resolution frozen at ExitBootServices; no runtime mode change, no hardware vsync, no multihead |
+| **Intel iGPU, reuse-GOP** | EDID read + plane page-flips on the GOP-set mode | Still bounded to GOP's resolution; but real driver-owned scanout |
+| **Intel iGPU, full modeset** (this doc) | Runtime modeset, vsync, multihead, from public docs | Tier 2–3 effort; DP link training; per-gen churn; **needs a cable-attached, documented iGPU** |
+| **Native NVIDIA GA106 direct** ([nvidia-gpus.md](nvidia-gpus.md)) | Same, on the RTX 3060 the monitor is actually plugged into | **Tier 4**; GPL-only reference; DMA channel modeset; de-emphasised legacy path |
+| **GA106 via GSP/OGKM** | Also unlocks 3D later | Tier 5; unstable version-pinned firmware ABI |
+
+**The verdict for *this reader* (RTX 3060 box):** For pure "see danos on my screen," **NVIDIA-direct
+is paradoxically the more relevant path**, because the monitor is already cabled to the 3060 and GOP
+already drives it — a native NVIDIA driver reprograms *that* live display. An Intel driver, however
+much easier to *write*, likely lights a dark motherboard port the reader isn't looking at, or hits an
+F-SKU with no iGPU.
+
+**The verdict for *learning display bring-up*:** **Intel wins decisively.** Public register PRMs, four
+independent open reference drivers, an MIT precedent (Haiku), a compact formally-analysed blueprint
+(libgfxinit), no signed-firmware wall, no VRAM/BAR memory manager, and a legitimate permissive
+clean-room path. It reaches "first pixel" far faster than the NVIDIA native path — *on hardware that
+actually has a cable-attached, documented Intel iGPU.* Those two goals — "run on my machine" and
+"learn the craft" — point at different silicon, and that is the honest bottom line.
+
+## "First light" milestones — a danos `.scanout` service
+
+Framed as a danos `.scanout` service (like the virtio-gpu and proposed NVIDIA ones), inheriting the
+GOP-initialized display — no firmware, no cold POST:
+
+1. **PCI/BAR bring-up** — enumerate the iGPU, map its MMIO BAR (`GTTMMADR` + register block) and the
+   aperture BAR via danos MMIO grants; confirm the display engine is GOP-live.
+2. **EDID** — implement GMBUS DDC (`0x50`) and DP AUX; read + parse the panel EDID and DPCD caps.
+   *(Smallest self-contained, gen-invariant milestone — a good first commit.)*
+3. **First pixel = reprogram, don't re-modeset** — with GOP's mode and GGTT mapping inherited,
+   reprogram the running plane (`PRI_CTL`/`PRI_STRIDE`/`PRI_SURF`, linear, 32bpp XRGB) to point at a
+   danos-owned system-RAM buffer; prove a page-flip via the `PRI_SURF` arming write on the *current*
+   mode before changing timings. This defers the entire DPLL/DDI/transcoder/link-training surface —
+   the hardest, most gen-specific ~70% of the work.
+4. **GGTT ownership** — write your own GGTT PTEs (via an MMIO grant to `GTTMMADR`) pointing at
+   compositor-owned pages, for double-buffered damage-driven present.
+5. **Wire into the compositor `.scanout` backend** (`attach_scanout`); add vsync via the display
+   vblank interrupt (IRQ-as-IPC).
+6. **Full mode-set** (the hard, gen-specific step) — for one chosen generation (Haswell/Broadwell or
+   Skylake): WRPLL/DPLL programming, the ~20-step DDI/transcoder/pipe enable sequence, panel power
+   sequencing for eDP (`PP_CONTROL`/`PP_ON_DELAYS`/`PP_OFF_DELAYS` — a common black-screen pitfall).
+7. **DisplayPort link training** — only if the panel is DP and GOP's link can't be reused; the
+   software CR/EQ state machine over AUX. TMDS/HDMI avoids it; a live eDP panel avoids most of it.
+8. **Multihead**, then optionally a second generation once one is solid.
+
+Keep the GOP backend as the fallback the whole way — a stall at any step still leaves danos with a
+working display, exactly the resilience v2 already provides via re-attach.
+
+## Reading list
+
+**Native reference — coreboot libgfxinit (GPL-2.0-or-later, SPARK/Ada):**
+- `common/hw-gfx-gma.adb` — `Enable_Output`, the end-to-end modeset state machine.
+- `common/hw-gfx-dp_training.adb` — the complete generic DP link-training CR/EQ loops.
+- `common/hw-gfx-gma-pipe_setup.adb` — plane/pipe/scaler + `DSPSURF`/`DSPSTRIDE`/`DSPCNTR` scanout.
+- `common/hw-gfx-gma-transcoder.adb` — timing generator; `common/hw-gfx-edid.adb`,
+  `hw-gfx-gma-i2c.adb`, `hw-gfx-dp_aux_ch.adb` — EDID/DDC/AUX; `hw-gfx-gma-registers.ads` — offsets.
+- `common/haswell*/`, `skylake/`, `tigerlake/` — the per-gen PLL/PHY/buffer-translation backends.
+
+**Vendor register specs — Intel OSRC PRMs:**
+- [Broadwell Vol 11: Display](https://cdrdv2-public.intel.com/690828/intel-gfx-prm-osrc-bdw-vol-11-display.pdf)
+  (CC-BY-ND) — the recommended Haswell/Broadwell-class enable sequences, plane, panel fitter.
+- [Tiger Lake Vol 12: Display Engine](https://cdrdv2-public.intel.com/705833/intel-gfx-prm-osrc-tgl-vol-12-display-engine.pdf)
+  (code samples 0BSD) — the most complete modern reference incl. PLL/voltage-swing value tables.
+- [DG2/Arc Vol 12: Display Engine](https://www.x.org/docs/intel/ACM/intel-gfx-prm-osrc-acm-vol12-displayengine.pdf)
+  — the newest public display PRM (Gen12.5, 2022).
+- [Igalia CC-BY-ND archive](https://github.com/Igalia/intel-osrc-gfx-prm) (Gen4–Gen9.5) and the
+  [kiwitree mirror](https://kiwitree.net/~lina/intel-gfx-docs/prm/) — stable mirrors.
+
+**GPL reference-of-last-resort — Linux i915 display:**
+- `intel_gmbus.c`, `intel_dp_aux.c` — the concrete EDID/DDC and DP-AUX register sequences.
+- `intel_ddi.c` / `intel_ddi_buf_trans.c`, `intel_cdclk.c`, `intel_dpll_mgr.c` — DDI/CDCLK/PLL;
+  `i9xx_plane.c`, `intel_crtc.c` — plane/pipe; `intel_dp.c` — link training. Huge and modular; a
+  reference to confirm undocumented quirks, not a template.
+
+**Permissive prior art — Haiku `intel_extreme` (MIT):**
+- [`src/add-ons/kernel/drivers/graphics/intel_extreme/`](https://github.com/haiku/haiku/tree/master/src/add-ons/kernel/drivers/graphics/intel_extreme/)
+  — a second independent modeset-only driver; MIT, so structurally readable for a permissive danos.
+- [generations.html](https://www.haiku-os.org/docs/develop/drivers/intel_extreme/generations.html)
+  — the best plain-English per-generation fault-line map.
+
+## Open questions (unresolved by the survey)
+
+- **Does the target machine have a usable, cable-attached iGPU at all?** F-SKU check, CPU generation,
+  and monitor cabling must be resolved before any effort estimate is trusted (see
+  [practical caveat](#the-practical-desktop-caveat)).
+- **Does danos even need native mode-*setting*, or only plane/scanout control on the GOP-set mode?**
+  If runtime mode changes aren't required, the driver collapses to EDID + plane page-flips, dropping
+  the DPLL/DDI/link-training ~70% of the work.
+- **GGTT vs raw physical:** confirm from the exact target-gen PRM that `PLANE_SURF` is interpreted as
+  a GGTT graphics address (well-established, but per-gen confirmation advisable), and the PTE size /
+  `GTTMMADR` / aperture layout for writing GGTT entries.
+- **Reuse the firmware/GOP GGTT + framebuffer, or install your own GGTT entries?** The latter (needed
+  for double-buffering) means writing GGTT PTEs from the userspace driver via an MMIO grant.
+- **eDP panel power sequencing** (`PP_*`, T1–T12 delays) — not covered in this pass and a common
+  black-screen source.
+- **IOMMU interaction** — whether the display's GGTT-mediated DMA needs IOMMU passthrough for the
+  framebuffer pages under danos's M16 IOMMU, or sits before the IOMMU on the target platform.
+- **DP link-training / AUX robustness and per-generation register drift** are the dominant *risks* —
+  not documentation scarcity.
+- **Exact Haswell/BDW MMIO offsets** (commonly cited: GMBUS ~`0xC5100`, `DDI_AUX_CTL_A` ~`0x64010`,
+  `DDI_BUF_CTL_A` ~`0x64000`, `DP_TP_CTL_A` ~`0x64040`) were not extracted verbatim from the PRM —
+  confirm against `i915_reg.h` before coding.
+
+---
+
+*Research snapshot; verify against current libgfxinit / i915 source and the specific target
+generation's PRM before building. Intel's public-PRM coverage and the muxing/F-SKU realities of a
+given machine both change what is actually achievable.*

docs/ipc.md

@@ -95,6 +95,30 @@ This is what makes a user-space driver possible at all, and it's the subject of
   every capability is either well-known (the registry) or inherited — there's no way
   to delegate one.
 - **Asynchronous / buffered send** for the cases where a rendezvous is the wrong
-  shape (logging, notifications between servers).
+  shape (logging, notifications between servers). *Landed as `ipc_send`* — a
+  non-blocking post to an endpoint's bounded payload queue, delivered through
+  `reply_wait` as a buffered message (badge bit `notify_message_bit`). Built for, and
+  first used by, the [input service](input.md)'s keyboard-event broadcast, where a
+  synchronous push would let one dead subscriber hang the fan-out. A full queue drops
+  the oldest (discrete messages, not a coalescing level like the notification ring).
 - **A bounded reply.** `MSG_MAX` is 256 bytes and the copy runs under the big kernel
   lock; a bulk transfer wants shared pages, not a copy.
+
+## Lifecycle conventions over IPC (M17)
+
+Three conventions from [process-lifecycle.md](process-lifecycle.md) ride the
+notification mechanism:
+
+- **Signals** arrive as notifications on the endpoint a process nominated with
+  `signal_bind` (`runtime.process.bindSignals`): badge = the signal bit plus the
+  coalesced pending mask (`runtime.process.signalsFrom` decodes). Statements,
+  never questions; no payload, no reply.
+- **One-shot timers** (`timer_bind`, `runtime.system.timerOnce`) land as a
+  timer-bit notification — the timed wait: a service arms a deadline and keeps
+  serving, instead of blocking in sleep.
+- **The universal ping**: a **zero-length request is the liveness probe**,
+  answered with a zero-length reply by the service harness itself
+  (`runtime.service.run`). No protocol's requests start at length zero, so the
+  encoding cannot collide, and a wedged service simply fails to answer — which
+  is the diagnosis. Deep health ("can I reach my hardware?") stays a per-service
+  protocol message.

docs/nvidia-gpus.md

@@ -0,0 +1,246 @@
+# Native NVIDIA GPU support — feasibility and roadmap
+
+**Status: research snapshot, not implemented.** This records what a *native* display driver for a
+real discrete NVIDIA GPU — specifically an **RTX 3060 (Ampere GA106)** — would take, and how it
+would slot into danos's pluggable scanout architecture. It is a survey of primary sources
+(NVIDIA's [open-gpu-kernel-modules](https://github.com/NVIDIA/open-gpu-kernel-modules), the Linux
+[nouveau/nvkm](https://github.com/torvalds/linux/tree/master/drivers/gpu/drm/nouveau) driver,
+NVIDIA's [open-gpu-doc](https://nvidia.github.io/open-gpu-doc/), and
+[linux-firmware](https://github.com/NVIDIA/linux-firmware)), not an implementation. The NVIDIA
+driver landscape moves quickly (GSP defaults, firmware ABIs); treat specifics as a mid-decade
+snapshot and re-verify against current source before building.
+
+Read [display.md](display.md) and [display-v2.md](display-v2.md) first — this doc assumes the
+v2 model where scanout is a **pluggable backend** and a native driver is just another `.scanout`
+service (like the virtio-gpu one), announcing to the compositor over `attach_scanout`.
+
+## TL;DR
+
+- A **minimal display-only driver** (EDID + mode-set + framebuffer scanout, **no** 3D/compute)
+  for the RTX 3060 **can and should avoid the GSP entirely**. nouveau has a register-level,
+  CPU-driven display path for Ampere (`nvkm/engine/disp/ga102.c`) that lights up GA106 with no
+  external firmware; the signed-firmware wall gates the **compute/graphics** engines (PGRAPH),
+  **not** the display controller. "GSP is mandatory on Ampere" is true only for NVIDIA's own
+  RM-object route.
+- **danos's UEFI GOP boot is the single biggest thing in its favour.** The VBIOS/GOP has already
+  run devinit and brought up the display PLLs, so a driver attaches to a **live, initialized**
+  GA106 — no firmware load, no cold-boot POST, no devinit interpreter. You reprogram a running
+  display rather than bring one up from cold.
+- It is still a **hard, multi-week-to-months expert effort** (effort tier ≈ 4/5) dominated by
+  NVDisplay channel-DMA programming, SOR/head routing, DisplayPort AUX + link training, and the
+  display supervisor handshake. The GSP/RM route is tier 5 (near-infeasible solo).
+- The **licensing tension is counterintuitive**: the permissively-licensed reference (NVIDIA
+  open-gpu-kernel-modules, MIT/GPLv2) is the **hard GSP path**; the register-level display code
+  you actually want lives in **GPL nouveau**. See [Licensing](#licensing).
+- The **window is closing**: GA10x (Ampere) is the *last* NVIDIA family with a register-level
+  display path — Ada (RTX 40) deleted its non-GSP display HAL. Targeting Ampere specifically
+  matters.
+- **Recommendation:** for *this card*, GOP already gives native-resolution scanout with zero GPU
+  code and zero maintenance. A native driver buys only runtime mode changes, hardware
+  vsync/vblank, and multihead. It is justified if that runtime control is a danos goal, or to
+  *learn the craft* — for which an Intel iGPU or a pre-Turing NVIDIA card reaches "first pixel"
+  far faster.
+
+## The GSP wall, and why display sits on the near side of it
+
+On Turing and later, NVIDIA split its driver's Resource Manager into a host **CPU-RM** and a
+**GSP-RM** running on an on-die RISC-V core ("Peregrine"), talking over RPC
+([LWN 953144](https://lwn.net/Articles/953144/)). The GSP is a *full resource manager*, not a
+display coprocessor — there is no "display-only" GSP image and no small display RPC subset. Its
+boot chain is entirely signed and mandatory: a VBIOS-resident **FWSEC-FRTS** app carves a
+write-protected region (WPR2), a signed **Booter** on the SEC2 falcon loads the GSP bootloader,
+and that loads **GSP-RM** inside WPR. The firmware ships pre-computed signatures and the driver
+picks one by an on-chip fuse-version register — **you cannot self-sign**, and there is **no stable
+firmware ABI** (it is revised every driver release; nouveau and the Rust nova-core driver each pin
+exactly one version). A GSP driver is a permanent maintenance liability, not a one-time build
+([LWN 1037379](https://lwn.net/Articles/1037379/),
+[nova-core cover letter](https://lore.freedesktop.org/nouveau/20250826-nova_firmware-v2-7-93566252fe3a@nvidia.com/T/)).
+
+**But display doesn't need any of that on Ampere.** `nvkm/engine/disp/ga102.c` dual-dispatches:
+
+```
+if (nvkm_gsp_rm(device->gsp)) return r535_disp_new(&ga102_disp, ...);  // GSP RPC path
+return nvkm_disp_new_(&ga102_disp, ...);                               // direct register path
+```
+
+Both branches use the same `ga102_disp` HAL and the same `GA102_DISP_*` class IDs; GSP merely
+swaps register programming for RPC. GA106 (chipset `0x176`) is wired to `ga102_disp_new` in the
+device table, identical to GA102/103/104/107. Ampere lit up displays via the **direct** path in
+Linux 5.11/5.17 — two years before GSP-RM landed (6.7, 2023)
+([ga102.c](https://raw.githubusercontent.com/torvalds/linux/master/drivers/gpu/drm/nouveau/nvkm/engine/disp/ga102.c),
+[Phoronix GA106](https://www.phoronix.com/news/Nouveau-NVIDIA-GA106)).
+
+**Caveat — this is now the legacy path.** As of Linux 6.18, nouveau defaults to GSP on
+Turing/Ampere; the direct path is a retained, forceable fallback (`nouveau.config=NvGspRm=0`, and
+automatic when GSP firmware is absent). It is stable and proven, but NVIDIA and nova-core are
+moving to GSP-only, and **Ada already deleted its non-GSP display HAL**. GA10x is the last family
+that keeps a register-level display path.
+
+## What "direct" actually entails
+
+"Direct" is not "plain register pokes." Only SOR / PLL / DP-link / clock setup is bare MMIO. The
+**mode-set and scanout themselves flow through the NVDisplay channels — a DMA pushbuffer**:
+
+- Display classes for Ampere (the C670 family): core `GA102_DISP_CORE_CHANNEL_DMA` (`0xc67d`),
+  window `0xc67e`, window-immediate `0xc67b`, cursor `0xc67a` (headers `clc67d.h` / `clc67e.h` /
+  `clc67a.h` in [open-gpu-doc `classes/display/`](https://github.com/NVIDIA/open-gpu-doc/tree/master/classes/display)).
+- The core channel needs **instance memory, a RAMHT, DMA objects, and a channel user-MMIO
+  region** ([disp/chan.c](https://raw.githubusercontent.com/torvalds/linux/master/drivers/gpu/drm/nouveau/nvkm/engine/disp/chan.c)).
+  The register-level "plumbing" to allocate/kick a channel is in NVIDIA's GA102 display register
+  manual: `NV_PDISP_FE_CHNCTL_CORE/WIN/CURS`, `NV_PDISP_FE_PBBASE/PBBASEHI`
+  ([dev_display_withoffset.ref.txt](https://raw.githubusercontent.com/NVIDIA/open-gpu-doc/master/manuals/ampere/ga102/dev_display_withoffset.ref.txt)).
+- **Mode-set is a method stream** on the core channel: `HEAD_SET_RASTER_*`,
+  `HEAD_SET_PIXEL_CLOCK_FREQUENCY`, `HEAD_SET_CONTROL_OUTPUT_RESOURCE`, `SOR_SET_CONTROL`
+  (protocol select), viewport/scaler, then `UPDATE`. The window channel points at the scanout
+  surface (`SET_CONTEXT_DMA_ISO`, `SET_STORAGE`, `SET_OFFSET`).
+- After `UPDATE` you must complete the display **supervisor** interrupt handshake (SV1/SV2/SV3).
+
+**EDID and DisplayPort are a separate subdev you must port.** open-gpu-doc documents *none* of
+EDID/DDC/AUX. On the direct path you read EDID in-driver via nouveau's `nvkm/subdev/i2c`: bit-bang
+**DDC/I²C at address `0x50`** (E-DDC `0x30`) for TMDS/HDMI, or native **DP AUX** in `i2c/aux.c`
+for DisplayPort. DisplayPort **link training** (the `dp.c` `train_cr` / `train_eq` state machine
+over AUX — clock recovery, lane/rate, voltage-swing/pre-emphasis) is the single hardest and most
+fragile piece; a DVI/HDMI (TMDS) panel avoids it entirely.
+
+## The memory floor (smaller than you'd fear)
+
+Neither route hands you a framebuffer allocator — even GSP-RM does not manage the scanout
+framebuffer; the driver owns VRAM and merely tells GSP where its page directory is. But
+display-only is a small fraction of a full GEM/TTM stack:
+
+- **Pitch-linear (untiled) scanout is allowed** on nv50→Ampere — the window's storage method has a
+  `PITCH` layout mode, so you skip block-linear tiling math
+  ([wndwc37e.c](https://raw.githubusercontent.com/torvalds/linux/master/drivers/gpu/drm/nouveau/dispnv50/wndwc37e.c)).
+- The window references its surface through a simple **display context-DMA**
+  (`SET_CONTEXT_DMA_ISO` + a 256-byte-granular `SET_OFFSET = addr>>8`) — a base/limit descriptor,
+  **not** the GPU's 5-level compute page tables. **No full GPU VMM is needed** for scanout.
+- The surface must live in **VRAM** in practice (nouveau always pins scanout to VRAM). *Open
+  question:* whether GA10x can scan out from a system-memory (GART) surface via a sysmem-target
+  ctxdma — which would let danos skip a VRAM allocator. No source forbids it; nouveau never does
+  it (confidence: medium).
+- **CPU access** to the framebuffer for compositing goes through **BAR1** (a VRAM aperture); BAR0
+  is the 16 MB register window. BAR1 can be smaller than 12 GB of VRAM unless Resizable BAR maps
+  it all.
+
+**Net:** you need (1) a contiguous aligned VRAM allocator (256-byte base, pitch a multiple of
+64 bytes — confirm against the Ampere display refs), (2) a little instmem for the channel
+pushbuffers + iso ctxdma, (3) a BAR1 CPU mapping. You do **not** need the 5-level VMM, GEM/TTM
+eviction, or tiling.
+
+## Licensing
+
+The tension is the opposite of convenient:
+
+- **NVIDIA open-gpu-kernel-modules is dual MIT/GPLv2** — usable under MIT, no copyleft on your
+  other code — **but its display logic is the GSP/RM-object route.** Its class headers
+  (`cl0073.h`, `cl2080.h`, `ctrl0073*.h`) are useful, permissive references.
+- **nouveau is GPLv2**, and the **register-level display sequences you actually want live in
+  nouveau**, not in the MIT code. So the *easy technical path is the GPL-licensed one.* Reading
+  GPL nouveau and reimplementing it in Zig is a derivative-work risk proportional to how closely
+  your code tracks its structure/constants.
+
+Options: **(a)** accept that the danos NVIDIA display driver is a **GPL component**. danos's
+userspace-driver-over-IPC model (a driver is a separate process behind a defined protocol, not
+linked into the kernel) is about the cleanest possible GPL boundary, so the GPL would be contained
+to that one binary and the rest of danos could keep its own license — but this is a
+licensing-boundary judgement that wants real diligence, not a settled fact. **(b)** clean-room
+from *specification* rather than *code*: [envytools](https://envytools.readthedocs.io) + NVIDIA's
+open-gpu-doc register manuals + the MIT OGKM class headers, treating nouveau as
+documentation-of-last-resort.
+
+**Firmware licensing is moot for the direct path** (no firmware is loaded). For completeness: the
+GSP blobs are marked redistributable under `LICENCE.nvidia`, which permits use by **any
+OSI-approved open-source OS** (not just Linux), on NVIDIA GPUs, **unmodified**, with **no
+reverse-engineering of the firmware binary**. The one gate — is danos released under an OSI
+license? — is only reached on the GSP route, which this doc recommends against for this card.
+
+## Prior art
+
+**No one has built a from-scratch native NVIDIA driver outside Linux.** FreeBSD ships
+`nvidia-drm-kmod`, a *port of NVIDIA's own closed `nvidia-drm.ko`* loading the GSP blob (its old
+nouveau port was removed). Haiku's NVIDIA support is likewise a *port of OGKM* (GSP, Turing+, very
+alpha). OpenBSD / DragonFly have neither. Every non-Linux OS that supports modern NVIDIA chose to
+**wrap NVIDIA's GSP stack** rather than write a native driver. A danos direct-register driver
+would have exactly one reference implementation — GPL nouveau — and no non-Linux precedent.
+
+## Alternatives
+
+| Option | What you get | The tradeoff |
+|---|---|---|
+| **Stay on GOP** (working today) | Native-res scanout, zero GPU code/firmware/maintenance | Resolution frozen at ExitBootServices; **no runtime mode change, no hardware vsync, no multihead** |
+| **Pre-Turing NVIDIA** (Kepler / early Maxwell) | Direct EVO/disp-core + CRTC/PLL modeset, **no signed firmware, no coprocessor**; mature nouveau reference | Older display class; not this card; only reclocking is firmware-gated |
+| **Intel iGPU** | **Publicly documented** register interfaces (Intel PRMs); no coprocessor mediating modeset | i915 is huge + generation-specific; write one generation from the PRM |
+| **Native GA106 direct** (this doc) | Runtime modeset, vsync, multihead on the actual card | Tier-4 effort; GPL reference; DP link training; legacy/de-emphasized path |
+| **GA106 via GSP/OGKM** | Also unlocks 3D / reclocking later | Tier-5; ~14k-line ante; unstable version-pinned ABI; unprecedented outside Linux |
+
+## "First light" milestones (direct path, inheriting GOP state)
+
+Framed as a danos `.scanout` service (like the virtio-gpu driver), taking the direct register path
+and inheriting the GOP-initialized display — no signed firmware, no devinit, no GSP:
+
+1. **PCI/BAR bring-up** — enumerate GA106 (`0x176`), map **BAR0** (registers) and **BAR1** (VRAM
+   aperture) via danos MMIO grants; confirm the display engine is GOP-live.
+2. **VRAM + instmem allocator** — contiguous aligned VRAM for the scanout surface (256-byte base)
+   + small instmem for pushbuffers / RAMHT / iso ctxdma. No VMM, no TTM.
+3. **EDID** — port `nvkm/subdev/i2c` DDC (`0x50`) + DP-AUX (`aux.c`); read + parse the panel EDID.
+4. **Core channel up** — allocate the `0xc67d` core channel as a DMA pushbuffer; stand up the
+   SV1/SV2/SV3 supervisor-interrupt handshake.
+5. **First pixel = reprogram, don't re-POST** — bind a window (`0xc67e`) at the existing WC
+   framebuffer via `SET_CONTEXT_DMA_ISO` + `SET_OFFSET`, pitch-linear, `UPDATE`; prove you can
+   drive the *current* GOP mode from your own channel before changing anything.
+6. **Modeset** — push raster timings on a head, route head→SOR→connector, program the pixel-clock
+   PLL, switch to an EDID mode (needs the `clc67d/e` method opcodes from the OGKM headers + the
+   supervisor timing from nouveau `head.c`).
+7. **DisplayPort link training** — only if the panel is DP and GOP's link can't be reused; the
+   `dp.c` `train_cr`/`train_eq` state machine. TMDS/HDMI is far simpler.
+8. **Wire into the compositor `.scanout` backend** (`attach_scanout`), add vsync via the display
+   interrupt, then multihead.
+
+Keep the GOP backend as the fallback the whole way — a stall at any step still leaves danos with a
+working display (exactly the resilience v2 already provides via re-attach).
+
+## Reading list
+
+**Direct path — nouveau (GPLv2):**
+- `nvkm/engine/disp/ga102.c` — the GA10x display HAL + the GSP/non-GSP dispatch.
+- `nvkm/engine/disp/{head.c, ior.c, dp.c, hdmi.c, chan.c}` — head/SOR routing, DP AUX + link
+  training, channel-DMA plumbing.
+- `dispnv50/{corec37d.c, corec57d.c, wndwc37e.c, wndwc57e.c, wndwc67e.c, headc37d.c, cursc37a.c}`.
+- `nvkm/subdev/i2c` (DDC + `aux.c`) for EDID; `nvkm/subdev/bios/init.c` + `devinit/` **only** if
+  you ever have to re-POST (danos's GOP handoff means you shouldn't).
+
+**Object model / GSP path — NVIDIA OGKM (MIT/GPLv2):** class headers `cl0073.h`, `cl2080.h`,
+`ctrl0073system.h`, `ctrl0073specific.h`; `src/nvidia/` for RM control sequences.
+`nvidia-modeset.ko` (NVKMS) is a *policy* layer over RM and can be bypassed entirely.
+[nova-core](https://lore.freedesktop.org/nouveau/) (Rust) is the forward-looking reference for GSP
+boot mechanics (falcon signing, queue rings, RPC).
+
+**Register / method specs — NVIDIA open-gpu-doc:**
+- [`classes/display/README.txt`](https://raw.githubusercontent.com/NVIDIA/open-gpu-doc/master/classes/display/README.txt)
+  — the channel model + class-to-GPU map (read first).
+- [`classes/display/clc67d.h`](https://raw.githubusercontent.com/NVIDIA/open-gpu-doc/master/classes/display/clc67d.h)
+  + `clc67e.h` / `clc67a.h` — the Ampere core/window/cursor mode-set method vocabulary.
+- [`manuals/ampere/ga102/dev_display_withoffset.ref.txt`](https://raw.githubusercontent.com/NVIDIA/open-gpu-doc/master/manuals/ampere/ga102/dev_display_withoffset.ref.txt)
+  — `NV_PDISP_FE_*` channel/pushbuffer registers + SOR.
+- [`DCB`](https://github.com/NVIDIA/open-gpu-doc/tree/master/DCB) — connector→output-resource
+  routing; [`Devinit`](https://github.com/NVIDIA/open-gpu-doc/tree/master/Devinit) +
+  [`BIOS-Information-Table`](https://github.com/NVIDIA/open-gpu-doc/tree/master/BIOS-Information-Table)
+  — VBIOS parsing (bring-up reference; not needed if inheriting GOP).
+- The 632 KB Volta [`dev_display.ref`](https://download.nvidia.com/open-gpu-doc/Display-Ref-Manuals/1/gv100/dev_display.ref)
+  is the best shot at SOR-DP/AUX register detail the smaller Ampere file omits.
+
+## Open questions (unresolved by the survey)
+
+Each needs a direct read of the named nouveau file or experimentation on the actual card:
+
+- Exact GA106 register/method offsets and PADLINK→SOR→connector wiring (can vary by board vendor).
+- Whether *any* PLL/devinit re-run is unavoidable vs. fully inherited from GOP.
+- Whether DisplayPort needs full retraining on takeover, or the GOP-established link can be reused.
+- The precise SV1/SV2/SV3 supervisor sequence.
+- Whether a system-memory-target scanout ctxdma could eliminate the VRAM allocator.
+- The exact `clc67d.h`/`clc67e.h` method opcode numbers (not captured verbatim in the survey).
+
+---
+
+*Research snapshot; verify against current nouveau / open-gpu-kernel-modules source before
+building — NVIDIA's GSP defaults and firmware ABIs change per release.*

docs/os-developer-guide/README.MD

@@ -0,0 +1,9 @@
+# OS Developer Guide
+
+This document is for those who need to understand the architectural decisions behind the OS.
+
+## Written in Zig?
+
+The os was initially written in zig because it has excellent support for EFI. With zig, we could forgo using a third party bootloader, reducing the time to boot up the kernel. Following the "Zen of Zig", helped to produce the most readable codebase for an operating system ever created. So those, new to OS development could quickly get up to speed.
+
+

docs/power.md

@@ -0,0 +1,128 @@
+# 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](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 `runtime.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 ([system/services/power/protocol.zig](../system/services/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 — `runtime.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, mirroring the kernel's own
+`system/devices/power.zig` `sleepValue`. 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 `power.zig` for its own test paths and
+panic-time poweroff, where no user space is available to ask.
+
+## 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-manager.md) — the supervision model init mirrors for
+  its own children.

docs/process-lifecycle.md

@@ -0,0 +1,327 @@
+# Process lifecycle: signals over IPC
+
+**Status: increments 1–4 built** (2026-07-12): claim release on death, exit
+reasons, published exit events, and signals + one-shot timers + the service
+harness are all in — the interface below is as-built. The primitives underneath
+predate this design ([process-management.md](process-management.md):
+spawn, the supervision link, kill, child-exit notifications); this document designs
+the layer above them — the standard vocabulary a danos process speaks about its own
+life, and the stable `runtime.process` interface that carries it. Nothing here is
+device- or driver-specific: a driver, the VFS, and a user application all stop,
+reload, and die the same way. The device manager is simply this design's first
+serious customer ([device-manager.md](device-manager.md)).
+
+**"POSIX" in this document means the concepts, never the letter of the standard.**
+danos borrows the ideas and the hard-won lessons (what SIGTERM *means*, why SIGPIPE
+was a mistake) without inheriting the mechanism, the API, or the names. The naming
+rule is danos's own and it is strict: plain words that communicate intent
+(`terminate`, `reload`, `exited`) and the IPC vocabulary the system already speaks
+(`bind`, `subscribe`, `publish`, `endpoint`) — never `SIG*`, never a second word for
+a concept that already has one. Literal POSIX arrives later and lives elsewhere: the
+`std.os.danos` seam that makes danos a Zig target, and eventually a **musl-based C
+layer** on the same native surface (see [zig-self-hosting.md](zig-self-hosting.md)) —
+musl's syscall surface retargeted at danos system calls and IPC protocols (files onto
+the VFS protocol, `sigaction`/`wait` onto this lifecycle, sockets onto whatever
+networking becomes). Ported programs see POSIX; the system underneath never does.
+
+## Why a standard vocabulary
+
+A supervisor can only manage processes it has never heard of if "please exit" means
+the same thing to all of them. That is the one thing POSIX signals got deeply right:
+`SIGTERM` means the same thing to nginx and to a five-line script, which is why
+process supervision on Unix (init systems, container runtimes) is possible at all.
+danos wants that property from day one, because supervision-and-restart is the
+system's core motivation ([resilience.md](resilience.md)).
+
+What POSIX got wrong — for a system like this — is the **delivery mechanism**:
+asynchronous control-flow hijack. A Unix handler runs on a stolen stack at an
+arbitrary instruction boundary, which is why the async-signal-safe function list
+exists, why `errno` must be saved, and why the canonical signal bug is a SIGTERM
+handler innocently calling `printf` mid-`malloc`. That entire bug class comes from
+the mechanism, not the vocabulary, and none of it is worth importing.
+
+A microkernel already has the right channel: **a signal is a message.** QNX delivers
+POSIX signals over its message passing; seL4 has notification objects; Erlang turned
+"death is a message to whoever linked" into a reliability philosophy. danos has
+already done it once without naming it: a child's death arrives as a notification
+badge on the supervisor's endpoint — the microkernel's SIGCHLD, the IRQ-as-IPC
+pattern reused. Signals are the same pattern reused a third time.
+
+## The mechanism
+
+- **`signal_bind(endpoint)`** — a process nominates the endpoint its signals arrive
+  on, exactly as `irq_bind` nominates where a device's interrupts land. The runtime
+  does this at startup for any program that opts in.
+- **`process_signal(id, signal)`** — posts the signal as an asynchronous
+  notification to the target's bound endpoint: badge = `notify_badge_bit |
+  notify_signal_bit | pending signals`. Non-blocking for the sender, always.
+- **Pending signals coalesce** in a per-process bitmask until the target next waits
+  — exactly like interrupt notifications, and exactly POSIX's own semantics for
+  non-realtime signals (two pending SIGTERMs are one SIGTERM). The bitmask *is* the
+  design: signals carry no payload. Anything with a payload is a protocol message.
+- **Authority**: the supervisor may signal its children — the same link that is
+  already the kill authority. A process may signal itself. Anything broader waits
+  for transferable process handles.
+- **No binding, no problem**: a process that never calls `signal_bind` is not
+  broken — its signals pend unread and only `process_kill` works on it. Simple
+  programs stay simple; the vocabulary is opt-in, the kill authority is not.
+
+Because delivery is a message into the process's own event loop, there is no
+async-signal-safe list in danos: a handler is ordinary code running at a point the
+process chose. The bug class is gone by construction, not by discipline.
+
+## The vocabulary: POSIX.1-1990, sorted honestly
+
+The full 1990 set, and what each becomes. Two intrinsically problematic cases get a
+defense below the table.
+
+| POSIX.1-1990 | danos disposition | Notes |
+|---|---|---|
+| SIGTERM | signal `terminate` | finish up and exit; the supervisor's polite half |
+| SIGHUP | signal `reload` | re-read configuration / re-scan |
+| SIGINT | signal `interrupt` | interactive interrupt; meaningful once a console can send it, in the vocabulary now so numbering is stable |
+| SIGQUIT | signal `quit` | as SIGINT, without the core-dump baggage |
+| SIGALRM | signal `alarm` | timer expiry as a message; the Unix SIGALRM+`longjmp` timeout hacks are impossible here. In the vocabulary, unbuilt: no consumer yet, and when one appears it is runtime sugar over the existing timer — zero kernel work |
+| SIGUSR1, SIGUSR2 | signals `user_1`, `user_2` | service-defined |
+| SIGCHLD | **already exists** — the exit notification | the badge carries the child id, dodging the classic coalescing bug (Unix code must loop `waitpid`) |
+| SIGKILL | `process_kill` — kernel mechanism | its definition is "cannot be handled"; it was never really a signal |
+| SIGABRT | exit reason `abort` | `abort()` is synchronous self-termination, not an event |
+| SIGSEGV, SIGILL, SIGFPE | exit reasons, **never delivered** | see below |
+| SIGPIPE | **an error return**, not a signal | see below |
+| SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU, SIGCONT | deferred | job control needs terminals, sessions, and process groups; stop/continue is scheduler territory |
+
+**The fault signals (SIGSEGV, SIGILL, SIGFPE) are intrinsically wrong for messages.**
+They are *synchronous* — raised at a specific faulting instruction, not "sometime
+soon". A message cannot be delivered to a process whose next instruction re-faults;
+it never reaches its event loop to read it. POSIX only makes fault handlers "work"
+via the async hijack (run the handler *instead of* the instruction), and even there,
+returning from a SIGSEGV handler without curing the cause is undefined behavior.
+danos's architecture already has the better answer: fault → the kernel kills the
+process ([resilience.md](resilience.md) step 2, built) → the supervisor reads the
+reason → restart. Recovery is restart, not a handler. This is also truer to the 1990
+standard than handling is: the standard's default action for all three was
+"terminate the process".
+
+**SIGPIPE deserves special contempt.** Its default kills a process that writes to a
+closed pipe — which is why "the whole server died because one client disconnected"
+is roughly every network daemon's first production bug, and why every mature codebase
+contains the same fix: ignore SIGPIPE, handle the `EPIPE` error return. danos made
+the right choice natively already — a reply owed to a dead peer fails with `-EPEER`.
+Errors from operations are error returns from those operations. The posix layer can
+synthesize SIGPIPE for ported code that expects it.
+
+### Statements, not questions
+
+A signal and a protocol message both travel over IPC — the difference is the
+**contract**, not the transport. danos IPC has two primitives, both already in
+daily use: the **asynchronous notification** (a badge — bits that coalesce into a
+pending mask; the sender never blocks; no payload, *no reply path*; how IRQs and
+exit events arrive) and the **synchronous call** (a rendezvous — payload both
+ways, the caller waits for the reply; how VFS requests work). A signal is the
+first kind: a *statement*. `terminate` wants no reply — the exit notification is
+its acknowledgement.
+
+A health probe is the second kind: a *question*, worthless without its answer —
+and the answer's absence within a deadline is the very thing being measured.
+Asked as a signal it has no reply channel (a coalescing bit can't carry an answer,
+and the authority rule forbids a child signalling its supervisor back); asked as a
+call, the timeout-is-the-diagnosis semantics come free. So there is no `health`
+signal. Liveness is the common **`ping`**: a reserved request every harness-run
+service answers automatically on its main endpoint — still free for the service
+author, still one obvious way — and a supervisor's probe is a `ping` call with a
+deadline.
+
+## The two iron rules
+
+1. **Cleanup is the kernel's job.** A process can die with no warning — fault,
+   kill, power. Correctness must never depend on a `terminate` handler running. On
+   any death the kernel releases the address space, IPC handles, IRQ bindings, and
+   owed replies (built), and must also release **device, I/O-port, and interrupt
+   claims and MSI vectors** (the known gap in
+   [process-management.md](process-management.md); increment 1). A signal handler is
+   for *graceful* work — flushing, deregistering, saving — never for *necessary*
+   work.
+2. **Kill is not a signal, and exit reasons are load-bearing.** The standard stop
+   sequence is *terminate → deadline → `process_kill`*; the unhandleable kill stays
+   a kernel mechanism. And a supervisor deciding whether to restart must know *how*
+   the child died: clean exit (meant to — don't restart), fault (restart with
+   backoff), killed (the supervisor did it). The exit notification today carries
+   only the id; it grows a reason. Restart policy cannot be written without it.
+
+## Who learns of a death
+
+A death has three audiences, and conflating them is how systems end up with either
+zombie state or privileged snooping:
+
+1. **The supervisor** — gets the exit notification on the endpoint it gave at spawn
+   (built), which grows the `ExitReason` (increment 2). The supervisor is the only
+   audience that needs the *reason*, because it is the only one deciding whether to
+   restart.
+2. **The peer owed a reply** — already built: a client that dies mid-request fails
+   the server's reply with `-EPEER`; a server that dies fails its waiting clients
+   the same way. This covers the *synchronous* case only.
+3. **The subscribers** — the new piece, and it is the input service's
+   publish/subscribe shape ([input.md](input.md)) applied to exits. A stateful
+   service accumulates per-client state across many requests: the VFS holds a dead
+   client's open file handles, the input service holds its subscriptions, a future
+   network stack holds its sockets. None of these are the client's supervisor, and
+   none learn anything from a failed reply if the client simply never calls again.
+   So the kernel **publishes every exit** to whoever subscribed:
+   `process_subscribe(endpoint)` adds a subscriber, and each death posts a
+   notification to every subscriber (badge = `notify_exit_bit | process id` — the
+   same encoding supervisors already decode, the IRQ-as-IPC pattern once more). The
+   subscriber filters for ids it holds state for and releases what the dead client
+   held. Correlating is free of bookkeeping: an IPC sender's badge already *is* its
+   task id (`runtime.ipc.Received`), so the id a service has been keying client
+   state by all along is the id the exit event carries.
+
+   Subscription, not broadcast-to-everyone: only processes that asked receive
+   events, the kernel keeps a bounded subscriber table, and delivery is the same
+   non-blocking coalescing notification as everything else — a dying process never
+   waits on its mourners. Subscribing is ungated, like `process_enumerate`: what is
+   running (and dying) is not a secret between cooperating processes. Subscribers
+   do not receive the exit reason — the VFS does not care *why* the client died.
+
+This is the service-side mirror of iron rule 1: **a service must never depend on
+its clients cleaning up after themselves.** Handle release on client death is the
+service's job, triggered by the published exit event — never by a courtesy
+"closing now" message that a crashed client will never send.
+
+## The stable interface: `runtime.process`
+
+`runtime.process` already owns what a process receives at birth (`Init`, the
+argv contract). It grows to own the other end of life.
+
+**The runtime is the stable interface; the numbers are not.** danos applications do
+not make system calls — they call the runtime library, and the system-call numbers,
+notification bits, and signal bit positions beneath it are a **private kernel ↔
+runtime contract** that may change at any time (settled 2026-07-12). This is why
+the runtime exists. Today kernel and runtime ship from one tree in one image, so
+"stability" is simply building them together. When driver binaries start shipping
+as separately-versioned applications — the whole point of the restart design — the
+binary's embedded runtime version becomes compatibility metadata (the same idea as
+the protocol version in the device manager's `hello`), and the kernel refuses what
+it cannot serve. Signals therefore need no reserved numbering scheme: the enum
+below is vocabulary, not ABI.
+
+```zig
+/// The signal vocabulary. The value is the bit position in the pending mask — a
+/// private kernel/runtime detail, free to change while they ship together.
+pub const Signal = enum(u5) {
+    terminate = 0, // SIGTERM: finish up and exit
+    reload = 1, // SIGHUP: re-read configuration
+    interrupt = 2, // SIGINT
+    quit = 3, // SIGQUIT
+    alarm = 4, // SIGALRM
+    user_1 = 5, // SIGUSR1
+    user_2 = 6, // SIGUSR2
+};
+
+/// A decoded pending mask: the coalesced set of signals a notification delivered.
+pub const SignalSet = struct {
+    pending: u32,
+    pub fn has(set: SignalSet, signal: Signal) bool { ... }
+    pub fn iterate(set: SignalSet) Iterator { ... }
+};
+
+/// Nominate `endpoint` as this process's signal endpoint (signal_bind). The
+/// runtime's service harness calls this; a bare program may call it directly and
+/// fold signals into its own replyWait loop.
+pub fn bindSignals(endpoint: usize) bool { ... }
+
+/// Decode a received badge into signals, or null if the badge is not a signal
+/// notification (mirrors ipc.Received.isChildExit).
+pub fn signalsFrom(badge: usize) ?SignalSet { ... }
+
+/// Send `signal` to process `id`. Supervisor-gated, like kill; non-blocking.
+pub fn sendSignal(id: u32, signal: Signal) bool { ... }
+
+/// The standard stop sequence: terminate, wait up to `deadline_ms` for the exit
+/// notification, then process_kill. The one call a supervisor needs.
+pub fn stop(id: u32, deadline_ms: u64) void { ... }
+
+/// Subscribe `endpoint` to published exit events (process_subscribe). Every
+/// process death posts an asynchronous notification: badge = notify_exit_bit |
+/// process id — the same encoding a supervisor's exit notification uses, decoded
+/// by the same ipc.Received helpers. For stateful services: release what the dead
+/// client held (file handles, subscriptions, sockets). Ungated, like
+/// process_enumerate.
+pub fn subscribeExits(endpoint: usize) bool { ... }
+
+/// How a process ended — queried after the exit notification (the kernel records
+/// it first, so the two never race). What restart policy reads. (Built in M17.2.)
+pub const ExitReason = enum(u8) {
+    exited, // returned from main / clean exit
+    aborted, // abort() — deliberate self-termination (SIGABRT's ghost; reserved)
+    segmentation_fault, // SIGSEGV's ghost
+    illegal_instruction, // SIGILL's ghost
+    arithmetic_fault, // SIGFPE's ghost
+    protection_fault, // general protection fault
+    fault, // any other CPU exception
+    killed, // process_kill
+};
+```
+
+Two deliberate absences. There is no `mask`/`block` API — a process that is not
+ready for a signal simply has not waited on its endpoint yet; the pending mask *is*
+the blocked set. And there is no per-signal handler registration at this layer —
+dispatch is the process's own `switch` over `SignalSet`, or the service harness's
+callbacks (`on_terminate`, `on_reload`) for programs that want defaults.
+
+### The service harness
+
+`runtime.service` owns the `replyWait` loop and folds every event source — signals,
+child exits, protocol messages — into callbacks, with the vocabulary's defaults:
+`terminate` returns from the loop (clean exit), the common `ping` is answered automatically,
+`reload` is ignored unless overridden. One loop, no locking, nothing reentrant. A
+service author writes domain logic; the lifecycle contract is satisfied by the
+harness. A process that bypasses the harness and ignores its signals meets the
+deadline-then-kill escalation — you cannot force a process to implement an
+interface, but you can make compliance free and non-compliance fatal.
+
+### The musl layer later
+
+The POSIX C layer is a **musl port**: musl's arch/syscall layer retargeted so that
+what musl believes are kernel syscalls become danos runtime calls and IPC — `open`
+and `read` onto the VFS protocol, `kill`/`sigaction`/`waitpid` onto this document's
+vocabulary, `exit` onto the runtime's exit path. `sigaction` handlers registered
+through it are invoked by the runtime's loop when the signal message arrives —
+synchronous underneath, async-looking to ported code, delivered at wait boundaries
+the way most Unix programs already experience signals (at syscalls). No stack hijack
+ever happens, `SA_RESTART` semantics come free because nothing was interrupted, and
+SIGPIPE can be synthesized from `-EPEER` for the programs that expect it. C programs
+get POSIX; danos-native programs never pay for it.
+
+## Increments
+
+1. **Kernel: release device/port/IRQ claims and MSI vectors on death** — the
+   cleanup half of iron rule 1, and the prerequisite for any restart story. Test:
+   kill a claiming driver, spawn it again, the claim succeeds.
+2. **Exit reason in the death notification** (`ExitReason` above).
+3. **Exit events**: `process_subscribe` in the kernel (bounded subscriber table,
+   publishes on every death), `runtime.process.subscribeExits`; the VFS becomes the
+   first subscriber — releasing a dead client's handles is its proof test.
+4. **Signals**: `signal_bind` + `process_signal` + the pending mask in the kernel;
+   `runtime.process` grows the interface above; the service harness handles
+   `terminate` and answers the common `ping`; `stop()` for supervisors.
+
+[device-manager.md](device-manager.md) builds directly on all four.
+
+## Settled questions (2026-07-12)
+
+- **Signal numbering is not ABI**: the runtime is the stable interface; the numbers
+  beneath it are a private kernel ↔ runtime contract (see "The stable interface").
+- **Liveness is a `ping` call, not a signal**: signals are statements, questions
+  are synchronous calls (see "Statements, not questions"). A service wanting *deep*
+  health ("can I reach my hardware?") defines its own protocol message on top.
+- **Process handles: deferred.** Pids + the supervisor gate cover everything
+  planned; transferable handles (Fuchsia-style, delegating signalling without
+  delegating kill) wait for the capability table to grow types beyond endpoints.
+- **`alarm`: in the vocabulary, unbuilt.** No consumer yet; when one appears it is
+  runtime sugar over the existing timer (arm a timer that posts your own signal) —
+  zero kernel work, so deferring costs nothing.
+- **Subscription granularity: all exits**, subscriber-side filtering — one
+  subscription per service, a bounded kernel table. Per-id subscriptions only if
+  event volume ever matters (hundreds of processes, not before).
+- **Client identity across the exit boundary: no convention needed** — an IPC
+  sender's badge already is its task id (see "Who learns of a death").

docs/process-management.md

@@ -0,0 +1,120 @@
+# Process Management
+
+How danos lists, supervises, and kills processes — the microkernel answer to
+`ps`, `kill`, and `SIGCHLD`/`wait`.
+
+## Why system calls, not `/proc`
+
+Unix systems sit on a spectrum. Classic BSD/macOS list processes through
+syscalls (`sysctl(KERN_PROC)`) and kill through `kill(2)`; Linux renders the
+process table as `/proc` for *reading* but still kills through a syscall; Plan 9
+made the file tree the whole interface (`echo kill > /proc/n/ctl`). Microkernels
+mostly abandon ambient PIDs: Minix and QNX route everything through a user-space
+process-manager server, and Fuchsia/seL4 control processes only through handles.
+
+danos rules out `/proc` **as the primitive**: here a `/proc` would be served by
+the VFS server — a user process — which would put the VFS in the path of process
+control. If the VFS (or anything under it) hangs, nothing could be listed or
+killed, *including the hung VFS*. The control plane for processes must not
+depend on a process. So the primitives are kernel system calls; a read-only
+`/proc` rendering can be layered on later, and a POSIX-style process-manager
+server can be built *from* these primitives when one is needed.
+
+## The three primitives
+
+### `process_enumerate(buffer, maximum) -> total`
+
+A snapshot of the task table into a caller buffer of `abi.ProcessDescriptor`
+(id, supervisor, state, priority, name) — the exact shape of
+`device_enumerate`, so `ps` is a user program over a snapshot, not a kernel
+service. The total may exceed what fit; call again with a larger buffer. Kernel
+tasks are included with an empty name — an honest listing shows the idle tasks
+too. Ungated and read-only: what is running is not a secret between cooperating
+bring-up processes.
+
+### `system_spawn(..., exit_endpoint) -> child id`, and the supervision link
+
+`system_spawn` records the caller as the child's **supervisor** and returns the
+child's process id (ids are monotonic, never reused — a stale id can only miss).
+That link is the kill authority: it answers "who may kill process 7?" without
+inventing users or permissions, the same way a device *claim* is the capability
+for `mmio_map`. It composes with the supervision hierarchy the device manager
+already forms: init supervises the services it starts, the device manager
+supervises the drivers it matches. (A transferable process *handle* — Fuchsia
+style — can replace the id once the handle table grows types beyond endpoints.)
+
+`exit_endpoint` (a handle, or `abi.no_cap`) is the supervisor's death-watch: when
+the child ends — clean exit, CPU fault, or `process_kill` — the kernel posts an
+asynchronous notification to that endpoint, exactly like a bound IRQ. The badge
+carries `abi.notify_badge_bit | abi.notify_exit_bit | child_id`, so one endpoint
+supervises many children and can even share with IRQ notifications. This is the
+microkernel's SIGCHLD: no new mechanism, just the IRQ-as-IPC pattern reused, and
+a supervisor's event loop (`ipc.replyWait`) already knows how to receive it. The
+child holds a reference to the endpoint from birth, so the notification cannot
+dangle even if the supervisor dies first.
+
+### `process_kill(id) -> 0 / -ESRCH / -EPERM`
+
+Only the supervisor may kill; kernel tasks are not killable processes. Like a
+signal, delivery is prompt but asynchronous — 0 means the kill is accepted and
+irrevocable; the exit notification confirms completion.
+
+## How a kill lands (the kernel mechanics)
+
+Everything below runs under the big kernel lock, where task states cannot move.
+
+- **Target ready or blocked** (not on any core): reaped on the killer's own
+  call. The reap releases what death always releases (IRQ bindings first, then
+  a client the target still owed a reply to is failed with `-EPEER`, IPC handles
+  closed, the exit notification posted last) — plus the unlinking only a
+  *remote* death needs: out of the ready queue, out of an endpoint's sender FIFO
+  (`Task.ipc_wait_endpoint`), out of a receive wait queue (`Task.wait_queue`),
+  and out of any server's owed-reply slot, so nothing ever dequeues a dangling
+  pointer. Destroying the address space is safe because no core can have it
+  loaded: every switch away from a task loads the next task's tables.
+- **Target running on another core**: it cannot be torn down mid-instruction,
+  so it is condemned (`Task.kill_pending`) and dies at whichever comes first:
+  - its next **system_call entry** — checked before dispatch, so a condemned
+    process cannot spawn, claim, or message anything on its way out;
+  - its core's next **timer tick** — but only when the task is not inside one
+    of its own system calls (`Task.in_system_call`): the tick may have
+    interrupted kernel code mid-operation, where teardown would leak whatever
+    the operation held. User-mode execution is always a safe kill point. The
+    tick-time terminate abandons the interrupt frame exactly like the fault
+    path (the LAPIC is acknowledged before the tick hook runs);
+  - any core's tick finding it **blocked or ready** (it entered a syscall and
+    parked after being condemned) — reaped by the same remote-reap path.
+
+  A pure user-mode spin loop that never makes a system call therefore dies
+  within one tick; nothing a process does can outrun the kill.
+
+The scheduler stays below the process layer: finishing a kill (IRQ bindings,
+handles, the notification) is called *up* through two hooks process.zig
+registers at boot (`terminate_current_hook`, `reap_task_hook`), mirroring how
+the architecture layer calls up into `tick`.
+
+## Known gaps (bring-up honesty)
+
+- ~~Device claims are not released on death~~ Closed (M17.1): every path out of a
+  process releases its device claims alongside its IRQ and MSI bindings
+  (`releaseTaskResourcesLocked`), so a restarted driver can claim its hardware
+  again — the cleanup half of [process-lifecycle.md](process-lifecycle.md)'s iron
+  rule 1. The `claim-release` test proves the kill → release → re-claim cycle.
+- Kernel stacks of dead tasks are leaked, as on every exit path (no reaper yet).
+- ~~There is no exit status in the notification~~ Closed (M17.2): the kernel
+  records how every process ends — exited, a fault class, or killed — before it
+  posts the exit notification, and the supervisor reads it with
+  `process_exit_reason` (`runtime.process.exitReason`). This is the input to
+  restart policy ([process-lifecycle.md](process-lifecycle.md)); an exit *code*
+  for the clean case can still ride alongside later.
+- Enumerate writes through the caller's raw pointer under the bring-up trust
+  model, like `device_enumerate` (an unmapped page is a self-DoS, not an
+  isolation break).
+
+## Tests
+
+`process-list` (enumerate), `process-kill` (kernel-level kill paths, refusals,
+notifications), `supervision` (the whole user-side surface via the process-test
+service: spawn supervised → enumerate → kill blocked and spinning children →
+notifications → gone), `claim-release` (a killed claim-holder's device is
+claimable again). See test/qemu_test.py.

docs/release-iso.md

@@ -0,0 +1,70 @@
+# The release ISO — flashable boot media
+
+`zig build release-x86-64` produces **`zig-out/danos-x86-64.iso`**, the file you
+hand to someone who wants to try danos on a real machine: point
+[balenaEtcher](https://etcher.balena.io) (or Raspberry Pi Imager, or plain `dd`)
+at it, flash a USB stick, and boot the stick. The same file also burns to
+optical media. `zig build check-iso-image` validates it without booting.
+
+```
+zig build release-x86-64
+# Etcher: select danos-x86-64.iso → select the stick → Flash
+# or: sudo dd if=zig-out/danos-x86-64.iso of=/dev/rdiskN bs=4m   (macOS; triple-check N)
+```
+
+## Why an ISO when danos-usb.img already boots
+
+`danos-usb.img` is a raw FAT32 **superfloppy** — a filesystem starting at
+sector 0, no partition table. UEFI firmware accepts that from a USB stick (it
+probes whole-disk FAT before giving up), which is why `dd`-ing the .img works
+and why QEMU and the test harness boot it directly. But it is a
+developer-shaped artifact: flashing apps expect an ISO, and a superfloppy
+can't be burned to a CD/DVD or carry a partition table for pickier firmware.
+
+The ISO wraps that same FAT image — bit-identical, built by the same
+`tools/make-fat-image.py` — in a container that boots everywhere release media
+gets consumed. One payload, two images: the .img stays the raw volume the QEMU
+harness mounts and boots, the .iso is what leaves the building.
+
+## How a hybrid ISO boots twice
+
+The trick (the same one Linux distribution ISOs use, usually via `xorriso
+-isohybrid…`) is that ISO9660 reserves its first 32 KiB as a **system area** it
+never touches — exactly where an MBR lives on a disk. So one file can carry two
+tables of contents, both pointing at the same embedded FAT image:
+
+* **Flashed to USB (Etcher, dd):** firmware sees a disk whose sector 0 is an
+  MBR with one partition of type `0xEF` (EFI System Partition) covering the
+  embedded FAT image. It mounts that ESP and runs `\EFI\BOOT\BOOTX64.efi` —
+  the standard removable-media path ([efi.md](efi.md)).
+* **Burned to optical media:** firmware reads the ISO9660 volume descriptors
+  at sector 16 and finds an **El Torito** boot record. Its catalog has one
+  entry, platform ID `0xEF` (EFI), whose start LBA is — again — the embedded
+  FAT image. The firmware exposes that image as a virtual disk and runs the
+  same `BOOTX64.efi` off it.
+
+Neither path involves the legacy BIOS boot-sector machinery: danos is
+UEFI-only ([system-requirements.md](system-requirements.md)), so the MBR holds
+no boot code, just the partition entry, and the El Torito entry is EFI-class,
+not floppy emulation.
+
+One El Torito wrinkle: the catalog's sector-count field is 16-bit (units of
+512 bytes), so it can name at most 32 MiB — less than the 64 MiB FAT image.
+That is fine in practice: firmware sizes the FAT filesystem from its own BPB,
+and the boot files sit in the first few MiB of the image (clusters are
+allocated from the front) either way. The USB path has no such cap.
+
+## The builder
+
+`tools/make-iso-image.py` follows the house rule of
+[make-fat-image.py](../tools/make-fat-image.py): pure Python 3 standard
+library, no external tools (no xorriso, mkisofs, or isohybrid), with a
+`--verify` mode the `check-iso-image` step runs — it checks that the MBR
+partition and the El Torito catalog agree on where the FAT image lives and
+that a FAT32 boot sector is actually there. Every timestamp field in the ISO
+is zeroed, so the build is reproducible byte-for-byte.
+
+The ISO9660 filesystem around the boot machinery is minimal but real: a root
+directory listing `BOOT.CAT` (the catalog) and `EFI.IMG` (the FAT image), so
+`file`, mount tools, and archive browsers can open the ISO and see what's in
+it.

docs/resilience.md

@@ -1,10 +1,17 @@
 # Resilience: fault isolation and live restart
 
-Steps 1–2 of the ordering below are **built**: user-mode isolation, and fault →
-kill the process → keep the core (`onException` in `system/kernel/kernel.zig`; the
-`fault-recovery` test proves a crashing ring-3 process dies alone while the system
-keeps running). The supervisor notification and restart policy (steps 3+) are
-still design. This is the property danos is really chasing:
+Steps 1–4 of the ordering below are **built** (M17–M18, 2026-07-13): user-mode
+isolation; fault → kill the process → keep the core (`onException`; the
+`fault-recovery` test); the supervisor notification **with exit reasons**
+([process-lifecycle.md](process-lifecycle.md) — clean exit, fault class, or
+killed, recorded before the notice posts); and the **restart policy itself**
+([device-manager.md](device-manager.md)): the device manager supervises every
+driver, restarts crashes with backoff, caps crash loops, and re-claims work
+because the kernel releases a dead process's claims. The `driver-restart` and
+`usb-report` scenarios prove kill → release → respawn → re-claim → re-report
+end to end. What remains of this document's ladder is scope, not mechanism:
+more of the system moved into restartable processes (the discovery migration,
+[discovery.md](discovery.md), is the next rung). This is the property danos is really chasing:
 **if a part of the OS breaks, isolate it, and re-initialise it — without rebooting.**
 A crashed driver gets restarted; a wedged service gets killed and brought back. It's
 the reason the [microkernel](vision.md) shape was chosen, and it's a *separate* goal

docs/syscall.md

@@ -47,6 +47,8 @@ Everything else---including`read()`,`write()`,`malloc()`, and`fork()`---will run
     -   **What it does:**Used strictly by your background user-space servers (like your disk driver or filesystem). It sends a reply to the last client that called it, and immediately puts the server to sleep until the next request arrives.[[1](https://news.ycombinator.com/item?id=33078441)]
 3.  **`Yield()`/`Thread_Ctrl()`**
     -   **What it does:**Allows a thread to voluntarily give up its CPU time slice, or allows a root task to spawn/kill threads.
+4.  **`ipc_send(endpoint, message_buffer)`(Asynchronous Send)**
+    -   **What it does:**Posts a small payload to an endpoint's bounded queue and returns *without* blocking — no rendezvous, no reply. The receiver picks it up through the same `IPC_ReplyWait`, as a buffered message. It is the async counterpart of `IPC_Call`, for one-to-many broadcasts where a synchronous rendezvous would let one dead or slow receiver hang the sender. The [input service](input.md) — keyboard-event fan-out — is its first user. A full queue drops the oldest message (a buffered message is discrete data, unlike a coalescing interrupt notification).
 
 * * * * *
 

docs/system-requirements.md

@@ -0,0 +1,227 @@
+# System Requirements
+
+Minimum and recommended hardware for running danos. Every requirement below is
+grounded in what the current code actually assumes at boot — this is a
+description of the real target, not an aspirational one.
+
+## Summary
+
+danos targets a **modern UEFI x86-64 PC with ACPI and PCIe**. The practical
+minimum is:
+
+- 64-bit x86-64 CPU with SSE2, APIC, and `syscall`/`sysret`
+- UEFI firmware (no BIOS / legacy boot)
+- ACPI tables: MADT, MCFG, FADT
+- PCIe with an ECAM (MMConfig) window
+- **128 MiB RAM** (target); see [Memory](#memory) for the breakdown
+- USB via **xHCI only**
+
+There is no support for legacy BIOS boot, x2APIC, port-IO PCI configuration, or
+any USB host controller other than xHCI.
+
+## Plain-language hardware guide
+
+If you don't want to cross-reference chipset datasheets, here's roughly what era
+of PC works. These are **guidance based on when the required features became
+standard**, not a list of tested machines — the authoritative rules are in the
+technical sections below.
+
+The feature that sets the floor is **built-in xHCI USB** (danos supports no other
+USB controller) combined with **UEFI firmware**. Both became standard on
+mainstream desktops and laptops around **2012**.
+
+| | Known-good baseline | Comfortable recommendation |
+|---|---|---|
+| **Intel** | 3rd-gen Core "Ivy Bridge" (2012) with a 7-series "Panther Point" chipset — Intel's first chipset with xHCI built in | 6th-gen Core "Skylake" (2015) or newer |
+| **AMD** | A-series "Llano" APU with an A75 FCH (2011) — the industry's first chipset with built-in xHCI | Any AM4 platform, i.e. Ryzen (2017) or newer |
+
+**AMD is not behind Intel here — it was first.** AMD's A75 FCH shipped with
+native xHCI in April 2011, about a year *ahead* of Intel's 7-series (2012); AMD
+was the first vendor to earn USB-IF certification for chipset-level USB 3.0. The
+two "comfortable recommendation" dates differ only because they name convenient,
+long-supported product lines (Skylake, Ryzen) — not because of any USB
+capability gap. Every AMD desktop platform from the A75 FCH (2011) and FM2/AM3+
+era onward has built-in xHCI, and any of them qualifies as a baseline.
+
+Older 64-bit machines (e.g. Intel Core 2, Nehalem, Sandy Bridge) meet the CPU
+requirements but typically **lack built-in xHCI and/or ship with BIOS instead of
+UEFI**, so they are not supported.
+
+### Matching your CPU by name
+
+If you know your chip's marketing name or codename, find it here. Everything from
+the **Supported** rows down works; the **Too old** row does not.
+
+**Intel Core** (the "-lake"/"-bridge"/"-well" codenames):
+
+| Status | Generation | Codename(s) | Year |
+|---|---|---|---|
+| Too old | 2nd gen | Sandy Bridge | 2011 |
+| Supported (baseline) | 3rd gen | Ivy Bridge | 2012 |
+| Supported | 4th–5th gen | Haswell, Broadwell | 2013–2014 |
+| **Recommended** | 6th–9th gen | **Skylake**, Kaby Lake, Coffee Lake | 2015–2018 |
+| Recommended | 10th–11th gen | Comet Lake, Ice Lake, Tiger Lake, Rocket Lake | 2019–2021 |
+| Recommended | 12th gen+ | Alder Lake, Raptor Lake | 2021–2023 |
+| Recommended | Core Ultra | Meteor Lake, Arrow Lake, Lunar Lake | 2023+ |
+
+**AMD:**
+
+| Status | Family | Codename(s) | Year |
+|---|---|---|---|
+| Supported (baseline) | A-series APU (A75/A85 FCH) | Llano, Trinity, Richland, Kaveri | 2011–2014 |
+| Supported | FX (AM3+) | Bulldozer, Piledriver | 2011–2012 |
+| **Recommended** | **Ryzen** 1000–5000 (AM4) | Summit/Pinnacle Ridge, Matisse, Vermeer (Zen–Zen 3) | 2017–2020 |
+| Recommended | Ryzen 7000+ (AM5) | Raphael, Granite Ridge (Zen 4 / Zen 5) | 2022+ |
+| Recommended | Threadripper / EPYC | Zen and later | 2017+ |
+
+(These map generations to the era their platforms shipped built-in xHCI + UEFI;
+they are guidance, not a tested-hardware list.)
+
+**Two caveats that matter regardless of CPU:**
+
+- **Firmware must be UEFI.** Many 2011-era machines could do either UEFI or
+  legacy BIOS — danos needs it set to UEFI. There is no BIOS boot path.
+- **Input is PS/2 only, for now.** danos does not yet support USB
+  keyboards/mice. This is fine on most **laptops** (their built-in keyboards are
+  wired to a PS/2-style i8042 controller) but means a **desktop with only USB
+  ports** currently has no usable keyboard. USB HID input is planned.
+
+Virtual machines are the easiest way to meet every requirement: QEMU (with OVMF/
+UEFI, a `qemu-xhci` controller, and the default Q35 machine type), or any
+hypervisor configured for UEFI firmware and an xHCI USB controller.
+
+## CPU / architecture
+
+| Requirement | Detail | Source |
+|---|---|---|
+| **x86-64, 64-bit only** | Kernel and loader are built exclusively for `x86_64`; the loader rejects any non-x86-64 kernel ELF (`error.WrongArchitecture`). | `build.zig:285`, `boot/efi.zig:418` |
+| **Long mode + PAE + NX** | AP trampoline sets `CR4.PAE`, `EFER.LME`, `EFER.NXE`; NX is used in kernel page-table entries. | `system/kernel/architecture/x86_64/trampoline.s:62` |
+| **SSE / SSE2** | Baseline: the compiler emits SSE for ordinary struct copies. Trampoline enables `CR4.OSFXSR` + `OSXMMEXCPT` and clears `CR0.EM`. | `build.zig:282`, `trampoline.s:62` |
+| **`syscall` / `sysret`** | Primary user↔kernel entry path. `EFER.SCE` enabled; `STAR`/`LSTAR`/`SFMASK` programmed per core. (`int 0x80` exists as a parallel gate.) | `architecture/x86_64/per-cpu.zig:59`, `isr.s:169` |
+| **Local APIC (xAPIC)** | LAPIC accessed via MMIO at `0xFEE00000`. LAPIC ID read as a `u8` — classic xAPIC. **x2APIC is not supported** (no MSR path). | `apic.zig:62`, `apic.zig:414` |
+| **CPUID + RDTSC** | CPUID leaf `0x15` for TSC frequency; RDTSC is the monotonic clock. | `apic.zig:279`, `apic.zig:84` |
+| **SMP (optional)** | Multi-core supported via INIT–SIPI–SIPI; ceiling `maximum_cpus = 128`. Single core is fine. Cores beyond the ceiling are parked. | `system/parameters.zig:16`, `apic.zig:144` |
+
+## Firmware / boot
+
+- **UEFI only.** A custom UEFI application loader is installed to
+  `\EFI\BOOT\BOOTX64.efi`. There is **no BIOS, multiboot, or limine** path. The
+  loader tolerates UEFI Class-3 machines with no legacy PIC/PIT.
+  (`build.zig:464`, `boot/efi.zig`)
+- **ACPI is the hardware-discovery mechanism.** The RSDP is taken from the UEFI
+  configuration table (ACPI 2.0 GUID preferred, 1.0 fallback). Without a valid
+  RSDP there is **no device discovery** — no SMP, no IOAPIC routing, no PCI/USB.
+  (`efi.zig:578`, `boot-handoff.zig:144`)
+- **Required ACPI tables:** MADT (interrupt topology), MCFG (PCIe ECAM base),
+  FADT (power / PM timer). Optionally consumed: HPET, DMAR, SPCR.
+  (`system/devices/acpi.zig:3`)
+- The loader reads `/system/kernel`, `/system/services/init`, and
+  `/boot/initial-ramdisk.img` off the FAT boot volume. The kernel can boot
+  "kernel-only" without init or the ramdisk. (`efi.zig:14`, `efi.zig:66`)
+
+## Interrupt controller
+
+- **Local APIC + I/O APIC required.** I/O APIC base, GSI base, and MADT
+  interrupt-source overrides come from ACPI. (`cpu.zig:365`, `apic.zig:119`)
+- **MSI supported** — edge-triggered, keyed by vector, no I/O APIC mask cycle.
+  Vector window 33–46, timer on 32, spurious on 47. (`system/kernel/irq.zig:70`,
+  `cpu.zig:397`)
+- The legacy 8259 PIC is remapped and masked **only if present** (MADT
+  `PCAT_COMPAT`); it is not required. (`apic.zig:103`)
+
+## PCI / PCIe
+
+- **PCIe with ECAM (MMConfig) required.** The PCI bus driver maps the host
+  bridge's ECAM window (1 MiB config space per bus) and computes config
+  addresses directly. **There is no legacy CF8/CFC port-IO config path** — the
+  driver bails if the bridge exposes no ECAM window. The ECAM base comes from
+  the ACPI MCFG table. (`system/drivers/pci-bus/pci-bus.zig:41`, `acpi.zig:6`)
+
+## USB
+
+- **xHCI only.** The sole USB driver is `usb-xhci-bus`, and the device manager
+  binds it strictly to PCI prog-IF `0x30` (xHCI). UHCI / OHCI / EHCI exist only
+  as report strings with no driver behind them — **USB 1.x/2.0-only controllers
+  are not supported.** (`system/drivers/usb-xhci-bus/`,
+  `system/services/device-manager/device-manager.zig:34`)
+- USB input (keyboard/mouse over HID) is future work; the current input stack is
+  PS/2. See [Buses & devices](#buses--devices).
+
+## Timers
+
+Calibration prefers, in order: (1) CPUID leaf `0x15` TSC frequency, (2) HPET,
+(3) ACPI PM timer (3.579545 MHz, from FADT), (4) legacy PIT. Any one suffices —
+HPET/PM-timer/PIT are optional fallbacks when CPUID `0x15` is absent.
+(`apic.zig:180`)
+
+- **TSC** — monotonic high-resolution clock.
+- **LAPIC timer** — scheduler heartbeat, periodic at `timer_hz = 1000 Hz`.
+  (`parameters.zig:39`)
+
+## Memory
+
+**Target: 128 MiB RAM.** The system uses 4 KiB pages and a bitmap physical-frame
+allocator built from the firmware memory map. There is no hardcoded minimum-RAM
+constant — the allocator only panics if there is no usable region, or none large
+enough to hold its own bitmap. (`system/kernel/pmm.zig:13`, `pmm.zig:77`)
+
+Where the budget goes:
+
+| Consumer | Size | Source |
+|---|---|---|
+| Kernel heap (cap, grown one page at a time) | up to **64 MiB** | `system/kernel/heap.zig:26` |
+| Kernel stack, per CPU | 16 KiB | `parameters.zig:26` |
+| IST stack, per CPU | 16 KiB | `parameters.zig:36` |
+| User stack, per task | 8 pages / 32 KiB | `parameters.zig:32` |
+| Max concurrent tasks | 32 | `parameters.zig:23` |
+| Boot page-table pool | 64 frames / 256 KiB | `efi.zig:299` |
+
+The 64 MiB heap cap plus kernel image, per-CPU stacks, task stacks, the frame
+bitmap, and DMA-contiguous allocations fit comfortably within 128 MiB on a
+single- or low-core-count machine. Very high core counts (toward the 128-CPU
+ceiling) add per-CPU stack overhead and push toward more RAM.
+
+**Note on the 4 GiB physmap:** the loader identity-maps and physmaps the low
+4 GiB of address space with 2 MiB leaves. This is *virtual address* reach, not a
+RAM requirement — RAM above 4 GiB simply needs an extra mapping window and is not
+needed to boot. (`efi.zig:305`)
+
+Virtual-memory layout (`boot-handoff.zig:47`):
+
+| Region | Base |
+|---|---|
+| User space | `0x0000_7000_0000_0000` |
+| Kernel heap | `0xFFFF_8000_0000_0000` |
+| Physmap | `0xFFFF_8800_0000_0000` |
+| Kernel image | `0xFFFF_FFFF_8000_0000` |
+
+## Buses & devices
+
+Buses with real drivers today:
+
+- **PCIe** via ECAM (`pci-bus`)
+- **xHCI USB** (`usb-xhci-bus`)
+- **PS/2** keyboard + mouse (`ps2-bus`) — the current input stack
+- **Serial UART** (16550/16450), configured from the ACPI SPCR table
+
+**No storage driver exists yet.** AHCI / NVMe / IDE are named for reporting only;
+there is no block-device driver. Persistent storage is future work.
+
+## IOMMU
+
+**Detection only; enforcement deferred.** The ACPI DMAR table is parsed for the
+first VT-d DRHD unit and its capabilities are exposed via `PlatformInfo`
+(`iommu_present`, `iommu_base`, `iommu_version`). No DMA-remapping tables are
+programmed and no translation is enforced. An IOMMU is therefore **not required**
+and does not currently constrain devices. (`system/devices/acpi.zig:96`)
+
+## What is explicitly NOT supported
+
+- Legacy BIOS / multiboot / limine boot
+- 32-bit x86
+- x2APIC
+- Legacy port-IO (CF8/CFC) PCI configuration
+- Non-xHCI USB (UHCI / OHCI / EHCI)
+- Machines without ACPI (no device discovery)
+- Persistent storage (no AHCI / NVMe / IDE driver yet)
+- USB HID input (PS/2 only for now)

docs/sysv.md

@@ -90,8 +90,10 @@ process) instead of silently corrupting the image
 (`buildEntryStack` in `system/kernel/process.zig`); `argv[0]` is always the path
 or initial-ramdisk name the process was spawned as, and `system_spawn`'s optional
 argument blob becomes `argv[1..]`. The runtime's `_start`
-(`library/runtime/start.zig`) hands the block to `rt_start`, which exposes it as
-`runtime.argumentCount()` / `runtime.argument(i)`. A C runtime's `crt0` would walk
+(`library/runtime/start.zig`) hands the block to `rt_start`, which builds a
+`runtime.process.Init` from it and passes that to the program's `main`
+(`pub fn main(init: runtime.process.Init)`; a parameterless `main()` is also
+accepted). A C runtime's `crt0` would walk
 the identical layout unmodified — that's the compatibility being bought. The
 `args` test proves the round trip.
 

docs/testing.md

@@ -27,6 +27,15 @@ transcript. Serial is per-architecture (x86 uses port I/O; an ARM board uses a
 memory-mapped UART), so it lives behind the [arch](arch.md) boundary — and adding
 a new architecture's UART is what makes the same tests run there.
 
+The serial log sink is **compiled in only under `-Dserial`** (off by default).
+A real machine often has no live legacy COM1 — writing to a dead one is slow —
+and the boot log is kept in a RAM buffer (`klog`) and flushed to disk instead,
+so serial is now purely a QEMU/dev aid. The harness (`test/qemu_test.py`) builds
+every case with `-Dserial=true`, and `zig build run-x86-64` boots a serial-enabled
+image variant, so both get the transcript; a flashable `zig build` image leaves
+serial out. (Even with `-Dserial`, a loopback probe disables a dead port at boot,
+so a serial-enabled image is still safe on real hardware.)
+
 ## In-kernel test cases
 
 Building with `-Dtest-case=<name>` makes the kernel, after normal bring-up, run one

docs/threading-plan.md

@@ -0,0 +1,469 @@
+# Threading — build plan (`runtime.Thread` over a private thread ABI)
+
+The ordered, checkpointable build-out for [threading.md](threading.md). Each milestone
+lands on its own and ends in a **verifiable gate** — shaped for a `/loop` run, like
+[display-v2-plan.md](display-v2-plan.md). Read threading.md first for the *why*.
+
+## Locked decisions (do not relitigate)
+
+- **`runtime.Thread` mirrors `std.Thread`'s API; the implementation is danos-native.**
+  Not literal `std.Thread` — that would break the [private ABI](syscall.md).
+- **Threads are a narrow, per-binary opt-in.** Default concurrency stays process + IPC
+  ([resilience.md](resilience.md)); only a service that asks is built
+  `single_threaded = false`.
+- **Blocking is futex-backed, never spin-backed** — waiters park in the kernel so an
+  idle core still halts ([halting.md](halting.md)).
+- **New syscalls are private**: extend [abi.zig](../system/abi.zig) `SystemCall` after
+  `shm_physical = 36` (`thread_spawn = 37`, `thread_exit = 38`, `current_core = 39`,
+  `futex_wait = 40`, `futex_wake = 41`) + a `library/runtime` wrapper; user code never names a number.
+- **Restart granularity stays the process** — a faulting thread kills its process; the
+  supervisor restarts the process, which respawns its threads.
+
+## Conventions
+
+Follow [coding-standards.md](coding-standards.md): spell out non-acronym abbreviations,
+kebab-case file names, no `Co-Authored-By` trailers. New user binaries go through
+`addUserBinary` (with the new `threaded` flag where a binary spawns threads) and get
+packed into the initial-ramdisk; new syscalls extend [abi.zig](../system/abi.zig)
+`SystemCall` + a `library/runtime` wrapper; test services live beside the code they
+exercise and register a `ServiceId` if they must be looked up.
+
+## How to verify along the way
+
+**Every gate is serial-checkable — no screenshots** (this plan runs unattended). A
+thread proves it ran by writing to **shared memory** the parent reads back, and proves
+parallelism by stamping the **core index** it ran on (like the `smp`/`affinity` cases).
+
+- `zig build test` — host unit tests (closure packing, mutex state machine, futex
+  wrapper encodings).
+- `python3 test/qemu_test.py <case>` — boots the kernel in QEMU; asserts on serial
+  markers. Thread cases set `smp: true` (real parallelism) and bump `mem` (they boot
+  the process/scheduler stack); each milestone **adds its case to `CASES`** so its gate
+  is runnable.
+- **Guardrail every milestone:** the concurrency-sensitive existing cases stay green —
+  `smoke`, `sched`, `priority`, `smp`, `affinity`, `process`, `process-kill`,
+  `supervision`, `fault-recovery`, `vfs-client-death`, `ipc`/`ipc-cap`,
+  `display-service`. A threading change that regresses those is rejected.
+
+## Unattended execution (the loop contract)
+
+This plan runs to completion **without human input**. Every design choice is already
+fixed in *Locked decisions*; the checkboxes are the only state. A loop iteration must:
+
+1. **Resume** at the first milestone that still has an unchecked `- [ ]`. (All earlier
+   milestones are done — do not revisit them.)
+2. **Work on a branch.** On the first iteration, branch off the current `main` into a new
+   branch (e.g. `threading-phase2` — Phase 1's `threading` is already merged); never
+   commit to `main` directly. Push that **branch** to `origin` after each milestone (step
+   5) so progress is backed up remotely; **do not push `main`** — merging Phase 2 into
+   `main` stays a human step.
+3. **Implement** every unchecked item in that milestone, including adding its
+   `-Dtest-case` to `CASES` in [test/qemu_test.py](../test/qemu_test.py) (with
+   `smp: true` / a `mem` bump where noted) so the gate is runnable.
+4. **Run the gate**: `python3 test/qemu_test.py <case>`, then the full **guardrail
+   set**, then `zig build` (clean) and `zig build test` (green).
+5. **Decide, do not ask:**
+   - **Green** = the milestone's case prints its stated marker(s) and reports `PASS`,
+     the whole guardrail set passes, `zig build` is clean, and host tests are green.
+     → tick this milestone's boxes **and** its `**Gate:**`-referenced case, `git commit`
+     (`threads(M<n>): <summary>`, no `Co-Authored-By` trailer per
+     [coding-standards.md](coding-standards.md)), then **`git push` the working branch to
+     `origin`** (use `-u` on the first push to set upstream). Continue to the next
+     milestone in the same iteration if budget remains; otherwise let the loop re-fire.
+   - **Red** = anything above fails. Diagnose from the captured serial log
+     (`zig-out/qemu-test/<case>-failed-serial.log`) and fix in place, then re-run — up to
+     **3 fix attempts** for that gate. A concurrency case that fails then passes on a
+     bare re-run is **flaky, not green**: re-run it **twice more** and treat green only
+     if it passes all; otherwise fix the race (a real threading bug), don't paper over
+     it.
+6. **A genuinely ambiguous fork is not a stop.** Pick the option most consistent with
+   [threading.md](threading.md)'s *Locked decisions*, note the choice in the commit
+   message, and continue. Do not pause for confirmation on in-scope, reversible work —
+   this plan is that authorization.
+
+**The only stop conditions:**
+
+- **Done** — every milestone box **in this plan** is checked (M1 through M11), `zig build`
+  clean, the whole `thread-*` suite + guardrail green. Phase 1 (M1–M6) is *already*
+  checked, so do **not** read that as Done: the loop's real work is the first plan section
+  that still has unchecked boxes — Phase 2 (M7–M11). Only stop when M7–M11 are all checked
+  too. Update threading.md's status line, push the final branch state to `origin`, and
+  stop. The branch is on `origin` for review; **merging Phase 2 into `main` is the user's
+  step**, not the loop's.
+- **Blocked** — a gate is still red after 3 fix attempts, or a step needs something
+  outside the repo (a toolchain change, new hardware, a decision no locked decision
+  covers). Append `> **BLOCKED (M<n>):** <what failed, what was tried, the serial
+  marker missing>` under that milestone, commit **and push** the WIP on the branch, and
+  stop. Do not thrash further and do not silently skip the milestone.
+
+Nothing else warrants stopping — not "should I proceed?", not "is this right?". The
+checkboxes + git history are the resumable record; the next iteration picks up from the
+first unchecked box.
+
+---
+
+## M1 — Address-space refcount (kernel foundation, no API, no behaviour change) ✅
+
+The one invariant change threads require, landed and proven **before** anything shares
+an address space. Today address space is 1:1 with a task and teardown destroys it on any user
+task's exit; make destruction happen on the **last** exit.
+
+- [x] A refcount keyed by the address-space root, held in `scheduler.zig`
+      (`address_space_refs`): `retainAddressSpace` takes a reference in `spawnUserLocked` (on the
+      success path, after the slot + stack are secured), all under the big kernel lock.
+- [x] Both task-teardown paths ([scheduler.zig](../system/kernel/scheduler.zig):
+      `exitUserLocked` and `destroyTaskLocked`) call `releaseAspace`, which decrements
+      and only `destroyAddressSpace`s at **zero**; an unretained space (hand-built test
+      spaces) is destroyed directly, preserving prior behaviour.
+- [x] `-Dtest-case=address-space-refcount`: spawn and reap several ring-3 processes in sequence
+      and assert (via test-observable `liveAddressSpaceCount`/`addressSpaceDestroyCount`) that the
+      live-space count returns to **baseline** and destructions advance by exactly that
+      many — each space destroyed exactly once, no leak, no double-free. (Refcount
+      observables, not raw frame counts, since kernel stacks are still leaked on exit.)
+
+**Gate (met):** `python3 test/qemu_test.py address-space-refcount` passes
+(`address-space-refcount: spaces released to baseline ok` → `DANOS-TEST-RESULT: PASS`), and the
+full guardrail set passes unchanged — 13/13 (`smoke`, `sched`, `priority`, `smp`,
+`affinity`, `process`, `process-kill`, `supervision`, `fault-recovery`,
+`vfs-client-death`, `ipc`, `ipc-cap`, `display-service`); default `zig build` clean,
+`zig build test` green. The reframing is invisible until an address space is actually shared.
+
+## M2 — `thread_spawn` + `thread_exit`: a thread runs in the shared address space ✅
+
+Spawn only — no join yet. Prove a second task executes in the **caller's** address
+space and exits cleanly.
+
+- [x] [abi.zig](../system/abi.zig): `thread_spawn = 37`, `thread_exit = 38`. Handlers in
+      process.zig; `thread_spawn` calls `scheduler.spawnThread` (shares the caller's
+      address space, `retainAddressSpace`); `thread_exit` ends the task like a process `exit(0)`
+      (`terminateCurrent` → `releaseAspace`). The closure pointer is delivered in the new
+      thread's **rdi** via a new `jump_to_user_arg` asm path (`t.user_arg`, 0 for a
+      process) — no naked runtime asm.
+- [x] `library/runtime/thread.zig` (barrel-exported as `runtime.Thread`): `spawn` maps a
+      stack (`mmap`), heap-allocates the `{args}` closure, and calls
+      `thread_spawn(&Closure.entry, stack_top, closure)`; `Closure.entry` (a plain C-ABI
+      Zig fn, closure in rdi) runs the function and calls `thread_exit`. Stack top is
+      16-aligned-minus-8 for the C entry.
+- [x] A `threaded` flag on the user-binary recipe (`addThreadedUserBinary` →
+      `single_threaded = false`); `thread-test` is the first opt-in binary.
+- [x] `-Dtest-case=thread-spawn`: `thread-test` spawns a worker that writes a sentinel to
+      a **shared** global and release-stores `done`; the main thread acquire-polls `done`
+      and asserts the shared global holds the sentinel — proof the worker ran in the same
+      address space.
+
+**Gate (met):** `python3 test/qemu_test.py thread-spawn` passes
+(`thread-test: child ran in shared address space ok` → `DANOS-TEST-RESULT: PASS`); guardrail set
+16/16 green (incl. `args`/`init`/`process`, which exercise the new `jump_to_user_arg`
+process path with arg 0) plus `address-space-refcount`; `zig build` clean, `zig build test`
+green.
+
+> **Note (deferred to M3+):** the mmap arena is per-*task* (`heap_next`), so two threads
+> in one address space that both `mmap` would collide. Fine for M2 (only the parent maps, for the
+> child's stack); make the arena per-address-space and the runtime heap thread-safe alongside the
+> `Mutex` work (M5).
+
+## M3 — `join` + `detach` + real parallelism ✅
+
+- [x] `join` over the existing exit-notification path
+      ([process-lifecycle.md](process-lifecycle.md)): `thread_spawn` gained a 4th arg, an
+      `exit_endpoint` handle (resolved + refcounted like `spawnProcessSupervised`, via
+      `spawnThreadSupervised`); `join` blocks in `ipc_reply_wait` on that endpoint until
+      the child-exit notice for its `tid`, then `munmap`s the stack. `detach` relinquishes
+      the join right (its stack is reclaimed at process exit — kernel-reaper reclaim for
+      detached threads is deferred; see note).
+- [x] `runtime.Thread.join` / `detach`, plus `Thread.currentCore()` (a new `current_core`
+      = 39 syscall) for the parallelism proof. `getCurrentId` deferred to M6 (TLS), where
+      a lighter self-id fits. The closure now rides the **thread's own stack** (not the
+      heap) — private per thread, so spawn/join touch no shared heap.
+- [x] `-Dtest-case=thread-join` (`smp: 4`): `thread-test` join mode spawns N=4 workers
+      that each do K=100k `@atomicRmw`-increments on a shared counter and stamp the core
+      they ran on; the main thread joins all N and asserts `counter == N*K` **and**
+      `@popCount(cores_seen) > 1` (genuine cross-core parallelism), then a detached worker
+      proves `detach` runs without a join.
+
+**Gate (met):** `python3 test/qemu_test.py thread-join` passes (`thread-test: join ok` →
+`DANOS-TEST-RESULT: PASS`), robust across 4 runs; guardrail 17/17 green (incl. `smp`,
+`affinity`, `process-kill`, and `args`/`init`/`process` on the exit-endpoint spawn path)
+plus `address-space-refcount`/`thread-spawn`; `zig build` clean, `zig build test` green.
+
+> **Note (deferred):** a detached thread's stack is freed only at process exit (not by the
+> reaper on thread exit) — kernel user-stack tracking + reclaim is a later refinement. And
+> the runtime heap is still not thread-safe: threads that both allocate concurrently would
+> race (the thread *machinery* avoids the heap, but worker code sharing an allocator does
+> not). Both fold into the M5 `Mutex`/allocator work.
+
+## M4 — Futex: the one blocking primitive ✅
+
+- [x] [abi.zig](../system/abi.zig): `futex_wait = 40`, `futex_wake = 41`. A waiter is a
+      `.blocked` task tagged with `Task.futex_addr` (no queue linkage);
+      `futex_wait(addr, expected, timeout_ns)` reads the user word under the big lock,
+      parks iff `*addr == expected`, and returns on wake or timeout; `futex_wake(addr,
+      count)` scans the task table and readies up to `count` matching waiters (same
+      address space). No spinning — a parked waiter leaves its core free to `hlt`. A
+      timed wait also sets `wake_at`, so the timer's `wakeExpired` wakes it; `futex_addr`
+      staying non-zero (only `futex_wake` clears it) is how the waiter tells timeout from
+      a real wake.
+- [x] `runtime.Thread.Futex` (`wait` / `timedWait` / `wake`) over the syscall wrappers.
+- [x] `-Dtest-case=thread-futex` (`smp: 4`): a waiter thread prints `waiting` and
+      `futex_wait`s on a word; the main thread publishes it, prints `waking`, and
+      `futex_wake`s; the waiter prints `woke`. Then a `timedWait` on an unwoken word
+      reports `error.Timeout`.
+
+**Gate (met):** `python3 test/qemu_test.py thread-futex` passes, robust across 3 runs —
+the case's **ordered** regex asserts `waiting → waking → woke → PASS` on the serial
+stream (the handoff proof), and `thread-futex: timeout ok` confirms the timeout.
+Guardrail 18/18 green (incl. `sleep`/`event`/`ipc` blocking paths) + `address-space-refcount`,
+`thread-spawn`, `thread-join`; `zig build` clean, `zig build test` green.
+
+> **Note:** the kernel test checks only the freshest verdict marker via `bufferHas` (the
+> in-memory log ring buffer evicts older lines); ordering is asserted against the full
+> serial stream by the qemu regex instead.
+
+## M5 — `Mutex` + `Condition` + `Semaphore` ✅
+
+- [x] `runtime.Thread.Mutex` (three-state futex mutex: CAS fast path, `futex_wait`/`wake`
+      slow path), `Condition` (`wait`/`timedWait`/`signal`/`broadcast`, a futex sequence
+      counter), `Semaphore` (permits over `Mutex`+`Condition`) — the same state machines
+      `std.Thread` uses, ported onto our `Futex`.
+- [x] `-Dtest-case=thread-mutex` (`smp: 4`): a bounded producer/consumer — 2 producers +
+      2 consumers over one `Mutex` and two `Condition`s move N=2000 unique items through
+      an 8-slot ring; the consumed checksum and tally match exactly (no lost/duplicated
+      item, no overrun) under real cross-core contention. The small ring forces producers
+      to block on full and consumers on empty, exercising `Condition.wait`.
+
+**Gate (met):** `python3 test/qemu_test.py thread-mutex` passes (`thread-mutex: ok` →
+`DANOS-TEST-RESULT: PASS`), robust across 3 runs; guardrail 17/17 green (incl.
+`sleep`/`event`/`ipc`) + all M1–M4 thread cases; `zig build` clean, `zig build test`
+green.
+
+> **Deferred (with rationale):**
+> - **`join` → futex completion word** — the exit-endpoint join (M3) is correct and
+>   tested. A futex-completion join needs the *kernel* to clear+wake a word after the
+>   thread is fully off its stack (a CLONE_CHILD_CLEARTID-style mechanism); doing it in
+>   the thread's own trampoline would let `join` `munmap` the stack while the thread still
+>   runs on it (use-after-free). Left on the exit-endpoint path; the kernel clear-on-exit
+>   is a later, separate refinement.
+> - **Host unit tests for the state machines** — `Mutex`/`Condition` bottom out in the
+>   `futex_*` syscalls, unavailable on the host without a mockable `Futex` seam. The QEMU
+>   `thread-mutex` gate exercises them under real concurrency instead; a host-side mock is
+>   future work.
+
+## M6 — `getCurrentId`, docs, and CI wiring ✅
+
+- [x] `getCurrentId` via a small `thread_self = 42` syscall (`runtime.Thread.getCurrentId`
+      returns the kernel task id). **Per-thread `threadlocal` TLS is deferred** — no
+      consumer needs it, and it would require context-switching the thread pointer per task
+      (real kernel + per-switch cost) for an unused feature; threaded binaries have run fine
+      without it through M2–M5. threading.md's TLS reasoning already scoped it as
+      deferred-unless-needed. When a consumer appears, the shape is: `thread_spawn`
+      allocates a per-thread TLS block, sets the thread pointer, and the context switch saves/
+      restores it.
+- [x] `RwLock` / `WaitGroup` deferred (no consumer yet); they slot onto the same
+      `Futex`/`Mutex`/`Condition` when wanted.
+- [x] All `thread-*` cases wired into [test/qemu_test.py](../test/qemu_test.py)
+      (`thread-spawn`/`-join`/`-futex`/`-mutex`/`-id`); threading.md + docs/README.md
+      status updated to **built**; the worked example is threading.md's win-condition.
+- [x] `-Dtest-case=thread-id` (`smp: 4`): two workers read `getCurrentId`; the main
+      thread confirms all three ids are non-zero and distinct — each thread has its own
+      kernel identity. (Renamed from `thread-tls`, which implied `threadlocal`.)
+
+**Gate (met):** `python3 test/qemu_test.py thread-id` passes; the whole `thread-*` suite
+(`thread-spawn`/`-join`/`-futex`/`-mutex`/`-id`) plus the full guardrail set pass; default
+`zig build` clean, `zig build test` green.
+
+---
+
+## Status
+
+**Phase 1 (M1–M6): built.** danos has `runtime.Thread` — `spawn`/`join`/`detach`,
+cross-core parallelism, futex, and `Mutex`/`Condition`/`Semaphore`, all over a private
+thread ABI behind the runtime.
+
+**Phase 2 (M7–M11): built.** Thread-safe allocation (M7), a task reaper that reclaims dead
+tasks' kernel stacks (M8), endpoint-free `thread_join` (M9), the per-thread thread pointer (M10),
+and `RwLock`/`WaitGroup` + host-testable sync (M11). Two things stay deferred by design
+(no consumer): the Zig `threadlocal` *compiler* layer (M10) and detached-thread user-stack
+reclaim (M9) — both noted in place.
+
+---
+
+## Phase 2 — hardening (M7–M11)
+
+The organising principle, so Phase 2 reinforces danos's goals rather than eroding them:
+
+- **Everything a thread owns is reclaimed on process death.** Thread stacks, TLS blocks,
+  and futex words live in the process's **address space**, and the kernel's per-process
+  state is keyed by the address-space root — so the M1 refcount + `destroyAddressSpace` already
+  free all of it when the last thread exits. A crashed or killed threaded process leaves
+  **nothing** behind. Phase 2 closes the one thing that is *not* address-space-owned — the
+  per-task **kernel** stack (kernel heap) — with a reaper (M8). This is the
+  [resilience](resilience.md) restart guarantee, extended to threads.
+- **Kernel owns mechanism; the runtime owns policy.** The kernel maps pages, saves/
+  restores the thread pointer, and reaps dead tasks; the runtime decides allocation, TLS layout,
+  and lock algorithms. Every new kernel entry stays a private syscall behind the runtime
+  ([syscall.md](syscall.md)) — the ABI stays renumberable.
+- **The process is still the isolation and restart boundary.** Threads share fate within
+  one process; Phase 2 never adds a way for one process to reach into another (the
+  cross-process futex stays explicitly out of scope, below).
+
+### M7 — Thread-safe allocation (the correctness gap) ✅
+
+Today the mmap arena cursor is per-*task* and the runtime heap is unlocked, so two
+threads in one process that both allocate corrupt each other. The thread *machinery*
+avoids this (closure on the stack, stacks mmap'd only by the spawner), but real
+multi-threaded code would hit it. Closed it:
+
+- [x] **Kernel — per-address-space mmap arena.** Grew M1's `address_space_refs` entry into the
+      per-address-space object holding the `mmap`/`mmio` arena cursors (moved off `Task`);
+      `scheduler.addressSpaceMmapNextPtr`/`addressSpaceDeviceMapNextPtr` expose them. `systemMmap`
+      reserves a disjoint range under a *brief* lock, then maps **per page** under a
+      short-held lock — not the whole grant — because the big lock is held with interrupts
+      disabled, so pinning it across a multi-MiB memset+map froze other cores (it timed
+      the `affinity` scenario out mid-bring-up). Freed at refcount zero, so the cursors
+      vanish with the process.
+- [x] **Runtime — thread-safe heap.** The allocator's two free-list mutators
+      (`rawAlloc`/`rawFree`) take a `Thread.Mutex`, gated on
+      `!@import("builtin").single_threaded` so single-threaded binaries compile it out and
+      pay nothing. Uncontended acquisition is a single CAS (no syscall).
+- [x] `-Dtest-case=thread-alloc` (`smp: 4`): 4 threads each do 500 `alloc`/fill/verify/
+      `free` cycles of varied sizes; each block is filled with a per-thread pattern and
+      verified before free, so any overlap between concurrent allocations is caught.
+
+**Gate (met):** `thread-alloc` passes (3× non-flaky); full guardrail 23/23 green,
+`zig build`/`zig build test` clean.
+
+> **Also fixed here:** the `affinity` guardrail's fixed-count busy-loop (`while (spins <
+> 3e9)`) had codegen-dependent wall-time — adding a function to `tests.zig` flipped how
+> the optimiser compiled it, swinging affinity from ~4 s to ~63 s and timing it out.
+> Reworked it (and the settle loop) to wait on the wall clock instead, so its duration is
+> independent of unrelated code changes.
+
+### M8 — The task reaper (cleanup + resilience) ✅
+
+A dead task's **kernel** stack was leaked ("no reaper yet") — every process *and* thread
+death lost one, so a crash loop bled kernel memory. The reaper fixes it and serves the
+[resilience](resilience.md) restart goal directly:
+
+- [x] A dying task cannot free the kernel stack it runs on, so `exit()`/`exitUserLocked`
+      record it in a **per-core `reap_after_switch` slot** and switch away; the task that
+      resumes on that core frees the stack in `switchTo`'s tail (it's on its own stack, the
+      big lock is still held so the slot can't have been reused). A **tick-time drain**
+      (`reapKillPendingLocked`) is the safety net for the case where the next task is
+      *fresh* (enters via the trampoline, bypassing `switchTo`'s tail). A task killed while
+      *not* running is freed immediately in `destroyTaskLocked`. A `live_stack_bytes`
+      counter is the observable. *(Detached-thread user-stack reclaim moves to M9, which
+      adds the joinable/detached flag.)*
+- [x] `-Dtest-case=task-reap` (`smp: 4`): spawn and kill 12 processes; poll the
+      test-observable `scheduler.liveStackBytes()` until it returns to **baseline** (a
+      correct reaper gets there in a few ms; a genuine leak times out) — every kernel
+      stack reclaimed, no leak. Threads exit through the same `exitUserLocked`, so covered.
+
+**Gate (met):** `task-reap` passes (5× isolated + 2× in the full batch); `fault-recovery`,
+`supervision`, `process-kill`, `address-space-refcount`, `smp`, `affinity` all still green (24/24
+full guardrail); `zig build`/`zig build test` clean.
+
+> **Bug found + fixed here (touches every context switch):** the post-`switchContext` reap
+> first read the `pc` **parameter**, but a task that migrated cores carries a *stale* `pc`
+> in its saved `switchTo` frame — so it read the wrong core's slot and freed a live stack
+> (a #GP under SMP). Fixed to re-fetch `thisCpu()` after the switch (the switch only swaps
+> stacks on the current core).
+
+### M9 — Futex-completion join (retire the per-thread endpoint)
+
+With the reaper (M8) able to act *after* a thread is fully off its stack, migrate `join`
+to the std shape and drop M3's per-thread exit endpoint:
+
+- [x] A **`thread_join(tid)` syscall** (not a user futex word): it blocks the caller until
+      the task with id `tid` exits, and the exit paths call `wakeJoinersLocked`. `join`
+      only reclaims the joined thread's **user** stack, which the thread vacates the moment
+      it enters the kernel to exit — so waking at *exit* time (not reap time) is safe, and
+      no reaper/address-space juggling or user-memory write is needed. This is equally
+      std-shaped (like `pthread_join`) and much simpler/safer than the planned
+      reaper-written completion word. `thread_spawn` no longer takes an exit endpoint (the
+      runtime passes `no_cap`); the per-thread IPC endpoint is gone.
+- [x] `thread-join` passes on the new path, and its join mode now runs **40 spawn+join
+      cycles** — under the old per-thread-endpoint scheme those leaked handles would
+      exhaust the 16-slot handle table; here they all succeed, proving join is endpoint-free.
+
+**Gate (met):** `thread-join` passes (3× isolated) on the `thread_join` path; full
+guardrail 26/26 (incl. `process-kill`, `supervision`, `fault-recovery`, `task-reap`);
+`zig build`/`zig build test` clean.
+
+> **Reaper hardened here (fixes an M8 flake).** M8's single per-core reap slot could be
+> *overwritten* by a second death on that core before the first drained (a fresh-task/SMP
+> timing window) — an intermittent one-stack leak (`task-reap` flaked ~20%). Replaced it
+> with a per-core reap **list** plus a `.reaping` task state so a pending slot can't be
+> reused before its stack is freed. `task-reap` now 11/11 isolated + 2× in the batch.
+
+> **Deferred:** detached-thread **user-stack** reclaim (still freed at process exit, as in
+> M3). Doing it in the reaper needs the saved address space + stack range and a
+> translate/unmap in a not-currently-loaded address space — real complexity for a bounded leak.
+> A follow-up when a consumer needs it.
+
+### M10 — Per-thread TLS: the thread-pointer mechanism ✅
+
+Give each thread its own thread pointer and private TLS storage — the foundation
+self-hosting Zig ([zig-self-hosting.md](zig-self-hosting.md)) will build `threadlocal` on.
+
+- [x] **Kernel** stores `thread_pointer` on `Task` and restores it on every context switch
+      **only when it changes** (the same conditional-load discipline as CR3;
+      `architecture.setThreadPointer` → `wrmsr IA32_FS_BASE` on x86_64). A
+      `set_thread_pointer(addr)` = 44 syscall sets the caller's `thread_pointer` and loads it
+      now. The kernel never touches FS, so there is no swapgs complication.
+- [x] **Runtime** lays a small per-thread TLS block at the top of each thread's stack
+      (self-pointer at `%fs:0` + scratch slots) and the thread trampoline calls
+      `set_thread_pointer` before any user code — so every spawned thread has a private,
+      switch-stable thread pointer. Reclaimed with the stack.
+- [x] `-Dtest-case=thread-tls` (`smp: 4`): two threads each write a unique marker to their
+      own `%fs:8` slot and — after both have written — read it back; a shared (non-per-thread)
+      FS base would clobber one and cause cross-talk. Both read their own marker → pass.
+
+**Gate (met):** `thread-tls` passes (3×); full guardrail 25/25 (the switch-time thread-pointer
+restore touches every context switch); `zig build`/`zig build test` clean.
+
+> **Deferred: the Zig `threadlocal` *compiler* layer.** Real `threadlocal` variables need
+> the ELF **variant-II TLS** surface — `.tdata`/`.tbss` sections + a `PT_TLS` program header
+> in `user.ld`, a runtime that copies the template with exact negative-offset layout, and
+> the `.large`-code-model TLS section names — a high-uncertainty lift for a feature with
+> **no consumer today** (threading.md scopes it "only if a consumer needs it"). What lands
+> here is the load-bearing piece — the per-thread thread pointer, context-switched — so adding the
+> compiler layer later is purely runtime+linker work on top, no kernel change. `getCurrentId`
+> stays the `thread_self` syscall (M6) rather than an fs self-slot (which would need the
+> main thread's TLS set up in `_start` too).
+
+**Gate:** `thread-tls` passes; full `thread-*` suite + guardrail green.
+
+### M11 — `RwLock`, `WaitGroup`, and host-testable sync ✅
+
+- [x] `runtime.Thread.RwLock` (reader-preferring: `>0` readers / `-1` writer / `0` free,
+      with `lock`/`tryLock`/`unlock` + `lockShared`/`tryLockShared`/`unlockShared`) and
+      `WaitGroup` (`start`/`finish`/`wait`), both on the existing `Mutex`/`Condition`.
+- [x] A compile-time `Futex` seam gated on `builtin.os.tag == .freestanding`: the futex
+      syscalls on danos, a spin+yield mock off-target (Zig 0.16 has no `std.Thread.Futex`;
+      `wake` is a no-op since the state machines re-check). `thread.zig` is wired into
+      `zig build test`, so `Mutex`/`RwLock`/`WaitGroup` run as **host unit tests** with real
+      `std.Thread` threads (`test` blocks only compile under test).
+- [x] `-Dtest-case=thread-rwlock` (`smp: 4`): 2 writers set both halves of a value under
+      the exclusive lock while 3 readers check the halves match under the shared lock —
+      zero half-write observations across ~150k reads. Host tests cover the Mutex,
+      RwLock, and WaitGroup state machines.
+
+**Gate (met):** `zig build test` covers the sync primitives (host threads); `thread-rwlock`
+passes (3×); full Done gate **26/26** (whole `thread-*` suite + guardrail); `zig build`
+clean.
+
+---
+
+## Deferred (explicitly not in this plan)
+
+- **Cross-process shared-memory futex** — the `(address_space, virtual_address)` key can become a
+  physical-address key so two processes share a futex through an [shm](display-v2.md)
+  region. Not needed for intra-process threads.
+- **Per-thread priorities / affinity distinct from the process** — threads inherit the
+  process priority ([scheduling.md](scheduling.md)); revisit only if it earns its keep.
+- **Per-thread signal delivery** — signals stay process-scoped
+  ([process-lifecycle.md](process-lifecycle.md)).
+- **A `pthread`/POSIX surface** — the API is `std.Thread`-shaped Zig, nothing more.
+- **A real `std.Thread` backend** — arrives with self-hosting
+  ([zig-self-hosting.md](zig-self-hosting.md)); it sits on these same primitives, so it
+  swaps the impl under `runtime.Thread`, not the call sites.

docs/threading.md

@@ -0,0 +1,332 @@
+# Threading: `runtime.Thread`, a std-shaped API over a private thread ABI
+
+A note on danos **threads** — several tasks sharing one address space — provided by a
+`runtime.Thread` type that mirrors the shape of Zig's `std.Thread` while keeping every
+kernel entry behind the [runtime](../library/runtime). **Built** (M1–M11, see
+[threading-plan.md](threading-plan.md)): `spawn`/`join`/`detach`, cross-core parallelism,
+a futex, `Mutex`/`Condition`/`Semaphore`/`RwLock`/`WaitGroup`, `getCurrentId`/`currentCore`,
+per-thread thread-pointer TLS, thread-safe allocation, and a task reaper that reclaims dead
+tasks' kernel stacks. Deferred by design (no consumer yet): the Zig `threadlocal`
+*compiler* layer (the per-thread thread pointer is in place, so it's runtime+linker work on top) and
+detached-thread user-stack reclaim — see the plan's M9/M10 notes. The analysis is against
+**Zig 0.16** (the pinned toolchain); `std.Thread`'s internals move between releases, so
+treat upstream shapes as "0.16.x."
+
+## The win condition
+
+A danos service can write
+
+```zig
+const t = try runtime.Thread.spawn(.{}, worker, .{ctx});
+// ... do other work concurrently ...
+t.join();
+```
+
+and get real parallelism across cores — with `runtime.Thread.Mutex`,
+`runtime.Thread.Condition`, and `runtime.Thread.Semaphore` available for
+coordination — **without any code path reaching the kernel except through the
+runtime**. The call sites read exactly like `std.Thread`, so the day danos becomes a
+real Zig target (see [self-hosting](#the-self-hosting-endgame)) we swap the
+implementation underneath, not the API above.
+
+## Locked decisions (do not relitigate)
+
+- **We build `runtime.Thread`, not literal `std.Thread`.** It mirrors std's *API and
+  features*; the implementation underneath is danos-native. See
+  [Why not literal std.Thread](#why-not-literal-stdthread).
+- **Threads are a narrow, opt-in capability — not the default concurrency tool.** The
+  default for resilience stays **process + IPC** ([resilience.md](resilience.md),
+  [ipc.md](ipc.md)). See [Where threads fit](#where-threads-fit-the-resilience-tension).
+- **Blocking synchronization is futex-backed, never spin-backed.** Waiters sleep in
+  the kernel so an idle core still halts ([halting.md](halting.md)).
+- **Per-binary opt-in to multi-threaded codegen.** Only a service that asks for
+  threads is built `single_threaded = false`; the rest stay lean and single-threaded.
+- **The thread ABI is private.** New syscalls extend [abi.zig](../system/abi.zig)
+  `SystemCall` and are reached only through `library/runtime` wrappers, exactly like
+  every other danos syscall ([syscall.md](syscall.md)) — numbers stay renumberable.
+
+## Why not literal `std.Thread`
+
+danos's ABI invariant is that the **runtime is the sole holder of the syscall ABI**,
+and that ABI is private and renumberable ([syscall.md](syscall.md) — "unstable
+private ABI"). That is a security and evolvability asset: no compiled binary can
+hardcode a syscall number, and the kernel can renumber freely because only the
+runtime — rebuilt in lockstep — knows the mapping.
+
+`std.Thread` is incompatible with that invariant on two counts:
+
+1. **It selects its backend from `builtin.os.tag`, and issues syscalls directly.**
+   danos targets `.os_tag = .freestanding` ([build.zig](../build.zig)), for which
+   `std.Thread` resolves to an unsupported stub that `@compileError`s. Adding a real
+   backend would either bake danos syscall numbers into std (breaking ABI privacy and
+   renumbering) or fork std to route back through the runtime — a permanent rebase
+   cost that buys nothing the native type doesn't.
+2. **Our user binaries are built `single_threaded = true`** ([build.zig](../build.zig)
+   `addUserBinary`), which compiles threading out entirely and makes atomics and TLS
+   single-threaded. Threads need this flipped per binary regardless.
+
+So we take the *shape* of `std.Thread`, not the *type*. The cost of replicating the
+surface (spawn/join/Mutex/Condition) is small; the cost of the std type is the ABI
+invariant.
+
+## Where threads fit: the resilience tension
+
+Threads are in genuine tension with a resilience-first microkernel, and it is worth
+being explicit so we do not reach for them by reflex.
+
+The reason danos pays for a microkernel is **fault isolation**
+([resilience.md](resilience.md)): a component corrupts its own address space, faults,
+and is **restarted** without touching anyone else — because the boundary *is* the
+address space. Threads deliberately remove that boundary *within* a process:
+
+- Threads share one address space, so one thread's stray write corrupts them all —
+  there is no isolation **between** threads.
+- Threads share fate: a fault in any thread, or a "kill the process" decision, takes
+  down **all** of them. Restartability lives at the process level, not the thread
+  level.
+- Shared mutable state reintroduces data races — the failure class the
+  isolate-and-message model was chosen to avoid.
+
+**Therefore:** the default answer to "make X concurrent" stays *another process over
+IPC* (isolated, independently restartable) or a single event loop with several
+message sources. Reach for a thread only inside **one** service that needs genuine
+**shared-memory, low-latency parallelism** and can accept intra-service fate-sharing —
+e.g. a compositor splitting tile compositing across cores, where per-tile IPC would be
+too chatty. "Input on one thread, display on another" is *not* that case; it wants two
+processes. The isolation boundary stays at process granularity.
+
+## The API surface (mirrors `std.Thread`)
+
+Lives in `library/runtime/thread.zig`, re-exported as `runtime.Thread`.
+
+```zig
+pub const Thread = struct {
+    pub const Id = u32;                       // the kernel task id
+    pub const SpawnConfig = struct {
+        stack_size: usize = default_stack_size,
+        allocator: ?std.mem.Allocator = null, // for the closure + stack bookkeeping
+    };
+    pub const SpawnError = error{ OutOfMemory, ThreadQuotaExceeded, SystemResources };
+
+    pub fn spawn(config: SpawnConfig, comptime function: anytype, args: anytype) SpawnError!Thread;
+    pub fn join(self: Thread) void;           // block until the thread ends, reclaim its stack
+    pub fn detach(self: Thread) void;         // give up the right to join; kernel reclaims on exit
+    pub fn getCurrentId() Id;
+    pub fn yield() void;                       // -> existing `yield` syscall
+
+    pub const Mutex     = struct { pub fn lock(*Mutex) void; pub fn tryLock(*Mutex) bool; pub fn unlock(*Mutex) void; };
+    pub const Condition = struct { pub fn wait(*Condition, *Mutex) void; pub fn timedWait(*Condition, *Mutex, u64) error{Timeout}!void; pub fn signal(*Condition) void; pub fn broadcast(*Condition) void; };
+    pub const Semaphore = struct { pub fn wait(*Semaphore) void; pub fn post(*Semaphore) void; };
+    pub const Futex     = struct { pub fn wait(*const atomic.Value(u32), u32) void; pub fn timedWait(...) error{Timeout}!void; pub fn wake(*const atomic.Value(u32), u32) void; };
+    // RwLock / ResetEvent / WaitGroup follow the same pattern, added as needed.
+};
+```
+
+Deviations from `std.Thread`, called out honestly:
+
+- **The thread function's return value is discarded** (as `std.Thread.join` returns
+  `void`). Return data through shared state or a `Semaphore`/`Condition`, not the
+  return.
+- `getCpuCount()` maps to the existing SMP core count ([smp.md](smp.md)); a service
+  rarely needs it.
+
+## Kernel primitives (new private syscalls)
+
+Four new entries extend [abi.zig](../system/abi.zig) `SystemCall` after
+`shm_physical = 36`, each with a `library/runtime` wrapper:
+
+| Syscall | Signature | Purpose |
+|---|---|---|
+| `thread_spawn` | `(entry, stack_top, arg) -> tid` | create a task sharing the **caller's** address space |
+| `thread_exit`  | `(stack_base, stack_len)` | end the calling thread; hand back its stack range for reclaim |
+| `futex_wait`   | `(addr, expected, timeout_ns) -> status` | block if `*addr == expected`, until woken or timeout |
+| `futex_wake`   | `(addr, count) -> woken` | wake up to `count` waiters on `addr` |
+
+Plus one invariant change with no new syscall: **address-space reference counting**.
+
+## Mechanics
+
+### Address-space reference counting
+
+Today an address space is 1:1 with a task: `spawnUserLocked` records `address_space` on the
+Task, and teardown does `destroyAddressSpace(t.address_space)` when **any** user task exits
+([scheduler.zig](../system/kernel/scheduler.zig)). With threads, several tasks share
+one `address_space`, so the first to exit would rip the address space out from under its
+siblings.
+
+Fix: a small refcount keyed by the address-space root (`createAddressSpace` in
+[process.zig](../system/kernel/process.zig) sets it to 1). `thread_spawn` increments
+it; task teardown decrements and only calls `destroyAddressSpace` at **zero**. All of
+this is already under the big kernel lock, so no new locking. This is the one piece
+that must land and be proven before anything shares an address space.
+
+### `thread_spawn` and the trampoline
+
+The scheduler already accepts an arbitrary `address_space` and does **not** smuggle values
+through registers — `startUserTask` reads the entry/stack from the Task and
+`jumpToUser`s ([scheduler.zig](../system/kernel/scheduler.zig)). That makes the thread
+path clean:
+
+1. The runtime's `spawn` `mmap`s a stack (syscall `4`), heap-allocates a closure —
+   `{ fn_ptr, args_tuple, completion }`, the std "Instance" pattern — and writes the
+   closure pointer to the **top word of the new stack**.
+2. It calls `thread_spawn(entry = &threadTrampoline, stack_top, arg = closure_ptr)`.
+   The kernel calls the same `spawnUserLocked` path with the **caller's address space**
+   (refcount++), `entry`, and `user_sp = stack_top`.
+3. `threadTrampoline` (a small runtime shim) reads the closure off its stack, calls
+   the user function, then calls `thread_exit`. No new register ABI — the closure
+   pointer rides the stack the runtime set up, mirroring how `startUserTask` avoids
+   register smuggling.
+
+Unlike a process start, there is **no** System V argc/argv/auxv block
+([sysv.md](sysv.md)) — a thread stack carries only the closure pointer.
+
+### Lifetime: exit, join, detach, stack reclaim
+
+- **`thread_exit`** marks the task dead and hands the kernel the thread's user-stack
+  range. The kernel reaps the task on the scheduler (already running on a *kernel*
+  stack, so it can safely unmap the user stack), decrements the address-space refcount, and
+  frees the task slot.
+- **`join` — Stage 1** reuses the existing exit-notification machinery
+  ([process-lifecycle.md](process-lifecycle.md)): `spawn` passes a per-thread
+  `exit_endpoint`, and `join` blocks in `ipc_reply_wait` until the child-exit
+  notification for that `tid` arrives, then `munmap`s the stack. No futex needed to
+  land spawn/join.
+- **`join` — Stage 2 refinement** migrates to the std shape: a `completion` word in
+  the closure that `thread_exit`'s trampoline `futex_wake`s and `join` `futex_wait`s
+  on — dropping the per-thread endpoint. Kept as a refinement so Stage 1 ships first.
+- **`detach`** relinquishes the join right; the kernel reclaims the stack and slot on
+  `thread_exit` (a detached thread's stack range is unmapped by the reaper, since no
+  joiner will).
+
+### Futex, and the sync primitives on top
+
+`futex_wait`/`futex_wake` are the one blocking primitive; `Mutex`, `Condition`, and
+`Semaphore` are ordinary user-space state machines over an `atomic.Value(u32)` that
+call the futex wrappers on the slow path — the same construction `std.Thread` uses,
+so the algorithms port directly.
+
+Keying: threads share an address space, so a **virtual address within that address space**
+identifies a futex uniquely; the kernel keys its wait queue by `(address_space_root, virtual_address)`.
+Keying by the **physical** address instead (translate `virtual_address -> physical_address` on entry) is a
+deliberate forward door: it lets two *processes* share a futex through an
+[shm](display-v2.md) region later, without changing the API. We start with the
+private-per-address-space key and note the physical-key upgrade.
+
+No spinning: a contended lock parks the task in the kernel and the core is free to run
+other work or `hlt` ([halting.md](halting.md)). This is why futex is a locked
+decision, not a "maybe later."
+
+### TLS and `getCurrentId`
+
+danos sets up no thread-pointer TLS today (fine under `single_threaded`). Two scoped needs:
+
+- **`getCurrentId`** returns the kernel task id — either a trivial syscall or, better,
+  a value the runtime stashes in a per-thread control block.
+- **`threadlocal` variables** need a real per-thread TLS block and the thread pointer set per
+  thread. `thread_spawn` sets the thread pointer to a runtime-allocated per-thread block; full
+  `threadlocal` support is Stage 3, only if a consumer needs it. Nothing in the core
+  spawn/join/mutex path requires `threadlocal`.
+
+### Build: multi-threaded codegen, opt-in
+
+`addUserBinary` gains a `threaded: bool = false` parameter; when set it builds that
+binary `single_threaded = false` so atomics and (later) TLS are real. Threads and
+atomics are unsound in a `single_threaded` image, so a binary must opt in **before**
+it may call `runtime.Thread.spawn`. Everyone else stays single-threaded and lean.
+
+## Interaction with the rest of the kernel
+
+- **Scheduler / SMP** ([scheduling.md](scheduling.md), [smp.md](smp.md)): a thread is
+  just another `Task` with an `address_space` shared with its siblings; the existing
+  per-core ready queues, priorities, and affinity apply unchanged. Threads of one
+  process can run on different cores simultaneously — that is the point.
+- **Halting** ([halting.md](halting.md)): futex-parked waiters keep the "idle core
+  halts" property intact under lock contention — no busy-wait.
+- **Lifecycle** ([process-lifecycle.md](process-lifecycle.md)): killing a process
+  must kill *all* its threads and only then drop the last address-space ref. The kill path
+  already targets a process; it fans out to every task on that address space.
+- **Resilience** ([resilience.md](resilience.md)): a faulting thread kills its whole
+  process (shared fate). The supervisor restarts the **process**, which respawns its
+  threads from a known-good state — restart granularity stays the process.
+- **IPC — two consequences threads forced ([ipc.md](ipc.md)):**
+  - *Handles do not cross threads.* The handle table lives on the `Task`
+    ([scheduler.zig](../system/kernel/scheduler.zig)), so a handle number is meaningful
+    only to the thread that created it — thread A's endpoint handle `3` is not thread B's.
+    A thread that needs to reach an endpoint another thread owns looks it up
+    (`ipc.lookup(service)`) to install its **own** handle to the same underlying endpoint.
+    This is how the display's mouse-listener thread reaches the compositor loop's endpoint
+    to poke it awake (docs/display.md).
+  - *IPC syscalls that touch shared kernel state now serialize under the big kernel lock.*
+    `create_ipc_endpoint`/`ipc_register`/`ipc_lookup` allocate from the kernel heap and
+    mutate the global service registry, endpoint refcounts, and handle tables. Those paths
+    were unlocked because a single-threaded process could not race itself; a multi-threaded
+    one can, from two cores at once. They now take `sync.enter()` like `call`/`reply_wait`/
+    `send` already did — the kernel heap has no lock of its own yet (heap.zig: "a lock comes
+    with threads/SMP"), so the big lock is what keeps its callers serialized.
+
+## Build-out plan (staged, each gate serial-checkable)
+
+The ordered, `/loop`-runnable milestones live in
+**[threading-plan.md](threading-plan.md)** (shaped like
+[display-v2-plan.md](display-v2-plan.md)): every milestone lands on its own and ends in
+a verifiable gate (`python3 test/qemu_test.py <case>`, asserting serial markers;
+`zig build test` for host unit tests). The stages below are the shape it expands.
+
+- **Stage 0 — address-space refcount.** Refcount on the address-space root; teardown destroys
+  at zero. No API yet; nothing shares an address space, so refcount is 1 everywhere.
+  *Gate:* the full QEMU suite stays green (no regression) — proves the reframing is
+  invisible until used.
+- **Stage 1 — spawn / join / detach.** `thread_spawn` + `thread_exit`, the trampoline,
+  stacks via `mmap`, join over the exit-endpoint, the `threaded` build flag.
+  *Gate:* `-Dtest-case=thread-spawn` — a threaded test service spawns N threads that
+  each `@atomicRmw`-increment a shared counter, the parent joins all N, and asserts
+  the total is exactly N × iterations. Runs `smp` (multi-core) to prove real
+  parallelism.
+- **Stage 2 — blocking synchronization.** `futex_wait`/`futex_wake` + `Futex`,
+  `Mutex`, `Condition`, `Semaphore`; optionally migrate join to a futex completion
+  word. *Gate:* `-Dtest-case=thread-mutex` — a bounded producer/consumer over a
+  `Mutex` + `Condition` moves K items with no lost wakeups and no busy-wait (assert
+  the consumer blocked, e.g. via a low idle tick count).
+- **Stage 3 — polish.** Per-thread TLS / thread pointer and `threadlocal` (only if a
+  consumer needs it), `RwLock`/`WaitGroup` as demanded, and this doc's cases wired
+  into [test/qemu_test.py](../test/qemu_test.py).
+
+## Conventions
+
+Follow [coding-standards.md](coding-standards.md): spell out non-acronym
+abbreviations, kebab-case file names, no `Co-Authored-By` trailers. New syscalls
+extend [abi.zig](../system/abi.zig) `SystemCall` + a `library/runtime` wrapper
+([syscall.md](syscall.md)). `runtime.Thread` is a first-class runtime module, the same
+way `runtime.process` ([process-lifecycle.md](process-lifecycle.md)) and `runtime.ipc`
+are — user code never names a syscall.
+
+## Non-goals
+
+- **No preemptive user-space signals delivered to a specific thread.** Signals stay
+  process-scoped ([process-lifecycle.md](process-lifecycle.md)).
+- **No thread priorities distinct from the process.** Threads inherit the process
+  priority; per-thread priority is a later question if it ever earns its keep.
+- **No cross-process shared-memory futex yet** — the physical-address key leaves the
+  door open, but the first cut is private-per-address-space.
+- **No `pthread`/POSIX surface.** The API is `std.Thread`-shaped Zig, nothing more.
+
+## The self-hosting endgame
+
+When danos becomes a real Zig target and we (eventually) add a danos backend to std
+([zig-self-hosting.md](zig-self-hosting.md)), `std.Thread` can sit *on top of* these
+same kernel primitives — the danos `std.Thread.Impl` would call the very
+`thread_spawn`/`futex_*` wrappers `runtime.Thread` already uses. Because
+`runtime.Thread` was built API-compatible from day one, that transition swaps the
+implementation, not a single call site. Designing to the std shape now is what makes
+the later self-hosting lift cheap.
+
+## Further reading
+
+- [scheduling.md](scheduling.md), [smp.md](smp.md) — the task model these threads join.
+- [resilience.md](resilience.md), [vision.md](vision.md) — why isolation is the default
+  and threads are the exception.
+- [syscall.md](syscall.md), [ipc.md](ipc.md) — the private ABI and the messaging model
+  threads sit beside.
+- [halting.md](halting.md) — the idle/halt property futex-backed blocking preserves.
+- [zig-self-hosting.md](zig-self-hosting.md) — the target this bends toward.

docs/timers.md

@@ -0,0 +1,117 @@
+# Timers and time
+
+Two different needs hide under the word "timer", and danos keeps them apart:
+
+- **Reading the clock** — *what time is it?* A read of a free-running counter.
+- **Waiting** — *wake me in N milliseconds*, or *notify me when a deadline passes.*
+
+Both are answered by the **kernel**, because the kernel already owns a timer: it has
+to, to preempt tasks. The LAPIC heartbeat and the calibrated TSC that back all of this
+are built in [device-interrupts.md](device-interrupts.md); the scheduler's blocking and
+wait queues are in [scheduling.md](scheduling.md). This page is about the surface a
+ring-3 program actually uses, and one deliberate absence: **there is no user-space time
+service.**
+
+## Why time is a syscall, not a service
+
+The tempting microkernel move is to put a timer *driver* in user space and have
+applications ask it for the time over IPC. For a **monotonic clock that is wrong** —
+reading `now()` should never cost an IPC round trip. The kernel is already holding the
+answer: it computes the current time every time it schedules, from the TSC, in a couple
+of instructions. Surfacing that as a system call is pure mechanism; routing it through a
+message to another process would be slower *and* redundant, and a device like the HPET
+(uncacheable MMIO reads) is a particularly bad thing to read on every `now()`.
+
+This is the same conclusion every serious system reaches: Linux and Zircon read the
+counter in the vDSO, L4 exposes a clock field in a shared kernel page, seL4 reads the
+cycle counter directly. None of them make a clock read an IPC. danos makes it a syscall.
+
+That "from the TSC" hides a portability question, because the TSC is only a valid clock
+when the CPU guarantees it is *invariant* and when every core's TSC is *synchronized*.
+danos checks both — the invariant-TSC CPUID bit (`0x80000007` EDX[8], set on Intel and
+AMD), and a cross-core "warp" check as the cores come up — and falls back to the HPET
+counter when either fails. So `now()` stays accurate on a real Intel box, a real AMD box,
+and inside a VM alike; only the source behind it differs. The mechanism is in
+[device-interrupts.md](device-interrupts.md).
+
+So the timer hardware lives in the kernel, and there is **no `hpet` driver and no time
+server** to consume. (An earlier HPET driver existed only to *demonstrate* the driver
+model; that role now lives in [drivers.md](drivers.md), as documentation.) The one place
+a user-space time service *is* justified — **wall-clock / calendar time** — is discussed
+at the end; it is deliberately not built yet.
+
+## The three system calls
+
+Time and waiting are three entries in the small syscall table ([syscall.md](syscall.md)):
+
+- **`clock` (#23)** → monotonic nanoseconds since boot. It only moves forward. Not
+  wall-clock: no date, no timezone. Backed by `architecture.nanos()` (TSC, scaled with a
+  128-bit intermediate so a long uptime can't overflow) — a few nanoseconds of
+  resolution, and just an `rdtsc` plus a multiply.
+- **`sleep` (#3)** → block the caller for N milliseconds. The scheduler records a wake
+  deadline and the tick sweep wakes it (`scheduler.sleep`).
+- **`timer_bind` (#31)** → arm a one-shot timer that, after N milliseconds, posts a
+  **timer notification** to an IPC endpoint. Unlike `sleep` it does **not** block: a
+  service can keep answering messages on the same endpoint while a deadline is pending.
+  This is the timed wait that stop-sequence escalation, hello deadlines, and restart
+  backoff are built from ([process-lifecycle.md](process-lifecycle.md),
+  [device-manager.md](device-manager.md)).
+
+The kernel's own scheduling timer (the LAPIC, vector 32) is never exposed to user space;
+programs read the TSC through `clock` and get timed wakeups through `sleep`/`timer_bind`,
+both riding the scheduler tick.
+
+## `runtime.time` — the generic interface
+
+Applications don't call the syscalls directly; they use `runtime.time`
+(`library/runtime/time.zig`), a thin `Instant`/`Duration` layer over them — an ergonomic
+front door, not new mechanism.
+
+```zig
+const time = @import("runtime").time;
+
+const start = time.now();                 // Instant — monotonic
+doWork();
+const took = start.elapsed();             // Duration
+time.sleep(time.Duration.fromMillis(5));  // block ~5 ms
+
+// A deadline delivered as a notification, so a service keeps serving meanwhile:
+_ = time.after(endpoint, time.Duration.fromMillis(200));
+```
+
+- `Duration` is nanoseconds under the hood, with `fromNanos/fromMicros/fromMillis/
+  fromSeconds` and `asNanos/asMillis`. `ceilMillis` rounds *up* to the kernel's
+  millisecond granularity, so a sub-millisecond `sleep` never rounds down to zero and
+  returns early. All arithmetic saturates rather than wraps.
+- `Instant` is a point on the monotonic clock: `since`, `elapsed`, `plus`, `reached` —
+  built for deadline loops (`while (!deadline.reached()) …`).
+- `now()` / `monotonicNanos()` wrap `clock`. `available()` reports whether the clock is
+  calibrated at all (the kernel returns 0 until the TSC frequency is known, so a caller
+  that needs real time can treat 0 as "unavailable" rather than assume it advances).
+- `sleep(d)` wraps `sleep`; `spin(d)` busy-polls `now()` for the sub-millisecond delays
+  the millisecond tick can't express; `after(endpoint, d)` wraps `timer_bind`.
+
+The raw wrappers (`system.clock`, `system.sleep`, `system.timerOnce`) stay in
+`library/runtime/system.zig`; `runtime.time` is the layer meant for everyday use.
+
+## Wall-clock time (not built)
+
+Everything above is **monotonic**: elapsed time since boot, perfect for timeouts and
+measurement, useless for "what is the date?" Calendar time — a real-time clock, time
+zones, leap seconds — is genuinely a **user-space** concern, and it *is* the case a time
+service is for. It would be backed by an **RTC** driver (the CMOS real-time clock), not
+the HPET, and exposed as a `CLOCK_REALTIME`-style service alongside the monotonic
+syscall. It is deferred until something needs it; the monotonic clock the kernel already
+owns covers every current use.
+
+## Verifying it
+
+`runtime.time`'s `Instant`/`Duration` arithmetic has unit tests that run on the host:
+
+```
+$ zig build test        # includes library/runtime/time.zig
+```
+
+End to end, the proof the clock is real is that it *advances*: read `now()`, `sleep` a
+`Duration`, read `now()` again, and the second reading is later — the kernel's timer
+driving a ring-3 program with no service in between.

docs/vdso.md

@@ -0,0 +1,206 @@
+# The vDSO — the public system-call boundary
+
+> **Status:** design note, not built. The runtime today issues raw `syscall`
+> instructions from `library/runtime/system-call.zig` using the numbers in
+> `system/abi.zig`. This note designs the layer that replaces that arrangement:
+> a **kernel-supplied, C-ABI entry library** mapped into every process — the
+> only supported way into the kernel — so the raw numbers can stay private,
+> be renumbered at will, and eventually be randomised per boot.
+
+## Why: the ABI danos promises, and the one it doesn't
+
+`system/abi.zig` is the **private** kernel ↔ runtime contract. Its header says
+so: the numbers are an implementation detail the runtime hides and may
+renumber, the same split as libSystem over the XNU syscalls on macOS or win32
+over the NT syscalls on Windows. Linux — with its world-visible, frozen
+syscall table — is the outlier, not the norm.
+
+That stance has consequences the moment binaries exist that we don't rebuild
+ourselves:
+
+1. **Third-party binaries** (docs/zig-self-hosting.md) must keep working across
+   kernel updates. If they contain raw `syscall` instructions with today's
+   numbers baked in, every renumbering breaks the world — the ABI would be
+   *de facto* public no matter what the header says. Go on macOS made exactly
+   this mistake: it issued XNU syscalls directly instead of going through
+   libSystem, and macOS updates repeatedly broke every Go binary until Go
+   switched to the library like everyone else.
+2. **Not everything is Zig.** A Rust or C program can't import the `runtime`
+   module. The public boundary has to be expressible in the one calling
+   convention every language speaks: the C ABI.
+3. **Randomised syscall numbers** — a hardening option we want open — only
+   work if no user binary anywhere knows a number at build time. The binding
+   must happen at *load time*, from something the kernel controls.
+
+All three point at the same well-known shape: a **vDSO** (virtual dynamic
+shared object). The kernel carries a small blob of user-mode code, maps it
+into every process at spawn, and that blob — not the application — contains
+the `syscall` instructions. Fuchsia works exactly this way: its vDSO is the
+*only* kernel entry, version-matched by construction because the kernel itself
+injects it. Because the kernel and the blob ship as one artifact, there is
+**no version skew, no loader, no search path, and no shared file on disk** —
+which is what makes this the resilient way to have a private ABI
+(docs/resilience.md), where a conventional `ld.so` + `/lib/libdanos.so`
+arrangement would add a loader to every spawn and a single shared point of
+failure.
+
+The public danos ABI then has exactly two layers, neither of which is
+`abi.zig`:
+
+| Layer | Contract | Spoken by |
+|-------|----------|-----------|
+| **vDSO** | C-ABI functions, this note | every language's thin shim (`runtime.system` for Zig, a `-sys` crate for Rust, a header for C) |
+| **IPC wire protocols** | byte layouts over `ipc_call` ([vfs-protocol.md](vfs-protocol.md) is the first one documented) | any client that can lay out bytes |
+
+Everything above those — the heap, `runtime.fs`, the service harness — is
+per-language convenience, compiled into each binary from source, exactly as
+today. Nothing about the Zig runtime's shape changes; it just stops being the
+*only* door.
+
+## The blob
+
+A single copy of the vDSO code lives in the kernel image (built by
+`build.zig` as a tiny freestanding object, embedded like the AP trampoline).
+At boot the kernel finalises it once — this is where randomised numbers would
+be patched in — and thereafter maps the **same physical pages** read-execute
+into every process's address space. The blob is:
+
+- **Position-independent.** It is mapped at a per-process randomised base, so
+  it must be PIC (rip-relative addressing only — no relocations to process).
+- **Stateless and re-entrant.** No writable data. Anything stateful belongs to
+  the process, not the vDSO.
+- **Architecture-specific.** The x86-64 blob wraps `syscall`; an aarch64 blob
+  wraps `svc #0`. It lives beside the other per-architecture kernel sources
+  (`system/kernel/architecture/<arch>/`), selected the same way the
+  `architecture` module is (docs/arch.md).
+
+### Shape: a function table, not an ELF
+
+A real `.so` with a dynamic symbol table is the conventional vDSO shape, but
+linking against one at load time needs a dynamic linker in every binary —
+machinery danos deliberately doesn't have. Instead the v1 shape is the
+simplest thing that is still a stable contract — a **function-pointer table**
+at the vDSO base:
+
+```
+offset 0   u64  magic        'danosVDS' — a mapped-the-wrong-thing guard
+offset 8   u64  api_level    incremented when the table grows
+offset 16  u64  count        number of table entries that follow
+offset 24  u64  table[count] function pointers into the vDSO's own code
+```
+
+Table *indices* are the public constants (published in a C header,
+`danos.h`), assigned once and append-only — the same discipline the IPC
+protocols use for operation values. The pointers point at stubs inside the
+blob; what those stubs put in `rax` is nobody's business but the kernel's.
+A language shim binds in one step: read the base from the init block, check
+the magic, keep the table pointer. Feature detection for a binary built
+against older headers is `count`/`api_level` — a kernel never removes or
+reorders entries.
+
+(If danos ever grows a real dynamic linker, the same blob can additionally
+present an ELF `dynsym` without breaking the table — Fuchsia's vDSO is
+likewise both a mappable blob and a linkable `.so`. That is a later
+convenience, not a requirement.)
+
+### Delivery: the auxiliary vector
+
+The kernel already builds a System V entry block — argc, argv, envp
+terminator, **auxiliary vector** — on every new process's stack
+(`buildEntryStack`, read by `runtime.start`). The vDSO base rides in a new
+auxv entry, exactly Linux's `AT_SYSINFO_EHDR` move. No new syscall, no magic
+address, and a language shim finds it the same portable way on every
+architecture.
+
+## The function surface
+
+One table entry per kernel call, C ABI (System V AMD64), names prefixed
+`danos_`. The current `SystemCall` set maps directly; integer arguments and
+returns are `u64`, errors return as negative values exactly as today.
+
+The calls that return two values in `rax:rdx` today — `dma_alloc`
+(virtual_address + physical_address), `msi_bind` (address + data), `shm_create` (virtual_address + handle) —
+become functions returning a two-`u64` struct. The System V ABI returns a
+16-byte struct in `rax:rdx`, so the stub is a plain `syscall; ret` — the
+C-ABI spelling of the existing convention, at zero cost.
+
+Grouped as `abi.zig` groups them:
+
+| Group | Functions |
+|-------|-----------|
+| process | `danos_exit`, `danos_yield`, `danos_sleep`, `danos_spawn`, `danos_process_enumerate`, `danos_process_kill`, `danos_process_exit_reason`, `danos_process_subscribe`, `danos_process_signal`, `danos_signal_bind` |
+| memory | `danos_mmap`, `danos_munmap`, `danos_dma_alloc`, `danos_dma_free`, `danos_shm_create`, `danos_shm_map`, `danos_shm_physical` |
+| ipc | `danos_endpoint_create`, `danos_ipc_register`, `danos_ipc_lookup`, `danos_ipc_call`, `danos_ipc_reply_wait`, `danos_ipc_send` |
+| devices | `danos_device_enumerate`, `danos_device_claim`, `danos_device_register`, `danos_mmio_map`, `danos_irq_bind`, `danos_irq_ack`, `danos_msi_bind`, `danos_io_read`, `danos_io_write` |
+| time | `danos_clock`, `danos_wall_clock`, `danos_timer_bind` |
+| diagnostics | `danos_debug_write`, `danos_klog_read` |
+
+The constants that ride alongside the calls — mmap protection bits, DMA
+flags, notification badge bits, `ExitReason`, `Signal`, well-known service
+ids, `page_size`, the IPC message maximum — move to the public header too:
+they are wire values a Rust program needs verbatim. What stays private in
+`abi.zig` is exactly the thing the vDSO exists to hide: the `SystemCall`
+numbers and the trap convention.
+
+## Enforcement, and an honest threat model
+
+Renumbering only has teeth if the kernel **refuses syscalls that don't come
+from the vDSO**. The check is cheap: on kernel entry, the saved user `rip`
+must lie inside the calling process's vDSO mapping; otherwise the process is
+killed with a fault-class exit reason (its supervisor restarts or gives up,
+docs/process-lifecycle.md — a foreign-syscall attempt is a bug or an attack,
+never something to limp past). Fuchsia enforces exactly this.
+
+What this buys, precisely:
+
+- **ABI freedom** — the real prize. The numbers can change per release or per
+  boot and nothing outside the kernel image cares. The private ABI stays
+  actually private, permanently.
+- **A single audited chokepoint** for kernel entry, per process, at a
+  randomised address.
+- **Raised bar for exploits**: shellcode can't issue a hard-coded `syscall`;
+  it must first discover the per-process vDSO base (ASLR) and call through
+  it.
+
+What it does *not* buy: an attacker with arbitrary code execution in a
+process can still *call* the vDSO functions — they are mapped executable in
+that process, and return-oriented chains reach them. Syscall randomisation is
+hardening, not a security boundary; the security boundary remains the
+capability model (what the process's endpoints and device claims let it do).
+It is worth building anyway — for the ABI freedom first and the hardening
+second — but the design should never be sold as more than that.
+
+## Migration
+
+Phased so every step ships alone (the M-milestone discipline):
+
+1. **The blob + the table.** Build the vDSO, map it at spawn, deliver the
+   base via auxv. `runtime.system-call.zig` binds through the table when the
+   auxv entry is present, falls back to raw `syscall` when absent — the whole
+   tree keeps booting during the transition.
+2. **Cut the runtime over.** Delete the raw stubs; `runtime` no longer
+   imports the `SystemCall` numbers at all (`abi.zig`'s enum becomes
+   kernel-internal). The QEMU suite passing proves the table carries the
+   whole system.
+3. **Enforce + randomise.** Add the `rip`-range check, then per-boot number
+   randomisation patched into the blob at kernel init. A test boots with
+   randomisation on and runs the full suite.
+4. **The other languages.** Publish `danos.h`; a Rust `danos-sys` crate wraps
+   the table. This is also the seam `std.os.danos` calls through when the Zig
+   self-hosting fork lands (docs/zig-self-hosting.md) — the vDSO is what
+   makes that seam stable across kernel versions.
+
+## What deliberately stays out
+
+- **No dynamic linker, no `/lib/*.so`.** The vDSO is kernel-injected precisely
+  so danos binaries can stay fully static above it. Sharing *library code*
+  across processes stays what it is today: a service behind IPC, or source
+  compiled into each binary.
+- **No file/device I/O in the vDSO.** The microkernel line doesn't move: the
+  vDSO wraps the same deliberately tiny table (docs/syscall.md); files are
+  still the VFS server's business over IPC.
+- **No fast-path user-mode implementations yet.** Linux's vDSO exists mostly
+  to answer `gettimeofday` without a kernel entry. `danos_clock` could one
+  day read the calibrated TSC in user mode the same way — the blob is where
+  such an optimisation would live — but that is an optimisation, not part of
+  this design's contract.

docs/vfs-protocol.md

@@ -0,0 +1,170 @@
+# The VFS wire protocol
+
+> **Status:** built and spoken today between `runtime.fs` (the client) and the
+> VFS server (`system/services/vfs`), with mounted backends (the FAT server)
+> speaking the same protocol behind the router. The Zig source of truth is
+> `system/services/vfs/protocol.zig` (the `vfs-protocol` module), whose unit
+> tests pin the sizes and values below. This page is the **language-neutral
+> wire specification** of that contract — what a Rust or C client implements
+> ([vdso.md](vdso.md) explains why the IPC protocols, not the syscall
+> numbers, are danos's public ABI).
+
+## Transport
+
+A VFS exchange is one synchronous IPC rendezvous (`ipc_call`,
+docs/ipc.md): the client sends one message and blocks; the server replies
+with one message. The endpoint is found by well-known service id
+(`ipc_lookup`, service id **1** = vfs).
+
+- A message is at most **256 bytes** (`message_maximum`).
+- A request is a fixed 32-byte **Request** header followed by an inline
+  payload of at most **224 bytes** (`maximum_payload`) — a path, or write
+  bytes. There is no multi-message request: paths and single reads/writes
+  must fit, and larger transfers loop (see *read* / *write*).
+- A reply is a fixed 24-byte **Reply** header followed by an inline payload —
+  read bytes, a `FileStatus`, or a `DirectoryEntry`.
+- All integers are **little-endian**; layouts are C layout for x86-64
+  (`extern struct`), offsets given below so nothing need be inferred.
+
+The kernel never parses any of this — it only moves the bytes
+(docs/syscall.md); files are entirely a user-space affair.
+
+## Request header — 32 bytes
+
+| offset | size | field | meaning |
+|-------:|-----:|-------|---------|
+| 0 | 4 | `operation` | an **Operation** value (below) |
+| 4 | 4 | — | padding |
+| 8 | 8 | `node` | the server-side open-node id from a prior `open`; 0 for path-based operations |
+| 16 | 8 | `offset` | byte position for read/write; entry index (cursor) for readdir; else 0 |
+| 24 | 4 | `len` | payload length for path/write operations; requested byte count for read |
+| 28 | 4 | `flags` | open flags (below); else 0 |
+
+## Reply header — 24 bytes
+
+| offset | size | field | meaning |
+|-------:|-----:|-------|---------|
+| 0 | 4 | `status` | **0 = success**, negative = failure (signed) |
+| 4 | 4 | — | padding |
+| 8 | 8 | `node` | the new open-node id (for `open`); else 0 |
+| 16 | 4 | `len` | reply payload length in bytes |
+| 20 | 4 | — | padding |
+
+On failure the router replies `status = -1`; a mounted backend's negative
+status is forwarded to the client verbatim. A richer errno vocabulary is
+future work — clients must treat *any* negative status as failure, not match
+on -1.
+
+## Operations
+
+Values are append-only and never renumbered (the same evolution rule every
+danos protocol follows); an unrecognised operation gets a `status = -1`
+reply.
+
+| value | operation | request payload | reply |
+|------:|-----------|-----------------|-------|
+| 0 | `open` | the path (`len` = its length), `flags` as below | `node` = open-node id |
+| 1 | `close` | — (`node` set) | status only |
+| 2 | `read` | — (`node`, `offset`, `len` = wanted count) | `len` bytes read, payload = the bytes; `len` 0 at end of file |
+| 3 | `write` | the bytes (`node`, `offset`, `len` = count) | `len` = bytes accepted (may be short — loop) |
+| 4 | `status` | — (`node` set) | payload = **FileStatus** (24 bytes) |
+| 5 | `readdir` | — (`node` = a directory, `offset` = cursor) | payload = one **DirectoryEntry** + name; `len` 0 at end |
+| 6 | `mount` | the mount-point path; the backend endpoint rides as the call's **capability** | status only |
+| 7 | `unmount` | the mount-point path | status only |
+| 8 | `mkdir` | the path | status only |
+| 9 | `unlink` | the path | status only |
+| 10 | `rename` | old path, one `0x00`, new path (`len` = total) | status only |
+
+Notes per operation:
+
+- **open** — paths are absolute (`/mnt/usb/notes.txt`) or bare names
+  (`greeting`); bare names resolve in the VFS's flat ramfs, absolute paths
+  route through the mount table (below). The returned `node` is an id in the
+  *router's* open table; clients never see a backend's own ids.
+- **read / write** — a single exchange moves at most 224 bytes
+  (`maximum_payload`); the client loops, advancing `offset` by the returned
+  `len`, until done (read) or the slice is written (write). A `write` reply
+  shorter than requested is progress, not an error; a `len` of 0 means no
+  forward progress — stop rather than spin.
+- **readdir** — `offset` is a **cursor: the entry index**, not a byte
+  position. Each call returns exactly one entry; the client increments the
+  cursor by 1. A reply with `len` 0 is end-of-directory. The directory must
+  have been opened with the `directory` flag.
+- **mount** — the one operation that passes a **capability**: the caller
+  (a filesystem server, e.g. FAT) sends its own request endpoint as the
+  `ipc_call` capability argument, and the router forwards everything under
+  the mount point to it — speaking this same protocol, with paths rewritten
+  relative to the mount. Prefixes match at path boundaries only
+  (`/mnt/usb` never captures `/mnt/usbextra`); the longest matching prefix
+  wins.
+- **rename** — same-directory rename only (the router requires old and new to
+  resolve under one mount).
+
+## Open flags
+
+Bitwise OR in `Request.flags`, meaningful for `open` only:
+
+| bit | name | meaning |
+|----:|------|---------|
+| 1 | `create` | create the file if it does not exist |
+| 2 | `directory` | open a directory node for `readdir` rather than a file |
+| 4 | `truncate` | truncate an existing file to zero length on open (replace, don't overwrite in place) |
+
+## FileStatus — 24 bytes (the `status` reply payload)
+
+| offset | size | field | meaning |
+|-------:|-----:|-------|---------|
+| 0 | 8 | `size` | file size in bytes |
+| 8 | 4 | `kind` | a **NodeKind** value |
+| 12 | 4 | — | padding |
+| 16 | 8 | `mtime` | modification time, Unix epoch seconds UTC; 0 if the backend keeps none |
+
+## DirectoryEntry — 16 bytes + name (the `readdir` reply payload)
+
+| offset | size | field | meaning |
+|-------:|-----:|-------|---------|
+| 0 | 4 | `kind` | a **NodeKind** value |
+| 4 | 4 | `name_len` | length of the name that follows |
+| 8 | 8 | `size` | the entry's size in bytes |
+| 16 | `name_len` | name | the entry's name, not NUL-terminated |
+
+## NodeKind
+
+Aligned to the FSH file-type table
+(docs/danos-file-system-hierarchy-FSH.md):
+
+| value | kind |
+|------:|------|
+| 0 | regular file |
+| 1 | directory |
+| 2 | character device |
+| 3 | block device |
+| 4 | symbolic link |
+| 5 | fifo |
+| 6 | socket |
+
+Clients should map unknown values to *regular* rather than reject — the
+table can grow.
+
+## Lifetimes and trust
+
+Open-node ids live in the server. A client that dies without closing leaks
+nothing permanently: the VFS subscribes to the kernel's published process-exit
+events (docs/process-lifecycle.md) and releases a dead client's handles,
+closing forwarded backend nodes best-effort. Ids are plain integers, not
+capabilities — the VFS trusts its callers with each other's ids today, which
+is acceptable while every client is part of the system image and worth
+revisiting (per-client id namespaces) before third-party binaries arrive.
+
+## Evolution rules
+
+What a non-Zig implementation may rely on, and what it must not:
+
+- Operation values, flag bits, `NodeKind` values, and struct layouts are
+  **append-only and frozen once shipped** — the unit tests in `protocol.zig`
+  pin them exactly so a refactor can't silently move them.
+- The 256-byte message ceiling is a property of the current IPC transport,
+  not a promise; clients should read `maximum_payload`-shaped limits from the
+  reply lengths they actually get (loop-until-done), not hard-code 224.
+- Negative statuses beyond -1 will appear (an errno vocabulary); success is
+  exactly 0.

docs/zig-self-hosting.md

@@ -0,0 +1,349 @@
+# Running Zig on danos: the self-hosting roadmap
+
+A design note (not built yet) on the path to making danos a **real Zig target** — a
+target you can name (`-target x86_64-danos`) and, eventually, run the Zig compiler
+itself on. It is forward-looking, like [vision.md](vision.md): it sets a direction
+and the decisions that follow from it, so the code we write now bends toward it
+instead of away.
+
+This note deliberately does **not** cover a text editor or terminal. Those are
+easier (single-process, I/O-bound) and fall out of the early phases here almost for
+free; the hard, shaping problem is the standard-library surface, so that is what
+this roadmap is about.
+
+The analysis behind it was done against **Zig 0.16** (the pinned toolchain). Zig's
+standard library moves between releases — especially the parts described here — so
+treat upstream references as "the shape in 0.16.x," and expect to re-check them on a
+toolchain bump.
+
+## The win condition
+
+danos runs the Zig compiler when a bare
+
+```
+zig build-exe hello.zig
+```
+
+completes **on danos** and produces a runnable danos binary. Note the milestone is
+`build-exe`, not `zig build`: the `zig build` runner spawns child processes (the
+build steps), which needs a whole process-control surface danos does not have yet.
+A single `build-exe` needs none of that (see Phase 3). Reaching `build-exe` is
+"self-hosting"; reaching `zig build` is a later, separate lift.
+
+### Non-goals
+
+- **No Linux syscall/ABI emulation.** danos will not implement the Linux `syscall`
+  interface so that stock `x86_64-linux` binaries run. That is a permanent
+  compatibility treadmill and it inverts the microkernel design — explicitly out.
+- **No musl port yet.** A musl libc port is a reasonable *later* effort (it unlocks
+  the C ecosystem), but it is not on the critical path to Zig-on-danos, and it is
+  deferred. The roadmap below is arranged so the work still pays off if musl ever
+  happens (see "The same surface, twice").
+- **Editor/terminal are out of scope for this note** (they are downstream of Phase 1).
+
+**On FFI.** Foreign-function interop splits the same way as the doors below. Zig-level
+and C-ABI-*exposing* FFI (`extern`, `callconv(.c)`, C-ABI structs) work on a real target
+immediately — and the `std.os.danos` seam is C-ABI-shaped by construction, so it is
+FFI-friendly from the start. *Consuming* C libraries (`@cImport`, linking archives) is
+the part that needs a libc + headers, i.e. the deferred musl door. So an eventual FFI
+need reinforces keeping that door open; it does not change the plan.
+
+## The realization that shapes everything: 0.16 gives us *one* seam
+
+The instinct "to target Zig we'd have to reimplement all the `std` namespaces" was
+how older Zig worked. Zig 0.16 (post-"writergate") is far kinder:
+
+- **`std.fs` is essentially gone.** It is now path helpers plus deprecated aliases;
+  there is no `std.fs.File`, `std.fs.Dir`, or `std.fs.cwd()`. File and directory
+  work goes through **`std.Io`** — a single runtime **vtable** (`Io.zig`) of
+  function pointers handed to `main` as `std.process.Init.io`. `std.Io.File` and
+  `std.Io.Dir` are thin forwarders to that vtable. `Io.zig` and the `fs` shim carry
+  **zero** per-OS branches.
+- **`std.posix` is one generic body** parameterised over a single `system` module.
+  With no libc, `system` resolves **per target OS**: `.linux => std.os.linux`,
+  `.plan9 => std.os.plan9`, and so on. The generic `std.posix.read`/`write`/`open`
+  bodies are just `system.read(...)` plus an errno switch — *identical for every
+  OS*. The only variable is what `system` binds to.
+- **`std.os.<tag>`** (e.g. `std/os/linux.zig`) is therefore the real porting seam: a
+  low-level, C-ABI-shaped module of `read/write/open/close/lseek/mmap/clock/exit/…`
+  plus an `errno` enum and the constant tables (`O_*`, `CLOCK_*`, `S_*`).
+
+Put together: **to port danos we write `std.os.danos` once** — the ~30-operation
+seam — and the whole `std.posix` / `std.fs` / `std.Io` tower above it lights up
+generically, because none of it branches on the OS. That is a dramatically smaller
+and more contained target than "reimplement the namespaces."
+
+## Three doors, and why we take the first
+
+| Door | What it is | Verdict |
+|------|-----------|---------|
+| **1. Implement the std seam** (`std.os.danos`) | Write the ~30-op `system` module over danos's native ABI + VFS; the generic std tower lights up. | **Take this.** The only door that touches neither C nor the Linux ABI. |
+| **2. Port musl** | Port musl libc to danos, link Zig against it. | Defer. Good later for the *C* ecosystem; barely helps *Zig* (std only uses libc on the libc-linked path). |
+| **3. Emulate the Linux ABI** | Implement Linux syscalls so stock linux binaries run. | Reject. Bottomless compatibility treadmill; against the design. |
+
+### The same surface, twice
+
+Doors 1 and 2 are the **same native surface at different layers**. `std.posix.read`
+is `system.read(...)` + an errno switch *regardless of OS* — the only question is
+whether `system` is **`std.os.danos` (Zig)** or **musl (C)**. Either way, the set of
+danos-facing operations you must implement is the *same* ~30 ops, all bottoming out
+in danos's native syscalls + the VFS/FAT server.
+
+So the runtime work below is **not throwaway** if musl ever happens: you are building
+the danos-native implementations of that surface either way. Door 1 just packages
+them as Zig; a future musl re-uses the identical kernel/VFS operations underneath. The
+two symmetries worth keeping in mind: doors 1 and 2 converge at the **top** (identical
+POSIX surface); doors 2 and 3 converge at the **bottom** (unmodified musl needs the
+Linux syscall ABI). Door 1 is the only one that avoids both C and Linux.
+
+### A fork is table stakes — for any door
+
+`std.Target.Os.Tag` is a **closed enum** baked into the compiler binary *and* into
+the `std` linked with every program; `-target x86_64-danos` resolves through it. So
+adding `danos` as a name requires patching and rebuilding the compiler — even the
+musl door needs this. "Fork Zig" is therefore not an extra cost unique to door 1; it
+is the price of admission for *any* real target. What door 1 adds on top is small and
+localised (below).
+
+## The architecture decision: `runtime.os` + `runtime.fs`, and retire `posix`
+
+danos already has the right split ([the private-ABI boundary](../README.md)): the
+kernel exposes a minimal syscall ABI ([syscall.md](syscall.md)); the **`runtime`**
+library is the stable, danos-native application ABI. What this roadmap adds:
+
+- **`runtime.os` — the seam.** A C-ABI-shaped module of the ~30 operations
+  (`read/write/open/close/lseek/mmap/munmap/clock/exit/…`) + an errno enum + the
+  constant tables, each backed by danos's native syscalls and the VFS. **Structure it
+  to mirror `std/os/linux.zig`.** This is the load-bearing, *non-throwaway* artifact:
+  when we fork Zig, `runtime.os` is copy-pasted (near-verbatim) into `std.os.danos`.
+- **`runtime.fs` — the thin native file API** danos programs use *today*, layered
+  over `runtime.os`. It is also the concrete backing for the `std.Io` vtable's
+  file-write entry once we're a real target, which is why program stdout, diagnostics,
+  and file writes should all be *decided once at that seam* rather than as bespoke
+  per-call helpers (see "How this informs decisions now").
+
+**Do not hand-mirror the high-level std namespaces.** `std.fs`/`std.Io`/`std.process`
+are generic and OS-agnostic; once `std.os.danos` exists and we fork, upstream *gives*
+them to danos for free. Hand-writing `runtime.std.fs` to imitate them would be
+redundant the day the fork works, and it would chase a moving target (0.16's `std.Io`
+is large and still shifting). Build the seam well; take the tower for free.
+
+**Why not a library called `std`?** Because `@import("std")` resolves to the
+compiler-provided standard library; a user module named `std` would *shadow* it for
+anything that imports it that way. That is the real reason the seam lives *inside* a
+forked std as `std/os/danos.zig`, not as a `runtime.std` library — and why danos's end
+state (`@import("std")` just working, and knowing danos) is the most natively Zig it can
+be. `runtime.os` is only the interim staging ground: developed against the stock
+toolchain so Phase 1 need not wait on the fork, then promoted near-verbatim into the
+fork's `std/os/danos.zig`.
+
+### Retire `library/posix`
+
+The `posix` compatibility layer (`unistd`, `stdio`) was the right instinct too early.
+Its whole value is POSIX *spellings* for POSIX software — and danos has no POSIX
+software; every current caller is danos-native code that could use `runtime.fs`
+directly. The real POSIX story arrives later and from elsewhere (musl, or upstream
+`std`'s own posix over `std.os.danos`), which supersedes a hand-rolled shim. So it is
+premature abstraction that adds a "which layer do I use?" fork with no payoff yet.
+
+Its footprint is tiny: **five** call sites, all `unistd` file operations —
+`system/services/fat/fat.zig` (`mount`), the `vfs-test` and `fat-test` clients, and
+(from the boot-log work) `init.zig` and `log-flush.zig`. `stdio.zig` is dead — nothing
+imports it. The plan: build `runtime.fs`, migrate those five to it, delete
+`library/posix/`, and drop the `posix` module from `build.zig`'s `addUserBinary`.
+
+## Where danos stands: coverage vs. the gaps
+
+What the seam needs, and what danos already provides:
+
+| std need | danos today | Gap |
+|----------|-------------|-----|
+| open / read / write / close / lseek | VFS (via the current `unistd`, → `runtime.fs`) | none — repackage |
+| directory read (`getdents`) | VFS `readdir` | none — repackage |
+| mmap / munmap | native syscalls ([abi.zig](../system/abi.zig)) | none |
+| page allocator | over `mmap`, via `root.os.heap.page_allocator` override | ~30-line hook |
+| monotonic clock | `clock` syscall | none |
+| args / argv | SysV entry stack ([sysv.md](sysv.md)), `runtime.process.Init` | none |
+| stdout / stderr | `debug_write` today | wire fd 1/2 to a console **byte** stream |
+| mkdir / unlink / rename / truncate | done — engine + VFS + `runtime.fs` (Phase 2) | — |
+| stat fields | `{size, kind, mtime}` | **mode / inode** still missing (cache validity) |
+| wall-clock / realtime | done — `wall_clock` syscall (CMOS RTC, Phase 2d) | — |
+| **environment variables** | `Init` has no env field | missing (can start empty) |
+| **cwd / chdir** | paths are absolute or bare | missing (no cwd anchor) |
+| **entropy / random** | — | missing (needed behind `vtable.random`) |
+| process spawn + exit status | `system_spawn` starts a *named ramdisk binary*; `ExitReason` is a *category* | no exec-of-path, no numeric `WEXITSTATUS` |
+| threads | one thread per process | avoided via `-fsingle-threaded` (below) |
+| symlinks | `NodeKind` has the tag; unimplemented | low priority |
+
+The clustering is clear: reads and memory are basically done; the real work is
+**filesystem mutation + richer stat + wall-clock**, and a few small seam pieces
+(page-allocator hook, stdio bytes, entropy). Process spawning and threads are
+side-stepped entirely for a single `build-exe`.
+
+## The roadmap
+
+### Phase 0 — Make `danos` a real target
+
+**Host, target, self-host — keep the three roles straight.** The *host* is where the
+compiler runs (your mac + linux dev machines); the *target* is what it emits (`danos`);
+and eventually danos becomes a host too (self-hosting — the win condition). So the move
+is: fork the compiler, build it **for** your dev hosts, and teach it to **cross-compile
+to** danos. You already do this — danos is cross-compiled `freestanding` from your dev
+host today; Phase 0 swaps that `freestanding` target for a real `x86_64-danos` one, which
+is what unlocks the native `std`.
+
+**Why a compiler fork, not just a `--zig-lib-dir` override.** `std.Target.Os.Tag` is a
+*closed enum compiled into the compiler binary*, so `-target x86_64-danos` will not even
+parse unless the compiler itself knows the tag. Overriding the std lib directory alone
+cannot add a target — and there is no libc-only shortcut (a future musl needs the same
+patch). The only alternative, staying on `freestanding` + hand-shims, is exactly the
+non-native feel we are leaving: `@import("std")` there is stubbed, not real.
+
+**The fork.** Clone `ziglang/zig` at the pinned 0.16 tag; build it with a stock
+same-version `zig` (`zig build` in the tree — a standard, LLVM-pulling, roughly one-time
+build); point danos's `build.zig`/CI at the resulting binary. Four localised patches:
+
+- add `danos` to `std.Target.Os.Tag`, in the "no version range" group alongside
+  plan9/serenity;
+- add `danos` to the freestanding/other **no-op `_start` list** in `std`'s `start.zig`,
+  so std does *not* emit its own System-V `_start` — danos keeps owning the entry shim
+  and `Init`/argv construction it already builds ([sysv.md](sysv.md));
+- wire the `system` selector `.danos => std.os.danos` in `std.posix`;
+- add `std/os/danos.zig` — **the seam itself**, promoted near-verbatim from the
+  `runtime.os` developed first in Phase 1 (against the stock toolchain, so the fork is
+  not a prerequisite for starting).
+
+This is the fork treadmill we accept once. Keep the patch set tiny and `else`-friendly,
+pin to one 0.16.x, and rebase on point releases.
+
+### Phase 1 — `runtime.os` read-side + allocator + stdio + cwd; retire `posix`
+
+Author `runtime.os` (→ `std.os.danos`): the `errno` enum, the constant tables, and
+the C-convention `read / write / open / openat / close / lseek / mmap / munmap /
+exit`, each returning result-or-`-errno`. Most backing already exists (VFS + native
+mmap + clock).
+
+- Provide `page_allocator` via `root.os.heap.page_allocator` (a thin override over
+  danos `mmap`). This sits **outside** the `std.Io` vtable, so it is wired separately.
+- Wire fd 0/1/2 to a console **byte** stream (today output only reaches `debug_write`;
+  input is structured `InputEvent` IPC — a byte tty is a new, small thing in both
+  directions).
+- Add a `getcwd`/`chdir` anchor so `std.fs.cwd()`-style resolution has something to
+  resolve against.
+- Build `runtime.fs` over `runtime.os`; migrate the five `posix` callers to it; delete
+  `library/posix/` and drop its build module.
+
+After Phase 1, the surface an editor or terminal needs (open/read/write/close/lseek/
+readdir/isatty/args/exit) exists. Those are downstream and out of scope here.
+
+### Phase 2 — Filesystem mutation + real stat (the compiler's cache tower)
+
+danos's biggest genuine gap, and the correctness-critical one:
+
+- Add **mkdir / unlink / rename / truncate** to *both* the VFS wire protocol
+  ([protocol.zig](../system/services/vfs/protocol.zig)) and the FAT engine
+  ([engine.zig](../system/services/fat/engine.zig)), then expose them via `runtime.os`.
+- Extend `stat` beyond `{size, kind}` to carry **mtime + inode + mode** — `std`'s file
+  stat needs them for build-cache validity — which in turn needs **wall-clock** time
+  (danos is monotonic-only today; an RTC/time service is the dependency).
+
+Because `std.fs`/`std.Io` have no per-OS branches, finishing this in `runtime.os`
+lights up the whole file tower for the compiler at once. Environment can stay an empty
+map until the kernel populates a non-empty `envp`.
+
+**Status — Phase 2 complete.** `truncate` (O_TRUNC, closing the boot-log stale-tail
+bug), `mkdir`, `unlink`, and `rename` are all wired through the FAT engine, the VFS
+protocol + router, and `runtime.fs` (`makeDirectory` / `remove` / `rename`) —
+host-tested and QEMU-tested (`fat-mutations` + `fat-rename` make a directory, write+read
+a file in it, rename it, then remove it through the mount). `removeFile` and `rename`
+are LFN-aware; `rename` is same-directory + 8.3 (cross-directory and long-name-
+preserving rename are noted limitations). Wall-clock is now a kernel syscall
+(`wall_clock`, a CMOS-RTC read anchored to the monotonic clock), and the FAT engine
+stamps and reports **mtime** — `stat` / `runtime.fs.Attributes` carry a real
+modification time (the `fat-mtime` case reads it back within seconds of the host clock).
+The remaining `stat` fields, `mode`/`inode`, are deferred (not needed until the
+compiler's cache layer wants them). **Everything past here is gated on Phase 0 (the
+fork):** the `runtime.os` seam, `cwd`, stdio-as-fds, and the compiler bring-up.
+
+### Phase 3 — Single-threaded, self-linked compiler bring-up
+
+Build the compiler with **two load-bearing flags**:
+
+- **`-fsingle-threaded`** removes `std.Thread` entirely — `Thread.spawn` is a hard
+  compile error under it, and `std.Io`'s threaded backend runs inline. danos being
+  one-thread-per-process is therefore **not** a blocker. Parallel codegen is a
+  throughput optimisation, not a correctness requirement.
+- **`-fno-llvm -fno-lld`** keeps codegen and linking **in-process** (the self-hosted
+  x86-64 backend + self-linker), so a single `build-exe` **never forks a child**. That
+  is what lets us defer the entire spawn/exec/wait surface.
+
+Then supply the few remaining seam pieces: `now` (wrap the danos clock), an entropy
+source behind `vtable.random` (`randomSecure` can alias it initially — low volume, for
+temp-file names and hashmap seeds), and the Phase-2 mkdir/rename/unlink for cache dir
+trees and atomic temp-then-rename output.
+
+**Explicitly deferred** (not on the `build-exe` path): child-process spawn/exec (only
+`zig build` and external tools need it), `std.Thread`, `fsync` (FAT is write-through
+today), symlinks, and musl.
+
+## Risks and gotchas
+
+- **The std-fork rebase treadmill is the main ongoing cost.** A new OS tag touches the
+  same broad file set plan9/serenity touch (hundreds of `native_os` sites, plus
+  "unsupported OS" `@compileError` dead-ends a new tag must be routed around), and the
+  entire `std.Io` layer is new in 0.16 and still moving. Stay pinned to one 0.16.x,
+  keep additions localised and `else`-friendly. Watch the closed-enum gotcha: adding
+  `danos` to `Os.Tag` can break existing *exhaustive* switches that lack an `else`, so
+  expect to touch switch sites beyond the ones you implement.
+- **Single-threaded is load-bearing.** The "no `std.Thread`" simplification rests
+  entirely on `-fsingle-threaded`. If a dependency or flag flips threading back on, you
+  inherit an unescapable compile error (no root-hook exists) — the only outs are a full
+  thread-impl fork or linking libc for pthreads. Keep `single_threaded` asserted end to
+  end.
+- **In-process linking is load-bearing.** Reaching the compiler without fork/exec
+  depends on `-fno-llvm -fno-lld`. The moment you shell out to LLD/`ld`, you need the
+  full `spawn`/`wait` surface — the hardest microkernel piece — and danos's
+  `system_spawn` only starts a *named ramdisk binary*, not exec of an arbitrary path.
+  Verify the self-hosted backend covers the target output before assuming child
+  processes are optional.
+- **The shim cannot host the compiler.** danos's current `runtime`/`posix` is fine for
+  danos's *own* native programs, but the compiler `import`s *upstream* `std`, which on
+  a non-target hits the void `system` stub. So the compiler forces the real target
+  (Phase 0's fork). Do not over-invest in extending the hand-shim for compiler
+  purposes; put that effort into `runtime.os` + the VFS/FAT operations, which both the
+  fork *and* a future musl consume.
+- **`"w"`/`O_CREAT` does not truncate — a silent-corruption bug on this road.** The FAT
+  engine's `writeFile` only *grows* `node.size`, so overwriting a shorter file leaves
+  trailing garbage. Harmless for the boot log today, but for a compiler it means
+  **corrupt `.o`/cache files that look like nondeterministic compiler bugs.** Land
+  `truncate` (Phase 2) before the compiler ever writes cache.
+- **Exit status is categorical, not numeric.** `process_exit_reason` returns an
+  `ExitReason` *category*, not a numeric code (`WEXITSTATUS`). Fine while spawn is
+  stubbed; the day `zig build` or external tools arrive, plan a kernel exit-record
+  extension — do not let it surprise you.
+
+## How this informs decisions now
+
+Two current decisions fall out of this roadmap:
+
+1. **The `runtime.fs` / `std.Io` question resolves at the vtable seam.** Because 0.16
+   routes *all* output through the `std.Io` vtable's file-write entry, and stdout/stderr
+   are just `File`s with well-known handles, build `runtime.fs` (and the console stdout)
+   as the concrete backing for that entry — not as a bespoke `std.Io.Writer`-only shim.
+   Decide it once, at the seam, and program stdout, diagnostics, and file writes all
+   flow through the same danos VFS/console path.
+2. **The boot-log `truncate` caveat is now fixed** (Phase 2a). It was the same
+   `writeFile`-only-grows gap that on the self-hosting road would corrupt build output;
+   `engine.truncate` + an O_TRUNC open flag now free the old chain so a shorter rewrite
+   leaves no stale tail, and the boot-log flush opens with it.
+
+## Related
+
+- [vision.md](vision.md) — the north star this serves.
+- [syscall.md](syscall.md) — the kernel↔runtime ABI `runtime.os` is built on.
+- [sysv.md](sysv.md) — the entry stack (`argc/argv/envp/auxv`) danos already constructs.
+- [ipc.md](ipc.md) — the IPC the VFS/FAT operations travel over.
+- [danos-file-system-hierarchy-FSH.md](danos-file-system-hierarchy-FSH.md) — the
+  filesystem layout the file surface serves.
+- [coding-standards.md](coding-standards.md) — danos naming (why the compat spellings
+  are confined, and now retired).

library/posix/posix.zig

@@ -1,13 +0,0 @@
-//! DanOS's POSIX / C compatibility layer — `unistd`, `stdio`, and (later) the C
-//! `errno` / `struct stat` / `extern "C"` surface. This is the *one* place POSIX and
-//! C spellings are allowed to appear verbatim (see docs/coding-standards.md): a file
-//! under library/posix/ *is* the foreign ABI, so it keeps the ABI's names. Everything
-//! it touches on the danos side (the VFS protocol, the runtime) uses danos names,
-//! which this layer translates to at the boundary.
-//!
-//! It is layered strictly *over* the runtime: it calls the runtime's IPC and heap,
-//! never the kernel's system calls directly. danos-native applications use the
-//! runtime; this exists so *POSIX* software can too.
-
-pub const unistd = @import("unistd.zig");
-pub const stdio = @import("stdio.zig");

library/posix/stdio.zig

@@ -1,115 +0,0 @@
-//! A small C stdio layer over the POSIX-style file API (unistd.zig). Unbuffered
-//! for now — each fread/fwrite is one VFS round trip; an internal buffer (fewer
-//! IPC calls) is a later optimisation. Both a Zig-callable API and `extern "C"`
-//! symbols are provided, so Zig and future C programs share it.
-
-const std = @import("std");
-const unistd = @import("unistd.zig");
-const heap = @import("runtime").heap;
-
-pub const SEEK_SET = unistd.SEEK_SET;
-pub const SEEK_CURRENT = unistd.SEEK_CURRENT;
-pub const SEEK_END = unistd.SEEK_END;
-
-/// A C `FILE`: an fd plus sticky end-of-file / error flags. Allocated on the
-/// heap; `fclose` frees it.
-pub const FILE = extern struct {
-    fd: i32,
-    eof: c_int = 0,
-    err: c_int = 0,
-};
-
-fn flagsFor(mode: []const u8) u32 {
-    if (mode.len == 0) return 0;
-    return switch (mode[0]) {
-        'w', 'a' => unistd.O_CREAT,
-        else => 0,
-    };
-}
-
-/// Open `path` in `mode` ("r"/"w"/"a", '+' ignored for now). Returns null on error.
-pub fn fopen(path: []const u8, mode: []const u8) ?*FILE {
-    const fd = unistd.open(path, flagsFor(mode));
-    if (fd < 0) return null;
-    const f = heap.allocator().create(FILE) catch {
-        unistd.close(fd);
-        return null;
-    };
-    f.* = .{ .fd = fd };
-    if (mode.len > 0 and mode[0] == 'a') _ = unistd.lseek(fd, 0, unistd.SEEK_END);
-    return f;
-}
-
-pub fn fclose(f: *FILE) c_int {
-    unistd.close(f.fd);
-    heap.allocator().destroy(f);
-    return 0;
-}
-
-/// Read `size*nmemb` bytes; returns the number of whole items read.
-pub fn fread(buffer: []u8, size: usize, nmemb: usize, f: *FILE) usize {
-    const total = size * nmemb;
-    if (total == 0) return 0;
-    const n = unistd.read(f.fd, buffer[0..@min(buffer.len, total)]);
-    if (n <= 0) {
-        f.eof = 1;
-        return 0;
-    }
-    return @as(usize, @intCast(n)) / size;
-}
-
-/// Write `size*nmemb` bytes; returns the number of whole items written.
-pub fn fwrite(data: []const u8, size: usize, nmemb: usize, f: *FILE) usize {
-    const total = @min(data.len, size * nmemb);
-    if (total == 0) return 0;
-    const n = unistd.write(f.fd, data[0..total]);
-    if (n <= 0) {
-        f.err = 1;
-        return 0;
-    }
-    return @as(usize, @intCast(n)) / size;
-}
-
-pub fn fseek(f: *FILE, off: i64, whence: u32) c_int {
-    f.eof = 0;
-    return if (unistd.lseek(f.fd, off, whence) < 0) -1 else 0;
-}
-
-pub fn ftell(f: *FILE) i64 {
-    return unistd.lseek(f.fd, 0, unistd.SEEK_CURRENT);
-}
-
-pub fn rewind(f: *FILE) void {
-    _ = fseek(f, 0, SEEK_SET);
-}
-
-pub fn feof(f: *FILE) c_int {
-    return f.eof;
-}
-
-pub fn ferror(f: *FILE) c_int {
-    return f.err;
-}
-
-pub fn fputs(s: []const u8, f: *FILE) c_int {
-    return if (unistd.write(f.fd, s) < 0) -1 else 0;
-}
-
-pub fn fputc(c: u8, f: *FILE) c_int {
-    const b = [_]u8{c};
-    return if (unistd.write(f.fd, &b) == 1) c else -1;
-}
-
-pub fn fgetc(f: *FILE) c_int {
-    var b: [1]u8 = undefined;
-    const n = unistd.read(f.fd, &b);
-    if (n <= 0) {
-        f.eof = 1;
-        return -1; // EOF
-    }
-    return b[0];
-}
-
-// Real `extern "C"` symbols (fopen/fread/fseek/...) — with a C-string signature
-// distinct from the Zig slice API above — land with the first C program, wired
-// via @export so they don't collide with these Zig names.

library/posix/unistd.zig

@@ -1,148 +0,0 @@
-//! POSIX-style file API for user programs — the low level under C stdio. Files
-//! are named objects served by the user-space VFS server (system/services/vfs/vfs.zig); each
-//! call marshals a request, IPC_Calls the VFS, and unmarshals the reply. The
-//! kernel knows nothing of files or fds — the fd table lives here, per process.
-
-const std = @import("std");
-const protocol = @import("vfs-protocol");
-const ipc = @import("runtime").ipc;
-
-pub const O_CREAT = protocol.create;
-pub const SEEK_SET: u32 = 0;
-pub const SEEK_CURRENT: u32 = 1;
-pub const SEEK_END: u32 = 2;
-
-// Resolve (and cache) the VFS server endpoint, looked up by well-known id.
-var vfs_handle: usize = 0;
-var vfs_resolved = false;
-fn vfs() ?usize {
-    if (!vfs_resolved) {
-        vfs_handle = ipc.lookup(.vfs) orelse return null;
-        vfs_resolved = true;
-    }
-    return vfs_handle;
-}
-
-const maximum_fds = 32;
-const Fd = struct { used: bool = false, node: u64 = 0, offset: u64 = 0 };
-var fds = [_]Fd{.{}} ** maximum_fds;
-
-fn allocFd() ?usize {
-    for (&fds, 0..) |*f, i| {
-        if (!f.used) {
-            f.* = .{ .used = true };
-            return i;
-        }
-    }
-    return null;
-}
-
-const Result = struct { reply: protocol.Reply, payload: []u8 };
-
-/// One request/reply round trip: [Request header][send payload] -> VFS ->
-/// [Reply header][receive payload]. The receive payload is written into `out`.
-fn transact(request: protocol.Request, send: []const u8, out: []u8) ?Result {
-    const h = vfs() orelse return null;
-    var message: [protocol.message_maximum]u8 = undefined;
-    @memcpy(message[0..protocol.request_size], std.mem.asBytes(&request));
-    const slen = @min(send.len, protocol.maximum_payload);
-    @memcpy(message[protocol.request_size..][0..slen], send[0..slen]);
-
-    var rbuf: [protocol.message_maximum]u8 = undefined;
-    const n = ipc.call(h, message[0 .. protocol.request_size + slen], &rbuf) catch return null;
-    if (n < protocol.reply_size) return null;
-    const reply = std.mem.bytesToValue(protocol.Reply, rbuf[0..protocol.reply_size]);
-    const rpl = @min(n - protocol.reply_size, out.len);
-    @memcpy(out[0..rpl], rbuf[protocol.reply_size..][0..rpl]);
-    return .{ .reply = reply, .payload = out[0..rpl] };
-}
-
-/// Open (or create, with O_CREAT) `path`; returns an fd or -1.
-pub fn open(path: []const u8, flags: u32) i32 {
-    const fd = allocFd() orelse return -1;
-    const request = protocol.Request{ .operation = .open, .node = 0, .offset = 0, .len = @intCast(path.len), .flags = flags };
-    const r = transact(request, path, &.{}) orelse {
-        fds[fd].used = false;
-        return -1;
-    };
-    if (r.reply.status != 0) {
-        fds[fd].used = false;
-        return -1;
-    }
-    fds[fd] = .{ .used = true, .node = r.reply.node, .offset = 0 };
-    return @intCast(fd);
-}
-
-fn fdPtr(fd: i32) ?*Fd {
-    if (fd < 0 or fd >= maximum_fds) return null;
-    const f = &fds[@intCast(fd)];
-    return if (f.used) f else null;
-}
-
-/// Read up to `buffer.len` bytes at the current offset; returns the count or -1.
-pub fn read(fd: i32, buffer: []u8) isize {
-    const f = fdPtr(fd) orelse return -1;
-    const want: u32 = @intCast(@min(buffer.len, protocol.maximum_payload));
-    const request = protocol.Request{ .operation = .read, .node = f.node, .offset = f.offset, .len = want, .flags = 0 };
-    const r = transact(request, &.{}, buffer) orelse return -1;
-    if (r.reply.status != 0) return -1;
-    f.offset += r.reply.len;
-    return @intCast(r.reply.len);
-}
-
-/// Write `data` at the current offset; returns the count or -1.
-pub fn write(fd: i32, data: []const u8) isize {
-    const f = fdPtr(fd) orelse return -1;
-    const want: u32 = @intCast(@min(data.len, protocol.maximum_payload));
-    const request = protocol.Request{ .operation = .write, .node = f.node, .offset = f.offset, .len = want, .flags = 0 };
-    const r = transact(request, data[0..want], &.{}) orelse return -1;
-    if (r.reply.status != 0) return -1;
-    f.offset += r.reply.len;
-    return @intCast(r.reply.len);
-}
-
-/// Reposition the fd's offset. Returns the new offset or -1. (SEEK_END needs the
-/// file size, which `stat` provides; handled by fetching it here.)
-pub fn lseek(fd: i32, off: i64, whence: u32) i64 {
-    const f = fdPtr(fd) orelse return -1;
-    const base: i64 = switch (whence) {
-        SEEK_SET => 0,
-        SEEK_CURRENT => @intCast(f.offset),
-        SEEK_END => blk: {
-            const request = protocol.Request{ .operation = .status, .node = f.node, .offset = 0, .len = 0, .flags = 0 };
-            var sbuf: [@sizeOf(protocol.FileStatus)]u8 = undefined;
-            const r = transact(request, &.{}, &sbuf) orelse return -1;
-            if (r.reply.status != 0 or r.payload.len < @sizeOf(protocol.FileStatus)) return -1;
-            const st = std.mem.bytesToValue(protocol.FileStatus, sbuf[0..@sizeOf(protocol.FileStatus)]);
-            break :blk @intCast(st.size);
-        },
-        else => return -1,
-    };
-    const pos = base + off;
-    if (pos < 0) return -1;
-    f.offset = @intCast(pos);
-    return pos;
-}
-
-/// Stat `path`. Returns 0 or -1.
-pub fn stat(path: []const u8, out: *protocol.FileStatus) i32 {
-    // Open, stat by node, close — simple and enough for now.
-    const fd = open(path, 0);
-    if (fd < 0) return -1;
-    defer close(fd);
-    const f = fdPtr(fd).?;
-    const request = protocol.Request{ .operation = .status, .node = f.node, .offset = 0, .len = 0, .flags = 0 };
-    var sbuf: [@sizeOf(protocol.FileStatus)]u8 = undefined;
-    const r = transact(request, &.{}, &sbuf) orelse return -1;
-    if (r.reply.status != 0 or r.payload.len < @sizeOf(protocol.FileStatus)) return -1;
-    out.* = std.mem.bytesToValue(protocol.FileStatus, sbuf[0..@sizeOf(protocol.FileStatus)]);
-    return 0;
-}
-
-/// Close an fd (best effort — tells the VFS to release the open file).
-pub fn close(fd: i32) void {
-    const f = fdPtr(fd) orelse return;
-    const request = protocol.Request{ .operation = .close, .node = f.node, .offset = 0, .len = 0, .flags = 0 };
-    _ = transact(request, &.{}, &.{});
-    f.used = false;
-}

library/runtime/block.zig

@@ -0,0 +1,69 @@
+//! Block-device client: the helper a filesystem uses to read and write a block
+//! device (a USB stick, via usb-storage) without hand-rolling the block-protocol
+//! IPC. Layered over `ipc` and the shared `block-protocol` wire format, like
+//! `runtime.usb` over the transfer protocol.
+//!
+//! Transfers name a caller-owned DMA buffer by physical address (from
+//! `runtime.dma.alloc`), so whole sectors move without crossing the IPC size
+//! limit — the same handoff usb-storage uses toward the controller.
+
+const std = @import("std");
+const ipc = @import("ipc.zig");
+const system = @import("system.zig");
+const protocol = @import("block-protocol");
+
+pub const Geometry = struct { block_size: u32, block_count: u64 };
+
+pub const Device = struct {
+    endpoint: ipc.Handle,
+
+    /// The device's block size and total block count.
+    pub fn geometry(self: Device) ?Geometry {
+        var request = protocol.Request{ .operation = @intFromEnum(protocol.Operation.geometry), .lba = 0, .count = 0, .physical = 0 };
+        var reply: [protocol.reply_size]u8 = undefined;
+        const n = ipc.call(self.endpoint, std.mem.asBytes(&request), &reply) catch return null;
+        if (n < protocol.reply_size) return null;
+        const result = std.mem.bytesToValue(protocol.Reply, reply[0..protocol.reply_size]);
+        if (result.status != 0) return null;
+        return .{ .block_size = result.block_size, .block_count = result.block_count };
+    }
+
+    /// Read `count` blocks starting at `lba` into the DMA buffer at `physical`.
+    pub fn read(self: Device, lba: u64, count: u32, physical: u64) bool {
+        return self.transfer(.read, lba, count, physical);
+    }
+
+    /// Write `count` blocks starting at `lba` from the DMA buffer at `physical`.
+    pub fn write(self: Device, lba: u64, count: u32, physical: u64) bool {
+        return self.transfer(.write, lba, count, physical);
+    }
+
+    /// Commit any device write cache to stable media (SCSI SYNCHRONIZE CACHE), so
+    /// prior writes survive a power-off. A filesystem calls this before the machine
+    /// goes down; no data transfer, so the buffer arguments are unused.
+    pub fn flush(self: Device) bool {
+        return self.transfer(.flush, 0, 0, 0);
+    }
+
+    fn transfer(self: Device, operation: protocol.Operation, lba: u64, count: u32, physical: u64) bool {
+        var request = protocol.Request{ .operation = @intFromEnum(operation), .lba = lba, .count = count, .physical = physical };
+        var reply: [protocol.reply_size]u8 = undefined;
+        const n = ipc.call(self.endpoint, std.mem.asBytes(&request), &reply) catch return false;
+        if (n < protocol.reply_size) return false;
+        return std.mem.bytesToValue(protocol.Reply, reply[0..protocol.reply_size]).status == 0;
+    }
+};
+
+/// Look up the block device, retrying generously while the USB storage chain
+/// (controller reset, enumeration, mass-storage bring-up) comes up.
+pub fn open() ?Device {
+    // Patient: the whole USB storage chain (firmware discovery, xHCI reset and
+    // enumeration, mass-storage bring-up) must complete first, which can take
+    // tens of seconds under emulation.
+    var attempts: usize = 0;
+    while (attempts < 1200) : (attempts += 1) {
+        if (ipc.lookup(.block)) |handle| return .{ .endpoint = handle };
+        system.sleep(50);
+    }
+    return null;
+}

library/runtime/device.zig

@@ -3,6 +3,7 @@
 //! ownership of its hardware; the claim is the capability the kernel checks before
 //! mapping registers or routing an IRQ.
 
+const std = @import("std");
 const abi = @import("abi");
 const device_abi = @import("device-abi");
 const sc = @import("system-call.zig");
@@ -36,6 +37,10 @@ pub fn mmioMap(device_id: u64, resource_index: u64) ?usize {
 /// `DeviceDescriptor.parent` for a device with no parent.
 pub const no_parent = device_abi.no_parent;
 
+/// `DeviceDescriptor.pci_class` for a device that is not a PCI function. Set this on
+/// descriptors passed to `register` unless the child really is one.
+pub const no_pci_class = device_abi.no_pci_class;
+
 /// Publish `descriptor` as a child of `parent_id`, which this process must have claimed.
 /// Returns the new device id. The child is left unclaimed, so whichever driver owns
 /// that class of device can `claim` it — that is how a bus hands off a device.
@@ -108,3 +113,19 @@ pub fn ioRead(device_id: u64, resource_index: u64, offset: u64, width: u8) ?u32
 pub fn ioWrite(device_id: u64, resource_index: u64, offset: u64, width: u8, value: u32) bool {
     return !failed(sc.systemCall5(.io_write, device_id, resource_index, offset, width, value));
 }
+
+/// Find DeviceDescription by hid
+///
+/// Utility function for driver development
+pub fn findDeviceDescriptorByHid(buffer: []DeviceDescriptor, hid_needle: []const u8) ?DeviceDescriptor {
+    const total = enumerate(buffer);
+    const n = @min(total, buffer.len);
+    for (@as([]DeviceDescriptor, buffer[0..n])) |d| {
+        const hid_haystack = d.hid[0..@intCast(d.hid_len)];
+        if (std.mem.eql(u8, hid_haystack, hid_needle)) {
+            return d;
+        }
+    }
+
+    return null;
+}

library/runtime/display.zig

@@ -0,0 +1,198 @@
+//! User-space display client: talk to the display service (query the mode, and — from D3
+//! — create layers, draw, and present) without hand-rolling the IPC. The `runtime.block`
+//! shape: a cached `.display` lookup with a boot-race retry, then extern-struct request/
+//! reply marshalling. See system/services/display/ and docs/display.md.
+
+const std = @import("std");
+const ipc = @import("ipc.zig");
+const system = @import("system.zig");
+const protocol = @import("display-protocol");
+
+/// The display's current mode, as `info()` reports it.
+pub const Info = struct {
+    width: u32,
+    height: u32,
+    pitch: u32, // bytes per row (may exceed width*4; see docs/framebuffer.md)
+    format: u32, // a device-abi DisplayFormat value (0 = rgbx, 1 = bgrx)
+};
+
+/// The service endpoint, looked up once and cached.
+var handle: ?ipc.Handle = null;
+
+/// Look up the display service, retrying while it comes up (a client races its
+/// registration at boot). Returns the endpoint, or null if it never appears.
+fn service() ?ipc.Handle {
+    if (handle) |h| return h;
+    var attempts: usize = 0;
+    while (attempts < 100) : (attempts += 1) {
+        if (ipc.lookup(.display)) |h| {
+            handle = h;
+            return h;
+        }
+        system.sleep(50);
+    }
+    return null;
+}
+
+/// Send one request, receive its reply; true on a zero status. `out` receives the reply
+/// so callers can read `info`/`layer` fields on success.
+fn transact(request: protocol.Request, out: *protocol.Reply) bool {
+    const h = service() orelse return false;
+    var req = request;
+    var reply: [protocol.reply_size]u8 = undefined;
+    const len = ipc.call(h, std.mem.asBytes(&req), &reply) catch return false;
+    if (len < protocol.reply_size) return false;
+    out.* = std.mem.bytesToValue(protocol.Reply, reply[0..protocol.reply_size]);
+    return out.status == 0;
+}
+
+/// The display's current mode, or null if the service never came up.
+pub fn info() ?Info {
+    var reply: protocol.Reply = undefined;
+    if (!transact(.{ .operation = @intFromEnum(protocol.Operation.info) }, &reply)) return null;
+    return .{ .width = reply.width, .height = reply.height, .pitch = reply.pitch, .format = reply.format };
+}
+
+/// Composite the dirty layers and flush the frame to the screen.
+pub fn present() bool {
+    var reply: protocol.Reply = undefined;
+    return transact(.{ .operation = @intFromEnum(protocol.Operation.present) }, &reply);
+}
+
+/// One selectable display mode.
+pub const Mode = protocol.Mode;
+
+/// Fill `out` with the resolutions the display can switch to; returns how many were written
+/// (zero on the GOP floor, or if the service never came up).
+pub fn modes(out: []Mode) usize {
+    const h = service() orelse return 0;
+    var request = protocol.Request{ .operation = @intFromEnum(protocol.Operation.get_modes) };
+    var reply: [protocol.modes_reply_size]u8 = undefined;
+    const len = ipc.call(h, std.mem.asBytes(&request), &reply) catch return 0;
+    if (len < protocol.modes_reply_size) return 0;
+    const answer = std.mem.bytesToValue(protocol.ModesReply, reply[0..protocol.modes_reply_size]);
+    if (answer.status != 0) return 0;
+    const count = @min(@min(answer.count, protocol.max_modes), out.len);
+    for (0..count) |i| out[i] = answer.modes[i];
+    return count;
+}
+
+/// Change the display resolution. Only a native backend that supports mode-setting honours it
+/// (on the GOP floor it returns false); on success the display's `info()` reports the new mode.
+pub fn setMode(width: u32, height: u32) bool {
+    var reply: protocol.Reply = undefined;
+    const changed = transact(.{ .operation = @intFromEnum(protocol.Operation.set_mode), .width = width, .height = height }, &reply);
+    if (changed) mode = null; // the cached mode is stale now
+    return changed;
+}
+
+/// The mode, cached after the first `info()` so `color()` doesn't round-trip per pixel.
+var mode: ?Info = null;
+
+fn cachedInfo() ?Info {
+    if (mode) |m| return m;
+    const i = info() orelse return null;
+    mode = i;
+    return i;
+}
+
+/// The native pixel value for an 8-bit-per-channel colour, in the display's format. A
+/// client packs colours through this so it never has to know the byte order itself.
+pub fn color(r: u8, g: u8, b: u8) u32 {
+    const format = if (cachedInfo()) |i| i.format else 0;
+    return protocol.pack(format, r, g, b);
+}
+
+/// A handle to a server-owned layer: a positioned, z-ordered surface the client draws
+/// into by command. Create with `createLayer`; drawing and moves take effect on the next
+/// `present`. Coordinates are signed (a layer may sit partly off-screen).
+pub const Layer = struct {
+    id: u32,
+
+    /// Fill a rectangle of this layer (layer-local coordinates) with a native `colour`.
+    pub fn fill(self: Layer, x: i32, y: i32, w: u32, h: u32, colour: u32) bool {
+        var reply: protocol.Reply = undefined;
+        return transact(.{
+            .operation = @intFromEnum(protocol.Operation.fill_rect),
+            .layer = self.id,
+            .x = @bitCast(x),
+            .y = @bitCast(y),
+            .width = w,
+            .height = h,
+            .colour = colour,
+        }, &reply);
+    }
+
+    /// Copy a `w`×`h` tile of native pixels (row-major, little-endian bytes) into this
+    /// layer at (`x`, `y`). The tile rides inline in the request, so `w*h*4` must fit
+    /// `protocol.maximum_payload`.
+    pub fn blitTile(self: Layer, x: i32, y: i32, w: u32, h: u32, pixels: []const u8) bool {
+        var request = protocol.Request{
+            .operation = @intFromEnum(protocol.Operation.blit_tile),
+            .layer = self.id,
+            .x = @bitCast(x),
+            .y = @bitCast(y),
+            .width = w,
+            .height = h,
+        };
+        const header = std.mem.asBytes(&request);
+        if (header.len + pixels.len > protocol.message_maximum) return false;
+        var buffer: [protocol.message_maximum]u8 = undefined;
+        @memcpy(buffer[0..header.len], header);
+        @memcpy(buffer[header.len..][0..pixels.len], pixels);
+        const h_svc = service() orelse return false;
+        var reply: [protocol.reply_size]u8 = undefined;
+        const len = ipc.call(h_svc, buffer[0 .. header.len + pixels.len], &reply) catch return false;
+        if (len < protocol.reply_size) return false;
+        return std.mem.bytesToValue(protocol.Reply, reply[0..protocol.reply_size]).status == 0;
+    }
+
+    /// Move / restack / show or hide the layer.
+    pub fn configure(self: Layer, x: i32, y: i32, z: u32, visible: bool) bool {
+        var reply: protocol.Reply = undefined;
+        return transact(.{
+            .operation = @intFromEnum(protocol.Operation.configure_layer),
+            .layer = self.id,
+            .x = @bitCast(x),
+            .y = @bitCast(y),
+            .z = z,
+            .visible = if (visible) 1 else 0,
+        }, &reply);
+    }
+
+    /// Mark a rectangle of this layer (layer-local) dirty for the next present — for when
+    /// the layer's pixels changed without a drawing call the compositor already tracked.
+    pub fn damage(self: Layer, x: i32, y: i32, w: u32, h: u32) bool {
+        var reply: protocol.Reply = undefined;
+        return transact(.{
+            .operation = @intFromEnum(protocol.Operation.damage),
+            .layer = self.id,
+            .x = @bitCast(x),
+            .y = @bitCast(y),
+            .width = w,
+            .height = h,
+        }, &reply);
+    }
+
+    /// Release the layer and its surface.
+    pub fn destroy(self: Layer) bool {
+        var reply: protocol.Reply = undefined;
+        return transact(.{ .operation = @intFromEnum(protocol.Operation.destroy_layer), .layer = self.id }, &reply);
+    }
+};
+
+/// Create a server-owned layer of `w`×`h` pixels at screen (`x`, `y`) with stacking order
+/// `z` (higher is nearer the front), initially visible. Returns a handle, or null.
+pub fn createLayer(x: i32, y: i32, w: u32, h: u32, z: u32) ?Layer {
+    var reply: protocol.Reply = undefined;
+    if (!transact(.{
+        .operation = @intFromEnum(protocol.Operation.create_layer),
+        .x = @bitCast(x),
+        .y = @bitCast(y),
+        .width = w,
+        .height = h,
+        .z = z,
+        .visible = 1,
+    }, &reply)) return null;
+    return .{ .id = reply.layer };
+}

library/runtime/fs.zig

@@ -0,0 +1,274 @@
+//! runtime.fs — the danos-native file API. A program opens, reads, writes, and
+//! lists files served by the user-space VFS (system/services/vfs), each call
+//! marshalling a vfs-protocol request over IPC. This is the danos-native layer
+//! danos programs use directly; it is also where the file operations that later
+//! become `std.os.danos` are staged (see docs/zig-self-hosting.md). It replaces
+//! the old POSIX `unistd` shim — a compatibility spelling danos does not need yet.
+//!
+//! Handles are *values*, not entries in a global descriptor table: a `File` /
+//! `Directory` owns its VFS node id and (for files) a byte offset. So there is no
+//! per-process fd limit and no shared table to synchronise — the danos-native
+//! shape, unlike the POSIX fd model the old shim emulated.
+
+const std = @import("std");
+const ipc = @import("ipc.zig");
+const protocol = @import("vfs-protocol");
+
+/// The kind of a filesystem node — re-exported so a caller need not import the
+/// wire protocol.
+pub const Kind = protocol.NodeKind;
+
+/// A node's metadata (the answer to a status request).
+pub const Attributes = struct {
+    size: u64,
+    kind: Kind,
+    /// Modification time — Unix epoch seconds, UTC. 0 if the filesystem has none.
+    mtime: u64 = 0,
+};
+
+// Map a wire `NodeKind` value to the enum, defaulting anything unrecognised to
+// `.regular` (the server is trusted, but a value outside the enum would be
+// illegal to `@enumFromInt` directly).
+fn kindFromWire(value: u32) Kind {
+    return switch (value) {
+        @intFromEnum(Kind.directory) => .directory,
+        @intFromEnum(Kind.character_device) => .character_device,
+        @intFromEnum(Kind.block_device) => .block_device,
+        @intFromEnum(Kind.symbolic_link) => .symbolic_link,
+        @intFromEnum(Kind.fifo) => .fifo,
+        @intFromEnum(Kind.socket) => .socket,
+        else => .regular,
+    };
+}
+
+/// How to open a path.
+pub const OpenOptions = struct {
+    /// Create the file if it does not exist.
+    create: bool = false,
+    /// Open a directory node (for listing) rather than a file.
+    directory: bool = false,
+    /// Truncate an existing file to zero length on open (O_TRUNC) — replace its
+    /// contents rather than overwriting in place.
+    truncate: bool = false,
+
+    fn wireFlags(self: OpenOptions) u32 {
+        var f: u32 = 0;
+        if (self.create) f |= protocol.create;
+        if (self.directory) f |= protocol.directory;
+        if (self.truncate) f |= protocol.truncate;
+        return f;
+    }
+};
+
+// The VFS server endpoint, looked up once by well-known id and cached.
+var vfs_handle: ipc.Handle = 0;
+var vfs_resolved = false;
+fn vfs() ?ipc.Handle {
+    if (!vfs_resolved) {
+        vfs_handle = ipc.lookup(.vfs) orelse return null;
+        vfs_resolved = true;
+    }
+    return vfs_handle;
+}
+
+const Result = struct { reply: protocol.Reply, payload: []u8 };
+
+// One request/reply round trip: [Request header][send payload] -> VFS ->
+// [Reply header][receive payload]. The receive payload lands in `out`.
+fn transact(request: protocol.Request, send: []const u8, out: []u8) ?Result {
+    const h = vfs() orelse return null;
+    var message: [protocol.message_maximum]u8 = undefined;
+    @memcpy(message[0..protocol.request_size], std.mem.asBytes(&request));
+    const slen = @min(send.len, protocol.maximum_payload);
+    @memcpy(message[protocol.request_size..][0..slen], send[0..slen]);
+
+    var rbuf: [protocol.message_maximum]u8 = undefined;
+    const n = ipc.call(h, message[0 .. protocol.request_size + slen], &rbuf) catch return null;
+    if (n < protocol.reply_size) return null;
+    const reply = std.mem.bytesToValue(protocol.Reply, rbuf[0..protocol.reply_size]);
+    const rpl = @min(n - protocol.reply_size, out.len);
+    @memcpy(out[0..rpl], rbuf[protocol.reply_size..][0..rpl]);
+    return .{ .reply = reply, .payload = out[0..rpl] };
+}
+
+/// An open file: a VFS node plus a byte cursor. Read and write advance the cursor.
+pub const File = struct {
+    node: u64,
+    offset: u64 = 0,
+
+    /// Read up to `buffer.len` bytes at the current offset; returns the count, or
+    /// null on error.
+    pub fn read(self: *File, buffer: []u8) ?usize {
+        const want: u32 = @intCast(@min(buffer.len, protocol.maximum_payload));
+        const request = protocol.Request{ .operation = .read, .node = self.node, .offset = self.offset, .len = want, .flags = 0 };
+        const r = transact(request, &.{}, buffer) orelse return null;
+        if (r.reply.status != 0) return null;
+        self.offset += r.reply.len;
+        return r.reply.len;
+    }
+
+    /// Write `data` at the current offset; returns the count written. A single
+    /// call is capped at the VFS payload size, so the return may be short — use
+    /// `writeAll` to write the whole slice. Null on error.
+    pub fn write(self: *File, data: []const u8) ?usize {
+        const want: u32 = @intCast(@min(data.len, protocol.maximum_payload));
+        const request = protocol.Request{ .operation = .write, .node = self.node, .offset = self.offset, .len = want, .flags = 0 };
+        const r = transact(request, data[0..want], &.{}) orelse return null;
+        if (r.reply.status != 0) return null;
+        self.offset += r.reply.len;
+        return r.reply.len;
+    }
+
+    /// Write all of `data`, looping past the per-call payload cap. Returns the
+    /// total written, or null if a write failed before any progress.
+    pub fn writeAll(self: *File, data: []const u8) ?usize {
+        var written: usize = 0;
+        while (written < data.len) {
+            const n = self.write(data[written..]) orelse return if (written == 0) null else written;
+            if (n == 0) return written; // no forward progress; stop rather than spin
+            written += n;
+        }
+        return written;
+    }
+
+    /// Move the read/write cursor to an absolute byte position.
+    pub fn seekTo(self: *File, position: u64) void {
+        self.offset = position;
+    }
+
+    /// This file's metadata.
+    pub fn attributes(self: *File) ?Attributes {
+        const request = protocol.Request{ .operation = .status, .node = self.node, .offset = 0, .len = 0, .flags = 0 };
+        var buffer: [@sizeOf(protocol.FileStatus)]u8 = undefined;
+        const r = transact(request, &.{}, &buffer) orelse return null;
+        if (r.reply.status != 0 or r.payload.len < @sizeOf(protocol.FileStatus)) return null;
+        const status = std.mem.bytesToValue(protocol.FileStatus, buffer[0..@sizeOf(protocol.FileStatus)]);
+        return .{ .size = status.size, .kind = kindFromWire(status.kind), .mtime = status.mtime };
+    }
+
+    /// Release the VFS's open handle for this file.
+    pub fn close(self: *File) void {
+        const request = protocol.Request{ .operation = .close, .node = self.node, .offset = 0, .len = 0, .flags = 0 };
+        _ = transact(request, &.{}, &.{});
+    }
+};
+
+/// Open (or create, with `.create`) `path`. Returns the open file, or null.
+pub fn open(path: []const u8, options: OpenOptions) ?File {
+    const request = protocol.Request{ .operation = .open, .node = 0, .offset = 0, .len = @intCast(path.len), .flags = options.wireFlags() };
+    const r = transact(request, path, &.{}) orelse return null;
+    if (r.reply.status != 0) return null;
+    return .{ .node = r.reply.node };
+}
+
+/// A path's metadata without keeping it open (open -> status -> close).
+pub fn attributes(path: []const u8) ?Attributes {
+    var file = open(path, .{}) orelse return null;
+    defer file.close();
+    return file.attributes();
+}
+
+/// Whether `path` resolves — handy as a readiness check (e.g. waiting for a mount
+/// to come up before writing to it).
+pub fn exists(path: []const u8) bool {
+    return attributes(path) != null;
+}
+
+/// One entry returned by `Directory.next`.
+pub const Entry = struct {
+    kind: Kind = .regular,
+    size: u64 = 0,
+    name_buffer: [64]u8 = undefined,
+    name_len: usize = 0,
+
+    pub fn name(self: *const Entry) []const u8 {
+        return self.name_buffer[0..self.name_len];
+    }
+};
+
+/// An open directory being listed, cursor-advanced by `next`.
+pub const Directory = struct {
+    node: u64,
+    cursor: u64 = 0,
+
+    /// Fill `entry` with the next directory entry; false at end of directory or
+    /// on error.
+    pub fn next(self: *Directory, entry: *Entry) bool {
+        const request = protocol.Request{ .operation = .readdir, .node = self.node, .offset = self.cursor, .len = 0, .flags = 0 };
+        var buffer: [protocol.message_maximum]u8 = undefined;
+        const r = transact(request, &.{}, &buffer) orelse return false;
+        if (r.reply.status != 0 or r.reply.len == 0) return false; // error or EOF
+        if (r.payload.len < protocol.directory_entry_size) return false;
+        const header = std.mem.bytesToValue(protocol.DirectoryEntry, r.payload[0..protocol.directory_entry_size]);
+        entry.kind = kindFromWire(header.kind);
+        entry.size = header.size;
+        const source = r.payload[protocol.directory_entry_size..];
+        const nlen = @min(@min(@as(usize, header.name_len), source.len), entry.name_buffer.len);
+        @memcpy(entry.name_buffer[0..nlen], source[0..nlen]);
+        entry.name_len = nlen;
+        self.cursor += 1;
+        return true;
+    }
+
+    /// Release the VFS's open handle for this directory.
+    pub fn close(self: *Directory) void {
+        var f = File{ .node = self.node };
+        f.close();
+    }
+};
+
+/// Open `path` as a directory for listing. Returns null if it isn't one / on error.
+pub fn openDirectory(path: []const u8) ?Directory {
+    const file = open(path, .{ .directory = true }) orelse return null;
+    return .{ .node = file.node };
+}
+
+// A path-based request that returns only a status (mkdir, unlink).
+fn pathOperation(operation: protocol.Operation, path: []const u8) bool {
+    const request = protocol.Request{ .operation = operation, .node = 0, .offset = 0, .len = @intCast(path.len), .flags = 0 };
+    const r = transact(request, path, &.{}) orelse return false;
+    return r.reply.status == 0;
+}
+
+/// Create a directory at `path` (its parent must already exist). Returns true on
+/// success. Only works under a mounted filesystem that supports directories.
+pub fn makeDirectory(path: []const u8) bool {
+    return pathOperation(.mkdir, path);
+}
+
+/// Remove the file at `path`. Returns true on success. Directories are refused
+/// (a separate directory-removal would have to check emptiness).
+pub fn remove(path: []const u8) bool {
+    return pathOperation(.unlink, path);
+}
+
+/// Rename `old_path` to `new_path`. Both must be in the same directory (same-
+/// directory, 8.3-name rename only for now). Returns true on success.
+pub fn rename(old_path: []const u8, new_path: []const u8) bool {
+    const total = old_path.len + 1 + new_path.len;
+    if (total > protocol.maximum_payload) return false;
+    var payload: [protocol.maximum_payload]u8 = undefined;
+    @memcpy(payload[0..old_path.len], old_path);
+    payload[old_path.len] = 0;
+    @memcpy(payload[old_path.len + 1 ..][0..new_path.len], new_path);
+    const request = protocol.Request{ .operation = .rename, .node = 0, .offset = 0, .len = @intCast(total), .flags = 0 };
+    const r = transact(request, payload[0..total], &.{}) orelse return false;
+    return r.reply.status == 0;
+}
+
+/// Mount a filesystem backend (its server endpoint) at absolute path `target`;
+/// the VFS then routes everything under `target` to that backend. This is the one
+/// call that hands the VFS a capability (the backend endpoint). Returns true on
+/// success.
+pub fn mount(target: []const u8, backend: ipc.Handle) bool {
+    const h = vfs() orelse return false;
+    const request = protocol.Request{ .operation = .mount, .node = 0, .offset = 0, .len = @intCast(target.len), .flags = 0 };
+    var message: [protocol.message_maximum]u8 = undefined;
+    @memcpy(message[0..protocol.request_size], std.mem.asBytes(&request));
+    const tlen = @min(target.len, protocol.maximum_payload);
+    @memcpy(message[protocol.request_size..][0..tlen], target[0..tlen]);
+    var rbuf: [protocol.message_maximum]u8 = undefined;
+    const result = ipc.callCap(h, message[0 .. protocol.request_size + tlen], &rbuf, backend) catch return false;
+    if (result.len < protocol.reply_size) return false;
+    return std.mem.bytesToValue(protocol.Reply, rbuf[0..protocol.reply_size]).status == 0;
+}

library/runtime/heap.zig

@@ -9,15 +9,32 @@
 //! — `grow` asks the kernel for pages via `mmap` instead of mapping frames
 //! itself, and the kernel picks the base address.
 //!
-//! Single-threaded and 16-byte maximum alignment, exactly like the kernel heap; a
-//! lock and larger alignments come when user programs gain threads.
+//! 16-byte maximum alignment, exactly like the kernel heap. The free list is guarded by
+//! a `Thread.Mutex` **only in multi-threaded binaries** (`addThreadedUserBinary`): the
+//! guard is gated on `builtin.single_threaded`, so an ordinary single-threaded binary
+//! compiles it out and pays nothing, while a threaded one can allocate safely from
+//! several threads at once (docs/threading-plan.md M7). The lock lives at the two
+//! free-list mutators — `rawAlloc`/`rawFree` — which every entry point funnels through.
 
 const std = @import("std");
+const builtin = @import("builtin");
 const abi = @import("abi");
 const system_calls = @import("system.zig");
+const Mutex = @import("thread.zig").Thread.Mutex;
 
 const page_size = abi.page_size;
 
+/// Guards `free_list`. A no-op in single-threaded builds (compiled out); a real futex
+/// mutex in threaded ones. Uncontended acquisition is a single CAS — no syscall.
+var heap_mutex: Mutex = .{};
+
+inline fn lockHeap() void {
+    if (comptime !builtin.single_threaded) heap_mutex.lock();
+}
+inline fn unlockHeap() void {
+    if (comptime !builtin.single_threaded) heap_mutex.unlock();
+}
+
 /// A block header, at the start of every block; while free it also links the
 /// free list via `next`.
 const Block = extern struct {
@@ -84,8 +101,11 @@ fn insertFree(block: *Block) void {
     }
 }
 
-/// Allocate `len` bytes (16-byte aligned), or null if out of memory.
+/// Allocate `len` bytes (16-byte aligned), or null if out of memory. Holds the heap lock
+/// across the free-list search and any `grow` (which also touches the free list).
 fn rawAlloc(len: usize) ?[*]u8 {
+    lockHeap();
+    defer unlockHeap();
     const need = alignUp(header_size + len, 16);
 
     var attempts: u32 = 0;
@@ -119,6 +139,8 @@ fn rawAlloc(len: usize) ?[*]u8 {
 }
 
 fn rawFree(ptr: [*]u8) void {
+    lockHeap();
+    defer unlockHeap();
     const block: *Block = @ptrFromInt(@intFromPtr(ptr) - header_size);
     insertFree(block);
 }

library/runtime/input.zig

@@ -0,0 +1,220 @@
+//! User-space input helpers: the client and publisher sides of the input service, so a
+//! program listening for input events — or a driver broadcasting them — doesn't hand-roll
+//! the IPC. Layered over `ipc` (endpoints, capability passing, `send`) and the shared
+//! `input-protocol` wire format, the way `device.zig` layers over the raw `device_*` calls.
+//! See system/services/input/input.zig.
+//!
+//! The service carries several device classes (keyboard, mouse, joystick/gamepad). A
+//! **source** publishes its class with the matching method:
+//!     var source = input.connectSource() orelse return;
+//!     _ = source.publishKeyboardEvent(.{ .kind = ..., .keycode = ..., ... });
+//!     _ = source.publishMouseEvent(.{ ... });
+//!     _ = source.publishJoystickEvent(.{ ... });
+//!
+//! A **subscriber** either takes one class with a typed helper —
+//!     var keys = input.subscribeKeyboard() orelse return;
+//!     while (true) { const key = keys.next() orelse continue; ... }
+//! — or takes several at once and inspects the tagged envelope:
+//!     var listener = input.subscribeAll() orelse return;
+//!     while (true) {
+//!         const event = listener.next() orelse continue;
+//!         if (event.asKeyboard()) |k| { ... } else if (event.asMouse()) |m| { ... }
+//!     }
+
+const std = @import("std");
+const abi = @import("abi");
+const ipc = @import("ipc.zig");
+const system = @import("system.zig");
+const protocol = @import("input-protocol");
+
+pub const DeviceKind = protocol.DeviceKind;
+pub const InputEvent = protocol.InputEvent;
+pub const KeyEvent = protocol.KeyEvent;
+pub const MouseEvent = protocol.MouseEvent;
+pub const JoystickEvent = protocol.JoystickEvent;
+pub const EventKind = protocol.EventKind;
+pub const MouseEventKind = protocol.MouseEventKind;
+pub const JoystickEventKind = protocol.JoystickEventKind;
+pub const Keycode = protocol.Keycode;
+
+/// Interest masks re-exported so a caller can `subscribe(input.device_keyboard |
+/// input.device_mouse)`.
+pub const device_keyboard = protocol.device_keyboard;
+pub const device_mouse = protocol.device_mouse;
+pub const device_joystick = protocol.device_joystick;
+pub const device_all = protocol.device_all;
+
+/// Look up the input service, retrying while it is still coming up. Both a subscriber and
+/// a source race the service's registration at boot, so both wait for it here rather than
+/// failing. Returns the service endpoint handle, or null if it never appears.
+fn lookupService() ?ipc.Handle {
+    var attempts: usize = 0;
+    while (attempts < 100) : (attempts += 1) {
+        if (ipc.lookup(.input)) |handle| return handle;
+        system.sleep(50);
+    }
+    return null;
+}
+
+// --- subscribing ------------------------------------------------------------
+
+/// A subscription to the input service: our own endpoint, which the service pushes events
+/// to. `next` returns each event as a tagged `InputEvent`; use `asKeyboard`/`asMouse`/
+/// `asJoystick` to decode. Created with `subscribe`/`subscribeAll`; for a single device
+/// class prefer the typed helpers (`subscribeKeyboard`, ...), which return decoded events.
+pub const Subscriber = struct {
+    /// The endpoint the service delivers events to (created and owned by us; its handle
+    /// was handed to the service as a capability at subscribe time).
+    endpoint: ipc.Handle,
+    receive: [protocol.event_size]u8 = undefined,
+
+    /// Block until the next event is pushed, and return it. Events arrive as asynchronous
+    /// buffered messages (`ipc_send` from the service), so nothing is owed in reply — the
+    /// empty reply this issues is a harmless no-op. Returns null for any non-event wake-up
+    /// (there should be none), so callers can loop.
+    pub fn next(self: *Subscriber) ?InputEvent {
+        const got = ipc.replyWait(self.endpoint, &.{}, &self.receive, null);
+        if (!got.isMessage() or got.len < protocol.event_size) return null;
+        return std.mem.bytesToValue(InputEvent, self.receive[0..protocol.event_size]);
+    }
+};
+
+/// Subscribe to the input classes named in `device_mask` (an OR of `device_*`, or
+/// `device_all`). Creates an endpoint for the service to push to and hands it over as a
+/// capability. Returns a `Subscriber` to loop `next` on, or null on failure.
+pub fn subscribe(device_mask: u32) ?Subscriber {
+    const service = lookupService() orelse return null;
+    const endpoint = ipc.createIpcEndpoint() orelse return null;
+
+    var request = protocol.Request{ .operation = @intFromEnum(protocol.Operation.subscribe), .device_mask = device_mask };
+    var reply: [protocol.reply_size]u8 = undefined;
+    const result = ipc.callCap(service, std.mem.asBytes(&request), &reply, endpoint) catch return null;
+    if (result.len < protocol.reply_size) return null;
+    if (std.mem.bytesToValue(protocol.Reply, reply[0..protocol.reply_size]).status != 0) return null;
+    return .{ .endpoint = endpoint };
+}
+
+/// Subscribe to every input class (keyboard, mouse, joystick) on one stream.
+pub fn subscribeAll() ?Subscriber {
+    return subscribe(device_all);
+}
+
+/// A subscriber filtered to keyboard events, whose `next` returns a decoded `KeyEvent`.
+pub const KeyboardSubscriber = struct {
+    inner: Subscriber,
+    pub fn next(self: *KeyboardSubscriber) ?KeyEvent {
+        return (self.inner.next() orelse return null).asKeyboard();
+    }
+};
+
+/// A subscriber filtered to mouse events, whose `next` returns a decoded `MouseEvent`.
+pub const MouseSubscriber = struct {
+    inner: Subscriber,
+    pub fn next(self: *MouseSubscriber) ?MouseEvent {
+        return (self.inner.next() orelse return null).asMouse();
+    }
+};
+
+/// A subscriber filtered to joystick/gamepad events, whose `next` returns a decoded
+/// `JoystickEvent`.
+pub const JoystickSubscriber = struct {
+    inner: Subscriber,
+    pub fn next(self: *JoystickSubscriber) ?JoystickEvent {
+        return (self.inner.next() orelse return null).asJoystick();
+    }
+};
+
+/// Subscribe to keyboard events only; `next` returns decoded `KeyEvent`s.
+pub fn subscribeKeyboard() ?KeyboardSubscriber {
+    return .{ .inner = subscribe(device_keyboard) orelse return null };
+}
+
+/// Subscribe to mouse events only; `next` returns decoded `MouseEvent`s.
+pub fn subscribeMouse() ?MouseSubscriber {
+    return .{ .inner = subscribe(device_mouse) orelse return null };
+}
+
+/// Subscribe to joystick/gamepad events only; `next` returns decoded `JoystickEvent`s.
+pub fn subscribeJoystick() ?JoystickSubscriber {
+    return .{ .inner = subscribe(device_joystick) orelse return null };
+}
+
+// --- publishing -------------------------------------------------------------
+
+/// A connection to the input service for a source (a keyboard/mouse/joystick driver) that
+/// publishes events. Each `publish*Event` is a short synchronous call the service answers
+/// at once; its own fan-out to subscribers is asynchronous, so publishing never blocks on
+/// a slow subscriber.
+pub const Publisher = struct {
+    service: ipc.Handle,
+
+    fn publish(self: Publisher, event: InputEvent) bool {
+        var request = protocol.Request{ .operation = @intFromEnum(protocol.Operation.publish), .event = event };
+        var reply: [protocol.reply_size]u8 = undefined;
+        const len = ipc.call(self.service, std.mem.asBytes(&request), &reply) catch return false;
+        if (len < protocol.reply_size) return false;
+        return std.mem.bytesToValue(protocol.Reply, reply[0..protocol.reply_size]).status == 0;
+    }
+
+    /// Broadcast a keyboard event to every subscriber that took keyboard events.
+    pub fn publishKeyboardEvent(self: Publisher, event: KeyEvent) bool {
+        return self.publish(InputEvent.fromKeyboard(event));
+    }
+    /// Broadcast a mouse event to every subscriber that took mouse events.
+    pub fn publishMouseEvent(self: Publisher, event: MouseEvent) bool {
+        return self.publish(InputEvent.fromMouse(event));
+    }
+    /// Broadcast a joystick/gamepad event to every subscriber that took joystick events.
+    pub fn publishJoystickEvent(self: Publisher, event: JoystickEvent) bool {
+        return self.publish(InputEvent.fromJoystick(event));
+    }
+};
+
+/// Connect to the input service as an event source, waiting for it to come up. Returns a
+/// `Publisher`, or null if the service never registered.
+pub fn connectSource() ?Publisher {
+    return .{ .service = lookupService() orelse return null };
+}
+
+// --- synthetic scaffolding --------------------------------------------------
+
+/// Synthetic key events, shared by the demo source and the keyboard driver's placeholder
+/// stream while real scancode decoding is still a follow-up. `step` rolls through A..E,
+/// emitting for each key a `key_down`, then a `key_press` carrying the character, then a
+/// `key_up`. Scaffolding, not wire protocol — hence it lives with the helpers.
+pub fn syntheticKeyEvent(step: usize) KeyEvent {
+    const Key = struct { code: Keycode, character: u32 };
+    const keys = [_]Key{
+        .{ .code = .a, .character = 'A' },
+        .{ .code = .b, .character = 'B' },
+        .{ .code = .c, .character = 'C' },
+        .{ .code = .d, .character = 'D' },
+        .{ .code = .e, .character = 'E' },
+    };
+    const key = keys[(step / 3) % keys.len];
+    return switch (step % 3) {
+        0 => .{ .kind = @intFromEnum(EventKind.key_down), .keycode = @intFromEnum(key.code), .character = 0, .modifiers = 0 },
+        1 => .{ .kind = @intFromEnum(EventKind.key_press), .keycode = @intFromEnum(key.code), .character = key.character, .modifiers = 0 },
+        else => .{ .kind = @intFromEnum(EventKind.key_up), .keycode = @intFromEnum(key.code), .character = 0, .modifiers = 0 },
+    };
+}
+
+/// Synthetic mouse events (placeholder until real PS/2 packet decoding). `step` alternates
+/// a small diagonal motion with a left-button click.
+pub fn syntheticMouseEvent(step: usize) MouseEvent {
+    return switch (step % 3) {
+        0 => .{ .kind = @intFromEnum(MouseEventKind.motion), .button = 0, .dx = 1, .dy = 1, .scroll_x = 0, .scroll_y = 0, .buttons = 0 },
+        1 => .{ .kind = @intFromEnum(MouseEventKind.button_down), .button = protocol.mouse_button_left, .dx = 0, .dy = 0, .scroll_x = 0, .scroll_y = 0, .buttons = protocol.mouse_button_left },
+        else => .{ .kind = @intFromEnum(MouseEventKind.button_up), .button = protocol.mouse_button_left, .dx = 0, .dy = 0, .scroll_x = 0, .scroll_y = 0, .buttons = 0 },
+    };
+}
+
+/// Synthetic joystick/gamepad events (placeholder until a real controller driver). `step`
+/// sweeps axis 0 and toggles button 0.
+pub fn syntheticJoystickEvent(step: usize) JoystickEvent {
+    return switch (step % 3) {
+        0 => .{ .kind = @intFromEnum(JoystickEventKind.axis), .control = 0, .value = 16384, .buttons = 0 },
+        1 => .{ .kind = @intFromEnum(JoystickEventKind.button_down), .control = 0, .value = 0, .buttons = 1 },
+        else => .{ .kind = @intFromEnum(JoystickEventKind.button_up), .control = 0, .value = 0, .buttons = 0 },
+    };
+}

library/runtime/ipc.zig

@@ -79,11 +79,41 @@ pub fn call(h: Handle, message: []const u8, reply: []u8) CallError!usize {
     return (try callCap(h, message, reply, null)).len;
 }
 
+/// Post `message` to endpoint `h`'s asynchronous queue and return immediately — no
+/// rendezvous, no reply, no blocking. The receiver picks it up through `replyWait` as a
+/// buffered message (`Received.isMessage`). Unlike `call`, this **cannot hang on a dead
+/// or slow peer**, which is why a broadcaster (the input service) delivers events this
+/// way. The payload must fit an endpoint slot (64 bytes); a full queue drops the oldest
+/// message. Returns false on failure (bad handle, oversized payload, bad buffer).
+pub fn send(h: Handle, message: []const u8) bool {
+    return !failed(sc.systemCall3(.ipc_send, h, @intFromPtr(message.ptr), message.len));
+}
+
 /// Set in `Received.badge` when what arrived is an asynchronous notification — a
 /// bound device interrupt — rather than a client's message. The low bits carry the
 /// GSI. See `isNotification`.
 pub const notify_badge_bit: u64 = abi.notify_badge_bit;
 
+/// Set alongside `notify_badge_bit` when the notification is a **signal** — the
+/// lifecycle vocabulary of docs/process-lifecycle.md, delivered to the endpoint
+/// nominated with `process.bindSignals`. Decode with `process.signalsFrom`.
+pub const notify_signal_bit: u64 = abi.notify_signal_bit;
+
+/// Set alongside `notify_badge_bit` when the notification is a **one-shot timer**
+/// landing (`system.timerOnce`).
+pub const notify_timer_bit: u64 = abi.notify_timer_bit;
+
+/// Set alongside `notify_badge_bit` when the notification is a **child-exit
+/// notice** — a process this one spawned (with an exit endpoint) has ended —
+/// rather than a device interrupt. The low bits carry the child's process id.
+pub const notify_exit_bit: u64 = abi.notify_exit_bit;
+
+/// Set alongside `notify_badge_bit` when the wake-up is a **buffered message** — a payload
+/// posted with `send` (`ipc_send`) — rather than a bare device interrupt or child-exit
+/// notice. The payload is in the `replyWait` receive buffer (`Received.len` bytes); the
+/// low bits of the badge carry the sender's task id. See `Received.isMessage`.
+pub const notify_message_bit: u64 = abi.notify_message_bit;
+
 /// The result of a `replyWait`: the request length, the sender's badge (a task id, or
 /// an IRQ notification if the high bit is set), and any capability the request carried.
 pub const Received = struct {
@@ -91,16 +121,53 @@ pub const Received = struct {
     badge: u64,
     cap: ?Handle,
 
-    /// True if this wake-up was a device interrupt, not a client request. A driver's
-    /// event loop branches on this; there is no reply owed on the notification path.
+    /// True if this wake-up was an asynchronous notification (a device interrupt
+    /// or a child-exit notice), not a client request. An event loop branches on
+    /// this; there is no reply owed on the notification path.
     pub fn isNotification(self: Received) bool {
         return self.badge & notify_badge_bit != 0;
     }
 
-    /// The interrupt source (a GSI), meaningful only when `isNotification`.
+    /// True if this wake-up tells of a supervised child's end — the notification
+    /// requested by passing an exit endpoint to `system.spawnSupervised`.
+    pub fn isChildExit(self: Received) bool {
+        return self.isNotification() and self.badge & notify_exit_bit != 0;
+    }
+
+    /// True if this wake-up is a **buffered message** posted with `send` (`ipc_send`):
+    /// there is a payload in the receive buffer (`self.len` bytes) and no reply is owed.
+    /// The subscriber side of a broadcast branches on this.
+    pub fn isMessage(self: Received) bool {
+        return self.isNotification() and self.badge & notify_message_bit != 0;
+    }
+
+    /// The task id of whoever posted a buffered message, meaningful only when
+    /// Whether this arrival is a signal notification — decode the set with
+    /// `process.signalsFrom(badge)`.
+    pub fn isSignal(self: Received) bool {
+        return self.isNotification() and self.badge & notify_signal_bit != 0;
+    }
+
+    /// Whether this arrival is a one-shot timer landing (`system.timerOnce`).
+    pub fn isTimer(self: Received) bool {
+        return self.isNotification() and self.badge & notify_timer_bit != 0;
+    }
+
+    /// `isMessage`. (The badge's low bits, with the three high marker bits masked off.)
+    pub fn senderTaskId(self: Received) u32 {
+        return @intCast(self.badge & ~(notify_badge_bit | notify_exit_bit | notify_message_bit));
+    }
+
+    /// The interrupt source (a GSI), meaningful only when `isNotification` and
+    /// not `isChildExit`.
     pub fn source(self: Received) u64 {
         return self.badge & ~notify_badge_bit;
     }
+
+    /// The ended child's process id, meaningful only when `isChildExit`.
+    pub fn childProcessId(self: Received) u32 {
+        return @intCast(self.badge & ~(notify_badge_bit | notify_exit_bit));
+    }
 };
 
 /// Server side of IPC_ReplyWait: deliver `reply` to the client last received (if any,

library/runtime/process.zig

@@ -0,0 +1,137 @@
+//! Process-level runtime types: what a user program receives at entry (`Init`,
+//! the argv contract) and the process end of the lifecycle
+//! (docs/process-lifecycle.md) — today the exit reason a supervisor reads to
+//! decide restart; signals and the stop sequence land here with M17.4. Mirrors
+//! the spirit of `std.process.Init.Minimal` in danos terms — std's `Args` holds
+//! no data on freestanding targets, so the type is danos's own.
+
+const std = @import("std");
+const abi = @import("abi");
+const sc = @import("system-call.zig");
+const ipc = @import("ipc.zig");
+const system = @import("system.zig");
+
+/// Everything a program receives at entry. Passed to
+/// `pub fn main(init: runtime.process.Init)`; programs that need nothing keep
+/// `pub fn main() void`. An `environment` field is added here once the kernel
+/// passes a non-empty envp (today it is always empty — see docs/sysv.md).
+pub const Init = struct {
+    arguments: Arguments,
+};
+
+/// The process arguments (argc/argv), parsed from the kernel-built System V
+/// entry block. The bytes live in the entry block at the top of the stack page,
+/// NUL-terminated, valid for the process's lifetime.
+pub const Arguments = struct {
+    /// argc — at least 1: argument 0 is the path or name this binary was
+    /// spawned as.
+    count: usize,
+    /// The argv pointers in the entry block (NULL-terminated after `count`
+    /// entries).
+    vector: [*]const [*:0]const u8,
+
+    /// Argument `index` (0 = the program's own path/name), or null if out of
+    /// range.
+    pub fn get(arguments: Arguments, index: usize) ?[:0]const u8 {
+        if (index >= arguments.count) return null;
+        return std.mem.span(arguments.vector[index]);
+    }
+
+    pub fn iterate(arguments: Arguments) Iterator {
+        return .{ .arguments = arguments };
+    }
+
+    pub const Iterator = struct {
+        arguments: Arguments,
+        index: usize = 0,
+
+        pub fn next(iterator: *Iterator) ?[:0]const u8 {
+            const argument = iterator.arguments.get(iterator.index) orelse return null;
+            iterator.index += 1;
+            return argument;
+        }
+    };
+};
+
+/// How a process ended — what a supervisor's restart policy reads: a clean exit
+/// meant to stop, a fault wants a restart with backoff, killed means the
+/// supervisor did it itself (docs/process-lifecycle.md).
+pub const ExitReason = abi.ExitReason;
+
+/// How dead child `id` ended. Ask after the exit notification arrives — the
+/// kernel records the reason before it posts the notification, so this never
+/// races it. Returns null for an id that never lived, is still alive, was
+/// evicted from the kernel's bounded record, or is not this process's child
+/// (the same authority gate as `kill`).
+pub fn exitReason(id: u32) ?ExitReason {
+    const r = sc.systemCall1(.process_exit_reason, id);
+    if (r > ~@as(usize, 0) - 4095) return null; // a wrapped -errno
+    return @enumFromInt(r);
+}
+
+/// The signal vocabulary (docs/process-lifecycle.md): POSIX's concepts, danos's
+/// names, message delivery. A signal is a one-way coalescing statement — never a
+/// question (liveness is the zero-length ping call) and never kill (that is
+/// `system.kill`, unhandleable by definition).
+pub const Signal = abi.Signal;
+
+/// The coalesced set of signals one notification delivered: two pending
+/// terminates arrive as one. Decode a received badge with `signalsFrom`.
+pub const SignalSet = struct {
+    pending: u32,
+
+    pub fn has(set: SignalSet, signal: Signal) bool {
+        return set.pending & (@as(u32, 1) << @intFromEnum(signal)) != 0;
+    }
+};
+
+/// Nominate `endpoint` as this process's signal endpoint. Signals posted while
+/// unbound have pended; they are delivered immediately on bind, coalesced.
+pub fn bindSignals(endpoint: usize) bool {
+    return sc.systemCall1(.signal_bind, endpoint) == 0;
+}
+
+/// Decode a received badge into the signals it delivered, or null if it is not
+/// a signal notification.
+pub fn signalsFrom(badge: u64) ?SignalSet {
+    if (badge & abi.notify_badge_bit == 0 or badge & abi.notify_signal_bit == 0) return null;
+    return .{ .pending = @truncate(badge & ~(abi.notify_badge_bit | abi.notify_signal_bit)) };
+}
+
+/// Post `signal` to child `id` (or to yourself). Supervisor-gated, like kill;
+/// non-blocking, always — a statement, not a conversation.
+pub fn sendSignal(id: u32, signal: Signal) bool {
+    return sc.systemCall2(.process_signal, id, @intFromEnum(signal)) == 0;
+}
+
+/// The standard stop sequence (docs/process-lifecycle.md): terminate, wait up to
+/// `deadline_ms` for the exit notification on `exit_endpoint` (the endpoint the
+/// child was spawned with), then kill. Any *other* notifications arriving on
+/// that endpoint while stopping are consumed and dropped — a supervisor with
+/// concurrent traffic implements the same sequence inside its own event loop
+/// (arm `system.timerOnce`, keep serving) instead of calling this.
+pub fn stop(id: u32, deadline_ms: u64, exit_endpoint: usize) void {
+    _ = sendSignal(id, .terminate);
+    _ = system.timerOnce(exit_endpoint, deadline_ms);
+    var receive: [8]u8 = undefined;
+    while (true) {
+        const got = ipc.replyWait(exit_endpoint, &.{}, &receive, null);
+        if (got.isChildExit() and got.childProcessId() == id) return;
+        if (got.isTimer()) break; // the deadline passed first — escalate
+    }
+    _ = system.kill(id);
+    while (true) {
+        const got = ipc.replyWait(exit_endpoint, &.{}, &receive, null);
+        if (got.isChildExit() and got.childProcessId() == id) return;
+    }
+}
+
+/// Subscribe `endpoint` to published exit events: every process death posts an
+/// asynchronous notification with the same badge encoding as a supervisor's exit
+/// notice (decode with `ipc.Received.isChildExit`/`childProcessId`). For stateful
+/// services: release what the dead client held — file handles, subscriptions —
+/// because a service must never depend on clients cleaning up after themselves
+/// (docs/process-lifecycle.md). Ungated, like `system.processes`.
+pub fn subscribeExits(endpoint: usize) bool {
+    return sc.systemCall1(.process_subscribe, endpoint) == 0;
+}

library/runtime/root.zig

@@ -0,0 +1,19 @@
+//! The root module every user binary is compiled through (build.zig,
+//! `addUserBinary`). The program's own file is imported as `program`, and this
+//! shim contributes the declarations Zig resolves from the compilation root —
+//! `main` (dispatched by runtime.start) and the panic handler — and pulls in the
+//! `_start` entry shim. A program therefore only defines `pub fn main`; nothing
+//! else is required in its source file.
+
+const runtime = @import("runtime");
+const program = @import("program");
+
+/// Resolved as `@import("root").main` by runtime.start's comptime dispatch.
+pub const main = program.main;
+
+/// The panic handler for every safety check in the image (runtime.start.panic).
+pub const panic = runtime.panic;
+
+comptime {
+    _ = &runtime.start._start; // pull the runtime entry shim into the image
+}

library/runtime/runtime.zig

@@ -4,18 +4,32 @@
 //! shim. It is compiled into each binary (inheriting its `.large` code model and
 //! freestanding target), so all user programs share one implementation.
 //!
-//! A user binary needs three lines:
-//!   const runtime = @import("runtime");
-//!   pub const panic = runtime.panic;
-//!   comptime { _ = &runtime.start._start; }   // pull the entry shim in
-//! and a `pub fn main() void`.
+//! A user binary only defines a `pub fn main() void` or
+//! `pub fn main(init: runtime.process.Init) void` (arguments arrive via `init`).
+//! The panic handler and the `_start` entry pull live in the shared compilation
+//! root, library/runtime/root.zig, which build.zig wires around every program —
+//! nothing to declare per source file.
 
 pub const system = @import("system.zig");
+/// Monotonic time, delays, and deadlines over the kernel clock/sleep/timer syscalls
+/// — an `Instant`/`Duration` front door, no time service (docs/timers.md).
+pub const time = @import("time.zig");
 pub const heap = @import("heap.zig");
 pub const ipc = @import("ipc.zig");
 pub const start = @import("start.zig");
 /// The VFS wire protocol (shared with the VFS server).
 pub const vfs_protocol = @import("vfs-protocol");
+
+/// The device-manager protocol: hello + tree reports (docs/device-manager.md).
+pub const device_manager_protocol = @import("device-manager-protocol");
+
+/// The power protocol: events (button, lid, battery) + shutdown (docs/power.md).
+pub const power_protocol = @import("power-protocol");
+/// Keyboard-event listening (subscribe/next) and broadcasting (publish), over the input
+/// service. See library/runtime/input.zig and system/services/input/.
+pub const input = @import("input.zig");
+/// The input wire protocol (shared with the input service and its clients).
+pub const input_protocol = @import("input-protocol");
 /// POSIX-style file API: open/read/write/lseek/stat/close.
 /// C stdio: fopen/fread/fwrite/fseek/ftell/fclose over unistd.
 /// Device access for drivers: enumerate/claim/mmioMap.
@@ -23,13 +37,46 @@ pub const device = @import("device.zig");
 /// DMA-capable memory for drivers: contiguous, pinned, uncacheable buffers.
 pub const dma = @import("dma.zig");
 
-/// Re-exported so a user binary can `pub const panic = runtime.panic;`.
+/// Shared cacheable memory: create a region + capability, pass the capability to another
+/// process (an `ipc_call` send_cap), map the same pages there. See library/runtime/shm.zig
+/// and docs/display-v2.md.
+pub const shm = @import("shm.zig");
+
+/// USB class-driver client: open a device on the xHCI bus and drive it
+/// (control / interrupt / bulk transfers). See library/runtime/usb.zig.
+pub const usb = @import("usb.zig");
+
+/// Block-device client: read/write a block device (a USB stick, via
+/// usb-storage). See library/runtime/block.zig.
+pub const block = @import("block.zig");
+
+/// Display-service client: query the mode, and (from D3) create layers, draw, and
+/// present frames. See library/runtime/display.zig and system/services/display/.
+pub const display = @import("display.zig");
+/// The display wire protocol (shared with the display service and its clients).
+pub const display_protocol = @import("display-protocol");
+/// The scanout wire protocol: the compositor's present channel to a native scanout driver
+/// (virtio-gpu). See system/services/display/scanout-protocol.zig and docs/display-v2.md.
+pub const scanout_protocol = @import("scanout-protocol");
+
+/// The danos-native file API (open/read/write/list over the user-space VFS) — the
+/// layer danos programs use directly, and where the operations that later become
+/// `std.os.danos` are staged. See docs/zig-self-hosting.md.
+pub const fs = @import("fs.zig");
+
+/// Re-exported so the root shim (root.zig) can install it as the panic handler.
 pub const panic = start.panic;
 
-/// Process arguments (argc/argv, parsed from the kernel-built entry stack):
-/// `argument(0)` is the path or name this binary was spawned as.
-pub const argumentCount = start.argumentCount;
-pub const argument = start.argument;
+/// Process entry types: the `Init` handed to `main`, and its `Arguments`.
+pub const process = @import("process.zig");
+
+/// Threads: `runtime.Thread`, std.Thread-shaped, over the private thread ABI
+/// (docs/threading.md). A binary must be built multi-threaded to spawn.
+pub const Thread = @import("thread.zig").Thread;
+
+/// The service harness: one replyWait loop folding requests, signals, and
+/// notifications into callbacks (docs/process-lifecycle.md).
+pub const service = @import("service.zig");
 
 /// The heap as a `std.mem.Allocator`, for Zig `std` containers in user code.
 pub const allocator = heap.allocator;

library/runtime/service.zig

@@ -0,0 +1,83 @@
+//! The service harness (docs/process-lifecycle.md): one replyWait loop that
+//! folds protocol requests, signals, and subscribed notifications into
+//! callbacks — so the lifecycle contract ("answers ping, exits on terminate")
+//! is satisfied by construction and a service author writes domain logic only.
+//! Nothing is asynchronous inside the process: a callback runs at a point the
+//! loop chose, never on a hijacked stack — the whole reason signals are
+//! messages.
+//!
+//! The liveness probe: a **zero-length request is the universal ping**, answered
+//! with a zero-length reply by the harness itself. No protocol's requests start
+//! at length zero, so the encoding cannot collide, and there is nothing for a
+//! service author to implement — a wedged service simply fails to answer, which
+//! is the diagnosis (see docs/ipc.md).
+
+const abi = @import("abi");
+const ipc = @import("ipc.zig");
+const process = @import("process.zig");
+
+pub const Callbacks = struct {
+    /// Called once with the service's endpoint before the loop starts — the
+    /// place to subscribe to exit events, bind IRQs, or announce readiness.
+    /// Return false to abort startup (the process exits).
+    init: ?*const fn (endpoint: ipc.Handle) bool = null,
+    /// One protocol request from `sender` (a task id): write the reply into
+    /// `reply`, return its length. `capability` is the handle the request
+    /// carried, if any (M13 cap passing — how a subscriber hands over its
+    /// endpoint). The zero-length ping never reaches this.
+    on_message: *const fn (message: []const u8, reply: []u8, sender: u32, capability: ?ipc.Handle) usize,
+    /// A notification that is not a signal — a subscribed exit event, a bound
+    /// IRQ, a timer landing. The raw badge; decode with the ipc helpers.
+    on_notification: ?*const fn (badge: u64) void = null,
+    /// The reload signal. Default: ignored.
+    on_reload: ?*const fn () void = null,
+    /// The terminate signal, called before the loop returns. The clean exit is
+    /// the return itself — never put *necessary* work here (iron rule 1: a kill
+    /// arrives with no warning; this is for graceful extras only).
+    on_terminate: ?*const fn () void = null,
+    /// Publish the endpoint under a well-known service id at startup.
+    service: ?abi.ServiceId = null,
+};
+
+/// Run the service: create and (optionally) register the endpoint, bind signals
+/// to it, call `init`, then serve until `terminate` arrives — at which point the
+/// loop returns and main's return is the clean exit the supervisor reads as
+/// `ExitReason.exited`. `maximum_message` sizes the receive and reply buffers
+/// (a service passes its protocol's message maximum).
+pub fn run(comptime maximum_message: usize, callbacks: Callbacks) void {
+    const endpoint = ipc.createIpcEndpoint() orelse return;
+    if (callbacks.service) |id| {
+        if (!ipc.register(id, endpoint)) return;
+    }
+    _ = process.bindSignals(endpoint);
+    if (callbacks.init) |initialise| {
+        if (!initialise(endpoint)) return;
+    }
+
+    var reply_buffer: [maximum_message]u8 = undefined;
+    var reply_len: usize = 0;
+    var receive: [maximum_message]u8 = undefined;
+    while (true) {
+        const got = ipc.replyWait(endpoint, reply_buffer[0..reply_len], &receive, null);
+        if (got.isNotification()) {
+            reply_len = 0; // nothing owed for a notification
+            if (process.signalsFrom(got.badge)) |signals| {
+                if (signals.has(.reload)) {
+                    if (callbacks.on_reload) |onReload| onReload();
+                }
+                if (signals.has(.terminate)) {
+                    if (callbacks.on_terminate) |onTerminate| onTerminate();
+                    return; // the loop's return IS the clean exit
+                }
+                continue;
+            }
+            if (callbacks.on_notification) |onNotification| onNotification(got.badge);
+            continue;
+        }
+        if (got.len == 0) {
+            reply_len = 0; // the universal ping: a zero-length reply, from the harness
+            continue;
+        }
+        reply_len = callbacks.on_message(receive[0..got.len], &reply_buffer, got.senderTaskId(), got.cap);
+    }
+}

library/runtime/shm.zig

@@ -0,0 +1,57 @@
+//! User-space shared memory: `shm_create` / `shm_map`. A process creates a shareable,
+//! zeroed, cacheable RAM region and gets back a pointer plus a **capability handle**; it
+//! passes that handle to another process as an `ipc_call` send_cap, and the receiver
+//! `shm_map`s it to map the same physical pages. The kernel primitive under the display
+//! compositor↔native-driver and app↔compositor surface paths (docs/display-v2.md). The
+//! generalization of capability passing from endpoints to memory objects.
+
+const abi = @import("abi");
+const sc = @import("system-call.zig");
+const ipc = @import("ipc.zig");
+
+inline fn failed(r: usize) bool {
+    return r > ~@as(usize, 0) - 4095; // a wrapped -errno lands in the top page
+}
+
+/// A shared region: the `ptr` the CPU touches, and the `handle` (a capability) to hand to
+/// another process as an `ipc_call` send_cap.
+pub const Region = struct {
+    ptr: [*]u8,
+    handle: ipc.Handle,
+    len: usize,
+};
+
+/// Grant `len` bytes (rounded up to whole pages) of shareable, zeroed, cacheable RAM.
+/// Returns the region or null on failure. Two return values — virtual_address in rax, handle in rdx —
+/// so this is a hand-written stub like `dma.alloc`.
+pub fn create(len: usize) ?Region {
+    var rax: usize = undefined;
+    var rdx: usize = undefined; // out: the capability handle
+    asm volatile ("syscall"
+        : [rax] "={rax}" (rax),
+          [rdx] "={rdx}" (rdx),
+        : [n] "{rax}" (@intFromEnum(abi.SystemCall.shm_create)),
+          [a0] "{rdi}" (len),
+        : .{ .rcx = true, .r11 = true, .memory = true });
+    if (failed(rax)) return null;
+    return .{ .ptr = @ptrFromInt(rax), .handle = rdx, .len = len };
+}
+
+/// Map the shared region named by a capability `handle` this process received (via an
+/// `ipc_call` send_cap) into its address space — the same physical pages the creator sees.
+/// Returns the pointer, or null on failure.
+pub fn map(handle: ipc.Handle) ?[*]u8 {
+    const r = sc.systemCall1(.shm_map, handle);
+    if (failed(r)) return null;
+    return @ptrFromInt(r);
+}
+
+/// The guest-physical base of the shared region named by `handle` (which this process must
+/// hold a capability for). The region's frames are contiguous, so this single address plus
+/// the region length is all a device needs — e.g. a virtio-gpu driver programming an
+/// `attach_backing`. Returns null on failure.
+pub fn physical(handle: ipc.Handle) ?usize {
+    const r = sc.systemCall1(.shm_physical, handle);
+    if (failed(r)) return null;
+    return r;
+}

library/runtime/start.zig

@@ -1,9 +1,11 @@
 //! The user-space process entry shim. Every user binary roots `_start` here (via
-//! `entry = _start` in build.zig) and forces this file to be analysed with
-//! `comptime { _ = &runtime.start._start; }`, so the whole runtime is linked in.
+//! `entry = _start` in build.zig); the shared compilation root, root.zig, forces
+//! this file to be analysed with `comptime { _ = &runtime.start._start; }`, so
+//! the whole runtime is linked in.
 
 const std = @import("std");
 const system = @import("system.zig");
+const process = @import("process.zig");
 
 /// The kernel enters at `_start` with rsp 16-aligned, pointing at the System V
 /// process-entry block it built: argc, argv pointers, NULL, envp terminator, the
@@ -20,35 +22,61 @@ pub export fn _start() callconv(.naked) noreturn {
     );
 }
 
-// The process-entry block, recorded by `rt_start` for the accessors below.
-var argument_count: usize = 0;
-var argument_vector: [*]const u64 = undefined;
-
 /// The first Zig frame, entered with `stack` pointing at the kernel-built entry
-/// block. Record argc/argv for the accessors, then hand control to the program's
-/// `main`. The heap is lazy (first alloc grows it), so there is no other runtime
-/// init to order here.
+/// block. Build the `process.Init` from it and dispatch to the program's `main`,
+/// whose signature is inspected at comptime. The heap is lazy (first alloc grows
+/// it), so there is no other runtime init to order here.
 export fn rt_start(stack: [*]const u64) callconv(.c) noreturn {
-    argument_count = stack[0];
-    argument_vector = stack + 1;
-    const root = @import("root"); // the user binary's root source file
-    root.main();
-    system.exit(0);
+    const init: process.Init = .{ .arguments = .{
+        .count = stack[0],
+        .vector = @ptrCast(stack + 1),
+    } };
+    system.exit(callMain(init));
 }
 
-/// Number of process arguments (argc). At least 1: argument 0 is the path or
-/// name this binary was spawned as.
-pub fn argumentCount() usize {
-    return argument_count;
-}
+/// Comptime-dispatch on root.main's signature, in the spirit of std's start.zig:
+/// zero parameters or one `process.Init`; returns void, noreturn, u8, !void, or !u8.
+fn callMain(init: process.Init) u8 {
+    const root = @import("root"); // root.zig, re-exporting the program's main
+    const main_information = @typeInfo(@TypeOf(root.main)).@"fn";
 
-/// Process argument `index` (0 = the program's own path/name), or an empty slice
-/// if out of range. The bytes live in the entry block at the top of the stack
-/// page, NUL-terminated, valid for the process's lifetime.
-pub fn argument(index: usize) []const u8 {
-    if (index >= argument_count) return "";
-    const string: [*:0]const u8 = @ptrFromInt(argument_vector[index]);
-    return std.mem.span(string);
+    const call_arguments = switch (main_information.params.len) {
+        0 => .{},
+        1 => arguments: {
+            const Parameter = main_information.params[0].type orelse
+                @compileError("main's parameter must be runtime.process.Init (not anytype)");
+            if (Parameter != process.Init)
+                @compileError("main's parameter must be runtime.process.Init, found " ++ @typeName(Parameter));
+            break :arguments .{init};
+        },
+        else => @compileError("main takes no parameters or a single runtime.process.Init"),
+    };
+
+    const ReturnType = main_information.return_type.?;
+    switch (@typeInfo(ReturnType)) {
+        .noreturn => @call(.auto, root.main, call_arguments),
+        .void => {
+            @call(.auto, root.main, call_arguments);
+            return 0;
+        },
+        .int => {
+            if (ReturnType != u8)
+                @compileError("main's integer return type must be u8, found " ++ @typeName(ReturnType));
+            return @call(.auto, root.main, call_arguments);
+        },
+        .error_union => {
+            const payload = @call(.auto, root.main, call_arguments) catch |err| {
+                var buffer: [128]u8 = undefined;
+                const line = std.fmt.bufPrint(&buffer, "main returned error: {s}\n", .{@errorName(err)}) catch "main returned an error\n";
+                _ = system.write(line);
+                return 1; // distinct from panic's 127
+            };
+            if (@TypeOf(payload) == void) return 0;
+            if (@TypeOf(payload) == u8) return payload;
+            @compileError("main's error-union payload must be void or u8, found " ++ @typeName(@TypeOf(payload)));
+        },
+        else => @compileError("main must return void, noreturn, u8, !void, or !u8, found " ++ @typeName(ReturnType)),
+    }
 }
 
 /// No runtime to unwind into — report a panic as a nonzero exit code.

library/runtime/system-call.zig

@@ -19,34 +19,49 @@ pub inline fn systemCall0(n: SystemCall) usize {
 pub inline fn systemCall1(n: SystemCall, a0: usize) usize {
     return asm volatile ("syscall"
         : [ret] "={rax}" (-> usize),
-        : [n] "{rax}" (@intFromEnum(n)), [a0] "{rdi}" (a0),
+        : [n] "{rax}" (@intFromEnum(n)),
+          [a0] "{rdi}" (a0),
         : .{ .rcx = true, .r11 = true, .memory = true });
 }
 
 pub inline fn systemCall2(n: SystemCall, a0: usize, a1: usize) usize {
     return asm volatile ("syscall"
         : [ret] "={rax}" (-> usize),
-        : [n] "{rax}" (@intFromEnum(n)), [a0] "{rdi}" (a0), [a1] "{rsi}" (a1),
+        : [n] "{rax}" (@intFromEnum(n)),
+          [a0] "{rdi}" (a0),
+          [a1] "{rsi}" (a1),
         : .{ .rcx = true, .r11 = true, .memory = true });
 }
 
 pub inline fn systemCall3(n: SystemCall, a0: usize, a1: usize, a2: usize) usize {
     return asm volatile ("syscall"
         : [ret] "={rax}" (-> usize),
-        : [n] "{rax}" (@intFromEnum(n)), [a0] "{rdi}" (a0), [a1] "{rsi}" (a1), [a2] "{rdx}" (a2),
+        : [n] "{rax}" (@intFromEnum(n)),
+          [a0] "{rdi}" (a0),
+          [a1] "{rsi}" (a1),
+          [a2] "{rdx}" (a2),
         : .{ .rcx = true, .r11 = true, .memory = true });
 }
 
 pub inline fn systemCall4(n: SystemCall, a0: usize, a1: usize, a2: usize, a3: usize) usize {
     return asm volatile ("syscall"
         : [ret] "={rax}" (-> usize),
-        : [n] "{rax}" (@intFromEnum(n)), [a0] "{rdi}" (a0), [a1] "{rsi}" (a1), [a2] "{rdx}" (a2), [a3] "{r10}" (a3),
+        : [n] "{rax}" (@intFromEnum(n)),
+          [a0] "{rdi}" (a0),
+          [a1] "{rsi}" (a1),
+          [a2] "{rdx}" (a2),
+          [a3] "{r10}" (a3),
         : .{ .rcx = true, .r11 = true, .memory = true });
 }
 
 pub inline fn systemCall5(n: SystemCall, a0: usize, a1: usize, a2: usize, a3: usize, a4: usize) usize {
     return asm volatile ("syscall"
         : [ret] "={rax}" (-> usize),
-        : [n] "{rax}" (@intFromEnum(n)), [a0] "{rdi}" (a0), [a1] "{rsi}" (a1), [a2] "{rdx}" (a2), [a3] "{r10}" (a3), [a4] "{r8}" (a4),
+        : [n] "{rax}" (@intFromEnum(n)),
+          [a0] "{rdi}" (a0),
+          [a1] "{rsi}" (a1),
+          [a2] "{rdx}" (a2),
+          [a3] "{r10}" (a3),
+          [a4] "{r8}" (a4),
         : .{ .rcx = true, .r11 = true, .memory = true });
 }

library/runtime/system.zig

@@ -2,6 +2,7 @@
 //! stubs, one per kernel call. Numbers come from `abi.SystemCall`, the single
 //! source of truth shared with the kernel dispatcher.
 
+const std = @import("std");
 const abi = @import("abi");
 const sc = @import("system-call.zig");
 
@@ -11,6 +12,10 @@ pub const PROT_READ: usize = abi.prot_read;
 pub const PROT_WRITE: usize = abi.prot_write;
 pub const PROT_EXEC: usize = abi.prot_exec;
 
+/// One `processes` entry — re-exported from the shared ABI so a user program can
+/// declare its snapshot buffer without importing `abi` itself.
+pub const ProcessDescriptor = abi.ProcessDescriptor;
+
 /// Give up the rest of this quantum.
 pub fn yield() void {
     _ = sc.systemCall0(.yield);
@@ -27,6 +32,15 @@ pub fn sleep(ms: usize) void {
     _ = sc.systemCall1(.sleep, ms);
 }
 
+/// Arm a one-shot timer: after `ms` milliseconds the kernel posts a timer
+/// notification (`ipc.Received.isTimer`) to `endpoint`. The timed wait of
+/// docs/process-lifecycle.md — a service arms a deadline and keeps serving,
+/// instead of blocking in sleep; what stop-sequence escalation, hello deadlines,
+/// and restart backoff are built from.
+pub fn timerOnce(endpoint: usize, ms: u64) bool {
+    return sc.systemCall2(.timer_bind, endpoint, ms) == 0;
+}
+
 /// Monotonic nanoseconds since boot — a time source for timeouts and short delays. It
 /// only ever moves forward. This is *not* wall-clock time (no date, no timezone — that
 /// is a user-space service layered on top). Deadline pattern for a bounded poll loop:
@@ -37,6 +51,24 @@ pub fn clock() u64 {
     return @intCast(sc.systemCall0(.clock));
 }
 
+/// Wall-clock time in Unix epoch seconds (UTC) — the real date/time, from the RTC.
+/// Unlike `clock` (monotonic since boot), this tracks calendar time, so it is what a
+/// filesystem stamps as a file's modification time. Formatting it into a calendar
+/// date/timezone is user-space policy layered on top.
+pub fn wallClock() u64 {
+    return @intCast(sc.systemCall0(.wall_clock));
+}
+
+/// Copy bytes out of the kernel's in-memory diagnostic log — the accumulated
+/// stream of everything `write` (and the kernel itself) has emitted — starting at
+/// `offset`, into `out`. Returns the number of bytes copied (0 at end of buffer).
+/// A program reads the whole log by looping from offset 0, advancing by the return
+/// value, until it gets 0. This is how the boot log is persisted to disk on a
+/// headless/real machine where serial output is otherwise lost.
+pub fn klogRead(offset: usize, out: []u8) usize {
+    return sc.systemCall3(.klog_read, offset, @intFromPtr(out.ptr), out.len);
+}
+
 /// End the process. Never returns.
 pub fn exit(code: usize) noreturn {
     _ = sc.systemCall1(.exit, code);
@@ -44,31 +76,74 @@ pub fn exit(code: usize) noreturn {
 }
 
 /// Start the binary bundled in the initial-ramdisk under `name` as a new ring-3
-/// process, returning true on success. The child's argv[0] is `name`. This is how
-/// a supervisor (the device manager) launches a driver it matched — danos-native,
-/// not POSIX (a spawn/exec family comes with the process work later).
-pub fn spawn(name: []const u8) bool {
-    return sc.systemCall4(.system_spawn, @intFromPtr(name.ptr), name.len, 0, 0) == 0;
+/// process, returning the child's process id (or null on failure). The child's
+/// argv[0] is `name`, and the caller becomes its **supervisor** — the only process
+/// allowed to `kill` it. This is how a supervisor (the device manager) launches a
+/// driver it matched — danos-native, not POSIX (a spawn/exec family comes with the
+/// POSIX layer later).
+pub fn spawn(name: []const u8) ?u32 {
+    return spawnSupervised(name, &.{}, null);
 }
 
 /// Like `spawn`, but hands the child command-line arguments: they arrive as
-/// argv[1..] on its System V entry stack (argv[0] is still `name`). Marshalled to
-/// the kernel as one NUL-separated blob; the combined arguments must fit
-/// `blob` (the kernel caps the blob at 256 bytes and argc at 8 anyway).
-pub fn spawnWithArguments(name: []const u8, arguments: []const []const u8) bool {
+/// argv[1..] on its System V entry stack (argv[0] is still `name`).
+pub fn spawnWithArguments(name: []const u8, arguments: []const []const u8) ?u32 {
+    return spawnSupervised(name, arguments, null);
+}
+
+/// The full spawn: command-line arguments for the child, and an optional endpoint
+/// (a handle from `ipc.createIpcEndpoint`) the kernel notifies when the child ends
+/// — any way it ends: clean exit, fault, or `kill`. The notification arrives via
+/// `ipc.replyWait` as a badge with the child-exit bit set and the child's id in
+/// the low bits (`ipc.Received.isChildExit`/`childProcessId`), so one endpoint can
+/// supervise many children. Arguments are marshalled to the kernel as one
+/// NUL-separated blob; the combined arguments must fit `blob` (the kernel caps the
+/// blob at 256 bytes and argc at 8 anyway). Returns the child's process id, or
+/// null on failure.
+pub fn spawnSupervised(name: []const u8, arguments: []const []const u8, exit_endpoint: ?usize) ?u32 {
     var blob: [256]u8 = undefined;
     var len: usize = 0;
     for (arguments, 0..) |argument, i| {
         if (i != 0) {
-            if (len >= blob.len) return false;
+            if (len >= blob.len) return null;
             blob[len] = 0;
             len += 1;
         }
-        if (len + argument.len > blob.len) return false;
+        if (len + argument.len > blob.len) return null;
         @memcpy(blob[len..][0..argument.len], argument);
         len += argument.len;
     }
-    return sc.systemCall4(.system_spawn, @intFromPtr(name.ptr), name.len, @intFromPtr(&blob), len) == 0;
+    const r = sc.systemCall5(.system_spawn, @intFromPtr(name.ptr), name.len, if (len == 0) 0 else @intFromPtr(&blob), len, exit_endpoint orelse abi.no_cap);
+    if (r > ~@as(usize, 0) - 4095) return null; // a wrapped -errno
+    return @intCast(r);
+}
+
+/// Snapshot the process table into `out` (up to its length) and return the total
+/// number of live processes — which may exceed `out.len`; call again with a larger
+/// buffer for the full listing. Kernel tasks are included, with an empty name.
+/// The primitive `ps` is built on.
+pub fn processes(out: []abi.ProcessDescriptor) usize {
+    return sc.systemCall2(.process_enumerate, @intFromPtr(out.ptr), out.len);
+}
+
+/// Whether a process spawned under `name` (its argv[0]) is currently alive.
+pub fn isProcessRunning(name: []const u8) bool {
+    var table: [32]ProcessDescriptor = undefined;
+    const total = processes(&table);
+    for (table[0..@min(total, table.len)]) |descriptor| {
+        if (std.mem.eql(u8, descriptor.name[0..descriptor.name_length], name)) return true;
+    }
+    return false;
+}
+
+/// End process `id`. Only its supervisor — the process that spawned it — may;
+/// anyone else gets false, as does a stale or unknown id (ids are never reused).
+/// Delivery is prompt but asynchronous, like a signal: a target caught running on
+/// another core dies at its next system call or timer tick. True means the kill
+/// is accepted and irrevocable; the exit notification (if an endpoint was given
+/// at spawn) confirms completion.
+pub fn kill(id: u32) bool {
+    return sc.systemCall1(.process_kill, id) == 0;
 }
 
 /// Grant `len` bytes (rounded up to whole pages) of fresh, zeroed, writable

library/runtime/thread.zig

@@ -0,0 +1,484 @@
+//! `runtime.Thread` — threads for danos, shaped like Zig's `std.Thread` but built on
+//! danos's private thread ABI (docs/threading.md). Several tasks share one address
+//! space; `spawn` starts one, the kernel delivers the closure pointer in the new
+//! thread's rdi, a plain Zig trampoline runs the user function and calls `thread_exit`,
+//! and `join` blocks on the thread's exit notification. See docs/threading.md for why
+//! this mirrors `std.Thread`'s API rather than being the literal type.
+//!
+//! The closure (the function's captured args) lives at the **top of the thread's own
+//! stack**, not the heap — each thread's stack is private, so there is no shared-heap
+//! concurrency in the spawn/join machinery (the runtime heap is not yet thread-safe).
+//! A binary must be built multi-threaded (`addThreadedUserBinary`) before it may spawn.
+
+const std = @import("std");
+const builtin = @import("builtin");
+const abi = @import("abi");
+const sc = @import("system-call.zig");
+const system = @import("system.zig");
+
+/// True in a real danos binary; false when this module is compiled for host unit tests.
+/// The `Futex` seam and the test blocks below branch on it so the lock/condvar state
+/// machines can be exercised on the host against `std.Thread.Futex` (docs/threading-plan.md
+/// M11), while the danos build uses the futex syscalls.
+const on_danos = builtin.os.tag == .freestanding;
+
+/// A thread stack, if the caller does not override it. 64 KiB of mmap'd, zeroed pages.
+pub const default_stack_size: usize = 64 * 1024;
+
+/// Bytes reserved at the top of each thread's stack for its per-thread TLS block (the
+/// self-pointer plus scratch slots reachable via `%fs`). docs/threading-plan.md M10.
+const tls_block_size: usize = 64;
+
+pub const Thread = struct {
+    /// The kernel task id of the spawned thread — what `join` waits on.
+    tid: u32,
+    /// The mmap'd stack, reclaimed by `join` (or at process exit after `detach`).
+    stack_base: usize,
+    stack_size: usize,
+
+    pub const Id = u32;
+
+    pub const SpawnConfig = struct {
+        /// Bytes of stack, rounded up to whole pages by the kernel's mmap.
+        stack_size: usize = default_stack_size,
+    };
+
+    pub const SpawnError = error{
+        /// The kernel refused the thread, the stack mmap failed, or no endpoint was free.
+        SystemResources,
+    };
+
+    /// Start `function(args...)` on a new thread sharing this address space. Mirrors
+    /// `std.Thread.spawn`. The thread's return value is discarded (as in `std.Thread`);
+    /// return data through shared state.
+    pub fn spawn(config: SpawnConfig, comptime function: anytype, args: anytype) SpawnError!Thread {
+        const Args = @TypeOf(args);
+        const Closure = struct {
+            tls_base: usize,
+            args: Args,
+            /// Entered directly by the kernel with `self` in rdi (C ABI). Establishes this
+            /// thread's TLS pointer, runs the user function, then ends the thread.
+            fn entry(self_addr: usize) callconv(.c) noreturn {
+                const self: *@This() = @ptrFromInt(self_addr);
+                setThreadPointer(self.tls_base); // per-thread thread pointer before any user code
+                @call(.auto, function, self.args);
+                exitThread();
+            }
+        };
+
+        const base = system.mmap(config.stack_size, system.PROT_READ | system.PROT_WRITE);
+        if (system.mmapFailed(base)) return error.SystemResources;
+
+        // Top of the thread's own stack, downward: the closure, then a small per-thread TLS
+        // block (the thread pointer points here; slot 0 is the variant-II self-pointer, the rest is
+        // scratch for user TLS), then the stack proper (rsp starts below the TLS block, so
+        // the growing stack never overwrites either).
+        var closure_addr = (base + config.stack_size) - @sizeOf(Closure);
+        closure_addr &= ~@as(usize, @alignOf(Closure) - 1); // align the closure down
+
+        const tls_base = (closure_addr - tls_block_size) & ~@as(usize, 15);
+        const tls: [*]usize = @ptrFromInt(tls_base);
+        tls[0] = tls_base; // self-pointer (fs:0), as the x86_64 TLS ABI expects
+
+        const closure: *Closure = @ptrFromInt(closure_addr);
+        closure.* = .{ .tls_base = tls_base, .args = args };
+
+        var stack_top = tls_base & ~@as(usize, 15); // 16-align below the TLS block
+        stack_top -= 8; // ...then rsp % 16 == 8 at the C entry
+
+        const tid = threadSpawn(@intFromPtr(&Closure.entry), stack_top, closure_addr);
+        if (threadSpawnFailed(tid)) {
+            _ = system.munmap(base, config.stack_size);
+            return error.SystemResources;
+        }
+        return .{ .tid = @intCast(tid), .stack_base = base, .stack_size = config.stack_size };
+    }
+
+    /// Block until this thread finishes, then reclaim its stack. Mirrors
+    /// `std.Thread.join`. The exit endpoint is private to this thread, so the first
+    /// child-exit notification on it is this thread's.
+    pub fn join(self: Thread) void {
+        _ = sc.systemCall1(.thread_join, self.tid); // block until the thread has exited
+        _ = system.munmap(self.stack_base, self.stack_size); // reclaim its (now-vacated) stack
+    }
+
+    /// Relinquish the right to join: never wait for or reclaim this thread. Its stack is
+    /// reclaimed at process exit (docs/threading-plan.md M3 — kernel-reaper stack reclaim
+    /// for detached threads is a later refinement). Mirrors `std.Thread.detach`.
+    pub fn detach(self: Thread) void {
+        _ = self;
+    }
+
+    /// The calling thread's id (its kernel task id). Mirrors `std.Thread.getCurrentId`.
+    pub fn getCurrentId() Id {
+        return @intCast(sc.systemCall0(.thread_self));
+    }
+
+    /// The dense 0-based index of the core the calling thread is running on. A danos
+    /// extension beyond `std.Thread`, used to observe genuine cross-core parallelism.
+    pub fn currentCore() Id {
+        return @intCast(sc.systemCall0(.current_core));
+    }
+
+    /// `std.Thread.Futex`-shaped block/wake on a `u32` atomic — the primitive the
+    /// blocking `Mutex`/`Condition`/`Semaphore` are built on. Waiters park in the
+    /// kernel (no busy-wait), so an idle core still halts (docs/halting.md).
+    pub const Futex = struct {
+        /// Block while `ptr.* == expect`. Returns when woken by `wake`, or promptly if
+        /// the value already differs (safe against spurious returns, as in std): the
+        /// caller re-checks its condition in a loop.
+        pub fn wait(ptr: *const std.atomic.Value(u32), expect: u32) void {
+            if (comptime on_danos) {
+                _ = futexWait(@intFromPtr(ptr), expect, 0);
+            } else {
+                // Host unit-test mock: spin+yield until the value changes (`wake` is a
+                // no-op — the callers re-check their condition in a loop anyway). Correct,
+                // if busy; fine for the state-machine tests.
+                while (ptr.load(.acquire) == expect) std.Thread.yield() catch {};
+            }
+        }
+
+        /// As `wait`, but returns `error.Timeout` if `timeout_ns` elapses first.
+        pub fn timedWait(ptr: *const std.atomic.Value(u32), expect: u32, timeout_ns: u64) error{Timeout}!void {
+            if (comptime on_danos) {
+                if (futexWait(@intFromPtr(ptr), expect, timeout_ns) == abi.futex_timed_out) return error.Timeout;
+            } else {
+                var spins: u64 = 0;
+                const limit = timeout_ns / 1000 + 1;
+                while (ptr.load(.acquire) == expect) : (spins += 1) {
+                    if (spins >= limit) return error.Timeout;
+                    std.Thread.yield() catch {};
+                }
+            }
+        }
+
+        /// Wake up to `max_waiters` threads blocked on `ptr`.
+        pub fn wake(ptr: *const std.atomic.Value(u32), max_waiters: u32) void {
+            if (comptime on_danos) {
+                _ = futexWake(@intFromPtr(ptr), max_waiters);
+            } else {
+                // host mock: spin-waiters re-check their condition, so no wake is needed.
+            }
+        }
+    };
+
+    /// A mutual-exclusion lock, `std.Thread.Mutex`-shaped. The classic three-state
+    /// futex mutex (unlocked / locked / contended): the fast path is a single CAS, and
+    /// only a contended lock ever enters the kernel.
+    pub const Mutex = struct {
+        state: std.atomic.Value(u32) = std.atomic.Value(u32).init(unlocked),
+
+        const unlocked: u32 = 0;
+        const locked: u32 = 1;
+        const contended: u32 = 2;
+
+        /// Try to take the lock without blocking; returns whether it was acquired.
+        pub fn tryLock(m: *Mutex) bool {
+            return m.state.cmpxchgStrong(unlocked, locked, .acquire, .monotonic) == null;
+        }
+
+        /// Acquire the lock, blocking in the kernel while it is contended.
+        pub fn lock(m: *Mutex) void {
+            if (m.state.cmpxchgStrong(unlocked, locked, .acquire, .monotonic) != null) m.lockSlow();
+        }
+
+        fn lockSlow(m: *Mutex) void {
+            @branchHint(.cold);
+            // Mark the lock contended and take it as soon as it falls unlocked; park on
+            // the futex while it stays contended. Marking contended may cause a spurious
+            // wake on unlock (harmless), never a missed one.
+            while (m.state.swap(contended, .acquire) != unlocked) {
+                Futex.wait(&m.state, contended);
+            }
+        }
+
+        /// Release the lock; wake one waiter if the lock was contended.
+        pub fn unlock(m: *Mutex) void {
+            if (m.state.swap(unlocked, .release) == contended) Futex.wake(&m.state, 1);
+        }
+    };
+
+    /// A condition variable, `std.Thread.Condition`-shaped. Spurious wakeups are
+    /// allowed — always wait in a predicate loop with the mutex held. Built on a futex
+    /// sequence counter: a waiter samples the seq, drops the mutex, and parks until the
+    /// seq changes (a signal that races the unlock bumps the seq, so it is not missed).
+    pub const Condition = struct {
+        seq: std.atomic.Value(u32) = std.atomic.Value(u32).init(0),
+
+        /// Atomically release `mutex` and block until signalled, then re-acquire it.
+        pub fn wait(c: *Condition, mutex: *Mutex) void {
+            const seq = c.seq.load(.acquire);
+            mutex.unlock();
+            Futex.wait(&c.seq, seq);
+            mutex.lock();
+        }
+
+        /// As `wait`, but returns `error.Timeout` if `timeout_ns` elapses first. The
+        /// mutex is re-acquired either way.
+        pub fn timedWait(c: *Condition, mutex: *Mutex, timeout_ns: u64) error{Timeout}!void {
+            const seq = c.seq.load(.acquire);
+            mutex.unlock();
+            const timed_out = if (Futex.timedWait(&c.seq, seq, timeout_ns)) |_| false else |_| true;
+            mutex.lock();
+            if (timed_out) return error.Timeout;
+        }
+
+        /// Wake one waiter.
+        pub fn signal(c: *Condition) void {
+            _ = c.seq.fetchAdd(1, .release);
+            Futex.wake(&c.seq, 1);
+        }
+
+        /// Wake all waiters.
+        pub fn broadcast(c: *Condition) void {
+            _ = c.seq.fetchAdd(1, .release);
+            Futex.wake(&c.seq, std.math.maxInt(u32));
+        }
+    };
+
+    /// A counting semaphore, `std.Thread.Semaphore`-shaped: a permit count guarded by a
+    /// `Mutex` + `Condition`.
+    pub const Semaphore = struct {
+        mutex: Mutex = .{},
+        cond: Condition = .{},
+        permits: usize = 0,
+
+        /// Take a permit, blocking until one is available.
+        pub fn wait(s: *Semaphore) void {
+            s.mutex.lock();
+            defer s.mutex.unlock();
+            while (s.permits == 0) s.cond.wait(&s.mutex);
+            s.permits -= 1;
+        }
+
+        /// Return a permit and wake a waiter.
+        pub fn post(s: *Semaphore) void {
+            s.mutex.lock();
+            defer s.mutex.unlock();
+            s.permits += 1;
+            s.cond.signal();
+        }
+    };
+
+    /// A reader/writer lock, `std.Thread.RwLock`-shaped: many concurrent readers OR one
+    /// exclusive writer. Reader-preferring (a steady stream of readers can delay a writer),
+    /// built on `Mutex` + `Condition` over a signed state: `>0` = that many readers hold
+    /// it, `-1` = a writer holds it, `0` = free.
+    pub const RwLock = struct {
+        mutex: Mutex = .{},
+        cond: Condition = .{},
+        state: i64 = 0,
+
+        /// Acquire shared (read) access, blocking while a writer holds the lock.
+        pub fn lockShared(rw: *RwLock) void {
+            rw.mutex.lock();
+            defer rw.mutex.unlock();
+            while (rw.state < 0) rw.cond.wait(&rw.mutex);
+            rw.state += 1;
+        }
+
+        /// Try to acquire shared access without blocking.
+        pub fn tryLockShared(rw: *RwLock) bool {
+            rw.mutex.lock();
+            defer rw.mutex.unlock();
+            if (rw.state < 0) return false;
+            rw.state += 1;
+            return true;
+        }
+
+        /// Release shared access; wake a waiting writer once the last reader leaves.
+        pub fn unlockShared(rw: *RwLock) void {
+            rw.mutex.lock();
+            defer rw.mutex.unlock();
+            rw.state -= 1;
+            if (rw.state == 0) rw.cond.broadcast();
+        }
+
+        /// Acquire exclusive (write) access, blocking until no readers or writer remain.
+        pub fn lock(rw: *RwLock) void {
+            rw.mutex.lock();
+            defer rw.mutex.unlock();
+            while (rw.state != 0) rw.cond.wait(&rw.mutex);
+            rw.state = -1;
+        }
+
+        /// Try to acquire exclusive access without blocking.
+        pub fn tryLock(rw: *RwLock) bool {
+            rw.mutex.lock();
+            defer rw.mutex.unlock();
+            if (rw.state != 0) return false;
+            rw.state = -1;
+            return true;
+        }
+
+        /// Release exclusive access; wake all waiters (they re-check their condition).
+        pub fn unlock(rw: *RwLock) void {
+            rw.mutex.lock();
+            defer rw.mutex.unlock();
+            rw.state = 0;
+            rw.cond.broadcast();
+        }
+    };
+
+    /// A `std.Thread.WaitGroup`-shaped counter: `start` before spawning work, `finish` as
+    /// each unit completes, `wait` blocks until the count returns to zero.
+    pub const WaitGroup = struct {
+        mutex: Mutex = .{},
+        cond: Condition = .{},
+        counter: usize = 0,
+
+        /// Register one pending unit of work.
+        pub fn start(wg: *WaitGroup) void {
+            wg.mutex.lock();
+            defer wg.mutex.unlock();
+            wg.counter += 1;
+        }
+
+        /// Mark one unit done; wake waiters if that was the last.
+        pub fn finish(wg: *WaitGroup) void {
+            wg.mutex.lock();
+            defer wg.mutex.unlock();
+            wg.counter -= 1;
+            if (wg.counter == 0) wg.cond.broadcast();
+        }
+
+        /// Block until every started unit has finished.
+        pub fn wait(wg: *WaitGroup) void {
+            wg.mutex.lock();
+            defer wg.mutex.unlock();
+            while (wg.counter != 0) wg.cond.wait(&wg.mutex);
+        }
+    };
+};
+
+/// thread_spawn(entry, stack_top, arg, exit_endpoint) -> tid, or a wrapped error.
+fn threadSpawn(entry: usize, stack_top: usize, arg: usize) usize {
+    const exit_endpoint: usize = @intCast(abi.no_cap); // join uses thread_join, not an endpoint
+    return sc.systemCall4(.thread_spawn, entry, stack_top, arg, exit_endpoint);
+}
+
+/// The kernel returns a real (small) task id on success and a wrapped `-1` on failure;
+/// no valid task id ever exceeds a u32.
+inline fn threadSpawnFailed(ret: usize) bool {
+    return ret > std.math.maxInt(u32);
+}
+
+/// End the calling thread. Never returns.
+fn exitThread() noreturn {
+    _ = sc.systemCall0(.thread_exit);
+    unreachable;
+}
+
+/// Set the calling thread's FS base (its user TLS thread pointer).
+fn setThreadPointer(addr: usize) void {
+    _ = sc.systemCall1(.set_thread_pointer, addr);
+}
+
+/// futex_wait(addr, expect, timeout_ns) -> status (abi.futex_*).
+fn futexWait(addr: usize, expect: u32, timeout_ns: u64) usize {
+    return sc.systemCall3(.futex_wait, addr, expect, timeout_ns);
+}
+
+/// futex_wake(addr, count) -> number woken.
+fn futexWake(addr: usize, count: u32) usize {
+    return sc.systemCall2(.futex_wake, addr, count);
+}
+
+// --- host unit tests (docs/threading-plan.md M11) ---------------------------
+//
+// These run under `zig build test` on the host: the `Futex` seam above uses
+// `std.Thread.Futex` off-danos, so the lock/condvar state machines can be exercised by
+// real host threads. They are never compiled into a danos binary (test blocks only build
+// under test), so their `std.Thread` use is fine even though `std.Thread` is unavailable
+// on the freestanding target.
+
+test "Mutex serialises concurrent increments across host threads" {
+    var m: Thread.Mutex = .{};
+    var counter: u64 = 0;
+    const workers = 8;
+    const per = 20_000;
+    const Ctx = struct {
+        m: *Thread.Mutex,
+        c: *u64,
+        fn run(ctx: @This()) void {
+            var i: usize = 0;
+            while (i < per) : (i += 1) {
+                ctx.m.lock();
+                ctx.c.* += 1;
+                ctx.m.unlock();
+            }
+        }
+    };
+    var handles: [workers]std.Thread = undefined;
+    for (&handles) |*h| h.* = try std.Thread.spawn(.{}, Ctx.run, .{Ctx{ .m = &m, .c = &counter }});
+    for (handles) |h| h.join();
+    try std.testing.expectEqual(@as(u64, workers * per), counter);
+}
+
+test "RwLock never lets a reader observe a half-written pair" {
+    var rw: Thread.RwLock = .{};
+    var a: u64 = 0;
+    var b: u64 = 0; // invariant while a lock is held: a == b
+    var stop = std.atomic.Value(bool).init(false);
+    var ok = std.atomic.Value(bool).init(true);
+
+    const Writer = struct {
+        rw: *Thread.RwLock,
+        a: *u64,
+        b: *u64,
+        stop: *std.atomic.Value(bool),
+        fn run(w: @This()) void {
+            var v: u64 = 1;
+            while (!w.stop.load(.acquire)) : (v +%= 1) {
+                w.rw.lock();
+                w.a.* = v; // update both halves under the exclusive lock...
+                w.b.* = v;
+                w.rw.unlock();
+            }
+        }
+    };
+    const Reader = struct {
+        rw: *Thread.RwLock,
+        a: *u64,
+        b: *u64,
+        ok: *std.atomic.Value(bool),
+        fn run(r: @This()) void {
+            var i: usize = 0;
+            while (i < 200_000) : (i += 1) {
+                r.rw.lockShared();
+                if (r.a.* != r.b.*) r.ok.store(false, .release); // ...so a reader must never see them differ
+                r.rw.unlockShared();
+            }
+        }
+    };
+
+    var writers: [2]std.Thread = undefined;
+    for (&writers) |*w| w.* = try std.Thread.spawn(.{}, Writer.run, .{Writer{ .rw = &rw, .a = &a, .b = &b, .stop = &stop }});
+    var readers: [4]std.Thread = undefined;
+    for (&readers) |*rd| rd.* = try std.Thread.spawn(.{}, Reader.run, .{Reader{ .rw = &rw, .a = &a, .b = &b, .ok = &ok }});
+    for (readers) |rd| rd.join();
+    stop.store(true, .release);
+    for (writers) |w| w.join();
+    try std.testing.expect(ok.load(.acquire));
+}
+
+test "WaitGroup blocks until every started unit finishes" {
+    var wg: Thread.WaitGroup = .{};
+    var done = std.atomic.Value(u32).init(0);
+    const n = 6;
+    const Ctx = struct {
+        wg: *Thread.WaitGroup,
+        done: *std.atomic.Value(u32),
+        fn run(c: @This()) void {
+            _ = c.done.fetchAdd(1, .monotonic);
+            c.wg.finish();
+        }
+    };
+    var i: usize = 0;
+    while (i < n) : (i += 1) wg.start();
+    var handles: [n]std.Thread = undefined;
+    for (&handles) |*h| h.* = try std.Thread.spawn(.{}, Ctx.run, .{Ctx{ .wg = &wg, .done = &done }});
+    wg.wait(); // must not return until all n finished
+    try std.testing.expectEqual(@as(u32, n), done.load(.acquire));
+    for (handles) |h| h.join();
+}

library/runtime/time.zig

@@ -0,0 +1,169 @@
+//! The danos time interface — monotonic time, delays, and deadlines for user space.
+//!
+//! There is no time *service*: the kernel already owns the scheduling timer and
+//! surfaces it directly, so reading the clock is one system call (an `rdtsc` and a
+//! scale), never an IPC round trip (docs/timers.md explains why). This module is a
+//! thin, generic layer over the `clock`/`sleep`/`timer_bind` wrappers in `system.zig`
+//! — an ergonomic `Instant`/`Duration` front door, not new mechanism.
+//!
+//! It is **monotonic** time only: nanoseconds since boot, moving forward, no date or
+//! timezone. Wall-clock/calendar time is a separate user-space service (an RTC-backed
+//! CLOCK_REALTIME) layered on top later.
+
+const std = @import("std");
+const system = @import("system.zig");
+
+const nanos_per_micro: u64 = 1_000;
+const nanos_per_milli: u64 = 1_000_000;
+const nanos_per_second: u64 = 1_000_000_000;
+
+/// A span of time, held as nanoseconds. Constructors name their unit; accessors
+/// truncate toward zero. `ceilMillis` rounds *up*, since `sleep`/`after` land on the
+/// kernel's millisecond granularity and rounding down could return early.
+pub const Duration = struct {
+    ns: u64,
+
+    pub fn fromNanos(n: u64) Duration {
+        return .{ .ns = n };
+    }
+    pub fn fromMicros(n: u64) Duration {
+        return .{ .ns = n *| nanos_per_micro };
+    }
+    pub fn fromMillis(n: u64) Duration {
+        return .{ .ns = n *| nanos_per_milli };
+    }
+    pub fn fromSeconds(n: u64) Duration {
+        return .{ .ns = n *| nanos_per_second };
+    }
+
+    pub fn asNanos(d: Duration) u64 {
+        return d.ns;
+    }
+    pub fn asMicros(d: Duration) u64 {
+        return d.ns / nanos_per_micro;
+    }
+    pub fn asMillis(d: Duration) u64 {
+        return d.ns / nanos_per_milli;
+    }
+    pub fn asSeconds(d: Duration) u64 {
+        return d.ns / nanos_per_second;
+    }
+
+    /// Whole milliseconds, rounded up — the argument `sleep`/`after` pass the kernel.
+    /// A non-zero sub-millisecond duration becomes 1 ms rather than 0.
+    pub fn ceilMillis(d: Duration) u64 {
+        return (d.ns +| (nanos_per_milli - 1)) / nanos_per_milli;
+    }
+
+    pub fn plus(a: Duration, b: Duration) Duration {
+        return .{ .ns = a.ns +| b.ns };
+    }
+};
+
+/// A point on the monotonic clock — nanoseconds since boot. Compare and subtract
+/// instants to measure elapsed time; it never runs backward, so `since` is safe to
+/// saturate at zero rather than wrap.
+pub const Instant = struct {
+    ns: u64,
+
+    /// The span from `earlier` to `self`, saturating at zero if `earlier` is later
+    /// (which the monotonic clock should never produce, but callers may pass any pair).
+    pub fn since(self: Instant, earlier: Instant) Duration {
+        return .{ .ns = self.ns -| earlier.ns };
+    }
+
+    /// How long since this instant, sampled now.
+    pub fn elapsed(self: Instant) Duration {
+        return now().since(self);
+    }
+
+    /// This instant advanced by `d` (a deadline, `d` from here).
+    pub fn plus(self: Instant, d: Duration) Instant {
+        return .{ .ns = self.ns +| d.ns };
+    }
+
+    /// Whether the monotonic clock has reached this instant (used as a deadline).
+    pub fn reached(deadline: Instant) bool {
+        return now().ns >= deadline.ns;
+    }
+};
+
+/// The current monotonic time.
+pub fn now() Instant {
+    return .{ .ns = system.clock() };
+}
+
+/// Monotonic nanoseconds since boot — the raw `clock()` reading, for callers that
+/// want a plain integer instead of an `Instant`.
+pub fn monotonicNanos() u64 {
+    return system.clock();
+}
+
+/// Whether the monotonic clock is usable. The kernel returns 0 until the TSC is
+/// calibrated (`tsc_hz == 0`); a caller that needs real time can treat that as
+/// "unavailable" instead of assuming the clock advances.
+pub fn available() bool {
+    return system.clock() != 0;
+}
+
+/// Block the caller for at least `d`, rounded up to the kernel's millisecond
+/// granularity. For sub-millisecond precision the scheduler cannot express, use
+/// `spin`.
+pub fn sleep(d: Duration) void {
+    system.sleep(d.ceilMillis());
+}
+
+/// Block the caller for `ms` milliseconds — the coarse, allocation-free form.
+pub fn sleepMillis(ms: u64) void {
+    system.sleep(ms);
+}
+
+/// Busy-wait until `d` has elapsed, polling the monotonic clock. This burns the CPU
+/// on purpose, to hit sub-millisecond delays the scheduler's millisecond tick cannot.
+/// Prefer `sleep` for anything at or above a millisecond.
+pub fn spin(d: Duration) void {
+    const deadline = now().plus(d);
+    while (!deadline.reached()) {}
+}
+
+/// Arm a one-shot timer against `endpoint` (a handle from `ipc.createIpcEndpoint`):
+/// after `d` the kernel posts a timer notification (`ipc.Received.isTimer`) there.
+/// Unlike `sleep`, this does not block — a service can keep serving IPC on the same
+/// endpoint while the deadline is pending. Rounds `d` up to milliseconds; returns
+/// false if the timer could not be armed. See `system.timerOnce`.
+pub fn after(endpoint: usize, d: Duration) bool {
+    return system.timerOnce(endpoint, d.ceilMillis());
+}
+
+test "Duration unit conversions round toward zero" {
+    try std.testing.expectEqual(@as(u64, 1_000_000_000), Duration.fromSeconds(1).asNanos());
+    try std.testing.expectEqual(@as(u64, 1_500), Duration.fromNanos(1_500).asNanos());
+    try std.testing.expectEqual(@as(u64, 2), Duration.fromMillis(2).asMillis());
+    try std.testing.expectEqual(@as(u64, 1), Duration.fromNanos(1_999_999).asMillis());
+    try std.testing.expectEqual(@as(u64, 250), Duration.fromMicros(250).asMicros());
+}
+
+test "ceilMillis rounds up, and never turns a nonzero span into zero" {
+    try std.testing.expectEqual(@as(u64, 0), Duration.fromNanos(0).ceilMillis());
+    try std.testing.expectEqual(@as(u64, 1), Duration.fromNanos(1).ceilMillis());
+    try std.testing.expectEqual(@as(u64, 1), Duration.fromMillis(1).ceilMillis());
+    try std.testing.expectEqual(@as(u64, 2), Duration.fromNanos(nanos_per_milli + 1).ceilMillis());
+    try std.testing.expectEqual(@as(u64, 5), Duration.fromMillis(5).ceilMillis());
+}
+
+test "Instant arithmetic: since saturates, plus/reached form deadlines" {
+    const t0 = Instant{ .ns = 1_000 };
+    const t1 = Instant{ .ns = 4_000 };
+    try std.testing.expectEqual(@as(u64, 3_000), t1.since(t0).asNanos());
+    // earlier-than-self can't happen on a monotonic clock; saturate rather than wrap.
+    try std.testing.expectEqual(@as(u64, 0), t0.since(t1).asNanos());
+    const deadline = t0.plus(Duration.fromNanos(2_500));
+    try std.testing.expectEqual(@as(u64, 3_500), deadline.ns);
+}
+
+test "saturating arithmetic does not overflow at the u64 ceiling" {
+    const big = Duration.fromSeconds(std.math.maxInt(u64));
+    try std.testing.expectEqual(@as(u64, std.math.maxInt(u64)), big.asNanos());
+    const late = Instant{ .ns = std.math.maxInt(u64) };
+    try std.testing.expectEqual(@as(u64, std.math.maxInt(u64)), late.plus(Duration.fromSeconds(10)).ns);
+}

library/runtime/usb.zig

@@ -0,0 +1,162 @@
+//! USB class-driver client: the helper a keyboard, mouse, or mass-storage driver
+//! uses to reach its device through the xHCI bus driver, so it never hand-rolls
+//! the transfer-protocol IPC. Layered over `ipc` and the shared
+//! `usb-transfer-protocol` wire format, the way `input.zig` layers over the input
+//! service and `device.zig` over the raw device calls.
+//!
+//! A class driver, spawned with its interface's assigned device id as argv[1]:
+//!     if (!usb.helloManager(id)) return;              // meet the spawn deadline
+//!     var device = usb.open(id) orelse return;        // open + get its endpoints
+//!     _ = device.controlOut(usb_abi.setProtocol(...));// class requests, descriptors
+//!     _ = device.subscribeInterrupt(address, length); // reports arrive asynchronously
+//!     while (true) { ... ipc.replyWait(device.endpoint, ...) ... }  // its own loop
+//!
+//! Reports are delivered to `device.endpoint` as asynchronous `InterruptReport`
+//! messages (the class driver runs a bare `replyWait` loop to read them, because
+//! the service harness drops buffered-message payloads — see service.zig).
+
+const std = @import("std");
+const ipc = @import("ipc.zig");
+const system = @import("system.zig");
+const protocol = @import("usb-transfer-protocol");
+const device_manager = @import("device-manager-protocol");
+
+pub const Endpoint = protocol.Endpoint;
+pub const InterruptReport = protocol.InterruptReport;
+pub const max_report_data = protocol.max_report_data;
+
+// Endpoint transfer types (EndpointDescriptor attributes), for `findEndpoint`.
+pub const transfer_type_bulk: u8 = 2;
+pub const transfer_type_interrupt: u8 = 3;
+
+/// An opened USB device: the bus endpoint to send requests to, this driver's own
+/// endpoint that reports arrive on, the device token, and the interface's
+/// endpoints (so a driver need not re-read the configuration descriptor).
+pub const Device = struct {
+    bus: ipc.Handle,
+    endpoint: ipc.Handle,
+    token: u64,
+    class: u8,
+    subclass: u8,
+    protocol_code: u8,
+    interface_number: u8,
+    endpoint_count: usize = 0,
+    endpoints: [protocol.max_reported_endpoints]Endpoint = undefined,
+
+    /// The interface's first endpoint of the given transfer type and direction
+    /// (`transfer_type_bulk` / `transfer_type_interrupt`), or null.
+    pub fn findEndpoint(self: *const Device, transfer_type: u8, direction_in: bool) ?Endpoint {
+        for (self.endpoints[0..self.endpoint_count]) |endpoint| {
+            if (endpoint.transfer_type == transfer_type and (endpoint.address & 0x80 != 0) == direction_in) return endpoint;
+        }
+        return null;
+    }
+
+    fn controlTransfer(self: *Device, setup: [8]u8, direction_in: bool, data: []u8) ?usize {
+        var request = protocol.ControlRequest{
+            .device_token = self.token,
+            .setup = setup,
+            .direction_in = @intFromBool(direction_in),
+            .data_length = @intCast(data.len),
+        };
+        if (!direction_in and data.len > 0) @memcpy(request.data[0..data.len], data);
+        var reply: [@sizeOf(protocol.ControlReply)]u8 = undefined;
+        const length = ipc.call(self.bus, std.mem.asBytes(&request), &reply) catch return null;
+        if (length < @sizeOf(protocol.ControlReply)) return null;
+        const control_reply = std.mem.bytesToValue(protocol.ControlReply, reply[0..@sizeOf(protocol.ControlReply)]);
+        if (control_reply.status != 0) return null;
+        const actual = @min(control_reply.actual_length, data.len);
+        if (direction_in and actual > 0) @memcpy(data[0..actual], control_reply.data[0..actual]);
+        return actual;
+    }
+
+    /// A control transfer with no data stage (SET_PROTOCOL, SET_IDLE, ...). The
+    /// `setup` is a bit-cast `usb_abi.Request`.
+    pub fn controlOut(self: *Device, setup: [8]u8) bool {
+        return self.controlTransfer(setup, false, &.{}) != null;
+    }
+
+    /// A device-to-host control transfer, returning the bytes read into `out`.
+    pub fn controlIn(self: *Device, setup: [8]u8, out: []u8) ?usize {
+        return self.controlTransfer(setup, true, out);
+    }
+
+    /// Begin periodic IN polling of an interrupt endpoint; reports flow back to
+    /// `self.endpoint` as asynchronous `InterruptReport` messages.
+    pub fn subscribeInterrupt(self: *Device, endpoint_address: u8, max_length: u16) bool {
+        var request = protocol.InterruptSubscribeRequest{
+            .device_token = self.token,
+            .endpoint_address = endpoint_address,
+            .max_length = max_length,
+        };
+        var reply: [@sizeOf(protocol.InterruptSubscribeReply)]u8 = undefined;
+        const length = ipc.call(self.bus, std.mem.asBytes(&request), &reply) catch return false;
+        if (length < @sizeOf(protocol.InterruptSubscribeReply)) return false;
+        return std.mem.bytesToValue(protocol.InterruptSubscribeReply, reply[0..@sizeOf(protocol.InterruptSubscribeReply)]).status == 0;
+    }
+
+    /// One bulk transfer (IN or OUT per `endpoint_address`'s direction bit) to or
+    /// from the caller's own DMA buffer at `physical`. Returns the bytes moved.
+    pub fn bulk(self: *Device, endpoint_address: u8, physical: u64, length: u32) ?u32 {
+        var request = protocol.BulkRequest{
+            .device_token = self.token,
+            .physical_address = physical,
+            .length = length,
+            .endpoint_address = endpoint_address,
+        };
+        var reply: [@sizeOf(protocol.BulkReply)]u8 = undefined;
+        const replied = ipc.call(self.bus, std.mem.asBytes(&request), &reply) catch return null;
+        if (replied < @sizeOf(protocol.BulkReply)) return null;
+        const bulk_reply = std.mem.bytesToValue(protocol.BulkReply, reply[0..@sizeOf(protocol.BulkReply)]);
+        if (bulk_reply.status != 0) return null;
+        return bulk_reply.actual_length;
+    }
+};
+
+/// Look up the USB bus and open the device with the assigned id, handing over a
+/// freshly created endpoint for asynchronous interrupt reports. Retries while the
+/// bus is still coming up (a class driver races the bus driver at boot).
+pub fn open(device_id: u64) ?Device {
+    var attempts: usize = 0;
+    const bus = while (attempts < 100) : (attempts += 1) {
+        if (ipc.lookup(.usb_bus)) |handle| break handle;
+        system.sleep(20);
+    } else return null;
+
+    const endpoint = ipc.createIpcEndpoint() orelse return null;
+    var request = protocol.OpenRequest{ .device_id = device_id };
+    var reply: [@sizeOf(protocol.OpenReply)]u8 = undefined;
+    const result = ipc.callCap(bus, std.mem.asBytes(&request), &reply, endpoint) catch return null;
+    if (result.len < @sizeOf(protocol.OpenReply)) return null;
+    const open_reply = std.mem.bytesToValue(protocol.OpenReply, reply[0..@sizeOf(protocol.OpenReply)]);
+    if (open_reply.status != 0) return null;
+
+    var device = Device{
+        .bus = bus,
+        .endpoint = endpoint,
+        .token = open_reply.device_token,
+        .class = open_reply.interface_class,
+        .subclass = open_reply.interface_subclass,
+        .protocol_code = open_reply.interface_protocol,
+        .interface_number = open_reply.interface_number,
+        .endpoint_count = @min(open_reply.endpoint_count, protocol.max_reported_endpoints),
+    };
+    for (0..device.endpoint_count) |index| device.endpoints[index] = open_reply.endpoints[index];
+    return device;
+}
+
+/// Hello the device manager as a class driver (Role.device) so a supervised
+/// spawn meets its hello deadline. Retries while the manager comes up.
+pub fn helloManager(device_id: u64) bool {
+    var attempts: usize = 0;
+    const manager = while (attempts < 100) : (attempts += 1) {
+        if (ipc.lookup(.device_manager)) |handle| break handle;
+        system.sleep(20);
+    } else return false;
+
+    const hello = device_manager.Hello{ .role = @intFromEnum(device_manager.Role.device), .device_id = device_id };
+    var reply: [device_manager.message_maximum]u8 = undefined;
+    const length = ipc.call(manager, std.mem.asBytes(&hello), &reply) catch return false;
+    if (length < device_manager.reply_size) return false;
+    return std.mem.bytesToValue(device_manager.HelloReply, reply[0..device_manager.reply_size]).status == 0;
+}

library/xkeyboard-config/README.md

@@ -0,0 +1,65 @@
+# xkeyboard-config — X11 keyboard layouts, compiled to Zig
+
+This module turns a physical key (a **USB HID usage**, as the [input module](../../docs/input.md)
+delivers in `KeyEvent.keycode`) plus a modifier state into a **keysym** and, when the key
+produces one, a **character** (a Unicode scalar). It is what lets a `keycode` become a
+`character` — a keymap — without danos shipping an X11 runtime.
+
+The layout data comes from the X11 [xkeyboard-config](https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config)
+database, but it is **compiled to native Zig at build time** rather than parsed at runtime.
+`tools/make-xkeyboard-config.py` reads the vendored xkb data and emits pure-data tables into
+`generated/layouts.zig`; `xkeyboard-config.zig` is the hand-written API over them. This is
+the same build-time-codegen pattern as `tools/make-initial-ramdisk.py`.
+
+## Using it
+
+```zig
+const xkb = @import("xkeyboard-config");
+
+const m = xkb.map(xkb.us, key_event.keycode, .{ .shift = shift_held, .caps_lock = caps });
+if (m.character) |ch| { /* a printable Unicode scalar */ }
+// m.keysym is always set (e.g. an X11 keysym for Return / F1 / a dead key).
+
+const layout = xkb.byName("gb") orelse xkb.us;   // choose a layout by name
+for (xkb.all) |l| { /* enumerate available layouts */ }
+```
+
+`Modifiers` carries `shift`, `caps_lock`, `level3` (AltGr), and `control`. `map` selects the
+level from the key's XKB *type* (the generated data) and those modifiers (the policy, in
+`xkeyboard-config.zig`), so data and semantics stay separable.
+
+Layouts: **us, gb, de, fr, es, dvorak**.
+
+## Regenerating
+
+```sh
+python3 tools/make-xkeyboard-config.py fetch      # network: download + vendor the data subset
+python3 tools/make-xkeyboard-config.py generate   # offline: emit generated/layouts.zig
+# or, from the build:
+zig build gen-xkeyboard-config
+```
+
+- **`fetch`** downloads the pinned xkeyboard-config release (version + sha256 in the script),
+  resolves the `include` graph for the configured layouts, and vendors *only* the symbols
+  files actually reached (plus `keysymdef.h`, `COPYING`, and `PROVENANCE.md`) into `vendor/`.
+  Run it when bumping the version or adding a layout.
+- **`generate`** is deterministic and offline — same vendored input produces byte-identical
+  output. To add a layout, extend `TARGETS` (and `HID_TO_NAME` if a new physical key is
+  involved), then re-run `fetch` (to vendor any new includes) and `generate`.
+
+## Scope
+
+A pragmatic subset, enough for real Latin-script typing:
+
+- **Group 1 only** — no multi-layout group switching.
+- **No dead-key / compose composition** — a dead key returns its keysym with no `character`
+  (composing `´` + `e` → `é` is a higher layer's job).
+- **Curated key types** — the common XKB types (one/two-level, alphabetic, four-level, …);
+  unmapped keys and unknown types fall back to level-by-shift.
+- **6 layouts** — extend via `TARGETS` as above.
+
+## Licensing
+
+xkeyboard-config and `keysymdef.h` (xorgproto) are MIT/X11 licensed. The vendored data
+subset carries the upstream `vendor/COPYING`, and `vendor/PROVENANCE.md` records the exact
+version, source URL, and sha256. The generated tables are a derived work under the same terms.

library/xkeyboard-config/vendor/COPYING

@@ -0,0 +1,190 @@
+Copyright 1996 by Joseph Moss
+Copyright (C) 2002-2007 Free Software Foundation, Inc.
+Copyright (C) Dmitry Golubev <lastguru@mail.ru>, 2003-2004
+Copyright (C) 2004, Gregory Mokhin <mokhin@bog.msu.ru>
+Copyright (C) 2006 Erdal Ronahî
+
+Permission to use, copy, modify, distribute, and sell this software and its
+documentation for any purpose is hereby granted without fee, provided that
+the above copyright notice appear in all copies and that both that
+copyright notice and this permission notice appear in supporting
+documentation, and that the name of the copyright holder(s) not be used in
+advertising or publicity pertaining to distribution of the software without
+specific, written prior permission.  The copyright holder(s) makes no
+representations about the suitability of this software for any purpose.  It
+is provided "as is" without express or implied warranty.
+
+THE COPYRIGHT HOLDER(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
+CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+
+
+Copyright (c) 1996  Digital Equipment Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL DIGITAL EQUIPMENT CORPORATION BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
+THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Except as contained in this notice, the name of the Digital Equipment
+Corporation shall not be used in advertising or otherwise to promote
+the sale, use or other dealings in this Software without prior written
+authorization from Digital Equipment Corporation.
+
+
+Copyright 1996, 1998  The Open Group
+
+Permission to use, copy, modify, distribute, and sell this software and its
+documentation for any purpose is hereby granted without fee, provided that
+the above copyright notice appear in all copies and that both that
+copyright notice and this permission notice appear in supporting
+documentation.
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+Except as contained in this notice, the name of The Open Group shall
+not be used in advertising or otherwise to promote the sale, use or
+other dealings in this Software without prior written authorization
+from The Open Group.
+
+
+Copyright 2004-2005 Sun Microsystems, Inc.  All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice (including the next
+paragraph) shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+
+
+Copyright (c) 1996 by Silicon Graphics Computer Systems, Inc.
+
+Permission to use, copy, modify, and distribute this
+software and its documentation for any purpose and without
+fee is hereby granted, provided that the above copyright
+notice appear in all copies and that both that copyright
+notice and this permission notice appear in supporting
+documentation, and that the name of Silicon Graphics not be
+used in advertising or publicity pertaining to distribution
+of the software without specific prior written permission.
+Silicon Graphics makes no representation about the suitability
+of this software for any purpose. It is provided "as is"
+without any express or implied warranty.
+
+SILICON GRAPHICS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
+SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL SILICON
+GRAPHICS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
+DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
+OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION  WITH
+THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+
+Copyright (c) 1996  X Consortium
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+Except as contained in this notice, the name of the X Consortium shall
+not be used in advertising or otherwise to promote the sale, use or
+other dealings in this Software without prior written authorization
+from the X Consortium.
+
+
+Copyright (C) 2004, 2006 Ævar Arnfjörð Bjarmason <avarab@gmail.com>
+
+Permission to use, copy, modify, distribute, and sell this software and its
+documentation for any purpose is hereby granted without fee, provided that
+the above copyright notice appear in all copies and that both that
+copyright notice and this permission notice appear in supporting
+documentation.
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+Except as contained in this notice, the name of a copyright holder shall
+not be used in advertising or otherwise to promote the sale, use or
+other dealings in this Software without prior written authorization of
+the copyright holder.
+
+
+Copyright (C) 1999, 2000 by Anton Zinoviev <anton@lml.bas.bg>
+
+This software may be used, modified, copied, distributed, and sold,
+in both source and binary form provided that the above copyright
+and these terms are retained. Under no circumstances is the author
+responsible for the proper functioning of this software, nor does
+the author assume any responsibility for damages incurred with its
+use.
+
+Permission is granted to anyone to use, distribute and modify
+this file in any way, provided that the above copyright notice
+is left intact and the author of the modification summarizes
+the changes in this header.
+
+This file is distributed without any expressed or implied warranty.

library/xkeyboard-config/vendor/PROVENANCE.md

@@ -0,0 +1,21 @@
+# Vendored xkeyboard-config subset
+
+- **Package**: xkeyboard-config 2.44
+- **Source**: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config/-/archive/xkeyboard-config-2.44/xkeyboard-config-2.44.tar.gz
+- **sha256**: `35e34edeaf4e8da8d0696ff6b241ee11ddb1b8c6730bac7252d4d0a88ea5f05b`
+- **keysymdef.h**: xorgproto, copied from `/opt/homebrew/include/X11/keysymdef.h`
+- **License**: MIT/X11 (see COPYING)
+
+Only the symbols files reachable from the generated layouts (tools/make-xkeyboard-config.py `TARGETS`) are vendored; regenerate with
+`python3 tools/make-xkeyboard-config.py fetch` then `... generate`.
+
+Vendored symbols files:
+
+- `symbols/de`
+- `symbols/es`
+- `symbols/fr`
+- `symbols/gb`
+- `symbols/kpdl`
+- `symbols/latin`
+- `symbols/level3`
+- `symbols/us`

library/xkeyboard-config/vendor/symbols/es

@@ -0,0 +1,250 @@
+// Keyboard layouts for Spain.
+
+// Modified for a real Spanish keyboard by Jon Tombs.
+default partial alphanumeric_keys
+xkb_symbols "basic" {
+
+    include "latin(type4)"
+
+    name[Group1]="Spanish";
+
+    key <TLDE>	{ [ masculine, ordfeminine,    backslash,   backslash ]	};
+    key <AE01>	{ [         1,     exclam,          bar,   exclamdown ]	};
+    key <AE03>	{ [         3, periodcentered, numbersign,   sterling ]	};
+    key <AE04>	{ [         4,     dollar,   asciitilde,       dollar ]	};
+    key <AE11>	{ [apostrophe,   question,    backslash, questiondown ]	};
+    key <AE12>	{ [exclamdown, questiondown, dead_cedilla, dead_ogonek]	};
+
+    key <AD11>	{ [dead_grave, dead_circumflex, bracketleft, dead_abovering ] };
+    key <AD12>	{ [      plus,   asterisk, bracketright,  dead_macron ]	};
+
+    key <AC10>	{ [    ntilde, Ntilde,   dead_tilde, dead_doubleacute ]	};
+    key <AC11>	{ [dead_acute, dead_diaeresis, braceleft,  dead_caron ]	};
+    key <BKSL>	{ [  ccedilla,   Ccedilla,   braceright,   dead_breve ]	};
+
+    include "level3(ralt_switch)"
+};
+
+partial alphanumeric_keys
+xkb_symbols "winkeys" {
+
+    include "es(basic)"
+    name[Group1]="Spanish (Windows)";
+    include "eurosign(5)"
+};
+
+partial alphanumeric_keys
+xkb_symbols "nodeadkeys" {
+
+    include "es(basic)"
+
+    name[Group1]="Spanish (no dead keys)";
+
+    key <AE12>	{ [exclamdown, questiondown,     cedilla,      ogonek ]	};
+    key <AD11>	{ [     grave, asciicircum,  bracketleft,      degree ]	};
+    key <AD12>	{ [      plus,   asterisk, bracketright,       macron ]	};
+    key <AC07>	{ [         j,          J,          ezh,          EZH ] };
+    key <AC10>	{ [    ntilde,     Ntilde,   asciitilde,  doubleacute ]	};
+    key <AC11>	{ [     acute,  diaeresis,    braceleft,        caron ]	};
+    key <BKSL>	{ [  ccedilla,   Ccedilla,   braceright,        breve ]	};
+    key <AB10>	{ [     minus, underscore,     ellipsis,     abovedot ]	};
+};
+
+// Spanish Dvorak mapping (note R-H exchange)
+partial alphanumeric_keys
+xkb_symbols "dvorak" {
+
+    name[Group1]="Spanish (Dvorak)";
+
+    key <TLDE> {[  masculine, ordfeminine, backslash, degree		]};
+    key <AE01> {[          1, exclam, bar, onesuperior			]};
+    key <AE02> {[          2, quotedbl, at, twosuperior			]};
+    key <AE03> {[          3, periodcentered, numbersign, threesuperior	]};
+    key <AE04> {[          4, dollar, asciitilde, onequarter		]};
+    key <AE05> {[          5, percent, brokenbar, fiveeighths		]};
+    key <AE06> {[          6, ampersand, notsign, threequarters		]};
+    key <AE07> {[          7, slash, onehalf, seveneighths		]};
+    key <AE08> {[          8, parenleft, oneeighth, threeeighths	]};
+    key <AE09> {[          9, parenright, asciicircum			]};
+    key <AE10> {[          0, equal, grave, dead_doubleacute		]};
+    key <AE11> {[ apostrophe, question, dead_macron, dead_ogonek	]};
+    key <AE12> {[ exclamdown, questiondown, dead_breve, dead_abovedot	]};
+
+    key <AD01> {[     period, colon, less, guillemotleft                ]};
+    key <AD02> {[      comma, semicolon, greater, guillemotright        ]};
+    key <AD03> {[     ntilde, Ntilde, lstroke, Lstroke			]};
+    key <AD04> {[          p, P, paragraph				]};
+    key <AD05> {[          y, Y, yen					]};
+    key <AD06> {[          f, F, tslash, Tslash				]};
+    key <AD07> {[          g, G, dstroke, Dstroke			]};
+    key <AD08> {[          c, C, cent, copyright			]};
+    key <AD09> {[          h, H, hstroke, Hstroke			]};
+    key <AD10> {[          l, L, sterling				]};
+    key <AD11> {[ dead_grave, dead_circumflex, bracketleft, dead_caron	]};
+    key <AD12> {[       plus, asterisk, bracketright, plusminus		]};
+
+    key <AC01> {[          a, A, ae, AE					]};
+    key <AC02> {[          o, O, oslash, Oslash				]};
+    key <AC03> {[          e, E, EuroSign				]};
+    key <AC04> {[          u, U, aring, Aring				]};
+    key <AC05> {[          i, I, oe, OE					]};
+    key <AC06> {[          d, D, eth, ETH				]};
+    key <AC07> {[          r, R, registered, trademark			]};
+    key <AC08> {[          t, T, thorn, THORN				]};
+    key <AC09> {[          n, N, eng, ENG				]};
+    key <AC10> {[          s, S, ssharp, section			]};
+    key <AC11> {[ dead_acute, dead_diaeresis, braceleft, dead_tilde	]};
+    key <BKSL> {[   ccedilla, Ccedilla, braceright, dead_cedilla	]};
+
+    key <LSGT> {[       less, greater, guillemotleft, guillemotright	]};
+    key <AB01> {[      minus, underscore, hyphen, macron		]};
+    key <AB02> {[          q, Q, currency				]};
+    key <AB03> {[          j, J						]};
+    key <AB04> {[          k, K, kra					]};
+    key <AB05> {[          x, X, multiply, division			]};
+    key <AB06> {[          b, B						]};
+    key <AB07> {[          m, M, mu					]};
+    key <AB08> {[          w, W						]};
+    key <AB09> {[          v, V						]};
+    key <AB10> {[          z, Z						]};
+
+    include "level3(ralt_switch)"
+};
+
+partial alphanumeric_keys
+xkb_symbols "cat" {
+
+    include "es(basic)"
+
+    name[Group1]="Catalan (Spain, with middle-dot L)";
+
+    key <AC09>  { [	    l,      L,		0x1000140,  0x100013F ] };
+};
+
+partial alphanumeric_keys
+xkb_symbols "ast" {
+
+    include "es(basic)"
+
+    name[Group1]="Asturian (Spain, with bottom-dot H and L)";
+
+    key <AC06>  { [	    h,      H,		0x1001E25,  0x1001E24 ] };
+    key <AC09>  { [	    l,      L,		0x1001E37,  0x1001E36 ] };
+};
+
+
+partial alphanumeric_keys
+xkb_symbols "olpc" {
+
+    // #HW-SPECIFIC
+
+    // http://wiki.laptop.org/go/OLPC_Spanish_Keyboard
+
+    include "us(basic)"
+    name[Group1]="Spanish";
+
+    key <AE00> { [    masculine,    ordfeminine      ] };
+    key <AE01> { [            1,         exclam,             bar ] };
+    key <AE02> { [            2,       quotedbl,              at ] };
+    key <AE03> { [            3,     dead_grave,      numbersign,   grave           ] };
+    key <AE05> { [            5,        percent,     asciicircum,   dead_circumflex ] };
+    key <AE06> { [            6,      ampersand,         notsign ] };
+    key <AE07> { [            7,          slash,       backslash ] };
+    key <AE08> { [            8,      parenleft                         ] };
+    key <AE09> { [            9,     parenright                         ] };
+    key <AE10> { [            0,          equal                  ] };
+    key <AE11> { [   apostrophe,       question                  ] };
+    key <AE12> { [   exclamdown,   questiondown                  ] };
+
+    key <AD03> { [            e,              E,        EuroSign ] };
+    key <AD11> { [   dead_acute, dead_diaeresis,           acute,   dead_abovering  ] };
+    key <AD12> { [  bracketleft,      braceleft                  ] };
+
+    key <AC10> { [       ntilde,        Ntilde                  ] };
+    key <AC11> { [         plus,       asterisk,      dead_tilde ] };
+    key <AC12> { [ bracketright,     braceright,      section    ] };
+
+    key <AB08> { [        comma,      semicolon                  ] };
+    key <AB09> { [       period,          colon                  ] };
+    key <AB10> { [        minus,     underscore                  ] };
+
+    key <I219> { [         less,        greater,  ISO_Next_Group ] };
+
+    include "level3(ralt_switch)"
+};
+
+partial alphanumeric_keys
+xkb_symbols "olpcm" {
+
+    // #HW-SPECIFIC
+
+    // Mechanical (non-membrane) OLPC Spanish keyboard layout.
+    // See: http://wiki.laptop.org/go/OLPC_Spanish_Non-membrane_Keyboard
+
+    include "us(basic)"
+    name[Group1]="Spanish";
+
+    key <AE00> { [    questiondown,    exclamdown, backslash      ] };
+    key <AE01> { [            1,         exclam,             bar ] };
+    key <AE02> { [            2,       quotedbl,              at ] };
+    key <AE03> { [            3,     dead_grave,      numbersign,   grave           ] };
+    key <AE04> { [            4,     dollar,     asciitilde,     dead_tilde ] };
+    key <AE05> { [            5,        percent,     asciicircum,   dead_circumflex ] };
+    key <AE06> { [            6,      ampersand,         notsign ] };
+    key <AE07> { [            7,          slash,       backslash ] };   // no '\' label on olpcm, leave for compatibility
+    key <AE08> { [            8,      parenleft,    masculine                ] };
+    key <AE09> { [            9,     parenright,    ordfeminine                 ] };
+    key <AE10> { [            0,          equal                  ] };
+    key <AE11> { [   apostrophe,       question                  ] };
+
+    key <AD03> { [            e,              E,        EuroSign ] };
+    key <AD11> { [   dead_acute, dead_diaeresis,     dead_abovering, acute  ] };
+    key <AD12> { [  plus,      asterisk                  ] };
+
+    key <AC10> { [       ntilde,        Ntilde                  ] };
+    // no AC11 or AC12 on olpcm
+
+    key <AB08> { [        comma,      semicolon                  ] };
+    key <AB09> { [       period,          colon                  ] };
+    key <AB10> { [        minus,     underscore                  ] };
+
+    key <AA02>  { [        less,        greater ] };
+    key <AA06>  { [  bracketleft,      braceleft,   ccedilla,         Ccedilla  ] };
+    key <AA07>  { [  bracketright,     braceright                ] };
+
+    include "level3(ralt_switch)"
+};
+
+partial alphanumeric_keys
+xkb_symbols "deadtilde" {
+
+    include "es(basic)"
+
+    name[Group1]="Spanish (dead tilde)";
+
+    key <AE04>	{ [         4,     dollar,   dead_tilde,       dollar ]	};
+    key <AC10>	{ [    ntilde, Ntilde,   asciitilde, dead_doubleacute ]	};
+};
+
+partial alphanumeric_keys
+xkb_symbols "olpc2" {
+    // #HW-SPECIFIC
+
+    // Modified variant of US International layout, specifically for Peru
+    // Contact: Sayamindu Dasgupta <sayamindu@laptop.org>
+
+    include "us(olpc)"
+    name[Group1]="Spanish";
+
+    key <AE03> { [  3, numbersign,   dead_grave,  dead_grave] }; // combining grave
+    key <I236>  { [ XF86Start ] };
+
+    include "level3(ralt_switch)"
+};
+
+// EXTRAS:
+
+partial alphanumeric_keys
+	xkb_symbols "sun_type6" {
+	include "sun_vndr/es(sun_type6)"
+};

library/xkeyboard-config/vendor/symbols/gb

@@ -0,0 +1,249 @@
+// Keyboard layouts for Great Britain.
+
+default partial alphanumeric_keys
+xkb_symbols "basic" {
+
+    // The basic UK layout, also known as the IBM 166 layout,
+    // but with the useless brokenbar pushed two levels up.
+
+    include "latin"
+
+    name[Group1]="English (UK)";
+
+    key <TLDE>	{ [     grave,    notsign,          bar,          bar ]	};
+    key <AE02>	{ [         2,   quotedbl,  twosuperior,    oneeighth ]	};
+    key <AE03>	{ [         3,   sterling, threesuperior,    sterling ]	};
+    key <AE04>	{ [         4,     dollar,     EuroSign,   onequarter ]	};
+
+    key <AC11>	{ [apostrophe,         at, dead_circumflex, dead_caron]	};
+    key <BKSL>	{ [numbersign, asciitilde,   dead_grave,   dead_breve ]	};
+
+    key <LSGT>	{ [ backslash,        bar,          bar,    brokenbar ]	};
+
+    include "level3(ralt_switch)"
+};
+
+partial alphanumeric_keys
+xkb_symbols "intl" {
+
+    // A UK layout but with five accents made into dead keys:
+    // grave, diaeresis, circumflex, acute, and tilde.
+    // By Phil Jones <philjones1 at blueyonder.co.uk>.
+
+    include "latin"
+
+    name[Group1]="English (UK, intl., with dead keys)";
+
+    key <TLDE>  { [ dead_grave,    notsign,            bar,         bar ] };
+    key <AE02>  { [   2,    dead_diaeresis,    twosuperior,     onehalf ] };
+    key <AE03>  { [   3,          sterling,  threesuperior,    onethird ] };
+    key <AE04>  { [   4,            dollar,       EuroSign,  onequarter ] };
+    key <AE06>  { [   6,   dead_circumflex,  threequarters,    onesixth ] };
+
+    key <AC11>  { [ dead_acute,         at,     apostrophe,         bar ] };
+    key <BKSL>  { [ numbersign, dead_tilde,            bar,         bar ] };
+
+    key <LSGT>  { [  backslash,        bar,            bar,         bar ] };
+    key <AB08>  { [      comma,       less,       ccedilla,    Ccedilla ] };
+
+    include "level3(ralt_switch)"
+};
+
+partial alphanumeric_keys
+xkb_symbols "extd" {
+    // Clone of the Microsoft "United Kingdom Extended" layout, which
+    // includes dead keys for: grave; diaeresis; circumflex; tilde; and
+    // accute. It also enables direct access to accute characters using
+    // the Multi_key (Alt Gr).
+    //
+    // Taken from...
+    //    "Windows Keyboard Layouts"
+    //    https://docs.microsoft.com/en-gb/globalization/windows-keyboard-layouts#U
+    //
+    // -- Jonathan Miles <jon@cybah.co.uk>
+
+    include "latin"
+
+    name[Group1]="English (UK, extended, Windows)";
+
+    key <TLDE> { [ dead_grave,    notsign,       brokenbar,    NoSymbol ] };
+    key <AE02> { [     2,        quotedbl,  dead_diaeresis,     onehalf ] };
+    key <AE03> { [     3,        sterling,   threesuperior,    onethird ] };
+    key <AE04> { [     4,          dollar,        EuroSign,  onequarter ] };
+    key <AE06> { [     6,     asciicircum, dead_circumflex,    NoSymbol ] };
+
+    key <AD02> { [   w,                 W,          wacute,      Wacute ] };
+    key <AD03> { [   e,                 E,          eacute,      Eacute ] };
+    key <AD06> { [   y,                 Y,          yacute,      Yacute ] };
+    key <AD07> { [   u,                 U,          uacute,      Uacute ] };
+    key <AD08> { [   i,                 I,          iacute,      Iacute ] };
+    key <AD09> { [   o,                 O,          oacute,      Oacute ] };
+    key <AD12> { [ bracketright, braceright,      NoSymbol,         bar ] };
+
+    key <AC01> { [   a,                 A,          aacute,      Aacute ] };
+    key <AC11> { [  apostrophe,         at,     dead_acute,      grave  ] };
+    key <BKSL>  { [ numbersign, asciitilde,     dead_tilde,    backslash ] };
+
+    key <LSGT>  { [  backslash,        bar,       NoSymbol,    NoSymbol ] };
+    key <AB03> { [   c,                 C,        ccedilla,    Ccedilla ] };
+
+    include "level3(ralt_switch)"
+};
+
+// Describe the differences between the US Colemak layout
+// and a UK variant. By Andy Buckley (andy@insectnation.org)
+
+partial alphanumeric_keys
+xkb_symbols "colemak" {
+    include "us(colemak)"
+
+    name[Group1]="English (UK, Colemak)";
+
+    key <TLDE>	{ [     grave,    notsign,          bar,   asciitilde ]	};
+    key <AE02>	{ [         2,   quotedbl,  twosuperior,    oneeighth ]	};
+    key <AE03>	{ [         3,   sterling, threesuperior,    sterling ]	};
+    key <AE04>	{ [         4,     dollar,     EuroSign,   onequarter ]	};
+
+    key <AC11>	{ [apostrophe,         at, dead_circumflex, dead_caron]	};
+    key <BKSL>	{ [numbersign, asciitilde,   dead_grave,   dead_breve ]	};
+
+    key <LSGT>	{ [ backslash,        bar,   asciitilde,    brokenbar ]	};
+};
+
+// Colemak-DH (ISO) layout, UK Variant, https://colemakmods.github.io/mod-dh/
+
+partial alphanumeric_keys
+xkb_symbols "colemak_dh" {
+    include "us(colemak_dh)"
+
+    name[Group1]="English (UK, Colemak-DH)";
+
+    key <TLDE>	{ [     grave,    notsign,          bar,   asciitilde ]	};
+    key <AE02>	{ [         2,   quotedbl,  twosuperior,    oneeighth ]	};
+    key <AE03>	{ [         3,   sterling, threesuperior,    sterling ]	};
+    key <AE04>	{ [         4,     dollar,     EuroSign,   onequarter ]	};
+
+    key <AC11>	{ [apostrophe,         at, dead_circumflex, dead_caron]	};
+    key <BKSL>	{ [numbersign, asciitilde,   dead_grave,   dead_breve ]	};
+
+    key <AB05>	{ [ backslash,        bar,   asciitilde,    brokenbar ]	};
+};
+
+
+// Dvorak (UK) keymap (by odaen) allowing the usage of
+// the £ and ? key and swapping the @ and " keys.
+
+partial alphanumeric_keys
+xkb_symbols "dvorak" {
+    include "us(dvorak-alt-intl)"
+
+    name[Group1]="English (UK, Dvorak)";
+
+    key <TLDE> { [	grave,	notsign,   bar,           bar		] };
+    key <AE02> { [	    2,	quotedbl,  twosuperior,   NoSymbol	] };
+    key <AE03> { [	    3,	sterling,  threesuperior, NoSymbol	] };
+    key <AD01> { [ apostrophe,	at		] };
+    key <BKSL> { [ numbersign,	asciitilde	] };
+    key <LSGT> { [  backslash,	bar		] };
+};
+
+// Dvorak letter positions, but punctuation all in the normal UK positions.
+
+partial alphanumeric_keys
+xkb_symbols "dvorakukp" {
+    include "gb(dvorak)"
+
+    name[Group1]="English (UK, Dvorak, with UK punctuation)";
+
+    key <AE11> {        [     minus,    underscore      ]       };
+    key <AE12> {        [     equal,    plus            ]       };
+    key <AD11> {        [ bracketleft,  braceleft       ]       };
+    key <AD12> {        [ bracketright, braceright      ]       };
+    key <AD01> {        [ slash,        question        ]       };
+    key <AC11> {        [apostrophe,    at,         dead_circumflex, dead_caron] };
+};
+
+partial alphanumeric_keys
+xkb_symbols "mac" {
+
+    include "latin"
+
+    name[Group1]= "English (UK, Macintosh)";
+
+    key <TLDE> {	[         section,       plusminus ]	};
+    key <AE02> {	[               2,              at,         EuroSign	]	};
+    key <AE03> {	[               3,        sterling,       numbersign	]	};
+    key <LSGT> {	[           grave,      asciitilde ]	};
+
+    include "level3(ralt_switch)"
+    include "level3(enter_switch)"
+};
+
+
+partial alphanumeric_keys
+xkb_symbols "mac_intl" {
+
+    include "latin"
+
+    name[Group1]="English (UK, Macintosh, intl.)";
+
+    key <TLDE>  { [ section,            plusminus,            notsign,    notsign ] }; //dead_grave
+    key <AE02>  { [   2,                       at,           EuroSign,    onehalf ] };
+    key <AE03>  { [   3,                 sterling,        twosuperior,   onethird ] };
+    key <AE04>  { [   4,                   dollar,      threesuperior, onequarter ] };
+    key <AE06>  { [   6,          dead_circumflex,           NoSymbol,   onesixth ] };
+    key <AD09>    { [   o,                        O,                 oe,       OE ] };
+
+    key <AC11>  { [ dead_acute,    dead_diaeresis,     dead_diaeresis,        bar ] }; //dead_doubleacute
+    key <BKSL>  { [ backslash,                bar,         numbersign,        bar ] };
+
+    key <LSGT>  { [ dead_grave,        dead_tilde,          brokenbar,        bar ] };
+
+    include "level3(ralt_switch)"
+};
+
+partial alphanumeric_keys
+xkb_symbols "pl" {
+
+    // Polish accented letters on upper levels of corresponding base letters.
+    // Idea from Wawrzyniec Niewodniczański, adapted by Aleksander Kowalski.
+
+    include "gb(basic)"
+
+    name[Group1]="Polish (British keyboard)";
+
+    key <AD03>  { [         e,          E,      eogonek,      Eogonek ] };
+    key <AD09>  { [         o,          O,       oacute,       Oacute ] };
+
+    key <AC01>  { [         a,          A,      aogonek,      Aogonek ] };
+    key <AC02>  { [         s,          S,       sacute,       Sacute ] };
+
+    key <AB01>  { [         z,          Z,    zabovedot,    Zabovedot ] };
+    key <AB02>  { [         x,          X,       zacute,       Zacute ] };
+    key <AB03>  { [         c,          C,       cacute,       Cacute ] };
+    key <AB06>  { [         n,          N,       nacute,       Nacute ] };
+};
+
+partial alphanumeric_keys
+xkb_symbols "gla" {
+
+    // Grave-accented letters on the upper levels of the relevant vowels.
+
+    include "gb(basic)"
+
+    name[Group1]="Scottish Gaelic";
+
+    key <AD03> { [   e,                 E,          egrave,      Egrave ] };
+    key <AD07> { [   u,                 U,          ugrave,      Ugrave ] };
+    key <AD08> { [   i,                 I,          igrave,      Igrave ] };
+    key <AD09> { [   o,                 O,          ograve,      Ograve ] };
+
+    key <AC01> { [   a,                 A,          agrave,      Agrave ] };
+};
+
+// EXTRAS:
+
+partial alphanumeric_keys
+	xkb_symbols "sun_type6" {
+	include "sun_vndr/gb(sun_type6)"
+};

library/xkeyboard-config/vendor/symbols/kpdl

@@ -0,0 +1,102 @@
+// The <KPDL> key is a mess.
+// It was probably originally meant to be a decimal separator.
+// Except since it was declared by USA people it didn't use the original
+// SI separator "," but a "." (since then the USA managed to f-up the SI
+// by making "." an accepted alternative, but standards still use "," as
+// default)
+// As a result users of SI-abiding countries expect either a "." or a ","
+// or a "decimal_separator" which may or may not be translated in one of the
+// above depending on applications.
+// It's not possible to define a default per-country since user expectations
+// depend on the conflicting choices of their most-used applications,
+// operating system, etc. Therefore it needs to be a configuration setting
+// Copyright © 2007 Nicolas Mailhot <nicolas.mailhot @ laposte.net>
+
+
+// Legacy <KPDL> #1
+// This assumes KP_Decimal will be translated in a dot
+partial keypad_keys
+xkb_symbols "dot" {
+
+    key.type[Group1]="KEYPAD" ;
+
+    key <KPDL> { [ KP_Delete, KP_Decimal ] }; // <delete> <separator>
+};
+
+
+// Legacy <KPDL> #2
+// This assumes KP_Separator will be translated in a comma
+partial keypad_keys
+xkb_symbols "comma" {
+
+    key.type[Group1]="KEYPAD" ;
+
+    key <KPDL> { [ KP_Delete, KP_Separator ] }; // <delete> <separator>
+};
+
+
+// Period <KPDL>, usual keyboard serigraphy in most countries
+partial keypad_keys
+xkb_symbols "dotoss" {
+
+    key.type[Group1]="FOUR_LEVEL_MIXED_KEYPAD" ;
+
+    key <KPDL> { [ KP_Delete, period, comma, 0x100202F ] }; // <delete> . , ⍽ (narrow no-break space)
+};
+
+
+// Period <KPDL>, usual keyboard serigraphy in most countries, latin-9 restriction
+partial keypad_keys
+xkb_symbols "dotoss_latin9" {
+
+    key.type[Group1]="FOUR_LEVEL_MIXED_KEYPAD" ;
+
+    key <KPDL> { [ KP_Delete, period, comma, nobreakspace ] }; // <delete> . , ⍽ (no-break space)
+};
+
+
+// Comma <KPDL>, what most non anglo-saxon people consider the real separator
+partial keypad_keys
+xkb_symbols "commaoss" {
+
+    key.type[Group1]="FOUR_LEVEL_MIXED_KEYPAD" ;
+
+    key <KPDL> { [ KP_Delete, comma, period, 0x100202F ] }; // <delete> , . ⍽ (narrow no-break space)
+};
+
+
+// Momayyez <KPDL>: Bahrain, Iran, Iraq, Kuwait, Oman, Qatar, Saudi Arabia, Syria, UAE
+partial keypad_keys
+xkb_symbols "momayyezoss" {
+
+    key.type[Group1]="FOUR_LEVEL_MIXED_KEYPAD" ;
+
+    key <KPDL> { [ KP_Delete, 0x100066B, comma, 0x100202F ] }; // <delete> ? , ⍽ (narrow no-break space)
+};
+
+
+// Abstracted <KPDL>, pray everything will work out (it usually does not)
+partial keypad_keys
+xkb_symbols "kposs" {
+
+    key.type[Group1]="FOUR_LEVEL_MIXED_KEYPAD" ;
+
+    key <KPDL> { [ KP_Delete, KP_Decimal, KP_Separator, 0x100202F ] }; // <delete> ? ? ⍽ (narrow no-break space)
+};
+
+// Spreadsheets may be configured to use the dot as decimal
+// punctuation, comma as a thousands separator and then semi-colon as
+// the list separator. Of these, dot and semi-colon is most important
+// when entering data by the keyboard; the comma can then be inferred
+// and added to the presentation afterwards. Using semi-colon as a
+// general separator may in fact be preferred to avoid ambiguities
+// in data files. Most times a decimal separator is hard-coded, it
+// seems to be period, probably since this is the syntax used in
+// (most) programming languages.
+partial keypad_keys
+xkb_symbols "semi" {
+
+    key.type[Group1]="FOUR_LEVEL_MIXED_KEYPAD" ;
+
+    key <KPDL> { [ NoSymbol, NoSymbol, semicolon ] };
+};

library/xkeyboard-config/vendor/symbols/latin

@@ -0,0 +1,255 @@
+// Common Latin alphabet layout
+
+default partial
+xkb_symbols "basic" {
+
+    key <AE01>	{ [         1,     exclam,  onesuperior,   exclamdown ]	};
+    key <AE02>	{ [         2,         at,  twosuperior,    oneeighth ]	};
+    key <AE03>	{ [         3, numbersign, threesuperior,    sterling ]	};
+    key <AE04>	{ [         4,     dollar,   onequarter,       dollar ]	};
+    key <AE05>	{ [         5,    percent,      onehalf, threeeighths ]	};
+    key <AE06>	{ [         6, asciicircum, threequarters, fiveeighths ] };
+    key <AE07>	{ [         7,  ampersand,    braceleft, seveneighths ]	};
+    key <AE08>	{ [         8,   asterisk,  bracketleft,    trademark ]	};
+    key <AE09>	{ [         9,  parenleft, bracketright,    plusminus ]	};
+    key <AE10>	{ [         0, parenright,   braceright,       degree ]	};
+    key <AE11>	{ [     minus, underscore,    backslash, questiondown ]	};
+    key <AE12>	{ [     equal,       plus, dead_cedilla,  dead_ogonek ]	};
+
+    key <AD01>	{ [         q,          Q,           at,  Greek_OMEGA ]	};
+    key <AD02>	{ [         w,          W,        U017F,      section ]	};
+    key <AD03>	{ [         e,          E,            e,            E ]	};
+    key <AD04>	{ [         r,          R,    paragraph,   registered ]	};
+    key <AD05>	{ [         t,          T,       tslash,       Tslash ]	};
+    key <AD06>	{ [         y,          Y,    leftarrow,          yen ]	};
+    key <AD07>	{ [         u,          U,    downarrow,      uparrow ]	};
+    key <AD08>	{ [         i,          I,   rightarrow,     idotless ]	};
+    key <AD09>	{ [         o,          O,       oslash,       Oslash ]	};
+    key <AD10>	{ [         p,          P,        thorn,        THORN ]	};
+    key <AD11>	{ [bracketleft,  braceleft, dead_diaeresis, dead_abovering ] };
+    key <AD12>	{ [bracketright, braceright, dead_tilde,  dead_macron ]	};
+
+    key <AC01>	{ [         a,          A,           ae,           AE ]	};
+    key <AC02>	{ [         s,          S,       ssharp,        U1E9E ]	};
+    key <AC03>	{ [         d,          D,          eth,          ETH ]	};
+    key <AC04>	{ [         f,          F,      dstroke,  ordfeminine ]	};
+    key <AC05>	{ [         g,          G,          eng,          ENG ]	};
+    key <AC06>	{ [         h,          H,      hstroke,      Hstroke ]	};
+    key <AC07>	{ [         j,          J,    dead_hook,    dead_horn ] };
+    key <AC08>	{ [         k,          K,          kra,    ampersand ]	};
+    key <AC09>	{ [         l,          L,      lstroke,      Lstroke ]	};
+    key <AC10>	{ [ semicolon,    colon, dead_acute, dead_doubleacute ]	};
+    key <AC11>	{ [apostrophe, quotedbl, dead_circumflex,  dead_caron ]	};
+    key <TLDE>	{ [     grave, asciitilde,      notsign,      notsign ]	};
+
+    key <BKSL>	{ [ backslash,        bar,   dead_grave,   dead_breve ]	};
+    key <AB01>	{ [         z,          Z, guillemotleft,        less ]	};
+    key <AB02>	{ [         x,          X, guillemotright,    greater ]	};
+    key <AB03>	{ [         c,          C,         cent,    copyright ]	};
+    key <AB04>	{ [         v,          V,   doublelowquotemark, singlelowquotemark ]	};
+    key <AB05>	{ [         b,          B,  leftdoublequotemark, leftsinglequotemark ] };
+    key <AB06>	{ [         n,          N, rightdoublequotemark, rightsinglequotemark ]	};
+    key <AB07>	{ [         m,          M,           mu,    masculine ]	};
+    key <AB08>	{ [     comma,       less,        U2022,     multiply ]	}; // bullet
+    key <AB09>	{ [    period,    greater, periodcentered,   division ]	};
+    key <AB10>	{ [     slash,   question, dead_belowdot, dead_abovedot ] };
+};
+
+// Northern Europe ( Danish, Finnish, Norwegian, Swedish) common layout
+
+partial
+xkb_symbols "type2" {
+
+    include "latin"
+
+    key <AE01>	{ [         1,     exclam,   exclamdown,  onesuperior ]	};
+    key <AE02>	{ [         2,   quotedbl,           at,  twosuperior ]	};
+    key <AE03>	{ [         3, numbersign,     sterling, threesuperior]	};
+    key <AE04>	{ [         4,   currency,       dollar,   onequarter ]	};
+    key <AE05>	{ [         5,    percent,      onehalf,         cent ]	};
+    key <AE06>	{ [         6,  ampersand,          yen,  fiveeighths ]	};
+    key <AE07>	{ [         7,      slash,    braceleft,     division ]	};
+    key <AE08>	{ [         8,  parenleft,  bracketleft, guillemotleft]	};
+    key <AE09>	{ [         9, parenright, bracketright, guillemotright] };
+    key <AE10>	{ [         0,      equal,   braceright,       degree ]	};
+
+    key <AD03>	{ [         e,          E,     EuroSign,         cent ]	};
+    key <AD04>	{ [         r,          R,   registered,   registered ]	};
+    key <AD05>	{ [         t,          T,        thorn,        THORN ]	};
+    key <AD09>	{ [         o,          O,           oe,           OE ]	};
+    key <AD11>	{ [     aring,  Aring, dead_diaeresis, dead_abovering ]	};
+    key <AD12>	{ [dead_diaeresis, dead_circumflex, dead_tilde, dead_caron ] };
+
+    key <AC01>	{ [         a,          A,  ordfeminine,    masculine ]	};
+
+    key <AB03>	{ [         c,          C,    copyright,    copyright ]	};
+    key <AB08>	{ [     comma,  semicolon, dead_cedilla,  dead_ogonek ]	};
+    key <AB09>	{ [    period,   colon, periodcentered, dead_abovedot ]	};
+    key <AB10>	{ [     minus, underscore, dead_belowdot, dead_abovedot ] };
+};
+
+// Slavic Latin ( Albanian, Croatian, Polish, Slovene, Yugoslav)
+// common layout
+
+partial
+xkb_symbols "type3" {
+
+    include "latin"
+
+    key <AD01>	{ [         q,          Q,    backslash,  Greek_OMEGA ]	};
+    key <AD02>	{ [         w,          W,          bar,      section ]	};
+    key <AD06>	{ [         z,          Z,    leftarrow,          yen ]	};
+
+    key <AC04>	{ [         f,          F,  bracketleft,  ordfeminine ]	};
+    key <AC05>	{ [         g,          G, bracketright,          ENG ]	};
+    key <AC08>	{ [         k,          K,      lstroke,    ampersand ]	};
+
+    key <AB01>	{ [         y,          Y, guillemotleft,        less ]	};
+    key <AB04>	{ [         v,          V,           at,        grave ]	};
+    key <AB05>	{ [         b,          B,    braceleft,   apostrophe ]	};
+    key <AB06>	{ [         n,          N,   braceright,        acute ]	};
+    key <AB07>	{ [         m,          M,      section,    masculine ]	};
+    key <AB08>	{ [     comma,  semicolon,         less,     multiply ]	};
+    key <AB09>	{ [    period,      colon,      greater,     division ]	};
+};
+
+// Another common Latin layout
+// (German, Estonian, Spanish, Icelandic, Italian, Latin American, Portuguese)
+
+partial
+xkb_symbols "type4" {
+
+    include "latin"
+
+    key <AE02>	{ [         2,   quotedbl,           at,    oneeighth ]	};
+    key <AE06>	{ [         6,  ampersand,      notsign,  fiveeighths ]	};
+    key <AE07>	{ [         7,      slash,    braceleft, seveneighths ]	};
+    key <AE08>	{ [         8,  parenleft,  bracketleft,    trademark ]	};
+    key <AE09>	{ [         9, parenright, bracketright,    plusminus ]	};
+    key <AE10>	{ [         0,      equal,   braceright,       degree ]	};
+
+    key <AD03>	{ [         e,          E,     EuroSign,         cent ]	};
+
+    key <AB08>	{ [   comma,  semicolon,          U2022,     multiply ]	}; // bullet
+    key <AB09>	{ [  period,      colon, periodcentered,     division ]	};
+    key <AB10>	{ [   minus, underscore, dead_belowdot, dead_abovedot ]	};
+};
+
+partial
+xkb_symbols "nodeadkeys" {
+
+    key <AE12>	{ [     equal,       plus,     cedilla,        ogonek ]	};
+    key <AD11>	{ [bracketleft,  braceleft,  diaeresis,        degree ]	};
+    key <AD12>	{ [bracketright, braceright, asciitilde,       macron ]	};
+    key <AC07>	{ [         j,          J,         ezh,           EZH ] };
+    key <AC10>	{ [ semicolon,      colon,       acute,   doubleacute ]	};
+    key <AC11>	{ [apostrophe,   quotedbl, asciicircum,         caron ]	};
+    key <BKSL>	{ [ backslash,        bar,       grave,         breve ]	};
+    key <AB10>	{ [     slash,   question,    ellipsis,      abovedot ]	};
+};
+
+partial
+xkb_symbols "type2_nodeadkeys" {
+
+    include "latin(nodeadkeys)"
+
+    key <AD11>	{ [     aring,      Aring,   diaeresis,        degree ]	};
+    key <AD12>	{ [ diaeresis, asciicircum, asciitilde,         caron ]	};
+    key <AB08>	{ [     comma,  semicolon,     cedilla,        ogonek ]	};
+    key <AB09>	{ [    period,   colon, periodcentered,      abovedot ]	};
+    key <AB10>	{ [   minus, underscore,      ellipsis,      abovedot ]	};
+};
+
+partial
+xkb_symbols "type3_nodeadkeys" {
+
+    include "latin(nodeadkeys)"
+};
+
+partial
+xkb_symbols "type4_nodeadkeys" {
+
+    include "latin(nodeadkeys)"
+
+    key <AB10>	{ [   minus, underscore,      ellipsis,      abovedot ]	};
+};
+
+// Added 2008.03.05 by Marcin Woliński
+// See http://marcinwolinski.pl/keyboard/ for a description.
+// Used by pl(intl)
+//
+// ┌─────┐
+// │ 2 4 │   2 = Shift,  4 = Level3 + Shift
+// │ 1 3 │   1 = Normal, 3 = Level3
+// └─────┘
+// ┌─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┲━━━━━━━━━┓
+// │ ~ ~ │ ! ' │ @ " │ # ˝ │ $ ¸ │ % ˇ │ ^ ^ │ & ˘ │ * ̇  │ ( ̣  │ ) ° │ _ ¯ │ + ˛ ┃ ⌫ Back- ┃
+// │ ` ` │ 1 ¡ │ 2 © │ 3 • │ 4 § │ 5 € │ 6 ¢ │ 7 − │ 8 × │ 9 ÷ │ 0 ° │ - – │ = — ┃  space  ┃
+// ┢━━━━━┷━┱───┴─┬───┴─┬───┴─┬───┴─┬───┴─┬───┴─┬───┴─┬───┴─┬───┴─┬───┴─┬───┴─┬───┺━┳━━━━━━━┫
+// ┃       ┃ Q   │ W   │ E   │ R   │ T   │ Y   │ U   │ I   │ O   │ P   │ { « │ } » ┃ Enter ┃
+// ┃Tab ↹  ┃ q   │ w   │ e   │ r   │ t   │ y   │ u   │ i   │ o   │ p   │ [ ‹ │ ] › ┃   ⏎   ┃
+// ┣━━━━━━━┻┱────┴┬────┴┬────┴┬────┴┬────┴┬────┴┬────┴┬────┴┬────┴┬────┴┬────┴┬────┺┓      ┃
+// ┃        ┃ A   │ S   │ D   │ F   │ G   │ H   │ J   │ K   │ L   │ : “ │ " ” │ | ¶ ┃      ┃
+// ┃Caps ⇬  ┃ a   │ s   │ d   │ f   │ g   │ h   │ j   │ k   │ l   │ ; ‘ │ ' ’ │ \   ┃      ┃
+// ┣━━━━━━━━┹────┬┴────┬┴────┬┴────┬┴────┬┴────┬┴────┬┴────┬┴────┬┴────┬┴────┲┷━━━━━┻━━━━━━┫
+// ┃             │ Z   │ X   │ C   │ V   │ B   │ N   │ M   │ < „ │ > · │ ? ¿ ┃             ┃
+// ┃Shift ⇧      │ z   │ x   │ c   │ v   │ b   │ n   │ m   │ , ‚ │ . … │ / ⁄ ┃Shift ⇧      ┃
+// ┣━━━━━━━┳━━━━━┷━┳━━━┷━━━┱─┴─────┴─────┴─────┴─────┴─────┴───┲━┷━━━━━╈━━━━━┻━┳━━━━━━━┳━━━┛
+// ┃       ┃       ┃       ┃ ␣                               ⍽ ┃       ┃       ┃       ┃
+// ┃Ctrl   ┃Meta   ┃Alt    ┃ ␣           Space               ⍽ ┃AltGr ⇮┃Menu   ┃Ctrl   ┃
+// ┗━━━━━━━┻━━━━━━━┻━━━━━━━┹───────────────────────────────────┺━━━━━━━┻━━━━━━━┻━━━━━━━┛
+
+partial
+xkb_symbols "intl" {
+
+    key <TLDE>	{ [     grave,  asciitilde, dead_grave,       dead_tilde ]	};
+    key <AE01>	{ [         1,      exclam, exclamdown,       dead_acute ]	};
+    key <AE02>	{ [         2,          at,  copyright,   dead_diaeresis ]	};
+    key <AE03>	{ [         3,  numbersign,      U2022, dead_doubleacute ]	}; // U+2022 is bullet (the name bullet does not work)
+    key <AE04>	{ [         4,      dollar,    section,     dead_cedilla ]	};
+    key <AE05>	{ [         5,     percent,   EuroSign,       dead_caron ]	};
+    key <AE06>	{ [         6, asciicircum,       cent,  dead_circumflex ]	};
+    key <AE07>	{ [         7,   ampersand,      U2212,       dead_breve ]	}; // U+2212 is MINUS SIGN
+    key <AE08>	{ [         8,    asterisk,   multiply,    dead_abovedot ]	};
+    key <AE09>	{ [         9,   parenleft,   division,    dead_belowdot ]	};
+    key <AE10>	{ [         0,  parenright,     degree,   dead_abovering ]	};
+    key <AE11>	{ [     minus,  underscore,     endash,      dead_macron ]	};
+    key <AE12>	{ [     equal,        plus,     emdash,      dead_ogonek ]	};
+
+    key <AD01>	{ [         q,          Q ]	};
+    key <AD02>	{ [         w,          W ]	};
+    key <AD03>	{ [         e,          E ]	};
+    key <AD04>	{ [         r,          R ]	};
+    key <AD05>	{ [         t,          T ]	};
+    key <AD06>	{ [         y,          Y ]	};
+    key <AD07>	{ [         u,          U ]	};
+    key <AD08>	{ [         i,          I ]	};
+    key <AD09>	{ [         o,          O ]	};
+    key <AD10>	{ [         p,          P ]	};
+    key <AD11>	{ [bracketleft,   braceleft,  U2039, guillemotleft ]    };
+    key <AD12>	{ [bracketright, braceright, U203A, guillemotright ]	};
+
+    key <AC01>	{ [         a,          A ]	};
+    key <AC02>	{ [         s,          S ]	};
+    key <AC03>	{ [         d,          D ]	};
+    key <AC04>	{ [         f,          F ]	};
+    key <AC05>	{ [         g,          G ]	};
+    key <AC06>	{ [         h,          H ]	};
+    key <AC07>	{ [         j,          J ]	};
+    key <AC08>	{ [         k,          K ]	};
+    key <AC09>	{ [         l,          L ]	};
+    key <AC10>	{ [ semicolon,      colon,  leftsinglequotemark,  leftdoublequotemark  ]  };
+    key <AC11>	{ [apostrophe,   quotedbl, rightsinglequotemark, rightdoublequotemark  ]  };
+
+    key <BKSL>	{ [ backslash,        bar, 	NoSymbol, paragraph ] };
+    key <AB01>	{ [         z,          Z ]	};
+    key <AB02>	{ [         x,          X ]	};
+    key <AB03>	{ [         c,          C ]	};
+    key <AB04>	{ [         v,          V ]	};
+    key <AB05>	{ [         b,          B ]     };
+    key <AB06>	{ [         n,          N ]	};
+    key <AB07>	{ [         m,          M ]	};
+    key <AB08>	{ [     comma,       less, singlelowquotemark, doublelowquotemark ]	};
+    key <AB09>	{ [    period,    greater, ellipsis, periodcentered ]	};
+    key <AB10>	{ [     slash,   question, U2044,  questiondown ]     };  // U+2044 is FRACTION SLASH
+};

library/xkeyboard-config/vendor/symbols/level3

@@ -0,0 +1,156 @@
+// These variants assign ISO_Level3_Shift to various keys
+// so that levels 3 and 4 can be reached.
+
+// The default behaviour:
+// the right Alt key (AltGr) chooses the third symbol engraved on a key.
+default partial modifier_keys
+xkb_symbols "ralt_switch" {
+  key <RALT> {[  ISO_Level3_Shift  ], type[group1]="ONE_LEVEL" };
+};
+
+// The right Alt key never chooses the third level.
+// This option attempts to undo the effect of a layout's inclusion of
+// 'ralt_switch'.  You may want to also select another level3 option
+// to map the level3 shift to some other key.
+partial modifier_keys
+xkb_symbols "ralt_alt" {
+  key <RALT> {[  Alt_R,  Meta_R  ], type[group1]="TWO_LEVEL" };
+  modifier_map Mod1 { <RALT> };
+};
+
+// The right Alt key (while pressed) chooses the third shift level,
+// and Compose is mapped to its second level.
+partial modifier_keys
+xkb_symbols "ralt_switch_multikey" {
+  key <RALT> {[  ISO_Level3_Shift,  Multi_key  ], type[group1]="TWO_LEVEL" };
+};
+
+// Either Alt key (while pressed) chooses the third shift level.
+// (To be used mostly to imitate Mac OS functionality.)
+partial modifier_keys
+xkb_symbols "alt_switch" {
+  include "level3(lalt_switch)"
+  include "level3(ralt_switch)"
+};
+
+// The left Alt key (while pressed) chooses the third shift level.
+partial modifier_keys
+xkb_symbols "lalt_switch" {
+  key <LALT> {[  ISO_Level3_Shift  ], type[group1]="ONE_LEVEL" };
+};
+
+// The right Ctrl key (while pressed) chooses the third shift level.
+partial modifier_keys
+xkb_symbols "switch" {
+  key <RCTL> {[  ISO_Level3_Shift  ], type[group1]="ONE_LEVEL" };
+};
+
+// The Menu key (while pressed) chooses the third shift level.
+partial modifier_keys
+xkb_symbols "menu_switch" {
+  key <MENU> {[  ISO_Level3_Shift  ], type[group1]="ONE_LEVEL" };
+};
+
+// Either Win key (while pressed) chooses the third shift level.
+partial modifier_keys
+xkb_symbols "win_switch" {
+  include "level3(lwin_switch)"
+  include "level3(rwin_switch)"
+};
+
+// The left Win key (while pressed) chooses the third shift level.
+partial modifier_keys
+xkb_symbols "lwin_switch" {
+  key <LWIN> {[  ISO_Level3_Shift  ], type[group1]="ONE_LEVEL" };
+};
+
+// The right Win key (while pressed) chooses the third shift level.
+partial modifier_keys
+xkb_symbols "rwin_switch" {
+  key <RWIN> {[  ISO_Level3_Shift  ], type[group1]="ONE_LEVEL" };
+};
+
+// The Enter key on the kepypad (while pressed) chooses the third shift level.
+// (This is especially useful for Mac laptops which miss the right Alt key.)
+partial modifier_keys
+xkb_symbols "enter_switch" {
+  key <KPEN> {[  ISO_Level3_Shift  ], type[group1]="ONE_LEVEL" };
+};
+
+// The CapsLock key (while pressed) chooses the third shift level.
+partial modifier_keys
+xkb_symbols "caps_switch" {
+  key <CAPS> {[  ISO_Level3_Shift  ], type[group1]="ONE_LEVEL" };
+};
+
+// The CapsLock key (while pressed) chooses the third shift level and
+// Ctrl + CapsLock has the original CapsLock function.
+// The 2023 DIN standard for German keyboards recommends it as an option:
+// - https://de.wikipedia.org/wiki/E1_(Tastaturbelegung)#Feststelltaste/Umschaltsperre
+// - https://en.wikipedia.org/wiki/Caps_Lock#Abolition
+partial modifier_keys
+xkb_symbols "caps_switch_capslock_with_ctrl" {
+    virtual_modifiers  LevelThree;
+
+    key <CAPS> {
+        type[Group1] = "PC_CONTROL_LEVEL2",
+        symbols[Group1] = [ ISO_Level3_Shift, Caps_Lock ],
+        // Explicit actions are preferred over modMap None/Mod5 { Caps_Lock }
+        // because they have no side effect
+        actions[Group1] = [ SetMods(modifiers = LevelThree), LockMods(modifiers = Lock) ]
+    };
+};
+
+// The Backslash key (while pressed) chooses the third shift level.
+partial modifier_keys
+xkb_symbols "bksl_switch" {
+  key <BKSL> {[  ISO_Level3_Shift  ], type[group1]="ONE_LEVEL" };
+};
+
+// The AC11 key (while pressed) chooses the third shift level.
+partial modifier_keys
+xkb_symbols "ac11_switch" {
+  key <AC11> {[  ISO_Level3_Shift  ], type[Group1]="ONE_LEVEL" };
+};
+
+// The Less/Greater key (while pressed) chooses the third shift level.
+partial modifier_keys
+xkb_symbols "lsgt_switch" {
+  key <LSGT> {[  ISO_Level3_Shift  ], type[group1]="ONE_LEVEL" };
+};
+
+// The CapsLock key (while pressed) chooses the third shift level,
+// and latches when pressed together with another third-level chooser.
+partial modifier_keys
+xkb_symbols "caps_switch_latch" {
+  key <CAPS> {[  ISO_Level3_Shift,  ISO_Level3_Shift,  ISO_Level3_Latch  ],
+                 type[group1]="THREE_LEVEL" };
+};
+
+// The Backslash key (while pressed) chooses the third shift level,
+// and latches when pressed together with another third-level chooser.
+partial modifier_keys
+xkb_symbols "bksl_switch_latch" {
+  key <BKSL> {[  ISO_Level3_Shift,  ISO_Level3_Shift,  ISO_Level3_Latch  ],
+                 type[group1]="THREE_LEVEL" };
+};
+
+// The Less/Greater key (while pressed) chooses the third shift level,
+// and latches when pressed together with another third-level chooser.
+partial modifier_keys
+xkb_symbols "lsgt_switch_latch" {
+  key <LSGT> {[  ISO_Level3_Shift,  ISO_Level3_Shift,  ISO_Level3_Latch  ],
+                 type[group1]="THREE_LEVEL" };
+};
+
+// Top-row digit key 4 chooses third shift level when pressed alone.
+partial modifier_keys
+xkb_symbols "4_switch_isolated" {
+  override key <AE04> {[  ISO_Level3_Shift  ]};
+};
+
+// Top-row digit key 9 chooses third shift level when pressed alone.
+partial modifier_keys
+xkb_symbols "9_switch_isolated" {
+  override key <AE09> {[  ISO_Level3_Shift  ]};
+};

library/xkeyboard-config/xkeyboard-config.zig

@@ -0,0 +1,153 @@
+//! xkeyboard-config — keyboard layouts, compiled from the X11 xkeyboard-config database
+//! into native Zig. It turns a physical key (a USB HID usage, as the input module delivers)
+//! plus a modifier state into a **keysym** and, when the key produces one, a **character**
+//! (a Unicode scalar). This is the piece that lets a `KeyEvent.keycode` become a
+//! `KeyEvent.character`, without shipping an X11 runtime.
+//!
+//! The layout tables in `generated/layouts.zig` are produced by
+//! `tools/make-xkeyboard-config.py` (see ./README.md to regenerate). Those tables are
+//! deliberately pure data — each key carries its up-to-four levels and an XKB *type*. The
+//! type -> level selection semantics (which modifier picks which level) live here, so the
+//! data and the policy are separable.
+//!
+//! Scope (documented in README.md): group 1 only, no dead-key/compose composition (a dead
+//! key returns its keysym with no character), and a curated set of key types. Layouts:
+//! us, gb, de, fr, es, dvorak.
+//!
+//! Upstream xkeyboard-config and keysymdef.h are MIT/X11 licensed; see vendor/COPYING and
+//! vendor/PROVENANCE.md.
+
+const std = @import("std");
+const generated = @import("layouts");
+
+pub const Level = generated.Level;
+pub const KeyType = generated.KeyType;
+pub const Key = generated.Key;
+pub const Layout = generated.Layout;
+
+/// The generated layouts, by name — as pointers, so they share identity with `all` and
+/// `byName` (and match the `*const Layout` that `map` takes).
+pub const us: *const Layout = &generated.us;
+pub const gb: *const Layout = &generated.gb;
+pub const de: *const Layout = &generated.de;
+pub const fr: *const Layout = &generated.fr;
+pub const es: *const Layout = &generated.es;
+pub const dvorak: *const Layout = &generated.dvorak;
+
+/// Every generated layout, for enumeration (e.g. a settings UI).
+pub const all = generated.all;
+
+/// The modifier state that selects a key's level. `level3` is AltGr (ISO Level3 Shift);
+/// `control` is accepted for completeness but does not affect level selection here.
+pub const Modifiers = struct {
+    shift: bool = false,
+    caps_lock: bool = false,
+    level3: bool = false,
+    control: bool = false,
+};
+
+/// The result of a lookup: the X11 `keysym`, and the `character` it produces (a Unicode
+/// scalar) when it is a printable key — null for keys that produce none (Return, F1, a
+/// bare dead key, an unmapped key).
+pub const Mapping = struct {
+    keysym: u32,
+    character: ?u21,
+};
+
+/// Which level (0..3) a key of `kind` selects under `mods`. XKB's canonical semantics:
+/// Shift picks the odd level, AltGr (level3) adds 2, and Caps acts like Shift for the
+/// alphabetic types. See the XKB "key types" — this covers the ones the vendored layouts
+/// use; anything else falls back to shift-or-not.
+fn selectLevel(kind: KeyType, mods: Modifiers) usize {
+    const shift_or_caps = mods.shift != mods.caps_lock; // XOR: Caps behaves like Shift
+    const low: usize = if (mods.shift) 1 else 0;
+    const high: usize = if (mods.level3) 2 else 0;
+    return switch (kind) {
+        .one_level => 0,
+        .two_level, .keypad, .other => low,
+        .alphabetic => if (shift_or_caps) 1 else 0,
+        .four_level => low + high,
+        .four_level_alphabetic => (if (shift_or_caps) @as(usize, 1) else 0) + high,
+        // Caps affects only the base pair, not the AltGr pair.
+        .four_level_semialphabetic => if (mods.level3) 2 + low else (if (shift_or_caps) @as(usize, 1) else 0),
+    };
+}
+
+/// Map a physical key (`hid_usage`, a USB HID keyboard-page usage) under `mods` on
+/// `layout` to its keysym and character. Falls back gracefully when the selected level is
+/// undefined for the key: it drops the AltGr component, then the shift component, so a key
+/// with only a base/shift pair still yields something sensible under AltGr.
+pub fn map(layout: *const Layout, hid_usage: u8, mods: Modifiers) Mapping {
+    const key = &layout.keys[hid_usage];
+    var level = selectLevel(key.kind, mods);
+    // Fall back to a defined level: full -> without AltGr -> base.
+    if (key.levels[level].keysym == 0 and key.levels[level].unicode == 0) {
+        const candidates = [_]usize{ level & 1, 0 };
+        for (candidates) |candidate| {
+            if (key.levels[candidate].keysym != 0 or key.levels[candidate].unicode != 0) {
+                level = candidate;
+                break;
+            }
+        }
+    }
+    const chosen = key.levels[level];
+    return .{
+        .keysym = chosen.keysym,
+        .character = if (chosen.unicode != 0) @intCast(chosen.unicode) else null,
+    };
+}
+
+/// Look up a layout by its name (`"us"`, `"gb"`, ...), or null if unknown.
+pub fn byName(name: []const u8) ?*const Layout {
+    for (all) |layout| {
+        if (std.mem.eql(u8, layout.name, name)) return layout;
+    }
+    return null;
+}
+
+// --- tests (host-run via `zig build test`) ---------------------------------
+
+const testing = std.testing;
+
+// USB HID usages used in the tests (keyboard page 0x07).
+const hid_a: u8 = 0x04;
+const hid_1: u8 = 0x1e;
+const hid_3: u8 = 0x20;
+
+test "us: letters obey shift and caps" {
+    try testing.expectEqual(@as(?u21, 'a'), map(us, hid_a, .{}).character);
+    try testing.expectEqual(@as(?u21, 'A'), map(us, hid_a, .{ .shift = true }).character);
+    try testing.expectEqual(@as(?u21, 'A'), map(us, hid_a, .{ .caps_lock = true }).character);
+    // Shift + Caps cancels for an alphabetic key.
+    try testing.expectEqual(@as(?u21, 'a'), map(us, hid_a, .{ .shift = true, .caps_lock = true }).character);
+}
+
+test "us: digits and their shifted symbols" {
+    try testing.expectEqual(@as(?u21, '1'), map(us, hid_1, .{}).character);
+    try testing.expectEqual(@as(?u21, '!'), map(us, hid_1, .{ .shift = true }).character);
+    try testing.expectEqual(@as(?u21, '3'), map(us, hid_3, .{}).character);
+    try testing.expectEqual(@as(?u21, '#'), map(us, hid_3, .{ .shift = true }).character);
+    // A digit is not alphabetic: Caps alone must not shift it.
+    try testing.expectEqual(@as(?u21, '3'), map(us, hid_3, .{ .caps_lock = true }).character);
+}
+
+test "layouts differ: GB pound vs US hash on shift+3" {
+    try testing.expectEqual(@as(?u21, '#'), map(us, hid_3, .{ .shift = true }).character);
+    try testing.expectEqual(@as(?u21, '£'), map(gb, hid_3, .{ .shift = true }).character);
+}
+
+test "french azerty places q where us has a" {
+    try testing.expectEqual(@as(?u21, 'q'), map(fr, hid_a, .{}).character);
+    try testing.expectEqual(@as(?u21, 'Q'), map(fr, hid_a, .{ .shift = true }).character);
+}
+
+test "byName resolves and rejects" {
+    try testing.expect(byName("us") == us);
+    try testing.expect(byName("gb") == gb);
+    try testing.expect(byName("nonsense") == null);
+}
+
+test "unmapped key yields no character" {
+    // HID 0x00 is not a key; every level is empty.
+    try testing.expectEqual(@as(?u21, null), map(us, 0x00, .{}).character);
+}

system/abi.zig

@@ -39,20 +39,63 @@ pub const SystemCall = enum(u64) {
     ipc_reply_wait = 10, // ipc_reply_wait(h, reply, len, receive, cap) -> receive_len (+badge in rdx)
     device_enumerate = 11, // device_enumerate(buffer, maximum) -> count: snapshot the device table
     device_claim = 12, // device_claim(id) -> ok: take exclusive ownership of a device
-    mmio_map = 13, // mmio_map(id, resource_index) -> vaddr: map a claimed device's MMIO into this AS
+    mmio_map = 13, // mmio_map(id, resource_index) -> virtual_address: map a claimed device's MMIO into this address space
     irq_bind = 14, // irq_bind(id, resource_index, endpoint): deliver a device IRQ as an IPC notification
     irq_ack = 15, // irq_ack(id, resource_index): re-arm a bound IRQ after servicing it
     device_register = 16, // device_register(parent_id, descriptor) -> id: publish a child of a device you claimed
-    system_spawn = 17, // system_spawn(name_ptr, name_len) -> 0: start a named initial-ramdisk binary as a new ring-3 process
-    dma_alloc = 18, // dma_alloc(len, flags) -> vaddr (rax), paddr (rdx): contiguous, pinned, uncacheable DMA memory
-    dma_free = 19, // dma_free(vaddr, len) -> 0: release a prior dma_alloc
+    system_spawn = 17, // system_spawn(name_ptr, name_len, arguments_ptr, arguments_len, exit_endpoint) -> child process id: start a named initial-ramdisk binary as a new ring-3 process
+    dma_alloc = 18, // dma_alloc(len, flags) -> virtual_address (rax), physical_address (rdx): contiguous, pinned, uncacheable DMA memory
+    dma_free = 19, // dma_free(virtual_address, len) -> 0: release a prior dma_alloc
     msi_bind = 20, // msi_bind(device_id, endpoint) -> address (rax), data (rdx): a per-device MSI vector for a claimed device
     io_read = 21, // io_read(device_id, resource_index, offset, width) -> value: read a port in a claimed device's io_port resource
     io_write = 22, // io_write(device_id, resource_index, offset, width, value) -> 0: write a port in a claimed device's io_port resource
     clock = 23, // clock() -> nanoseconds since boot: a monotonic time source (for timeouts/delays)
+    process_enumerate = 24, // process_enumerate(buffer, maximum) -> total: snapshot the task table
+    process_kill = 25, // process_kill(id) -> 0/-errno: end a process this process spawned
+    ipc_send = 26, // ipc_send(handle, message_ptr, message_len) -> 0/-errno: post a payload to an endpoint's async queue without blocking
+    process_exit_reason = 27, // process_exit_reason(id) -> ExitReason/-errno: how a dead child ended (its supervisor only)
+    process_subscribe = 28, // process_subscribe(endpoint) -> 0/-errno: subscribe to published exit events — every death posts a notification
+    signal_bind = 29, // signal_bind(endpoint) -> 0/-errno: nominate the endpoint this process's signals arrive on
+    process_signal = 30, // process_signal(id, signal) -> 0/-errno: post a signal to a child (or to yourself)
+    timer_bind = 31, // timer_bind(endpoint, ms) -> 0/-errno: one-shot timer — posts a notification when ms elapse
+    klog_read = 32, // klog_read(offset, ptr, len) -> bytes copied: copy the kernel RAM log buffer out to a user buffer (for persisting the boot log to disk)
+    wall_clock = 33, // wall_clock() -> Unix epoch seconds (UTC): the RTC wall-clock time, for filesystem timestamps (mtime). Monotonic time is `clock`.
+    shm_create = 34, // shm_create(len) -> virtual_address (rax), handle (rdx): a shareable, zeroed, cacheable RAM region mapped into this AS; the handle is a capability passed to another process as an ipc_call send_cap (docs/display-v2.md)
+    shm_map = 35, // shm_map(cap) -> virtual_address: map the shared region named by a received capability into this address space (the same physical pages the creator sees)
+    shm_physical = 36, // shm_physical(cap) -> physical_address: the guest-physical base of a shared region held by capability, so a driver can program it into a device (e.g. virtio-gpu attach_backing); the pages are contiguous (docs/display-v2.md)
+    thread_spawn = 37, // thread_spawn(entry, stack_top, arg, exit_endpoint) -> tid: start a task sharing the caller's address space at `entry` on `stack_top`, `arg` in rdi; exit_endpoint (a handle, or no_cap) is notified when it ends — how join waits (docs/threading.md)
+    thread_exit = 38, // thread_exit(): end the calling thread, dropping one reference to its address space (destroyed on the last)
+    current_core = 39, // current_core() -> index: the dense 0-based index of the core the caller is running on (for parallelism/affinity introspection)
+    futex_wait = 40, // futex_wait(addr, expected, timeout_ns) -> status: if *addr == expected, block until woken or the timeout; returns futex_woken/mismatch/timed_out (docs/threading.md)
+    futex_wake = 41, // futex_wake(addr, count) -> woken: wake up to `count` tasks blocked in futex_wait on `addr` in this address space
+    thread_self = 42, // thread_self() -> tid: the calling thread's kernel task id (runtime.Thread.getCurrentId)
+    thread_join = 43, // thread_join(tid) -> 0: block until the thread with id `tid` has exited (runtime.Thread.join; no per-thread IPC endpoint) (docs/threading.md)
+    set_thread_pointer = 44, // set_thread_pointer(addr) -> 0: set the caller's thread pointer (user-space TLS base; x86_64 IA32_FS_BASE, aarch64 TPIDR_EL0); restored per task across context switches (docs/threading-plan.md M10)
     _,
 };
 
+/// `futex_wait` return codes (in rax).
+pub const futex_woken: u64 = 0; // woken by a futex_wake
+pub const futex_mismatch: u64 = 1; // *addr != expected on entry; the caller did not block
+pub const futex_timed_out: u64 = 2; // the timeout elapsed before a wake
+
+/// How a process ended — recorded by the kernel at death, queried by the
+/// supervisor with `process_exit_reason`, and the input to its restart decision
+/// (docs/process-lifecycle.md): a clean exit meant to stop, a fault wants a
+/// restart with backoff, killed means the supervisor did it itself. The faults
+/// mirror the CPU exceptions a ring-3 process can die of; they are exit reasons,
+/// never delivered to the faulting process (recovery is restart, not a handler).
+pub const ExitReason = enum(u8) {
+    exited = 0, // returned from main / called exit
+    aborted = 1, // deliberate self-termination (reserved: no abort path yet)
+    segmentation_fault = 2, // page fault
+    illegal_instruction = 3, // invalid opcode
+    arithmetic_fault = 4, // divide error, x87 or SIMD fault
+    protection_fault = 5, // general protection fault
+    fault = 6, // any other CPU exception
+    killed = 7, // process_kill
+};
+
 /// The x86 MSI message address base (`0xFEE0_0000`): a device raises an MSI by writing
 /// `data` to this address, which the Local APIC turns into an interrupt at the vector
 /// in `data`. The kernel returns the concrete (address, data) from `msi_bind`; this is
@@ -67,17 +110,98 @@ pub const dma_write_combining: u64 = 2; // write-combining (framebuffers); needs
 pub const dma_below_4g: u64 = 4; // physical address must fit 32 bits (legacy DMA engines)
 
 /// Set in the badge returned by `ipc_reply_wait` when what arrived is an
-/// **asynchronous notification** (today: a device interrupt bound with `irq_bind`)
-/// rather than a message from a client. There is no payload and no reply owed; the
-/// low bits carry the source, a GSI. Shared so the kernel's ISR and the driver's
-/// event loop can't disagree about which bit means "the hardware spoke".
+/// **asynchronous notification** (a device interrupt bound with `irq_bind`, or a
+/// child-exit notice — see `notify_exit_bit`) rather than a message from a client.
+/// There is no payload and no reply owed; the low bits carry the source. Shared so
+/// the kernel's ISR and the driver's event loop can't disagree about which bit
+/// means "the hardware spoke".
 pub const notify_badge_bit: u64 = 1 << 63;
 
+/// Set (alongside `notify_badge_bit`) in the badge of a **child-exit notification**:
+/// posted to the endpoint a supervisor passed to `system_spawn` when that child ends
+/// — by clean exit, by a fault, or by `process_kill`. The low bits carry the child's
+/// process id, so one endpoint can supervise many children (and even share with IRQ
+/// notifications, which never set this bit). The microkernel's SIGCHLD.
+pub const notify_exit_bit: u64 = 1 << 62;
+
+/// Set (alongside `notify_badge_bit`) in the badge of a **buffered message** — a payload
+/// posted to an endpoint's async queue by `ipc_send`, delivered through `ipc_reply_wait`
+/// like a notification (no reply owed) but carrying bytes in the receive buffer, not just
+/// a badge. This is what distinguishes a payload-bearing async message from a bare IRQ /
+/// child-exit notification (which sets neither this nor `notify_exit_bit`). The low bits
+/// carry the sender's task id. The async counterpart of the synchronous `ipc_call`, for
+/// broadcasts where a rendezvous is the wrong shape (the input service is the first user).
+pub const notify_message_bit: u64 = 1 << 61;
+
+/// Set (alongside `notify_badge_bit`) in the badge of a **signal notification** —
+/// the process-lifecycle vocabulary of docs/process-lifecycle.md, delivered to the
+/// endpoint the process nominated with `signal_bind`. The low bits carry the
+/// coalesced pending mask (bit positions = `Signal` values): signals are
+/// statements, not questions, and two pending terminates are one terminate.
+pub const notify_signal_bit: u64 = 1 << 60;
+
+/// Set (alongside `notify_badge_bit`) in the badge of a **timer notification** —
+/// a one-shot `timer_bind` deadline landing. No payload bits: what to do when the
+/// deadline fires is whatever the receiver armed it for (a stop-sequence
+/// escalation, a restart backoff, an alarm).
+pub const notify_timer_bit: u64 = 1 << 59;
+
+/// The signal vocabulary (docs/process-lifecycle.md): POSIX's concepts, danos's
+/// names, message delivery. The value is the bit position in the pending mask — a
+/// private kernel/runtime detail, free to change while they ship together. Kill
+/// is not here (it is `process_kill`, unhandleable by definition); faults are not
+/// here (they are `ExitReason`s — recovery is restart, not a handler); liveness is
+/// not here (a question, asked as the zero-length ping call, not a statement).
+pub const Signal = enum(u5) {
+    terminate = 0, // finish up and exit (the polite half of the stop sequence)
+    reload = 1, // re-read configuration / re-scan
+    interrupt = 2, // interactive interrupt (no sender until a console exists)
+    quit = 3, // as interrupt, by convention more final
+    alarm = 4, // a timer the process armed for itself (unbuilt: no consumer yet)
+    user_1 = 5, // service-defined
+    user_2 = 6, // service-defined
+};
+
+/// Capacity of `ProcessDescriptor.name` — matches the longest name `system_spawn`
+/// accepts, so a process's recorded name (its argv[0]) is never truncated.
+pub const maximum_process_name = 64;
+
+/// What a process is doing right now, as reported by `process_enumerate`. Crosses
+/// the system_call boundary as `ProcessDescriptor.state`.
+pub const ProcessState = enum(u32) {
+    ready = 0, // runnable, waiting for a core
+    running = 1, // executing on a core right now
+    blocked = 2, // waiting (sleeping, or blocked in IPC)
+};
+
+/// One `process_enumerate` entry — the kernel's view of a live task, kernel tasks
+/// included (they carry an empty name and id 0 is the boot task). Fixed layout
+/// (extern) because it crosses the kernel↔user boundary by memory copy, like
+/// `DeviceDescriptor` in the device ABI.
+pub const ProcessDescriptor = extern struct {
+    id: u32, // kernel-assigned process id; never reused (monotonic)
+    supervisor: u32, // id of the process that spawned it (0 = the kernel)
+    state: u32, // a ProcessState value
+    priority: u32,
+    name_length: u32,
+    name: [maximum_process_name]u8, // argv[0] at spawn; empty for kernel tasks
+};
+
 /// Well-known IPC service ids for the bootstrap name registry (create_ipc_endpoint +
 /// ipc_register/ipc_lookup). Small integers, so no string interning is needed
 /// during bring-up. The VFS server registers under `vfs`; clients look it up.
 pub const ServiceId = enum(u32) {
     vfs = 1,
+    input = 2,
+    ps2_bus = 3, // the 8042 owner; child device drivers attach here for raw bytes
+    device_manager = 4, // the tree, the matcher, the supervisor (docs/device-manager.md)
+    power = 5, // system power: events (button, lid, battery) + shutdown (docs/power.md; domain-named per docs/discovery.md — the acpi service registers it on x86, a PSCI service will on ARM)
+    usb_bus = 6, // the xHCI host-controller driver's transfer endpoint; USB class drivers look it up and `callCap`-open their device to get a private per-device transfer channel (docs/driver-model.md)
+    block = 7, // a block-device driver (USB mass storage today): read/write of fixed-size blocks, the storage a filesystem sits on
+    fat = 8, // the FAT filesystem server; the VFS mounts it and forwards paths under its mount point (/mnt/usb) to it
+    display = 9, // the display service: owns the framebuffer, composites a layer stack, presents frames (docs/display.md)
+    shm_test = 10, // the shm test server (V2): a client passes it a shared-memory capability, it maps + verifies (docs/display-v2.md)
+    scanout = 11, // a native scanout driver (virtio-gpu): the compositor finds it here to upgrade off the GOP framebuffer (docs/display-v2.md)
     _,
 };
 

system/boot-handoff.zig

@@ -32,10 +32,10 @@ pub const PixelFormat = enum(u32) {
 /// Output Protocol (a headless server, say). The kernel must treat on-screen
 /// output as optional and never assume a framebuffer exists.
 pub const Framebuffer = extern struct {
-    base: usize,            // the memory address where pixel data starts (0 = none)
-    width: u32,             // visible pixels per row (e.g. 1920)
-    height: u32,            // visible rows (e.g. 1080)
-    pitch: u32,             // bytes from the start of one row to the start of the next
+    base: usize, // the memory address where pixel data starts (0 = none)
+    width: u32, // visible pixels per row (e.g. 1920)
+    height: u32, // visible rows (e.g. 1080)
+    pitch: u32, // bytes from the start of one row to the start of the next
     format: PixelFormat,
 
     /// Whether a usable framebuffer was handed over.

system/devices/acpi-ids.zig

@@ -1,60 +1,120 @@
 //! ACPI / PnP hardware-ID (`_HID`) names: the flat analog of pci-class.zig for
 //! `acpi_device` nodes. Unlike PCI, ACPI has no class/subclass/prog-IF taxonomy — a
 //! device's identity *is* its `_HID` string (`PNP0303` simply means "PS/2 keyboard"),
-//! so this is a plain id -> description registry rather than a hierarchical decoder.
+//! so this is a plain id <-> name registry rather than a hierarchical decoder.
 //! The well-known PnP/ACPI IDs; vendor-specific ids (e.g. `QEMU0002`, `INTC1234`) have
-//! no standard name and return "". Pure reference data, so it is shared by kernel
-//! discovery (the device-tree dump) and any user-space tool.
+//! no standard name and decode to nothing. Pure reference data, so it is shared by
+//! kernel discovery (the device-tree dump) and any user-space driver or tool.
+//!
+//! Code that means a specific device names the `HardwareId` variant instead of its
+//! `_HID` string — `HardwareId.ps2_keyboard.hid()` reads without a registry lookup,
+//! where a bare `"PNP0303"` does not.
 
 const std = @import("std");
 
-const Entry = struct { hid: []const u8, name: []const u8 };
+/// The common standard PnP/ACPI hardware IDs, as named values. Prefix ranges hint at
+/// the grouping (PNP03xx keyboards, PNP0Fxx pointing devices, PNP0Cxx ACPI
+/// power/thermal, PNP0Axx buses), but there is no formal hierarchy — hence a flat
+/// enum over a flat registry.
+pub const HardwareId = enum {
+    programmable_interrupt_controller,
+    system_timer,
+    high_precision_event_timer,
+    dma_controller,
+    ps2_keyboard,
+    parallel_port,
+    ecp_parallel_port,
+    serial_port,
+    floppy_disk_controller,
+    system_speaker,
+    pci_bus,
+    generic_container,
+    /// The second id the ACPI spec assigns the same "Generic Container Device" name.
+    generic_container_extended,
+    pci_express_root_bridge,
+    real_time_clock,
+    system_board,
+    motherboard_reserved_resources,
+    math_coprocessor,
+    acpi_system_board,
+    embedded_controller,
+    control_method_battery,
+    fan,
+    power_button,
+    lid,
+    sleep_button,
+    pci_interrupt_link,
+    microsoft_ps2_mouse,
+    ps2_mouse,
+    ac_adapter,
+    processor_device,
+    processor_aggregator,
+    processor_container,
 
-/// The common standard PnP/ACPI hardware IDs. Prefix ranges hint at the grouping
-/// (PNP03xx keyboards, PNP0Fxx pointing devices, PNP0Cxx ACPI power/thermal,
-/// PNP0Axx buses), but there is no formal hierarchy — hence a flat table.
-const table = [_]Entry{
-    .{ .hid = "PNP0000", .name = "Programmable Interrupt Controller (PIC)" },
-    .{ .hid = "PNP0100", .name = "System Timer (PIT)" },
-    .{ .hid = "PNP0103", .name = "High Precision Event Timer (HPET)" },
-    .{ .hid = "PNP0200", .name = "DMA Controller" },
-    .{ .hid = "PNP0303", .name = "PS/2 Keyboard" },
-    .{ .hid = "PNP0400", .name = "Standard LPT Parallel Port" },
-    .{ .hid = "PNP0401", .name = "ECP Parallel Port" },
-    .{ .hid = "PNP0501", .name = "16550A-compatible Serial Port" },
-    .{ .hid = "PNP0700", .name = "PC Floppy Disk Controller" },
-    .{ .hid = "PNP0800", .name = "System Speaker" },
-    .{ .hid = "PNP0A03", .name = "PCI Bus" },
-    .{ .hid = "PNP0A05", .name = "Generic Container Device" },
-    .{ .hid = "PNP0A06", .name = "Generic Container Device" },
-    .{ .hid = "PNP0A08", .name = "PCI Express Root Bridge" },
-    .{ .hid = "PNP0B00", .name = "Real-Time Clock (RTC)" },
-    .{ .hid = "PNP0C01", .name = "System Board" },
-    .{ .hid = "PNP0C02", .name = "Motherboard Reserved Resources" },
-    .{ .hid = "PNP0C04", .name = "Math Coprocessor" },
-    .{ .hid = "PNP0C08", .name = "ACPI System Board" },
-    .{ .hid = "PNP0C09", .name = "ACPI Embedded Controller" },
-    .{ .hid = "PNP0C0A", .name = "ACPI Control Method Battery" },
-    .{ .hid = "PNP0C0B", .name = "ACPI Fan" },
-    .{ .hid = "PNP0C0C", .name = "ACPI Power Button" },
-    .{ .hid = "PNP0C0D", .name = "ACPI Lid" },
-    .{ .hid = "PNP0C0E", .name = "ACPI Sleep Button" },
-    .{ .hid = "PNP0C0F", .name = "PCI Interrupt Link Device" },
-    .{ .hid = "PNP0F03", .name = "Microsoft PS/2 Mouse" },
-    .{ .hid = "PNP0F13", .name = "PS/2 Mouse" },
-    .{ .hid = "ACPI0003", .name = "AC Adapter" },
-    .{ .hid = "ACPI0007", .name = "Processor Device" },
-    .{ .hid = "ACPI000C", .name = "Processor Aggregator" },
-    .{ .hid = "ACPI0010", .name = "Processor Container" },
+    const Entry = struct { hid: []const u8, name: []const u8 };
+
+    /// The registry row for this id: its `_HID` string and human-readable name.
+    fn entry(self: HardwareId) Entry {
+        return switch (self) {
+            .programmable_interrupt_controller => .{ .hid = "PNP0000", .name = "Programmable Interrupt Controller (PIC)" },
+            .system_timer => .{ .hid = "PNP0100", .name = "System Timer (PIT)" },
+            .high_precision_event_timer => .{ .hid = "PNP0103", .name = "High Precision Event Timer (HPET)" },
+            .dma_controller => .{ .hid = "PNP0200", .name = "DMA Controller" },
+            .ps2_keyboard => .{ .hid = "PNP0303", .name = "PS/2 Keyboard" },
+            .parallel_port => .{ .hid = "PNP0400", .name = "Standard LPT Parallel Port" },
+            .ecp_parallel_port => .{ .hid = "PNP0401", .name = "ECP Parallel Port" },
+            .serial_port => .{ .hid = "PNP0501", .name = "16550A-compatible Serial Port" },
+            .floppy_disk_controller => .{ .hid = "PNP0700", .name = "PC Floppy Disk Controller" },
+            .system_speaker => .{ .hid = "PNP0800", .name = "System Speaker" },
+            .pci_bus => .{ .hid = "PNP0A03", .name = "PCI Bus" },
+            .generic_container => .{ .hid = "PNP0A05", .name = "Generic Container Device" },
+            .generic_container_extended => .{ .hid = "PNP0A06", .name = "Generic Container Device" },
+            .pci_express_root_bridge => .{ .hid = "PNP0A08", .name = "PCI Express Root Bridge" },
+            .real_time_clock => .{ .hid = "PNP0B00", .name = "Real-Time Clock (RTC)" },
+            .system_board => .{ .hid = "PNP0C01", .name = "System Board" },
+            .motherboard_reserved_resources => .{ .hid = "PNP0C02", .name = "Motherboard Reserved Resources" },
+            .math_coprocessor => .{ .hid = "PNP0C04", .name = "Math Coprocessor" },
+            .acpi_system_board => .{ .hid = "PNP0C08", .name = "ACPI System Board" },
+            .embedded_controller => .{ .hid = "PNP0C09", .name = "ACPI Embedded Controller" },
+            .control_method_battery => .{ .hid = "PNP0C0A", .name = "ACPI Control Method Battery" },
+            .fan => .{ .hid = "PNP0C0B", .name = "ACPI Fan" },
+            .power_button => .{ .hid = "PNP0C0C", .name = "ACPI Power Button" },
+            .lid => .{ .hid = "PNP0C0D", .name = "ACPI Lid" },
+            .sleep_button => .{ .hid = "PNP0C0E", .name = "ACPI Sleep Button" },
+            .pci_interrupt_link => .{ .hid = "PNP0C0F", .name = "PCI Interrupt Link Device" },
+            .microsoft_ps2_mouse => .{ .hid = "PNP0F03", .name = "Microsoft PS/2 Mouse" },
+            .ps2_mouse => .{ .hid = "PNP0F13", .name = "PS/2 Mouse" },
+            .ac_adapter => .{ .hid = "ACPI0003", .name = "AC Adapter" },
+            .processor_device => .{ .hid = "ACPI0007", .name = "Processor Device" },
+            .processor_aggregator => .{ .hid = "ACPI000C", .name = "Processor Aggregator" },
+            .processor_container => .{ .hid = "ACPI0010", .name = "Processor Container" },
+        };
+    }
+
+    /// This id's `_HID` string (e.g. `.ps2_keyboard` -> "PNP0303").
+    pub fn hid(self: HardwareId) []const u8 {
+        return self.entry().hid;
+    }
+
+    /// This id's human-readable name (e.g. `.ps2_keyboard` -> "PS/2 Keyboard").
+    pub fn description(self: HardwareId) []const u8 {
+        return self.entry().name;
+    }
+
+    /// The named value for a `_HID` string, or null if it is not a known standard
+    /// id (vendor-specific ids are not in the registry).
+    pub fn fromHid(hid_string: []const u8) ?HardwareId {
+        for (std.enums.values(HardwareId)) |id| {
+            if (std.mem.eql(u8, id.hid(), hid_string)) return id;
+        }
+        return null;
+    }
 };
 
-/// The human-readable name for a `_HID`, or "" if it is not a known standard id
-/// (vendor-specific ids have no registry name — callers just print the raw HID).
+/// The human-readable name for a `_HID` string, or "" if it is not a known standard
+/// id (vendor-specific ids have no registry name — callers just print the raw HID).
 pub fn description(hid: []const u8) []const u8 {
-    for (table) |entry| {
-        if (std.mem.eql(u8, entry.hid, hid)) return entry.name;
-    }
-    return "";
+    return (HardwareId.fromHid(hid) orelse return "").description();
 }
 
 test "decodes standard PnP/ACPI ids and leaves the rest alone" {
@@ -66,3 +126,13 @@ test "decodes standard PnP/ACPI ids and leaves the rest alone" {
     try eq("", description("QEMU0002")); // vendor-specific: no standard name
     try eq("", description("")); // no HID at all
 }
+
+test "named values round-trip through their _HID strings" {
+    const testing = std.testing;
+    try testing.expectEqualStrings("PNP0303", HardwareId.ps2_keyboard.hid());
+    try testing.expectEqual(@as(?HardwareId, .ps2_mouse), HardwareId.fromHid("PNP0F13"));
+    try testing.expectEqual(@as(?HardwareId, null), HardwareId.fromHid("QEMU0002"));
+    for (std.enums.values(HardwareId)) |id| {
+        try testing.expectEqual(@as(?HardwareId, id), HardwareId.fromHid(id.hid()));
+    }
+}

system/devices/acpi.zig

@@ -3,11 +3,13 @@
 //! Walks the ACPI tables the firmware left in memory (starting from the RSDP the
 //! bootloader handed us) and translates the static tables into the generic
 //! `device` model, so the kernel enumerates hardware without knowing ACPI is the
-//! source. This is deliberately the *static-table* path: MADT (CPUs / interrupt
-//! controllers), MCFG (PCIe ECAM -> PCI enumeration), HPET (timer), and FADT
-//! (power register map). The DSDT/SSDT bytecode is handed to the `aml` submodule
-//! only to extract the sleep-state (`_Sx`) values for power management; full AML namespace
-//! interpretation is a separate, larger subproject.
+//! source. This is deliberately the *static-table* path, and **only** that: MADT
+//! (CPUs / interrupt controllers), MCFG (PCIe ECAM -> PCI enumeration), HPET
+//! (timer), and FADT (power register map). The DSDT/SSDT bytecode is *not*
+//! interpreted here — the kernel collects the blobs and publishes them on the
+//! acpi-tables node for the ring-3 acpi service to parse (device enumeration and
+//! soft-off). Keeping the ~0.5 MB AML interpretation out of kernel init keeps it
+//! off the single-core critical path (nothing else runs alongside it there).
 //!
 //! ACPI tables live in `.acpi_tables` / `.acpi_nvs` memory, which the kernel
 //! identity-maps, so table addresses are dereferenced directly. PCIe ECAM is MMIO
@@ -19,7 +21,6 @@ const boot_handoff = @import("boot-handoff");
 const abi = @import("abi");
 const parameters = @import("parameters");
 const device_model = @import("device-model.zig");
-const aml = @import("aml/aml.zig");
 const DeviceTree = device_model.DeviceTree;
 const Hal = device_model.Hal;
 
@@ -37,9 +38,15 @@ pub const RegisterAccess = struct {
     }
 };
 
-/// Everything the power subsystem needs, extracted from the FADT and the AML
-/// sleep packages during discovery. Populated by `discover`, read by `power`.
+/// The power register map, extracted from the FADT during discovery. Populated by
+/// `discover`, read by `power` (kernel reboot). The **sleep-state (`_Sx`) values
+/// live in AML**, which the kernel no longer parses — soft-off (S5) is owned by the
+/// ring-3 acpi service (it re-parses the blobs on the published acpi-tables node and
+/// writes the PM1 control register itself). So this holds only the FADT scalars.
 pub const PowerInformation = struct {
+    /// The System Control Interrupt's GSI (FADT SCI_INT) — the line ACPI events
+    /// (power button, GPEs) arrive on. Published to the acpi service for M21.
+    sci_interrupt: u16 = 0,
     /// The SMM command port and the value that switches the platform into ACPI mode.
     smi_cmd: u16 = 0,
     acpi_enable: u8 = 0,
@@ -51,9 +58,6 @@ pub const PowerInformation = struct {
     reset: RegisterAccess = .{},
     reset_value: u8 = 0,
     reset_supported: bool = false,
-    /// SLP_TYP values for S5 (soft off) and S3 (suspend), from the AML sleep-state (`_Sx`) packages.
-    s5: ?aml.SleepType = null,
-    s3: ?aml.SleepType = null,
 };
 
 /// Filled in by `discover`; the power service reads it to reboot/shutdown.
@@ -137,25 +141,20 @@ const maximum_cpus = parameters.maximum_cpus;
 /// Filled in by `discover` (from the MADT); SMP bring-up reads it to wake the APs.
 pub var cpu_information: CpuInformation = .{};
 
-/// Integrity/diagnostics for the AML parse. `consumed == total` means the parser
-/// walked every byte of the DSDT/SSDTs without desyncing.
-pub const AmlStats = struct {
-    nodes: usize = 0,
-    consumed: usize = 0,
-    total: usize = 0,
-};
-pub var aml_stats: AmlStats = .{};
-
-/// The ACPI namespace built from the DSDT/SSDTs, kept for sleep-state (`_Sx`) lookup now and
-/// device enumeration later. Null until `discover` runs successfully.
-pub var namespace: ?aml.Namespace = null;
-
 /// Physical address of the DSDT the FADT points at, or 0.
 pub var dsdt_physical: u64 = 0;
 
+/// The FADT itself (physical + length), published on the acpi-tables node so
+/// the ring-3 acpi service can read the PM1 event and GPE blocks it needs for
+/// the event side (docs/acpi.md — ACPI events). Distinguished from the AML
+/// blob resources by its intact "FACP" header — the blobs are header-stripped.
+var fadt_physical: u64 = 0;
+var fadt_length: u64 = 0;
+
 // AML blocks (DSDT + any SSDTs) collected during the table walk, as physical
-// address + length of each table's post-header bytecode. Scanned after the walk
-// for the sleep-state (`_Sx`) packages.
+// address + length of each table's post-header bytecode. The kernel does not
+// interpret them — it publishes them on the acpi-tables node for the ring-3 acpi
+// service to parse (device enumeration + soft-off). See publishAcpiTablesNode.
 var aml_block_physical: [32]u64 = undefined;
 var aml_block_len: [32]usize = undefined;
 var aml_block_count: usize = 0;
@@ -197,7 +196,8 @@ const ExtendedSystemDescriptorPointer = extern struct {
     root_system_description_table_address: u32 align(1),
     /// The size of the RSDP.
     length: u32 align(1),
-    /// A 64-bit physical address pointing to the XSDT. If the revision is at least 2, the XSDT should be used regardless of architecture, as the RSDT was deprecated.
+    /// A 64-bit physical address pointing to the XSDT. If the revision is at least 2, the XSDT
+    /// should be used regardless of architecture, as the RSDT was deprecated.
     extended_system_descriptor_table_address: u64 align(1),
     /// A checksum used for the entire table.
     extended_checksum: u8,
@@ -357,38 +357,20 @@ const Hpet = extern struct {
     page_protection: u8,
 };
 
-// --- PCI configuration-space header (first 64 bytes, common fields) ---------
-
-const PciHeader = extern struct {
-    vendor_id: u16 align(1),
-    device_id: u16 align(1),
-    command: u16 align(1),
-    status: u16 align(1),
-    revision_id: u8,
-    prog_if: u8,
-    subclass: u8,
-    class_code: u8,
-    cache_line_size: u8,
-    latency_timer: u8,
-    /// bit 7 set => multi-function device.
-    header_type: u8,
-    bist: u8,
-    // 0x10 onward (BARs, etc.) depends on header_type; read separately.
-};
-
 // --- Entry point ------------------------------------------------------------
 
 /// Discover hardware from the ACPI tables rooted at `rsdp_physical` and populate
 /// `device_tree`. `hal` provides MMIO mapping (for PCIe ECAM) and port I/O. Also parses the
-/// FADT and the AML sleep-state (`_Sx`) packages into `power_information` for the power service.
-pub fn discover(rsdp_physical: u64, device_tree: *DeviceTree, hal: Hal) !void {
+/// FADT into `power_information`, and publishes the AML blobs for the ring-3 acpi service.
+pub fn discover(rsdp_physical: u64, memory_regions: []const boot_handoff.MemoryRegion, device_tree: *DeviceTree, hal: Hal) !void {
     if (rsdp_physical == 0) return error.NoRsdp;
+    boot_memory_regions = memory_regions;
 
     // Start clean so a re-run doesn't accumulate stale state.
     power_information = .{};
+    fadt_physical = 0;
+    fadt_length = 0;
     platform_information = .{};
-    aml_stats = .{};
-    namespace = null;
     dsdt_physical = 0;
     aml_block_count = 0;
 
@@ -405,24 +387,50 @@ pub fn discover(rsdp_physical: u64, device_tree: *DeviceTree, hal: Hal) !void {
         try walkRoot(u32, rsdp.root_system_description_table_address, device_tree, hal);
     }
 
-    // Now that the DSDT and any SSDTs are collected, build the AML namespace and
-    // read the sleep types from it.
-    var blocks: [aml_block_physical.len][]const u8 = undefined;
-    for (0..aml_block_count) |i| {
-        blocks[i] = @as([*]const u8, @ptrFromInt(boot_handoff.physicalToVirtual(aml_block_physical[i])))[0..aml_block_len[i]];
-    }
-    const active = blocks[0..aml_block_count];
-    if (aml.parse(device_tree.allocator, active)) |pr| {
-        namespace = pr.namespace;
-        aml_stats = .{ .nodes = namespace.?.nodeCount(), .consumed = pr.consumed, .total = pr.total };
-        power_information.s5 = aml.sleepState(&namespace.?, 5);
-        power_information.s3 = aml.sleepState(&namespace.?, 3);
-        // Fold the namespace's Device objects into the generic tree.
-        wireAcpiDevices(device_tree, &namespace.?, hal) catch {};
-    } else |_| {
-        // AML parse failed (e.g. out of memory); power stays best-effort with
-        // whatever the FADT alone provided.
+    // The kernel does **not** interpret the DSDT/SSDTs. Static-table discovery
+    // above (MADT/HPET/FADT/MCFG) is all the kernel needs — CPUs, timers, PCIe,
+    // and the power register map. The AML bytecode (device enumeration and the
+    // sleep-state `_Sx` values for soft-off) is entirely the ring-3 acpi service's
+    // job: it claims the acpi-tables node published below, parses the same blobs,
+    // and both registers the `_HID` devices and owns S5. Not parsing ~0.5 MB of
+    // AML in the kernel keeps boot latency off the critical, single-core path.
+
+    // Publish the acpi-tables node (docs/discovery.md): the AML blobs as
+    // memory resources for the acpi service to map and parse in ring 3, a broad
+    // io_port grant for the OperationRegion access its interpreter needs, and
+    // the SCI for the events track (M21). Exactly one node, one trusted
+    // claimant — the sole path by which AML (devices + soft-off) reaches ring 3,
+    // now that the kernel keeps only the *static* tables for itself.
+    publishAcpiTablesNode(device_tree) catch {};
+}
+
+/// Build the acpi-tables node (see the call site in discover). Best-effort: a
+/// failure here leaves the kernel-seeded tree working, only the ring-3 service
+/// finds nothing to claim.
+fn publishAcpiTablesNode(device_tree: *DeviceTree) !void {
+    const node = try device_tree.addChild(device_tree.root, .acpi_tables, "acpi-tables");
+    // One memory resource per AML block — page-aligned base down, length padded
+    // up to cover the bytecode, so mmio_map hands the service a pointer into it.
+    var i: usize = 0;
+    while (i < aml_block_count and i < device_model.maximum_resources - 2) : (i += 1) {
+        // mmio_map preserves the sub-page offset, so the service maps this and
+        // gets a pointer straight to the bytecode.
+        _ = node.addResource(.memory, aml_block_physical[i], aml_block_len[i]);
     }
+    // The broad I/O grant: OperationRegions name whatever ports the firmware
+    // chose (EC, PM1, GPE, SMBus); which ports cannot be known before the AML
+    // that names them is parsed, so the grant is the whole space — the honest
+    // trust boundary of docs/discovery.md (the acpi service's one trusted node).
+    _ = node.addResource(.io_port, 0, 1 << 16);
+    // A broad interrupt window: ACPI _CRS names legacy ISA IRQs (the PS/2 lines
+    // 1 and 12, the RTC, …), and the service registers those devices under this
+    // node, so it must own a superset. The range [0, 256) covers every GSI; the
+    // SCI (recorded first, len 1) stays distinct so M21 can pick it out.
+    if (power_information.sci_interrupt != 0) _ = node.addResource(.irq, power_information.sci_interrupt, 1);
+    _ = node.addResource(.irq, 0, 256);
+    // The FADT rides along (M21): the service reads the PM1 event / GPE blocks
+    // from its own copy, telling it apart from the AML blobs by signature.
+    if (fadt_physical != 0) _ = node.addResource(.memory, fadt_physical, fadt_length);
 }
 
 /// Walk the RSDT (Entry = u32) or XSDT (Entry = u64): validate it, then dispatch
@@ -448,17 +456,19 @@ fn handleTable(device_tree: *DeviceTree, hal: Hal, sdt_physical: u64) !void {
     if (std.mem.eql(u8, &sig, &APIC)) {
         try parseMadt(device_tree, header);
     } else if (std.mem.eql(u8, &sig, &MCFG)) {
-        try parseMcfg(device_tree, hal, header);
+        try parseMcfg(device_tree, header);
     } else if (std.mem.eql(u8, &sig, &HPET)) {
         try parseHpet(device_tree, hal, header);
     } else if (std.mem.eql(u8, &sig, &FACP)) {
+        fadt_physical = sdt_physical;
+        fadt_length = header.length;
         parseFadt(header);
     } else if (std.mem.eql(u8, &sig, &SPCR)) {
         parseSpcr(header);
     } else if (std.mem.eql(u8, &sig, &DMAR)) {
         parseDmar(hal, header);
     } else if (std.mem.eql(u8, &sig, &SSDT)) {
-        // Secondary namespace bytecode — collect for the sleep-state (`_Sx`) scan.
+        // Secondary namespace bytecode — collect it to publish for the ring-3 parse.
         addAmlBlock(sdt_physical);
     }
     // Any other signature is recognised but left opaque for now.
@@ -533,7 +543,7 @@ fn parseMadt(device_tree: *DeviceTree, header: *const SystemDescriptorTableHeade
 }
 
 /// MCFG -> a pci_host_bridge per ECAM segment, then a PCI enumeration underneath.
-fn parseMcfg(device_tree: *DeviceTree, hal: Hal, header: *const SystemDescriptorTableHeader) !void {
+fn parseMcfg(device_tree: *DeviceTree, header: *const SystemDescriptorTableHeader) !void {
     const total: usize = header.length;
     const base: [*]const u8 = @ptrCast(header);
 
@@ -548,109 +558,85 @@ fn parseMcfg(device_tree: *DeviceTree, hal: Hal, header: *const SystemDescriptor
         // ECAM window: 1 MiB of configuration space per bus.
         _ = bridge.addResource(.memory, alloc.base_address, bus_count << 20);
         _ = bridge.addResource(.bus_range, alloc.start_bus, bus_count);
+        addBridgeApertures(bridge);
+        // The bridge decodes the whole 16-bit I/O space toward its bus — the
+        // window functions' I/O BARs must register-contain within (M19.2).
+        _ = bridge.addResource(.io_port, 0, 1 << 16);
 
-        try enumeratePci(device_tree, bridge, hal, alloc.*);
+        // The function walk itself retired to ring 3 (M19.3): the pci-bus
+        // driver claims this bridge, repeats the scan through its ECAM grant,
+        // and device_registers what it finds — the kernel seeds only the
+        // bridge. The scan's equivalence was proven before the hand-off
+        // (pci-scan), and the walk's history is in git if archaeology calls.
     }
 }
 
-/// Brute-force scan the ECAM window's bus range for present PCI functions. No
-/// bridge recursion yet: on the ECAM path the host bridge decodes every bus in
-/// the window, so scanning the declared range finds everything QEMU exposes.
-fn enumeratePci(
-    device_tree: *DeviceTree,
-    bridge: *device_model.Device,
-    hal: Hal,
-    alloc: McfgAllocation,
-) !void {
-    var bus: u16 = alloc.start_bus;
-    while (bus <= alloc.end_bus) : (bus += 1) {
-        var device: u8 = 0;
-        while (device < 32) : (device += 1) {
-            const h0: *align(1) const PciHeader = @ptrCast(pciConfigurationPtr(alloc, hal, @intCast(bus), device, 0));
-            if (h0.vendor_id == 0xFFFF) continue; // no function 0 => slot empty
+/// The boot memory map, stored at discover() entry for the aperture derivation
+/// below (and, in M20, for the acpi-tables node's containment windows).
+var boot_memory_regions: []const boot_handoff.MemoryRegion = &.{};
 
-            const funcs: u8 = if (h0.header_type & 0x80 != 0) 8 else 1;
-            var function: u8 = 0;
-            while (function < funcs) : (function += 1) {
-                const configuration = pciConfigurationPtr(alloc, hal, @intCast(bus), device, function);
-                const h: *align(1) const PciHeader = @ptrCast(configuration);
-                if (h.vendor_id == 0xFFFF) continue;
-
-                var nb: [24]u8 = undefined;
-                const nm = std.fmt.bufPrint(&nb, "{s}:{x:0>2}:{x:0>2}.{d}", .{
-                    bridge.name(), bus, device, function,
-                }) catch "pcidev";
-                const node = try device_tree.addChild(bridge, .pci_device, nm);
-                // Resource 0 is the function's own 4 KiB ECAM configuration space. A
-                // claimed PCI driver mmio_maps this to reach its command register,
-                // BARs, and — the point — its capability list (MSI/MSI-X, PCIe
-                // extended caps), without any new syscall. Physical address per the
-                // ECAM formula (same as pciConfigurationPtr).
-                const config_physical = alloc.base_address +
-                    (@as(u64, @as(u8, @intCast(bus)) - alloc.start_bus) << 20) +
-                    (@as(u64, device) << 15) + (@as(u64, function) << 12);
-                _ = node.addResource(.memory, config_physical, abi.page_size);
-                node.ids.pci_vendor = h.vendor_id;
-                node.ids.pci_device = h.device_id;
-                node.ids.pci_class = (@as(u24, h.class_code) << 16) |
-                    (@as(u24, h.subclass) << 8) | h.prog_if;
-                node.ids.pci_bdf = (@as(u16, @intCast(bus)) << 8) | (@as(u16, device) << 3) | function;
-
-                // BARs only exist in header type 0 (normal devices), not bridges.
-                if (h.header_type & 0x7F == 0) addBars(node, configuration);
+/// The bridge's MMIO apertures, derived from the boot memory map's holes
+/// (docs/discovery.md — apertures from the memory map): registered PCI functions carry BAR
+/// resources, and `device_register` containment demands the bridge own windows
+/// that cover them. Everything the firmware described is "not hole"; the low
+/// aperture runs from the end of the described space below 4 GiB up to the
+/// I/O-APIC region, the high one from 4 GiB (or the end of RAM above it) to
+/// the 46-bit line. Coarse, mechanical, and AML-free — available at boot no
+/// matter what later moved to user space.
+fn addBridgeApertures(bridge: *device_model.Device) void {
+    // Below 4 GiB the described regions are sparse (RAM low, firmware flash
+    // and tables high), so the holes are the *gaps between* them — a single
+    // "after the last region" rule dies on OVMF's flash at the very top.
+    // Sort-merge the described ranges, then keep the three largest gaps
+    // (resource slots are bounded at 8 per device; ECAM + bus range + 3 + the
+    // high aperture fits). Above 4 GiB one aperture runs from the end of the
+    // described space to the 46-bit line.
+    const Range = struct { base: u64, end: u64 };
+    var below: [64]Range = undefined;
+    var below_count: usize = 0;
+    var high_end: u64 = 1 << 32;
+    for (boot_memory_regions) |region| {
+        const end = region.base + region.pages * 4096;
+        // Above 4 GiB only *usable RAM* blocks the aperture: OVMF describes
+        // its own 64-bit PCI window as a reserved region and then programs
+        // BARs inside it — honoring reserved there would exclude the very
+        // space BARs live in. Below 4 GiB every described region blocks (the
+        // kernel image, the tables, the ramdisk all live there). Bring-up
+        // trust: only the bridge's claimant can register into the aperture.
+        if (region.kind == .usable and end > high_end) high_end = end;
+        if (region.base >= (1 << 32) or below_count == below.len) continue;
+        below[below_count] = .{ .base = region.base, .end = @min(end, 1 << 32) };
+        below_count += 1;
+    }
+    // Insertion sort by base (the map is small and this runs once at boot).
+    for (1..below_count) |i| {
+        const key = below[i];
+        var j = i;
+        while (j > 0 and below[j - 1].base > key.base) : (j -= 1) below[j] = below[j - 1];
+        below[j] = key;
+    }
+    // Walk the sorted ranges, collecting inter-region gaps of at least 1 MiB.
+    var gaps: [3]Range = .{Range{ .base = 0, .end = 0 }} ** 3;
+    var cursor: u64 = 0;
+    var index: usize = 0;
+    while (index <= below_count) : (index += 1) {
+        const gap_end = if (index == below_count) (1 << 32) else below[index].base;
+        if (gap_end > cursor and gap_end - cursor >= (1 << 20)) {
+            // Keep the three largest, replacing the smallest kept so far.
+            var smallest: usize = 0;
+            for (gaps, 0..) |gap, gi| {
+                if (gap.end - gap.base < gaps[smallest].end - gaps[smallest].base) smallest = gi;
+            }
+            if (gap_end - cursor > gaps[smallest].end - gaps[smallest].base) {
+                gaps[smallest] = .{ .base = cursor, .end = gap_end };
             }
         }
+        if (index < below_count and below[index].end > cursor) cursor = below[index].end;
     }
-}
-
-/// Record and size the memory/IO windows named by a device's Base Address
-/// Registers. Sizing is the standard probe: disable decode, write all-ones, read
-/// back the writable (address) bits, restore. `size = ~mask + 1`.
-fn addBars(node: *device_model.Device, configuration: [*]align(1) u8) void {
-    // Stop the device decoding its BARs while we transiently write all-ones.
-    const command = rd(u16, configuration, 0x04);
-    wr(u16, configuration, 0x04, command & ~@as(u16, 0b11));
-
-    var i: usize = 0;
-    while (i < 6) : (i += 1) {
-        const off = 0x10 + i * 4;
-        const orig = rd(u32, configuration, off);
-        if (orig == 0) continue;
-
-        if (orig & 1 != 0) {
-            // I/O-space BAR (16-bit address space on x86).
-            wr(u32, configuration, off, 0xFFFF_FFFF);
-            const readback = rd(u32, configuration, off);
-            wr(u32, configuration, off, orig);
-            const mask = readback & 0xFFFF_FFFC;
-            const size: u32 = if (mask == 0) 0 else (~mask +% 1) & 0xFFFF;
-            _ = node.addResource(.io_port, orig & 0xFFFF_FFFC, size);
-        } else if ((orig >> 1) & 0x3 == 2) {
-            // 64-bit memory BAR: this BAR pair spans two configuration slots.
-            const orig_hi = rd(u32, configuration, off + 4);
-            wr(u32, configuration, off, 0xFFFF_FFFF);
-            wr(u32, configuration, off + 4, 0xFFFF_FFFF);
-            const lo = rd(u32, configuration, off);
-            const hi = rd(u32, configuration, off + 4);
-            wr(u32, configuration, off, orig);
-            wr(u32, configuration, off + 4, orig_hi);
-            const readback = (@as(u64, hi) << 32) | (lo & 0xFFFF_FFF0);
-            const size: u64 = if (readback == 0) 0 else ~readback +% 1;
-            const address = (@as(u64, orig_hi) << 32) | (orig & 0xFFFF_FFF0);
-            _ = node.addResource(.memory, address, size);
-            i += 1; // consumed the high half
-        } else {
-            // 32-bit memory BAR.
-            wr(u32, configuration, off, 0xFFFF_FFFF);
-            const readback = rd(u32, configuration, off);
-            wr(u32, configuration, off, orig);
-            const mask = readback & 0xFFFF_FFF0;
-            const size: u32 = if (mask == 0) 0 else ~mask +% 1;
-            _ = node.addResource(.memory, orig & 0xFFFF_FFF0, size);
-        }
+    for (gaps) |gap| {
+        if (gap.end > gap.base) _ = bridge.addResource(.memory, gap.base, gap.end - gap.base);
     }
-
-    wr(u16, configuration, 0x04, command); // restore decode
+    _ = bridge.addResource(.memory, high_end, (@as(u64, 1) << 46) - high_end);
 }
 
 /// HPET -> a timer node with its register block as an MMIO resource, plus the GSI
@@ -709,6 +695,7 @@ const fadt_pm1a_cnt_blk = 64; // u32 (I/O port)
 const fadt_pm1b_cnt_blk = 68; // u32 (I/O port)
 const fadt_pm_tmr_blk = 76; // u32 (I/O port) — the PM timer counter
 const fadt_pm1_cnt_len = 89; // u8 (bytes)
+const fadt_sci_int = 46; // u16 (the SCI's GSI)
 const fadt_flags = 112; // u32
 const fadt_reset_register = 116; // GAS (12 bytes)
 const fadt_reset_value = 128; // u8
@@ -719,13 +706,14 @@ const fadt_x_pm_tmr_blk = 208; // GAS
 const flag_reset_register_supported = 1 << 10;
 const flag_tmr_value_ext = 1 << 8; // PM timer counter is 32-bit (else 24-bit)
 
-/// FADT -> the power register map (into `power_information`) and the DSDT address, which
-/// is queued for the AML sleep-state (`_Sx`) scan. No AML interpretation happens here.
+/// FADT -> the power register map (into `power_information`) and the DSDT address,
+/// whose bytecode is collected for the ring-3 parse. No AML interpretation here.
 fn parseFadt(header: *const SystemDescriptorTableHeader) void {
     const base: [*]align(1) const u8 = @ptrCast(header);
     const len: usize = header.length;
     const pi = &power_information;
 
+    pi.sci_interrupt = @truncate(fadt(u16, base, len, fadt_sci_int) orelse 0);
     pi.smi_cmd = @truncate(fadt(u32, base, len, fadt_smi_cmd) orelse 0);
     pi.acpi_enable = fadt(u8, base, len, fadt_acpi_enable) orelse 0;
     pi.acpi_disable = fadt(u8, base, len, fadt_acpi_disable) orelse 0;
@@ -805,337 +793,6 @@ fn parseDmar(hal: Hal, header: *const SystemDescriptorTableHeader) void {
     }
 }
 
-// --- AML namespace -> generic device tree -----------------------------------
-
-/// The PCI bus context while descending the ACPI namespace: the generic host
-/// bridge whose children ACPI address (`_ADR`) devices resolve against, and the bus number.
-const PciContext = struct { bridge: *device_model.Device, bus: u8 };
-
-/// Mirror the ACPI namespace's Device objects into the generic tree, *merging*
-/// them with the PCI-enumerated nodes: a PCI root bridge (`PNP0A03`/`PNP0A08`)
-/// folds onto the existing `pci_host_bridge`, and each addressed (`_ADR`) device folds onto
-/// the matching PCI function (annotating it with the ACPI hardware ID (`_HID`) and nesting the
-/// ACPI-only children — keyboard, RTC, … — beneath it). Namespace devices with no
-/// PCI match land under a synthetic `acpi` node.
-fn wireAcpiDevices(device_tree: *DeviceTree, aml_namespace: *aml.Namespace, hal: Hal) !void {
-    var arena = std.heap.ArenaAllocator.init(device_tree.allocator);
-    defer arena.deinit();
-    var interpreter = aml.Interpreter.init(aml_namespace, .{
-        .mapMmio = hal.mapMmio,
-        .pioRead = hal.pioRead,
-        .pioWrite = hal.pioWrite,
-    }, arena.allocator());
-
-    const acpi_root = try device_tree.addChild(device_tree.root, .unknown, "acpi");
-    try mirrorDevices(device_tree, aml_namespace.root, acpi_root, null, &interpreter);
-}
-
-fn mirrorDevices(device_tree: *DeviceTree, node: *aml.Node, parent_device: *device_model.Device, context: ?PciContext, interpreter: *aml.Interpreter) (error{OutOfMemory})!void {
-    var child = node.first_child;
-    while (child) |c| : (child = c.next_sibling) {
-        if (c.kind != .device) {
-            // A scope — the System Bus (\_SB), General Purpose Events (\_GPE), … —
-            // descend without adding a node.
-            try mirrorDevices(device_tree, c, parent_device, context, interpreter);
-            continue;
-        }
-
-        // Skip devices the firmware reports as not present (via a device-status (`_STA`) method),
-        // along with their whole subtree — per the ACPI rules.
-        if (!devicePresent(interpreter, c)) continue;
-
-        var mirrored_device: *device_model.Device = undefined;
-        var child_context = context;
-
-        if (isPciRootNode(c)) {
-            // The PCI root bridge folds onto the generic host bridge.
-            mirrored_device = matchHostBridge(device_tree) orelse
-                try device_tree.addChild(parent_device, .acpi_device, &c.segment);
-            child_context = .{ .bridge = mirrored_device, .bus = 0 };
-        } else {
-            // An addressed device folds onto its matching PCI function; anything
-            // else becomes a fresh node under the current parent.
-            mirrored_device = pick: {
-                if (context) |pc| {
-                    if (readAdr(c)) |adr| {
-                        if (findPciNode(pc.bridge, pc.bus, adr)) |pnode| break :pick pnode;
-                    }
-                }
-                break :pick try device_tree.addChild(parent_device, .acpi_device, &c.segment);
-            };
-        }
-
-        applyHid(mirrored_device, c, interpreter);
-        applyCrs(mirrored_device, c, interpreter);
-        try mirrorDevices(device_tree, c, mirrored_device, child_context, interpreter);
-    }
-}
-
-/// Evaluate a device's status (`_STA`) to decide if it is present. An absent status
-/// (`_STA`) means present by default; an evaluation failure is treated as present too (we'd
-/// rather over-report than hide a device we couldn't introspect).
-fn devicePresent(interpreter: *aml.Interpreter, node: *aml.Node) bool {
-    const sta = aml.Namespace.childOf(node, seg4("_STA")) orelse return true;
-    const obj = interpreter.evaluate(sta, &.{}) catch return true;
-    const status = obj.asInteger() catch return true;
-    return (status & 0x01) != 0; // bit 0 = present
-}
-
-/// The first PCI host bridge in the generic tree (segment 0).
-fn matchHostBridge(device_tree: *DeviceTree) ?*device_model.Device {
-    var c = device_tree.root.first_child;
-    while (c) |ch| : (c = ch.next_sibling) {
-        if (ch.class == .pci_host_bridge) return ch;
-    }
-    return null;
-}
-
-/// The PCI function node under `bridge` at the address the device's address object
-/// (`_ADR`) names (device/function on
-/// `bus`), or null.
-fn findPciNode(bridge: *device_model.Device, bus: u8, adr: u32) ?*device_model.Device {
-    const device: u16 = @truncate((adr >> 16) & 0x1F);
-    const function: u16 = @truncate(adr & 0x7);
-    const target: u16 = (@as(u16, bus) << 8) | (device << 3) | function;
-    var c = bridge.first_child;
-    while (c) |ch| : (c = ch.next_sibling) {
-        if (ch.ids.pci_bdf) |bdf| {
-            if (bdf == target) return ch;
-        }
-    }
-    return null;
-}
-
-/// A device's address (`_ADR`) — a static integer Name — or null.
-fn readAdr(node: *aml.Node) ?u32 {
-    const n = aml.Namespace.childOf(node, seg4("_ADR")) orelse return null;
-    if (n.kind != .name) return null;
-    var p: usize = 0;
-    return @truncate(readIntObj(n.value, &p) orelse return null);
-}
-
-/// Whether a namespace device is a PCI(e) host bridge (`PNP0A03` / `PNP0A08`).
-fn isPciRootNode(node: *aml.Node) bool {
-    const hid = aml.Namespace.childOf(node, seg4("_HID")) orelse return false;
-    if (hid.kind != .name or hid.value.len == 0) return false;
-    switch (hid.value[0]) {
-        0x00, 0x01, 0xFF, 0x0A, 0x0B, 0x0C, 0x0E => {
-            var p: usize = 0;
-            const n = readIntObj(hid.value, &p) orelse return false;
-            return n == 0x030AD041 or n == 0x080AD041; // PNP0A03 / PNP0A08
-        },
-        0x0D => {
-            const s = cstr(hid.value[1..]);
-            return std.mem.eql(u8, s, "PNP0A03") or std.mem.eql(u8, s, "PNP0A08");
-        },
-        else => return false,
-    }
-}
-
-/// Read a device's hardware ID (`_HID`) into the generic device: an integer decodes as an EISA
-/// id ("PNP0A03"), a string is taken verbatim. Handles both the common static
-/// Name form and a Method form (evaluated).
-fn applyHid(device: *device_model.Device, node: *aml.Node, interpreter: *aml.Interpreter) void {
-    const hid = aml.Namespace.childOf(node, seg4("_HID")) orelse return;
-    if (hid.kind == .method) {
-        const obj = interpreter.evaluate(hid, &.{}) catch return;
-        switch (obj) {
-            .integer => |n| setEisaHid(device, @truncate(n)),
-            .string => |s| device.setHid(s),
-            else => {},
-        }
-        return;
-    }
-    if (hid.kind != .name or hid.value.len == 0) return;
-    const v = hid.value;
-    switch (v[0]) {
-        0x00, 0x01, 0xFF, 0x0A, 0x0B, 0x0C, 0x0E => {
-            var p: usize = 0;
-            const n = readIntObj(v, &p) orelse return;
-            setEisaHid(device, @truncate(n));
-        },
-        0x0D => device.setHid(cstr(v[1..])), // StringPrefix
-        else => {},
-    }
-}
-
-fn setEisaHid(device: *device_model.Device, id: u32) void {
-    device.ids.acpi_hid = id;
-    var buffer: [8]u8 = undefined;
-    device.setHid(eisaIdToStr(id, &buffer));
-}
-
-/// Parse a device's current resource settings (`_CRS`). The evaluator handles both the static
-/// `Buffer` form (a `Name`) and the method form uniformly, yielding the
-/// ResourceTemplate bytes we then decode.
-fn applyCrs(device: *device_model.Device, node: *aml.Node, interpreter: *aml.Interpreter) void {
-    const crs = aml.Namespace.childOf(node, seg4("_CRS")) orelse return;
-    const obj = interpreter.evaluate(crs, &.{}) catch return;
-    const buffer = switch (obj) {
-        .buffer => |b| b,
-        else => return,
-    };
-    parseResourceTemplate(device, buffer);
-}
-
-/// Walk a ResourceTemplate byte list, adding recognised descriptors as resources.
-fn parseResourceTemplate(device: *device_model.Device, bytes: []const u8) void {
-    var i: usize = 0;
-    while (i < bytes.len) {
-        const tag = bytes[i];
-        if (tag & 0x80 == 0) {
-            // Small descriptor: length in low 3 bits, type in bits [6:3].
-            const len: usize = tag & 0x07;
-            const body = i + 1;
-            if (body + len > bytes.len) break;
-            switch ((tag >> 3) & 0x0F) {
-                0x04 => if (len >= 2) { // IRQ: a 16-bit mask, one resource per set bit
-                    const mask = @as(u16, bytes[body]) | (@as(u16, bytes[body + 1]) << 8);
-                    var b: usize = 0;
-                    while (b < 16) : (b += 1) {
-                        if (mask & (@as(u16, 1) << @intCast(b)) != 0) _ = device.addResource(.irq, b, 1);
-                    }
-                },
-                0x08 => if (len >= 7) { // IO port: minimum at +1, length at +6
-                    _ = device.addResource(.io_port, rd16(bytes, body + 1), bytes[body + 6]);
-                },
-                0x09 => if (len >= 3) { // Fixed IO: base at +0, length at +2
-                    _ = device.addResource(.io_port, rd16(bytes, body), bytes[body + 2]);
-                },
-                0x0F => break, // EndTag
-                else => {},
-            }
-            i = body + len;
-        } else {
-            // Large descriptor: 16-bit length follows the tag.
-            if (i + 3 > bytes.len) break;
-            const len: usize = @intCast(rd16(bytes, i + 1));
-            const body = i + 3;
-            if (body + len > bytes.len) break;
-            switch (tag) {
-                0x85 => if (len >= 17) { // Memory32: minimum at +1, length at +13
-                    _ = device.addResource(.memory, rd32(bytes, body + 1), rd32(bytes, body + 13));
-                },
-                0x86 => if (len >= 9) { // Memory32Fixed: base at +1, length at +5
-                    _ = device.addResource(.memory, rd32(bytes, body + 1), rd32(bytes, body + 5));
-                },
-                0x89 => if (len >= 2) { // Extended IRQ: count at +1, then count u32s
-                    const count = bytes[body + 1];
-                    var k: usize = 0;
-                    while (k < count and body + 2 + k * 4 + 4 <= body + len) : (k += 1) {
-                        _ = device.addResource(.irq, rd32(bytes, body + 2 + k * 4), 1);
-                    }
-                },
-                0x87, 0x88, 0x8A => parseAddressSpace(device, tag, bytes[body .. body + len]),
-                else => {},
-            }
-            i = body + len;
-        }
-    }
-}
-
-/// Word/DWord/QWord address-space descriptors: resource type at [0], then
-/// granularity/minimum/maximum/translation/length, each of width `w`.
-fn parseAddressSpace(device: *device_model.Device, tag: u8, body: []const u8) void {
-    const w: usize = switch (tag) {
-        0x88 => 2, // Word
-        0x87 => 4, // DWord
-        else => 8, // QWord (0x8A)
-    };
-    if (body.len < 3 + 5 * w) return;
-    const minimum = readN(body, 3 + w, w);
-    const length = readN(body, 3 + 4 * w, w);
-    const kind: device_model.ResourceKind = switch (body[0]) {
-        0 => .memory,
-        1 => .io_port,
-        else => .bus_range,
-    };
-    _ = device.addResource(kind, minimum, length);
-}
-
-/// Decode a packed EISA id into its 7-char string (e.g. 0x030AD041 -> "PNP0A03").
-fn eisaIdToStr(id: u32, buffer: *[8]u8) []const u8 {
-    const b0: u16 = @intCast(id & 0xFF);
-    const b1: u16 = @intCast((id >> 8) & 0xFF);
-    const b2: u8 = @truncate(id >> 16);
-    const b3: u8 = @truncate(id >> 24);
-    const mfg = (b0 << 8) | b1;
-    buffer[0] = '@' + @as(u8, @intCast((mfg >> 10) & 0x1F));
-    buffer[1] = '@' + @as(u8, @intCast((mfg >> 5) & 0x1F));
-    buffer[2] = '@' + @as(u8, @intCast(mfg & 0x1F));
-    buffer[3] = hexDigit((b2 >> 4) & 0xF);
-    buffer[4] = hexDigit(b2 & 0xF);
-    buffer[5] = hexDigit((b3 >> 4) & 0xF);
-    buffer[6] = hexDigit(b3 & 0xF);
-    return buffer[0..7];
-}
-
-fn hexDigit(n: u8) u8 {
-    return if (n < 10) '0' + n else 'A' + (n - 10);
-}
-
-fn seg4(comptime s: *const [4:0]u8) [4]u8 {
-    return s[0..4].*;
-}
-
-fn cstr(bytes: []const u8) []const u8 {
-    const index = std.mem.indexOfScalar(u8, bytes, 0) orelse bytes.len;
-    return bytes[0..index];
-}
-
-const PkgLen = struct { value: usize, size: usize };
-
-fn packageLength(bytes: []const u8, p: usize) ?PkgLen {
-    if (p >= bytes.len) return null;
-    const lead = bytes[p];
-    const follow: usize = lead >> 6;
-    if (p + 1 + follow > bytes.len) return null;
-    if (follow == 0) return .{ .value = lead & 0x3F, .size = 1 };
-    var value: usize = lead & 0x0F;
-    var i: usize = 0;
-    while (i < follow) : (i += 1) value |= @as(usize, bytes[p + 1 + i]) << @intCast(4 + i * 8);
-    return .{ .value = value, .size = 1 + follow };
-}
-
-/// Read an AML integer object at `p`, advancing `p` past it.
-fn readIntObj(bytes: []const u8, p: *usize) ?u64 {
-    if (p.* >= bytes.len) return null;
-    const opcode = bytes[p.*];
-    p.* += 1;
-    return switch (opcode) {
-        0x00 => 0,
-        0x01 => 1,
-        0xFF => 0xFF,
-        0x0A => readLE(bytes, p, 1),
-        0x0B => readLE(bytes, p, 2),
-        0x0C => readLE(bytes, p, 4),
-        0x0E => readLE(bytes, p, 8),
-        else => null,
-    };
-}
-
-fn readLE(bytes: []const u8, p: *usize, n: usize) ?u64 {
-    if (p.* + n > bytes.len) return null;
-    const v = readN(bytes, p.*, n);
-    p.* += n;
-    return v;
-}
-
-fn readN(bytes: []const u8, off: usize, n: usize) u64 {
-    var v: u64 = 0;
-    var k: usize = 0;
-    while (k < n and off + k < bytes.len) : (k += 1) v |= @as(u64, bytes[off + k]) << @intCast(k * 8);
-    return v;
-}
-
-fn rd16(bytes: []const u8, off: usize) u64 {
-    return readN(bytes, off, 2);
-}
-
-fn rd32(bytes: []const u8, off: usize) u64 {
-    return readN(bytes, off, 4);
-}
-
 // --- helpers ----------------------------------------------------------------
 
 /// Sum `len` bytes; an ACPI table/pointer is valid when the low 8 bits are zero.
@@ -1176,58 +833,9 @@ fn readCntRegister(base: [*]align(1) const u8, len: usize, xoff: usize, legacy_o
     return .{ .mmio = false, .address = port, .width = width };
 }
 
-/// The mapped configuration space of one PCI function (its 4 KiB ECAM page). Mapped
-/// writable so BAR sizing can probe it; reads and writes both go through here.
-fn pciConfigurationPtr(alloc: McfgAllocation, hal: Hal, bus: u8, device: u8, function: u8) [*]align(1) u8 {
-    const physical = alloc.base_address +
-        (@as(u64, bus - alloc.start_bus) << 20) +
-        (@as(u64, device) << 15) +
-        (@as(u64, function) << 12);
-    // Map the configuration page (writable, for BAR sizing) and use the virtual
-    // address the HAL hands back.
-    return @ptrFromInt(hal.mapMmio(physical, abi.page_size, true));
-}
-
 /// Read a little-endian integer at `off` from a (possibly unaligned) byte pointer.
 /// x86 is little-endian and native, so an unaligned load suffices.
 fn rd(comptime T: type, bytes: [*]align(1) const u8, off: usize) T {
     const p: *align(1) const T = @ptrCast(bytes + off);
     return p.*;
 }
-
-/// Write a little-endian integer at `off` through a (possibly unaligned) pointer.
-fn wr(comptime T: type, bytes: [*]align(1) u8, off: usize, value: T) void {
-    const p: *align(1) T = @ptrCast(bytes + off);
-    p.* = value;
-}
-
-// --- tests ------------------------------------------------------------------
-
-test "eisaIdToStr decodes a packed EISA id" {
-    var buffer: [8]u8 = undefined;
-    // 0x030AD041 is the well-known encoding of "PNP0A03" (PCI root bridge).
-    try std.testing.expectEqualStrings("PNP0A03", eisaIdToStr(0x030AD041, &buffer));
-}
-
-test "parseResourceTemplate extracts IO, IRQ, and fixed memory" {
-    // ResourceTemplate { IO(minimum 0x60, len 8), IRQ(4), Memory32Fixed(0xFED00000, 0x1000) }
-    const runtime = [_]u8{
-        0x47, 0x01, 0x60, 0x00, 0x60, 0x00, 0x01, 0x08, // small IO descriptor
-        0x22, 0x10, 0x00, // small IRQ descriptor (mask bit 4 -> IRQ 4)
-        0x86, 0x09, 0x00, 0x01, 0x00, 0x00, 0xD0, 0xFE, 0x00, 0x10, 0x00, 0x00, // Memory32Fixed
-        0x79, 0x00, // EndTag
-    };
-    var device = device_model.Device{};
-    parseResourceTemplate(&device, &runtime);
-
-    try std.testing.expectEqual(@as(u8, 3), device.resource_count);
-    const rs = device.resources[0..device.resource_count];
-    try std.testing.expectEqual(device_model.ResourceKind.io_port, rs[0].kind);
-    try std.testing.expectEqual(@as(u64, 0x60), rs[0].start);
-    try std.testing.expectEqual(@as(u64, 8), rs[0].len);
-    try std.testing.expectEqual(device_model.ResourceKind.irq, rs[1].kind);
-    try std.testing.expectEqual(@as(u64, 4), rs[1].start);
-    try std.testing.expectEqual(device_model.ResourceKind.memory, rs[2].kind);
-    try std.testing.expectEqual(@as(u64, 0xFED00000), rs[2].start);
-    try std.testing.expectEqual(@as(u64, 0x1000), rs[2].len);
-}

system/devices/aml/aml.zig

@@ -12,6 +12,11 @@ const std = @import("std");
 const opcode = @import("opcodes.zig");
 const parser = @import("parser.zig");
 
+/// The named AML opcode/prefix bytes (`zero_opcode`, `byte_prefix`, …). Re-exported so
+/// callers that decode raw AML bytes — e.g. the acpi service reading a `_HID` integer —
+/// name the opcodes instead of writing bare 0x0A/0x0B/… literals (docs/coding-standards.md).
+pub const opcodes = @import("opcodes.zig");
+
 pub const Namespace = @import("namespace.zig").Namespace;
 pub const Node = @import("namespace.zig").Node;
 pub const NodeKind = @import("namespace.zig").NodeKind;
@@ -50,6 +55,20 @@ pub fn parse(allocator: std.mem.Allocator, blocks: []const []const u8) !ParseRes
     return .{ .namespace = namespace, .consumed = consumed, .total = total };
 }
 
+/// Count the Device objects in a parsed namespace — what the acpi service
+/// (docs/discovery.md) reports, and what the kernel's own parse counts
+/// so the two can be checked equal across the ring-3 move.
+pub fn deviceCount(namespace: *const Namespace) usize {
+    return countKind(namespace.root, .device);
+}
+
+fn countKind(node: *const Node, kind: NodeKind) usize {
+    var n: usize = if (node.kind == kind) 1 else 0;
+    var c = node.first_child;
+    while (c) |child| : (c = child.next_sibling) n += countKind(child, kind);
+    return n;
+}
+
 /// Look up the `\_S{state}` sleep package in a parsed namespace and return its
 /// first two integer elements (SLP_TYP for PM1a / PM1b), or null if absent.
 pub fn sleepState(namespace: *Namespace, state: u8) ?SleepType {
@@ -126,17 +145,22 @@ test "parses a nested namespace and finds the sleep package" {
         // Scope(\_SB) packagelen=0x27
         0x10, 0x27, 0x5C, 0x5F, 0x53, 0x42, 0x5F,
         // Device(PCI0) packagelen=0x1F
-        0x5B, 0x82, 0x1F, 0x50, 0x43, 0x49, 0x30,
+        0x5B, 0x82, 0x1F, 0x50, 0x43,
+        0x49, 0x30,
         // Name(_HID, 0x11)
         0x08, 0x5F, 0x48, 0x49, 0x44, 0x0A, 0x11,
         // Method(MTHD, flags=1) empty, packagelen=0x06
-        0x14, 0x06, 0x4D, 0x54, 0x48, 0x44, 0x01,
+        0x14, 0x06, 0x4D,
+        0x54, 0x48, 0x44, 0x01,
         // Method(CALL, flags=0) { MTHD(Zero) }, packagelen=0x0B
-        0x14, 0x0B, 0x43, 0x41, 0x4C, 0x4C, 0x00, 0x4D, 0x54, 0x48, 0x44, 0x00,
+        0x14, 0x0B, 0x43, 0x41, 0x4C, 0x4C, 0x00, 0x4D,
+        0x54, 0x48, 0x44, 0x00,
         // OperationRegion(DBG0, SystemIO, Word 0x0402, Byte 1)
-        0x5B, 0x80, 0x44, 0x42, 0x47, 0x30, 0x01, 0x0B, 0x02, 0x04, 0x0A, 0x01,
+        0x5B, 0x80, 0x44, 0x42, 0x47, 0x30, 0x01, 0x0B,
+        0x02, 0x04, 0x0A, 0x01,
         // Field(DBG0, flags=1) { DBGB, 8 }, packagelen=0x0B
-        0x5B, 0x81, 0x0B, 0x44, 0x42, 0x47, 0x30, 0x01, 0x44, 0x42, 0x47, 0x42, 0x08,
+        0x5B, 0x81, 0x0B, 0x44, 0x42, 0x47, 0x30, 0x01,
+        0x44, 0x42, 0x47, 0x42, 0x08,
     };
 
     var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
@@ -206,3 +230,31 @@ test "interpreter runs a method with args, arithmetic, and control flow" {
     const lo = try interpreter.evaluate(tst, &.{.{ .integer = 2 }}); // 2+5=7 !> 10 -> 0
     try std.testing.expectEqual(@as(u64, 0), try lo.asInteger());
 }
+
+test "interpreter records Notify(device, code)" {
+    // Device(DEV_) { Name(_HID, 0x030AD041) }   // PNP0A03-ish placeholder
+    // Method(TST_, 0) { Notify(DEV_, 0x80); Return(Zero) }
+    // Encoded: a Device holding a Name, then a Method issuing Notify on it.
+    const blob = [_]u8{
+        0x5B, 0x82, 0x0F, 0x44, 0x45, 0x56, 0x5F, // Device(DEV_) len=0x0F (pkglen + DEV_ + Name)
+        0x08, 0x5F, 0x48, 0x49, 0x44, 0x0C, 0x41, 0xD0, 0x0A, 0x03, // Name(_HID, DWord 0x030AD041)
+        0x14, 0x0F, 0x54, 0x53, 0x54, 0x5F, 0x00, // Method(TST_, 0) len=0x0F (pkglen + TST_ + flags + body)
+        0x86, 0x44, 0x45, 0x56, 0x5F, 0x0A, 0x80, // Notify(DEV_, 0x80)
+        0xA4, 0x00, // Return(Zero)
+    };
+
+    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena.deinit();
+    var result = try parse(arena.allocator(), &.{&blob});
+    const namespace = &result.namespace;
+    const tst = namespace.resolve(namespace.root, false, 0, &.{.{ 'T', 'S', 'T', '_' }}) orelse return error.NoMethod;
+    const dev = namespace.resolve(namespace.root, false, 0, &.{.{ 'D', 'E', 'V', '_' }}) orelse return error.NoDevice;
+
+    var interpreter = Interpreter.init(namespace, .{ .mapMmio = noMap, .pioRead = noRead, .pioWrite = noWrite }, arena.allocator());
+    _ = try interpreter.evaluate(tst, &.{});
+
+    const events = interpreter.takeNotifications();
+    try std.testing.expectEqual(@as(usize, 1), events.len);
+    try std.testing.expectEqual(dev, events[0].node);
+    try std.testing.expectEqual(@as(u64, 0x80), events[0].code);
+}

system/devices/aml/interpreter.zig

@@ -141,6 +141,9 @@ const Frame = struct {
 /// A CreateField binding: a name that indexes into a buffer object.
 const BufferField = struct { buffer: *Node, byte_off: usize, bit_width: u32 };
 
+/// One Notify(device, code) the interpreter executed.
+pub const NotifyEvent = struct { node: *Node, code: u64 };
+
 pub const Interpreter = struct {
     namespace: *Namespace,
     hal: Hal,
@@ -149,6 +152,11 @@ pub const Interpreter = struct {
     dynamic_overrides: std.AutoHashMapUnmanaged(*Node, Object) = .{},
     /// CreateField bindings active for the current evaluation.
     fields: std.AutoHashMapUnmanaged(*Node, BufferField) = .{},
+    /// Notify(device, code) operations the last evaluation executed — a GPE or
+    /// EC handler tells the OS "look at this device" this way. Bounded; the
+    /// caller drains it with `takeNotifications` after `evaluate` (M21).
+    notify_queue: [16]NotifyEvent = undefined,
+    notify_count: usize = 0,
 
     pub fn init(namespace: *Namespace, hal: Hal, arena: std.mem.Allocator) Interpreter {
         return .{ .namespace = namespace, .hal = hal, .arena = arena };
@@ -157,6 +165,7 @@ pub const Interpreter = struct {
     /// Evaluate a namespace object: invoke a Method, read a Name's value, or read a
     /// Field. Resets per-evaluation runtime state first.
     pub fn evaluate(self: *Interpreter, node: *Node, args: []const Object) Error!Object {
+        self.notify_count = 0;
         self.dynamic_overrides.clearRetainingCapacity();
         self.fields.clearRetainingCapacity();
         return self.invoke(node, args);
@@ -267,6 +276,8 @@ pub const Interpreter = struct {
             },
             opcode.to_buffer_opcode => try self.passThroughUnary(current, frame),
 
+            opcode.notify_opcode => try self.notify(current, frame),
+
             opcode.extended_opcode_prefix => try self.ext(current, frame),
 
             // CreateXField: source, index, name  (bit widths differ by op)
@@ -542,6 +553,36 @@ pub const Interpreter = struct {
         try self.storeInto(current, frame, value);
     }
 
+    /// Notify(SuperName, NotifyValue): resolve the named device, evaluate the
+    /// code, and record the pair for the caller to dispatch. AML control flow
+    /// continues (Notify returns nothing).
+    fn notify(self: *Interpreter, current: *Cursor, frame: *Frame) Error!Object {
+        const lead = current.peek() orelse return error.Truncated;
+        var target: ?*Node = null;
+        if (isNameStart(lead)) {
+            const name_path = try current.nameString();
+            target = self.namespace.resolve(frame.scope, name_path.rooted, name_path.parents, name_path.slice());
+        } else {
+            // A non-name SuperName (Local/Arg holding a reference).
+            const obj = try self.term(current, frame);
+            if (obj == .reference) target = obj.reference;
+        }
+        const code = try self.evaluateInteger(current, frame);
+        if (target) |node| {
+            if (self.notify_count < self.notify_queue.len) {
+                self.notify_queue[self.notify_count] = .{ .node = node, .code = code };
+                self.notify_count += 1;
+            }
+        }
+        return .uninitialized;
+    }
+
+    /// The Notify events the last `evaluate` produced. Valid until the next
+    /// `evaluate` clears the queue.
+    pub fn takeNotifications(self: *Interpreter) []const NotifyEvent {
+        return self.notify_queue[0..self.notify_count];
+    }
+
     fn storeInto(self: *Interpreter, current: *Cursor, frame: *Frame, value: Object) Error!void {
         const lead = current.peek() orelse return error.Truncated;
         if (isNameStart(lead)) {

system/devices/device-abi.zig

@@ -28,6 +28,23 @@ pub const DeviceClass = enum(u32) {
     /// A device named in the ACPI namespace (from the DSDT/SSDT), carrying a
     /// hardware ID (`_HID`) and, where static, current resource settings (`_CRS`).
     acpi_device,
+    /// The ACPI tables themselves, published as one node for the user-space acpi
+    /// service (docs/discovery.md): memory resources over the AML blobs,
+    /// a broad io_port grant for OperationRegion access, and the SCI interrupt.
+    /// The one node whose claimant is trusted to run firmware bytecode.
+    acpi_tables,
+    /// One interface of a USB device, registered by the xHCI bus driver. It owns
+    /// no MMIO — it is reached through its controller — so it carries no
+    /// resources; the (class, subclass, protocol) triple that says what it is
+    /// travels in the bus report's identity, not here.
+    usb_device,
+    /// A scanout framebuffer: a linear region of pixel memory the display service
+    /// claims and maps. Unlike the other classes this one is not firmware-discovered
+    /// — the kernel seeds it from the loader's [[boot-handoff]] framebuffer
+    /// (`devices_broker.seedDisplay`). Its one `memory` resource is the framebuffer,
+    /// flagged write-combining; the geometry to interpret it travels in
+    /// `DeviceDescriptor.display`.
+    display,
     unknown,
 };
 
@@ -49,13 +66,46 @@ pub const ResourceDescriptor = extern struct {
     kind: u64, // a ResourceKind value
     start: u64,
     len: u64,
+    /// A bitmask of `resource_flag_*` hints. Zero for a plain register/RAM window;
+    /// the kernel reads it when it maps the resource. Defaulted so every existing
+    /// literal (which never set flags) keeps compiling and lays out identically.
+    flags: u64 = 0,
 };
 
+/// `ResourceDescriptor.flags`: map this `memory` resource **write-combining** rather
+/// than strong-uncacheable — for a framebuffer, where batched bursts to pixel memory
+/// are the whole point (an uncacheable framebuffer blit is glacial). See
+/// `mmio_map` (system/kernel/process.zig) and `setupPat` (…/x86_64/paging.zig).
+pub const resource_flag_write_combining: u64 = 1 << 0;
+
 pub const maximum_device_resources = 8;
 
+/// The byte order of a display's pixels — mirrors the loader's `PixelFormat`
+/// ([[boot-handoff]]) with the same numeric values, but lives here so user space
+/// (which must never import the loader↔kernel handoff) can name it. Only the two
+/// linear 32-bpp layouts a console can paint into exist; see docs/gop.md.
+pub const DisplayFormat = enum(u32) {
+    rgbx = 0, // byte 0 = Red,  1 = Green, 2 = Blue,  3 = reserved
+    bgrx = 1, // byte 0 = Blue, 1 = Green, 2 = Red,   3 = reserved
+};
+
+/// The geometry of a `display` device's framebuffer, carried in its descriptor so a
+/// claiming driver knows how to interpret the pixel bytes its `memory` resource maps.
+/// `pitch` is bytes per row (may exceed `width * 4`; see docs/framebuffer.md).
+pub const DisplayInfo = extern struct {
+    width: u32 = 0, // visible pixels per row
+    height: u32 = 0, // visible rows
+    pitch: u32 = 0, // bytes from one row's start to the next
+    format: u32 = 0, // a DisplayFormat value
+};
+
 /// `DeviceDescriptor.parent` for a device with no parent — a root of the device tree.
 pub const no_parent: u64 = ~@as(u64, 0);
 
+/// `DeviceDescriptor.pci_class` for a device that is not a PCI function. (Zero would be
+/// ambiguous: 0x000000 is a real class code, "unclassified device".)
+pub const no_pci_class: u64 = ~@as(u64, 0);
+
 /// A device, as snapshotted for user space by `device_enumerate`. A driver scans
 /// these to find the hardware it owns, claims it, and maps its MMIO.
 ///
@@ -69,8 +119,18 @@ pub const DeviceDescriptor = extern struct {
     id: u64,
     parent: u64, // a device id, or `no_parent`
     class: u64, // a DeviceClass value
+    // The PCI class/subclass/prog-IF triple packed as 0xCCSSPP when this device is a PCI
+    // function, or `no_pci_class` otherwise. This is how a manager tells *what* a
+    // `pci_device` is (an xHCI controller, an AHCI controller) — decode the triple into
+    // names with the pci-class module.
+    pci_class: u64,
     hid_len: u64,
     resource_count: u64,
     hid: [8]u8,
     resources: [maximum_device_resources]ResourceDescriptor,
+    // Framebuffer geometry, meaningful only when `class` is `DeviceClass.display`
+    // (zeroed otherwise). Kept here — a class-specific field on the shared descriptor —
+    // the same way `pci_class` is meaningful only for `pci_device` and `hid` only for
+    // `acpi_device`.
+    display: DisplayInfo = .{},
 };

system/devices/device-model.zig

@@ -3,7 +3,7 @@
 //! Discovery backends (ACPI today, device-tree later) translate their native
 //! hardware description into this one shape, so the rest of the kernel walks a
 //! plain `Device` tree without knowing which firmware described the machine —
-//! the same discipline `root.zig`'s `MemoryKind` applies to memory and `architecture`
+//! the same discipline `ps2-library.zig`'s `MemoryKind` applies to memory and `architecture`
 //! applies to the CPU.
 //!
 //! This is deliberately minimal: enough to *describe* what was discovered (a
@@ -198,8 +198,7 @@ fn dumpNode(device: *const Device, depth: usize, emit: *const fn ([]const u8) vo
             std.fmt.bufPrint(buffer[indent..], "{s} [{s}] hid={s} ({s})\n", .{ device.name(), @tagName(device.class), device.hid(), desc }) catch return
         else
             std.fmt.bufPrint(buffer[indent..], "{s} [{s}] hid={s}\n", .{ device.name(), @tagName(device.class), device.hid() }) catch return;
-    } else
-        std.fmt.bufPrint(buffer[indent..], "{s} [{s}]\n", .{ device.name(), @tagName(device.class) }) catch return;
+    } else std.fmt.bufPrint(buffer[indent..], "{s} [{s}]\n", .{ device.name(), @tagName(device.class) }) catch return;
     emit(buffer[0 .. indent + body.len]);
 
     // For a PCI function, decode its class code — the (class / subclass / prog-IF)

system/devices/pci-class.zig

@@ -7,6 +7,16 @@
 //! apart. Pure reference data (from the PCI spec; see https://wiki.osdev.org/PCI) — no
 //! hardware access — so it is shared by kernel discovery (the device-tree dump) and any
 //! user-space tool (a future lspci, driver matching).
+//!
+//! The taxonomy is named, not numbered (docs/coding-standards.md, "Named values"): the
+//! base class is a `BaseClass` enum, and each class with defined subclasses gets a
+//! namespace holding its `SubClass` enum (and, where the spec defines them, per-subclass
+//! `ProgIf` enums) — the same shape as `usb-ids.zig`. Code that *means* a specific class
+//! names it (`BaseClass.serial_bus`, `serial_bus.usb.ProgIf.xhci`) rather than writing a
+//! bare 0x0C/0x03/0x30. The `className`/`subclassName`/`progIfName` functions still take
+//! the raw bytes a function reports in its header, because that is what hardware hands us.
+
+const std = @import("std");
 
 /// The three bytes of a PCI class code, unpacked from the `0xCCSSPP` value discovery
 /// records in `Device.ids.pci_class` (CC = base class, SS = subclass, PP = prog-IF).
@@ -22,148 +32,465 @@ pub const ClassCode = struct {
             .prog_if = @intCast(packed_code & 0xFF),
         };
     }
+
+    /// Re-pack the triple into the `0xCCSSPP` form. Lets code name a whole class code
+    /// from its parts — `pack(.{ .base = @intFromEnum(BaseClass.serial_bus), … })` —
+    /// instead of writing the literal 0x0C0330.
+    pub fn pack(self: ClassCode) u24 {
+        return (@as(u24, self.base) << 16) | (@as(u24, self.subclass) << 8) | self.prog_if;
+    }
 };
 
+/// Base class (config byte 0x0B). Non-exhaustive: an unlisted code is a real but
+/// unnamed class, decoded as "Unknown" rather than rejected.
+pub const BaseClass = enum(u8) {
+    unclassified = 0x00,
+    mass_storage = 0x01,
+    network = 0x02,
+    display = 0x03,
+    multimedia = 0x04,
+    memory = 0x05,
+    bridge = 0x06,
+    simple_communication = 0x07,
+    base_system_peripheral = 0x08,
+    input_device = 0x09,
+    docking_station = 0x0A,
+    processor = 0x0B,
+    serial_bus = 0x0C,
+    wireless = 0x0D,
+    intelligent = 0x0E,
+    satellite_communication = 0x0F,
+    encryption = 0x10,
+    signal_processing = 0x11,
+    processing_accelerator = 0x12,
+    non_essential_instrumentation = 0x13,
+    co_processor = 0x40,
+    unassigned = 0xFF,
+    _,
+
+    pub fn name(self: BaseClass) []const u8 {
+        return switch (self) {
+            .unclassified => "Unclassified",
+            .mass_storage => "Mass Storage Controller",
+            .network => "Network Controller",
+            .display => "Display Controller",
+            .multimedia => "Multimedia Controller",
+            .memory => "Memory Controller",
+            .bridge => "Bridge",
+            .simple_communication => "Simple Communication Controller",
+            .base_system_peripheral => "Base System Peripheral",
+            .input_device => "Input Device Controller",
+            .docking_station => "Docking Station",
+            .processor => "Processor",
+            .serial_bus => "Serial Bus Controller",
+            .wireless => "Wireless Controller",
+            .intelligent => "Intelligent Controller",
+            .satellite_communication => "Satellite Communication Controller",
+            .encryption => "Encryption Controller",
+            .signal_processing => "Signal Processing Controller",
+            .processing_accelerator => "Processing Accelerator",
+            .non_essential_instrumentation => "Non-Essential Instrumentation",
+            .co_processor => "Co-Processor",
+            .unassigned => "Unassigned Class (Vendor specific)",
+            _ => "Unknown",
+        };
+    }
+};
+
+// --- Per-class subclass (and prog-IF) taxonomies --------------------------------------
+// One namespace per base class that has defined subclasses, named after the class. Each
+// holds an exhaustive `SubClass` enum (so an unlisted code decodes to the class default,
+// not a wrong name), and, where the spec assigns them, per-subclass `ProgIf` enums.
+
+pub const mass_storage = struct {
+    pub const SubClass = enum(u8) {
+        scsi_bus = 0x00,
+        ide = 0x01,
+        floppy = 0x02,
+        ipi_bus = 0x03,
+        raid = 0x04,
+        ata = 0x05,
+        serial_ata = 0x06,
+        serial_attached_scsi = 0x07,
+        non_volatile_memory = 0x08,
+
+        pub fn name(self: SubClass) []const u8 {
+            return switch (self) {
+                .scsi_bus => "SCSI Bus Controller",
+                .ide => "IDE Controller",
+                .floppy => "Floppy Disk Controller",
+                .ipi_bus => "IPI Bus Controller",
+                .raid => "RAID Controller",
+                .ata => "ATA Controller",
+                .serial_ata => "Serial ATA Controller",
+                .serial_attached_scsi => "Serial Attached SCSI Controller",
+                .non_volatile_memory => "Non-Volatile Memory Controller",
+            };
+        }
+    };
+
+    pub const serial_ata = struct {
+        pub const ProgIf = enum(u8) {
+            vendor_specific = 0x00,
+            ahci = 0x01,
+            serial_storage_bus = 0x02,
+
+            pub fn name(self: ProgIf) []const u8 {
+                return switch (self) {
+                    .vendor_specific => "Vendor Specific Interface",
+                    .ahci => "AHCI 1.0",
+                    .serial_storage_bus => "Serial Storage Bus",
+                };
+            }
+        };
+    };
+
+    pub const non_volatile_memory = struct {
+        pub const ProgIf = enum(u8) {
+            nvmhci = 0x01,
+            nvm_express = 0x02,
+
+            pub fn name(self: ProgIf) []const u8 {
+                return switch (self) {
+                    .nvmhci => "NVMHCI",
+                    .nvm_express => "NVM Express",
+                };
+            }
+        };
+    };
+};
+
+pub const network = struct {
+    pub const SubClass = enum(u8) {
+        ethernet = 0x00,
+        token_ring = 0x01,
+        fddi = 0x02,
+        atm = 0x03,
+        isdn = 0x04,
+        picmg_multi_computing = 0x06,
+        infiniband = 0x07,
+        fabric = 0x08,
+
+        pub fn name(self: SubClass) []const u8 {
+            return switch (self) {
+                .ethernet => "Ethernet Controller",
+                .token_ring => "Token Ring Controller",
+                .fddi => "FDDI Controller",
+                .atm => "ATM Controller",
+                .isdn => "ISDN Controller",
+                .picmg_multi_computing => "PICMG 2.14 Multi Computing Controller",
+                .infiniband => "Infiniband Controller",
+                .fabric => "Fabric Controller",
+            };
+        }
+    };
+};
+
+pub const display = struct {
+    pub const SubClass = enum(u8) {
+        vga_compatible = 0x00,
+        xga = 0x01,
+        three_dimensional = 0x02,
+
+        pub fn name(self: SubClass) []const u8 {
+            return switch (self) {
+                .vga_compatible => "VGA Compatible Controller",
+                .xga => "XGA Controller",
+                .three_dimensional => "3D Controller (Not VGA-Compatible)",
+            };
+        }
+    };
+
+    pub const vga_compatible = struct {
+        pub const ProgIf = enum(u8) {
+            vga = 0x00,
+            compatible_8514 = 0x01,
+
+            pub fn name(self: ProgIf) []const u8 {
+                return switch (self) {
+                    .vga => "VGA Controller",
+                    .compatible_8514 => "8514-Compatible Controller",
+                };
+            }
+        };
+    };
+};
+
+pub const multimedia = struct {
+    pub const SubClass = enum(u8) {
+        video = 0x00,
+        audio = 0x01,
+        telephony = 0x02,
+        audio_device = 0x03,
+
+        pub fn name(self: SubClass) []const u8 {
+            return switch (self) {
+                .video => "Multimedia Video Controller",
+                .audio => "Multimedia Audio Controller",
+                .telephony => "Computer Telephony Device",
+                .audio_device => "Audio Device",
+            };
+        }
+    };
+};
+
+pub const memory = struct {
+    pub const SubClass = enum(u8) {
+        ram = 0x00,
+        flash = 0x01,
+
+        pub fn name(self: SubClass) []const u8 {
+            return switch (self) {
+                .ram => "RAM Controller",
+                .flash => "Flash Controller",
+            };
+        }
+    };
+};
+
+pub const bridge = struct {
+    pub const SubClass = enum(u8) {
+        host = 0x00,
+        isa = 0x01,
+        eisa = 0x02,
+        mca = 0x03,
+        pci_to_pci = 0x04,
+        pcmcia = 0x05,
+        nubus = 0x06,
+        cardbus = 0x07,
+        raceway = 0x08,
+        pci_to_pci_semi_transparent = 0x09,
+        infiniband_to_pci = 0x0A,
+
+        pub fn name(self: SubClass) []const u8 {
+            return switch (self) {
+                .host => "Host Bridge",
+                .isa => "ISA Bridge",
+                .eisa => "EISA Bridge",
+                .mca => "MCA Bridge",
+                .pci_to_pci => "PCI-to-PCI Bridge",
+                .pcmcia => "PCMCIA Bridge",
+                .nubus => "NuBus Bridge",
+                .cardbus => "CardBus Bridge",
+                .raceway => "RACEway Bridge",
+                .pci_to_pci_semi_transparent => "PCI-to-PCI Bridge (Semi-Transparent)",
+                .infiniband_to_pci => "InfiniBand-to-PCI Host Bridge",
+            };
+        }
+    };
+
+    pub const pci_to_pci = struct {
+        pub const ProgIf = enum(u8) {
+            normal_decode = 0x00,
+            subtractive_decode = 0x01,
+
+            pub fn name(self: ProgIf) []const u8 {
+                return switch (self) {
+                    .normal_decode => "Normal Decode",
+                    .subtractive_decode => "Subtractive Decode",
+                };
+            }
+        };
+    };
+};
+
+pub const simple_communication = struct {
+    pub const SubClass = enum(u8) {
+        serial = 0x00,
+        parallel = 0x01,
+        multiport_serial = 0x02,
+        modem = 0x03,
+        gpib = 0x04,
+        smart_card = 0x05,
+
+        pub fn name(self: SubClass) []const u8 {
+            return switch (self) {
+                .serial => "Serial Controller",
+                .parallel => "Parallel Controller",
+                .multiport_serial => "Multiport Serial Controller",
+                .modem => "Modem",
+                .gpib => "IEEE 488.1/2 (GPIB) Controller",
+                .smart_card => "Smart Card Controller",
+            };
+        }
+    };
+
+    pub const serial = struct {
+        pub const ProgIf = enum(u8) {
+            compatible_8250 = 0x00,
+            compatible_16450 = 0x01,
+            compatible_16550 = 0x02,
+            compatible_16650 = 0x03,
+            compatible_16750 = 0x04,
+            compatible_16850 = 0x05,
+            compatible_16950 = 0x06,
+
+            pub fn name(self: ProgIf) []const u8 {
+                return switch (self) {
+                    .compatible_8250 => "8250-Compatible (Generic XT)",
+                    .compatible_16450 => "16450-Compatible",
+                    .compatible_16550 => "16550-Compatible",
+                    .compatible_16650 => "16650-Compatible",
+                    .compatible_16750 => "16750-Compatible",
+                    .compatible_16850 => "16850-Compatible",
+                    .compatible_16950 => "16950-Compatible",
+                };
+            }
+        };
+    };
+};
+
+pub const base_system_peripheral = struct {
+    pub const SubClass = enum(u8) {
+        pic = 0x00,
+        dma = 0x01,
+        timer = 0x02,
+        rtc = 0x03,
+        pci_hot_plug = 0x04,
+        sd_host = 0x05,
+        iommu = 0x06,
+
+        pub fn name(self: SubClass) []const u8 {
+            return switch (self) {
+                .pic => "PIC",
+                .dma => "DMA Controller",
+                .timer => "Timer",
+                .rtc => "RTC Controller",
+                .pci_hot_plug => "PCI Hot-Plug Controller",
+                .sd_host => "SD Host Controller",
+                .iommu => "IOMMU",
+            };
+        }
+    };
+};
+
+pub const input_device = struct {
+    pub const SubClass = enum(u8) {
+        keyboard = 0x00,
+        digitizer_pen = 0x01,
+        mouse = 0x02,
+        scanner = 0x03,
+        gameport = 0x04,
+
+        pub fn name(self: SubClass) []const u8 {
+            return switch (self) {
+                .keyboard => "Keyboard Controller",
+                .digitizer_pen => "Digitizer Pen",
+                .mouse => "Mouse Controller",
+                .scanner => "Scanner Controller",
+                .gameport => "Gameport Controller",
+            };
+        }
+    };
+};
+
+pub const serial_bus = struct {
+    pub const SubClass = enum(u8) {
+        firewire = 0x00,
+        access_bus = 0x01,
+        ssa = 0x02,
+        usb = 0x03,
+        fibre_channel = 0x04,
+        smbus = 0x05,
+        infiniband = 0x06,
+        ipmi = 0x07,
+        sercos = 0x08,
+        canbus = 0x09,
+
+        pub fn name(self: SubClass) []const u8 {
+            return switch (self) {
+                .firewire => "FireWire (IEEE 1394) Controller",
+                .access_bus => "ACCESS Bus Controller",
+                .ssa => "SSA",
+                .usb => "USB Controller",
+                .fibre_channel => "Fibre Channel",
+                .smbus => "SMBus Controller",
+                .infiniband => "InfiniBand Controller",
+                .ipmi => "IPMI Interface",
+                .sercos => "SERCOS Interface (IEC 61491)",
+                .canbus => "CANbus Controller",
+            };
+        }
+    };
+
+    pub const usb = struct {
+        pub const ProgIf = enum(u8) {
+            uhci = 0x00,
+            ohci = 0x10,
+            ehci = 0x20,
+            xhci = 0x30,
+            unspecified = 0x80,
+            device = 0xFE,
+
+            pub fn name(self: ProgIf) []const u8 {
+                return switch (self) {
+                    .uhci => "UHCI Controller",
+                    .ohci => "OHCI Controller",
+                    .ehci => "EHCI (USB2) Controller",
+                    .xhci => "XHCI (USB3) Controller",
+                    .unspecified => "Unspecified",
+                    .device => "USB Device (not a host controller)",
+                };
+            }
+        };
+    };
+};
+
+pub const wireless = struct {
+    pub const SubClass = enum(u8) {
+        irda = 0x00,
+        consumer_ir = 0x01,
+        rf = 0x10,
+        bluetooth = 0x11,
+        broadband = 0x12,
+        ethernet_802_1a = 0x20,
+        ethernet_802_1b = 0x21,
+
+        pub fn name(self: SubClass) []const u8 {
+            return switch (self) {
+                .irda => "iRDA Compatible Controller",
+                .consumer_ir => "Consumer IR Controller",
+                .rf => "RF Controller",
+                .bluetooth => "Bluetooth Controller",
+                .broadband => "Broadband Controller",
+                .ethernet_802_1a => "Ethernet Controller (802.1a)",
+                .ethernet_802_1b => "Ethernet Controller (802.1b)",
+            };
+        }
+    };
+};
+
+// --- Raw-byte decoding (what a function reports in its header) -------------------------
+
+/// The name of an exhaustive class-code enum member, or null if `value` is not one — the
+/// bridge from a raw config byte to a named taxonomy above.
+fn enumName(comptime Enum: type, value: u8) ?[]const u8 {
+    return (std.enums.fromInt(Enum, value) orelse return null).name();
+}
+
 /// Name of the base class (byte 0x0B), e.g. `0x06` -> "Bridge".
 pub fn className(base: u8) []const u8 {
-    return switch (base) {
-        0x00 => "Unclassified",
-        0x01 => "Mass Storage Controller",
-        0x02 => "Network Controller",
-        0x03 => "Display Controller",
-        0x04 => "Multimedia Controller",
-        0x05 => "Memory Controller",
-        0x06 => "Bridge",
-        0x07 => "Simple Communication Controller",
-        0x08 => "Base System Peripheral",
-        0x09 => "Input Device Controller",
-        0x0A => "Docking Station",
-        0x0B => "Processor",
-        0x0C => "Serial Bus Controller",
-        0x0D => "Wireless Controller",
-        0x0E => "Intelligent Controller",
-        0x0F => "Satellite Communication Controller",
-        0x10 => "Encryption Controller",
-        0x11 => "Signal Processing Controller",
-        0x12 => "Processing Accelerator",
-        0x13 => "Non-Essential Instrumentation",
-        0x40 => "Co-Processor",
-        0xFF => "Unassigned Class (Vendor specific)",
-        else => "Unknown",
-    };
+    return @as(BaseClass, @enumFromInt(base)).name();
 }
 
 /// Name of the subclass within its base class, e.g. `(0x06, 0x01)` -> "ISA Bridge".
 /// Subclass `0x80` is "Other" by PCI convention; anything unlisted is "Unknown".
 pub fn subclassName(base: u8, subclass: u8) []const u8 {
-    return switch (base) {
-        0x01 => switch (subclass) {
-            0x00 => "SCSI Bus Controller",
-            0x01 => "IDE Controller",
-            0x02 => "Floppy Disk Controller",
-            0x03 => "IPI Bus Controller",
-            0x04 => "RAID Controller",
-            0x05 => "ATA Controller",
-            0x06 => "Serial ATA Controller",
-            0x07 => "Serial Attached SCSI Controller",
-            0x08 => "Non-Volatile Memory Controller",
-            else => defaultSubclass(subclass),
-        },
-        0x02 => switch (subclass) {
-            0x00 => "Ethernet Controller",
-            0x01 => "Token Ring Controller",
-            0x02 => "FDDI Controller",
-            0x03 => "ATM Controller",
-            0x04 => "ISDN Controller",
-            0x06 => "PICMG 2.14 Multi Computing Controller",
-            0x07 => "Infiniband Controller",
-            0x08 => "Fabric Controller",
-            else => defaultSubclass(subclass),
-        },
-        0x03 => switch (subclass) {
-            0x00 => "VGA Compatible Controller",
-            0x01 => "XGA Controller",
-            0x02 => "3D Controller (Not VGA-Compatible)",
-            else => defaultSubclass(subclass),
-        },
-        0x04 => switch (subclass) {
-            0x00 => "Multimedia Video Controller",
-            0x01 => "Multimedia Audio Controller",
-            0x02 => "Computer Telephony Device",
-            0x03 => "Audio Device",
-            else => defaultSubclass(subclass),
-        },
-        0x05 => switch (subclass) {
-            0x00 => "RAM Controller",
-            0x01 => "Flash Controller",
-            else => defaultSubclass(subclass),
-        },
-        0x06 => switch (subclass) {
-            0x00 => "Host Bridge",
-            0x01 => "ISA Bridge",
-            0x02 => "EISA Bridge",
-            0x03 => "MCA Bridge",
-            0x04 => "PCI-to-PCI Bridge",
-            0x05 => "PCMCIA Bridge",
-            0x06 => "NuBus Bridge",
-            0x07 => "CardBus Bridge",
-            0x08 => "RACEway Bridge",
-            0x09 => "PCI-to-PCI Bridge (Semi-Transparent)",
-            0x0A => "InfiniBand-to-PCI Host Bridge",
-            else => defaultSubclass(subclass),
-        },
-        0x07 => switch (subclass) {
-            0x00 => "Serial Controller",
-            0x01 => "Parallel Controller",
-            0x02 => "Multiport Serial Controller",
-            0x03 => "Modem",
-            0x04 => "IEEE 488.1/2 (GPIB) Controller",
-            0x05 => "Smart Card Controller",
-            else => defaultSubclass(subclass),
-        },
-        0x08 => switch (subclass) {
-            0x00 => "PIC",
-            0x01 => "DMA Controller",
-            0x02 => "Timer",
-            0x03 => "RTC Controller",
-            0x04 => "PCI Hot-Plug Controller",
-            0x05 => "SD Host Controller",
-            0x06 => "IOMMU",
-            else => defaultSubclass(subclass),
-        },
-        0x09 => switch (subclass) {
-            0x00 => "Keyboard Controller",
-            0x01 => "Digitizer Pen",
-            0x02 => "Mouse Controller",
-            0x03 => "Scanner Controller",
-            0x04 => "Gameport Controller",
-            else => defaultSubclass(subclass),
-        },
-        0x0C => switch (subclass) {
-            0x00 => "FireWire (IEEE 1394) Controller",
-            0x01 => "ACCESS Bus Controller",
-            0x02 => "SSA",
-            0x03 => "USB Controller",
-            0x04 => "Fibre Channel",
-            0x05 => "SMBus Controller",
-            0x06 => "InfiniBand Controller",
-            0x07 => "IPMI Interface",
-            0x08 => "SERCOS Interface (IEC 61491)",
-            0x09 => "CANbus Controller",
-            else => defaultSubclass(subclass),
-        },
-        0x0D => switch (subclass) {
-            0x00 => "iRDA Compatible Controller",
-            0x01 => "Consumer IR Controller",
-            0x10 => "RF Controller",
-            0x11 => "Bluetooth Controller",
-            0x12 => "Broadband Controller",
-            0x20 => "Ethernet Controller (802.1a)",
-            0x21 => "Ethernet Controller (802.1b)",
-            else => defaultSubclass(subclass),
-        },
-        else => defaultSubclass(subclass),
+    const named: ?[]const u8 = switch (@as(BaseClass, @enumFromInt(base))) {
+        .mass_storage => enumName(mass_storage.SubClass, subclass),
+        .network => enumName(network.SubClass, subclass),
+        .display => enumName(display.SubClass, subclass),
+        .multimedia => enumName(multimedia.SubClass, subclass),
+        .memory => enumName(memory.SubClass, subclass),
+        .bridge => enumName(bridge.SubClass, subclass),
+        .simple_communication => enumName(simple_communication.SubClass, subclass),
+        .base_system_peripheral => enumName(base_system_peripheral.SubClass, subclass),
+        .input_device => enumName(input_device.SubClass, subclass),
+        .serial_bus => enumName(serial_bus.SubClass, subclass),
+        .wireless => enumName(wireless.SubClass, subclass),
+        else => null,
     };
+    return named orelse defaultSubclass(subclass);
 }
 
 fn defaultSubclass(subclass: u8) []const u8 {
@@ -175,68 +502,34 @@ fn defaultSubclass(subclass: u8) []const u8 {
 /// Returns "" when the prog-IF carries no standard meaning for this class/subclass —
 /// callers just print the hex byte in that case.
 pub fn progIfName(base: u8, subclass: u8, prog_if: u8) []const u8 {
-    return switch (base) {
-        0x01 => switch (subclass) {
-            0x06 => switch (prog_if) { // Serial ATA
-                0x00 => "Vendor Specific Interface",
-                0x01 => "AHCI 1.0",
-                0x02 => "Serial Storage Bus",
-                else => "",
-            },
-            0x08 => switch (prog_if) { // Non-Volatile Memory
-                0x01 => "NVMHCI",
-                0x02 => "NVM Express",
-                else => "",
-            },
-            else => "",
+    const named: ?[]const u8 = switch (@as(BaseClass, @enumFromInt(base))) {
+        .mass_storage => switch (std.enums.fromInt(mass_storage.SubClass, subclass) orelse return "") {
+            .serial_ata => enumName(mass_storage.serial_ata.ProgIf, prog_if),
+            .non_volatile_memory => enumName(mass_storage.non_volatile_memory.ProgIf, prog_if),
+            else => null,
         },
-        0x03 => switch (subclass) {
-            0x00 => switch (prog_if) { // VGA Compatible
-                0x00 => "VGA Controller",
-                0x01 => "8514-Compatible Controller",
-                else => "",
-            },
-            else => "",
+        .display => switch (std.enums.fromInt(display.SubClass, subclass) orelse return "") {
+            .vga_compatible => enumName(display.vga_compatible.ProgIf, prog_if),
+            else => null,
         },
-        0x06 => switch (subclass) {
-            0x04 => switch (prog_if) { // PCI-to-PCI Bridge
-                0x00 => "Normal Decode",
-                0x01 => "Subtractive Decode",
-                else => "",
-            },
-            else => "",
+        .bridge => switch (std.enums.fromInt(bridge.SubClass, subclass) orelse return "") {
+            .pci_to_pci => enumName(bridge.pci_to_pci.ProgIf, prog_if),
+            else => null,
         },
-        0x07 => switch (subclass) {
-            0x00 => switch (prog_if) { // Serial Controller
-                0x00 => "8250-Compatible (Generic XT)",
-                0x01 => "16450-Compatible",
-                0x02 => "16550-Compatible",
-                0x03 => "16650-Compatible",
-                0x04 => "16750-Compatible",
-                0x05 => "16850-Compatible",
-                0x06 => "16950-Compatible",
-                else => "",
-            },
-            else => "",
+        .simple_communication => switch (std.enums.fromInt(simple_communication.SubClass, subclass) orelse return "") {
+            .serial => enumName(simple_communication.serial.ProgIf, prog_if),
+            else => null,
         },
-        0x0C => switch (subclass) {
-            0x03 => switch (prog_if) { // USB Controller
-                0x00 => "UHCI Controller",
-                0x10 => "OHCI Controller",
-                0x20 => "EHCI (USB2) Controller",
-                0x30 => "XHCI (USB3) Controller",
-                0x80 => "Unspecified",
-                0xFE => "USB Device (not a host controller)",
-                else => "",
-            },
-            else => "",
+        .serial_bus => switch (std.enums.fromInt(serial_bus.SubClass, subclass) orelse return "") {
+            .usb => enumName(serial_bus.usb.ProgIf, prog_if),
+            else => null,
         },
-        else => "",
+        else => null,
     };
+    return named orelse "";
 }
 
 test "decodes the common class codes" {
-    const std = @import("std");
     const eq = std.testing.expectEqualStrings;
 
     const isa = ClassCode.unpack(0x06_01_00);
@@ -251,11 +544,25 @@ test "decodes the common class codes" {
     try eq("AHCI 1.0", progIfName(ahci.base, ahci.subclass, ahci.prog_if));
 
     const xhci = ClassCode.unpack(0x0C_03_30);
+    try eq("Serial Bus Controller", className(xhci.base));
     try eq("USB Controller", subclassName(xhci.base, xhci.subclass));
     try eq("XHCI (USB3) Controller", progIfName(xhci.base, xhci.subclass, xhci.prog_if));
+}
 
-    // Unknowns and the "Other" convention.
-    try eq("Other", subclassName(0x02, 0x80));
-    try eq("Unknown", subclassName(0x06, 0x7E));
-    try eq("", progIfName(0x06, 0x00, 0x00)); // host bridge: prog-IF has no standard name
+test "unlisted codes fall back without a wrong name" {
+    const eq = std.testing.expectEqualStrings;
+    try eq("Unknown", className(0x77)); // no such base class
+    try eq("Other", subclassName(0x01, 0x80)); // 0x80 is the PCI "Other" convention
+    try eq("Unknown", subclassName(0x01, 0x7A)); // unlisted mass-storage subclass
+    try eq("", progIfName(0x01, 0x06, 0x7F)); // no standard SATA prog-IF for 0x7F
+    try eq("", progIfName(0x02, 0x00, 0x00)); // class with no prog-IF taxonomy at all
+}
+
+test "named parts pack to the raw triple" {
+    const xhci = ClassCode{
+        .base = @intFromEnum(BaseClass.serial_bus),
+        .subclass = @intFromEnum(serial_bus.SubClass.usb),
+        .prog_if = @intFromEnum(serial_bus.usb.ProgIf.xhci),
+    };
+    try std.testing.expectEqual(@as(u24, 0x0C_03_30), xhci.pack());
 }

system/devices/platform.zig

@@ -22,13 +22,14 @@ pub const Resource = device_model.Resource;
 pub const ResourceKind = device_model.ResourceKind;
 pub const Hal = device_model.Hal;
 pub const PowerInformation = acpi.PowerInformation;
-pub const AmlStats = acpi.AmlStats;
 pub const PlatformInformation = acpi.PlatformInformation;
 pub const RegisterAccess = acpi.RegisterAccess;
 pub const IsoEntry = acpi.IsoEntry;
 pub const Cpu = acpi.Cpu;
 
-/// The register map + sleep types discovery extracted, for logging/diagnostics.
+/// The FADT power register map discovery extracted (PM1 control, reset register),
+/// for kernel reboot and diagnostics. Sleep-state values are userspace's (S5 is
+/// owned by the ring-3 acpi service), so they are not here.
 pub fn powerInformation() PowerInformation {
     return acpi.power_information;
 }
@@ -39,11 +40,6 @@ pub fn platformInformation() PlatformInformation {
     return acpi.platform_information;
 }
 
-/// AML parse integrity/diagnostics (namespace node count, bytes consumed).
-pub fn amlStats() AmlStats {
-    return acpi.aml_stats;
-}
-
 /// The usable logical processors discovered during enumeration — one entry per
 /// core danos may schedule on, each carrying the Local APIC ID an SMP wake targets.
 /// `len` is the hardware's degree of parallelism: how many tasks *could* run at the
@@ -72,7 +68,8 @@ pub fn discover(
     var device_tree = try DeviceTree.init(allocator);
 
     if (boot_information.acpi_rsdp != 0) {
-        try acpi.discover(boot_information.acpi_rsdp, &device_tree, hal);
+        const memory_regions = @as([*]const boot_handoff.MemoryRegion, @ptrFromInt(boot_handoff.physicalToVirtual(boot_information.memory_map.regions)))[0..boot_information.memory_map.len];
+        try acpi.discover(boot_information.acpi_rsdp, memory_regions, &device_tree, hal);
     } else {
         // No ACPI RSDP. A device-tree boot would parse its blob here; today that
         // path is a stub, so this reports the machine described itself no way we
@@ -84,12 +81,8 @@ pub fn discover(
 }
 
 /// Restart the machine. Never returns on success; returns only if no reset method
-/// worked (extremely unlikely). Backend-agnostic entry the kernel calls.
+/// worked (extremely unlikely). Backend-agnostic entry the kernel calls. Soft-off
+/// (S5) is not a kernel operation — the ring-3 acpi service owns it (docs/power.md).
 pub fn reboot(hal: Hal) void {
     power.reboot(hal);
 }
-
-/// Power the machine off (ACPI S5). Never returns on success.
-pub fn shutdown(hal: Hal) void {
-    power.shutdown(hal);
-}

system/devices/power.zig

@@ -1,34 +1,17 @@
-//! Machine power control: enter ACPI mode, reboot, and power off (ACPI S5).
+//! Machine reboot: restart via the FADT reset register, with legacy fallbacks.
 //!
-//! Built entirely on the register map `acpi` extracted from the FADT plus the
-//! sleep-state (`_Sx`) types the AML submodule pulled from the DSDT, driven through the
-//! injected `Hal` (port I/O and MMIO). Nothing here is x86-specific beyond the
-//! well-known legacy reset fallbacks, which are guarded behind the ACPI methods.
-//!
-//! S3 (suspend-to-RAM) is stubbed: it needs a wake trampoline and device
-//! re-initialisation, a milestone of its own.
+//! Built on the register map `acpi` extracted from the FADT, driven through the
+//! injected `Hal` (port I/O and MMIO). Soft-off (ACPI S5) and suspend (S3) are
+//! **not** here: they need the AML sleep-state (`_Sx`) values, which the kernel no
+//! longer parses — the ring-3 acpi service owns power management (it re-parses the
+//! blobs and writes the PM1 control register itself). See docs/power.md. Reboot
+//! stays in the kernel because it needs no AML — only the FADT reset register and
+//! the well-known legacy fallbacks — so it survives as a last-resort restart.
 
 const acpi = @import("acpi.zig");
 const device_model = @import("device-model.zig");
 const Hal = device_model.Hal;
 
-const slp_en: u32 = 1 << 13; // SLP_EN: writing 1 triggers the sleep transition
-const sci_en: u32 = 1 << 0; // SCI_EN in PM1 control: set once ACPI mode is active
-
-/// Switch the platform into ACPI mode if it isn't already, so the PM1 control
-/// register is live. A no-op when the firmware exposes no SMI command port (ACPI
-/// already enabled, as under QEMU/OVMF) — we still verify SCI_EN first.
-pub fn enable(hal: Hal) void {
-    const pi = acpi.power_information;
-    if (!pi.pm1a_cnt.present()) return;
-    if (readRegister(hal, pi.pm1a_cnt) & sci_en != 0) return; // already in ACPI mode
-    if (pi.smi_cmd == 0 or pi.acpi_enable == 0) return; // no way to switch; assume fine
-
-    hal.pioWrite(1, pi.smi_cmd, pi.acpi_enable);
-    var spins: usize = 0;
-    while (readRegister(hal, pi.pm1a_cnt) & sci_en == 0 and spins < 1_000_000) : (spins += 1) {}
-}
-
 /// Restart the machine. Tries the ACPI reset register first, then the two legacy
 /// fallbacks. Returns only if every method failed (very unlikely).
 pub fn reboot(hal: Hal) void {
@@ -48,42 +31,6 @@ pub fn reboot(hal: Hal) void {
     delay();
 }
 
-/// Power the machine off via ACPI S5. Requires the soft-off (`_S5`) sleep type; if
-/// it wasn't found in the AML, there is nothing safe to do and this returns.
-pub fn shutdown(hal: Hal) void {
-    enable(hal);
-    const pi = acpi.power_information;
-    const s5 = pi.s5 orelse return;
-
-    if (pi.pm1a_cnt.present()) {
-        writeRegister(hal, pi.pm1a_cnt, sleepValue(s5.slp_typ_a));
-    }
-    if (pi.pm1b_cnt.present()) {
-        writeRegister(hal, pi.pm1b_cnt, sleepValue(s5.slp_typ_b));
-    }
-    delay();
-}
-
-/// S3 suspend-to-RAM — not implemented (needs a wake path + device re-init).
-pub fn sleepS3(hal: Hal) error{Unsupported}!void {
-    _ = hal;
-    return error.Unsupported;
-}
-
-/// The PM1 control write that requests sleep type `slp_typ`: SLP_TYP in bits
-/// [12:10], SLP_EN in bit 13.
-fn sleepValue(slp_typ: u8) u32 {
-    return (@as(u32, slp_typ & 0x7) << 10) | slp_en;
-}
-
-fn readRegister(hal: Hal, register: acpi.RegisterAccess) u32 {
-    if (register.mmio) {
-        const p: *align(1) volatile u32 = @ptrFromInt(hal.mapMmio(register.address, 4, true));
-        return p.*;
-    }
-    return hal.pioRead(register.width, @intCast(register.address));
-}
-
 fn writeRegister(hal: Hal, register: acpi.RegisterAccess, value: u32) void {
     if (register.mmio) {
         const p: *align(1) volatile u32 = @ptrFromInt(hal.mapMmio(register.address, 4, true));
@@ -93,8 +40,8 @@ fn writeRegister(hal: Hal, register: acpi.RegisterAccess, value: u32) void {
     }
 }
 
-/// A short busy-wait so a reset/power-off takes effect before we fall through to
-/// the next method. The empty asm is an architecture-neutral barrier that keeps the loop
+/// A short busy-wait so a reset takes effect before we fall through to the next
+/// method. The empty asm is an architecture-neutral barrier that keeps the loop
 /// from being optimised away.
 fn delay() void {
     var i: usize = 0;

system/devices/usb-abi.zig

@@ -0,0 +1,945 @@
+//! USB device-framework wire ABI: the set-up packets, standard requests, and standard
+//! descriptors every USB device speaks over its default control pipe, as defined by chapter 9
+//! of the USB 2.0 specification (see https://wiki.osdev.org/Universal_Serial_Bus). Pure data
+//! definitions — no hardware access — shared by the host-controller bus drivers (which build
+//! the requests) and anything that parses what devices return (device naming, driver
+//! matching, configuration). The structs mirror the wire byte-for-byte: multi-byte fields are
+//! little-endian and align(1), so a descriptor can be bit-cast straight out of a transfer
+//! buffer at any offset, and bitmap bytes are packed structs so no caller ever needs a magic
+//! mask. Class, subclass, and protocol code tables live in usb-ids.zig.
+
+pub const DeviceState = enum(u8) {
+    // Immediately after the USB device is attached to the USB system, it is in this state.
+    // The USB specifications do not define the state of a USB device that is detached from
+    // a USB system.
+    attached,
+    // A device is in this state after it has both been attached to the bus, and the VBUS line is
+    // applied to the device (the host controller drives the VBUS at +5V, however this is only
+    // particularly important for hardware developers). In this state, the device must not respond
+    // to any bus transactions. The USB specification recognizes three potential scenarios with
+    // respect to how a device draws power:
+    //    - Self-Powered Devices draw power from an external power source (e.g, a USB printer plugs
+    //      into the wall as well as a USB port). Although the device may be considered
+    //      technically "powered" even before attachment to the USB, it is still only considered
+    //      powered after the VBUS line is applied to the device.
+    //    - Bus-Powered Devices draw power solely from the USB up to 100mA.
+    //    - Self- or Bus-Powered Devices may draw power from either the bus or an external power
+    //      source, depending on the configuration. These devices may change power source at any
+    //      time. If a device is currently self-powered and requires more than 100mA of power, but
+    //      switches to being bus-powered, then the device must return to the Address state.
+    powered,
+    // A device in the powered state enters the default state after receiving a bus reset. In this
+    // state, the device is addressable at the default, reserved address of 0. At this point, the
+    // device is operating at the correct speed. The host is expected to allow 10 milliseconds
+    // before expecting the device to respond to data transfers after reset.
+    default,
+    // A device enters this state after the host assigns it an address via the default control pipe,
+    // which is always accessible whether the device's address has been set or not.
+    address,
+    // A device is in this state after the host examines its possible configurations and selects
+    // one. All endpoint's data toggle bits are initialized to zero when a device enters this state.
+    configured,
+    // When no traffic is observed on the bus for a period of 1 millisecond, a USB device enters
+    // this state, characterized by its low power consumption. The device's address and
+    // configuration settings are maintained while suspended. A device exits the suspended state as
+    // soon as it begins seeing bus activity again. The host is expected to allow 10 milliseconds
+    // before expecting the device to respond to data transfers after resume.
+    suspended,
+};
+
+pub const RequestCode = enum(u8) {
+    get_status = 0,
+    clear_feature = 1,
+    set_feature = 3,
+    set_address = 5,
+    get_descriptor = 6,
+    set_descriptor = 7,
+    get_configuration = 8,
+    set_configuration = 9,
+    get_interface = 10,
+    set_interface = 11,
+    sync_frame = 12,
+    // Non-exhaustive: class-specific requests (HID, mass storage) reuse this byte
+    // field with codes from their own class's namespace — see the class-request
+    // constructors below. Some class codes numerically coincide with a standard
+    // one; the wire byte is what matters, and the constructors set it explicitly.
+    _,
+};
+
+// Direction of an endpoint, from the host's point of view
+pub const EndpointDirection = enum(u1) {
+    out = 0,
+    in = 1,
+};
+
+// Identifier newtypes: distinct wire-sized types for values that identify something on the
+// device rather than count something. Each is a non-exhaustive enum whose values originate
+// in the descriptors below and flow, still typed, into the standard request constructors —
+// so an interface number can never be passed where a configuration value is expected.
+
+// The bus address of a device, assigned by the host with SET_ADDRESS. Addresses are 7 bits
+// wide.
+pub const DeviceAddress = enum(u7) {
+    // The default address every device answers at after a reset, until SET_ADDRESS
+    // completes
+    default = 0,
+    _,
+};
+
+// Identifies a configuration; from ConfigurationDescriptor.configuration_value.
+pub const ConfigurationValue = enum(u8) {
+    // Not configured: returned by GET_CONFIGURATION while the device is in the address
+    // state, and passed to SET_CONFIGURATION to return a configured device to the address
+    // state
+    none = 0,
+    _,
+};
+
+// Identifies an interface within a configuration; from
+// InterfaceDescriptor.interface_number.
+pub const InterfaceNumber = enum(u8) { _ };
+
+// Selects between the alternate settings of one interface; from
+// InterfaceDescriptor.alternate_setting.
+pub const AlternateSetting = enum(u8) {
+    // The default setting of an interface
+    default = 0,
+    _,
+};
+
+// The number of an endpoint within a device, 4 bits wide. The direction bit carried
+// alongside it tells the two endpoints sharing a number apart.
+pub const EndpointNumber = enum(u4) {
+    // Endpoint zero: the default control pipe every device provides
+    default_control = 0,
+    _,
+};
+
+// Index of a STRING descriptor, stored in descriptors that reference a string and passed to
+// GET_DESCRIPTOR to read it.
+pub const StringIndex = enum(u8) {
+    // The device has no string descriptor for this field
+    none = 0,
+    _,
+};
+
+// Characteristics of a device request (the bmRequestType field of a set-up packet). Fields are
+// declared least-significant first: recipient occupies bits 4...0, kind bits 6...5, and
+// direction bit 7.
+pub const RequestType = packed struct(u8) {
+    // The recipient of the request (values 4...31 are reserved)
+    recipient: Recipient,
+    // The type of the request
+    kind: Kind,
+    // Data transfer direction. The value of this bit is ignored when length is zero.
+    direction: Direction,
+
+    pub const Recipient = enum(u5) {
+        device = 0,
+        interface = 1,
+        endpoint = 2,
+        other = 3,
+    };
+
+    pub const Kind = enum(u2) {
+        standard = 0,
+        class = 1,
+        vendor = 2,
+        reserved = 3,
+    };
+
+    pub const Direction = enum(u1) {
+        host_to_device = 0,
+        device_to_host = 1,
+    };
+};
+
+pub const Request = extern struct {
+    // Characteristics of the request
+    request_type: RequestType,
+    // Specific request
+    request_code: RequestCode,
+    // Word-sized field that may (or may not) serve as a parameter to the request, depending
+    // on the specific request. For GET_DESCRIPTOR and SET_DESCRIPTOR, bit-cast a
+    // DescriptorValue into this field.
+    value: u16 align(1),
+    // Word-sized field that may (or may not) serve as a parameter to the request, depending
+    // on the specific request. Typically this field holds an index or an offset value. When
+    // request_type specifies an endpoint or an interface as the recipient, bit-cast an
+    // EndpointIndex or an InterfaceIndex into this field.
+    index: u16 align(1),
+    // Number of bytes to transfer if there is a DATA stage.
+    //   - If this field is non-zero, and request_type indicates a transfer from
+    //     device-to-host, then the device must never return more than length bytes of data.
+    //     However, a device may return less.
+    //   - If this field is non-zero, and request_type indicates a transfer from
+    //     host-to-device, then the host must send exactly length bytes of data. If the host
+    //     sends more than length bytes, the behavior of the device is undefined.
+    length: u16 align(1),
+
+    // The format of the index field when request_type specifies an endpoint as the
+    // recipient. The host should always set the direction bit to zero (but the device
+    // should accept either value) when the endpoint is part of a control pipe.
+    pub const EndpointIndex = packed struct(u16) {
+        // Endpoint number
+        number: EndpointNumber,
+        // Reserved (reset to zero)
+        reserved: u3 = 0,
+        // Selects the OUT or the IN endpoint with the specified endpoint number
+        direction: EndpointDirection,
+        // Reserved (reset to zero)
+        reserved_high: u8 = 0,
+    };
+
+    // The format of the index field when request_type specifies an interface as the
+    // recipient.
+    pub const InterfaceIndex = packed struct(u16) {
+        // Interface number
+        number: u8,
+        // Reserved (reset to zero)
+        reserved: u8 = 0,
+    };
+
+    // The format of the value field of GET_DESCRIPTOR and SET_DESCRIPTOR requests: the
+    // descriptor type in the high byte, and the descriptor index in the low byte. The index
+    // is used to select a specific descriptor (only for CONFIGURATION and STRING
+    // descriptors) when several descriptors of that type are implemented by a device.
+    pub const DescriptorValue = packed struct(u16) {
+        // Descriptor index
+        index: u8 = 0,
+        // Descriptor type
+        kind: DescriptorType,
+    };
+};
+
+// Feature selectors, used as the value field of CLEAR_FEATURE and SET_FEATURE requests. The
+// comment on each value notes the recipient the selector applies to.
+pub const FeatureSelector = enum(u16) {
+    // Halts an endpoint (recipient: endpoint)
+    endpoint_halt = 0,
+    // Enables or disables the device's remote wakeup capability (recipient: device)
+    device_remote_wakeup = 1,
+    // Puts a hi-speed device into a test mode, selected by a TestMode value in the high
+    // byte of the index field (recipient: device)
+    test_mode = 2,
+};
+
+// Test mode selectors, passed in the high byte of the index field of a SET_FEATURE request
+// with the test_mode feature selector. Values 06h...3Fh are reserved for standard test
+// selectors and C0h...FFh for vendor-specific test modes; all other unlisted values are
+// reserved.
+pub const TestMode = enum(u8) {
+    test_j = 0x01,
+    test_k = 0x02,
+    test_se0_nak = 0x03,
+    test_packet = 0x04,
+    test_force_enable = 0x05,
+    _,
+};
+
+// The two bytes returned by a GET_STATUS request directed at a device. Fields are declared
+// least-significant first.
+pub const DeviceStatus = packed struct(u16) {
+    // Whether the device is currently self-powered (as opposed to bus-powered). This bit
+    // cannot be changed with the SET_FEATURE or CLEAR_FEATURE requests.
+    self_powered: bool,
+    // Whether the device is currently enabled to request remote wakeup. Changed with the
+    // SET_FEATURE and CLEAR_FEATURE requests using the device_remote_wakeup feature
+    // selector.
+    remote_wakeup: bool,
+    // Reserved (reset to zero)
+    reserved: u14,
+};
+
+// The two bytes returned by a GET_STATUS request directed at an endpoint. (A GET_STATUS
+// request directed at an interface returns two bytes that are entirely reserved.)
+pub const EndpointStatus = packed struct(u16) {
+    // Whether the endpoint is currently halted. Set with the SET_FEATURE request using the
+    // endpoint_halt feature selector, and cleared with CLEAR_FEATURE.
+    halted: bool,
+    // Reserved (reset to zero)
+    reserved: u15,
+};
+
+// A target for the standard requests that may be directed at the device, an interface, or
+// an endpoint.
+pub const Target = union(enum) {
+    device,
+    interface: InterfaceNumber,
+    endpoint: Request.EndpointIndex,
+
+    fn recipient(target: Target) RequestType.Recipient {
+        return switch (target) {
+            .device => .device,
+            .interface => .interface,
+            .endpoint => .endpoint,
+        };
+    }
+
+    fn index(target: Target) u16 {
+        return switch (target) {
+            .device => 0,
+            .interface => |number| @intFromEnum(number),
+            .endpoint => |endpoint| @bitCast(endpoint),
+        };
+    }
+};
+
+// Constructors for the standard device requests, one per RequestCode. Each returns a
+// ready-to-send set-up packet with the request_type, value, index, and length fields the
+// specification prescribes for that request.
+
+// Reads the status of the given target: bit-cast the two bytes the device returns into a
+// DeviceStatus or an EndpointStatus. (The two bytes returned for an interface are entirely
+// reserved.)
+pub fn getStatus(target: Target) Request {
+    return .{
+        .request_type = .{
+            .recipient = target.recipient(),
+            .kind = .standard,
+            .direction = .device_to_host,
+        },
+        .request_code = .get_status,
+        .value = 0,
+        .index = target.index(),
+        .length = 2,
+    };
+}
+
+// Clears or disables the given feature. A device cannot be taken out of a test mode with
+// this request; test_mode is only cleared by cycling power.
+pub fn clearFeature(feature: FeatureSelector, target: Target) Request {
+    return .{
+        .request_type = .{
+            .recipient = target.recipient(),
+            .kind = .standard,
+            .direction = .host_to_device,
+        },
+        .request_code = .clear_feature,
+        .value = @intFromEnum(feature),
+        .index = target.index(),
+        .length = 0,
+    };
+}
+
+// Sets or enables the given feature. For the test_mode feature selector, use setTestMode
+// instead: the test selector rides in the high byte of the index field.
+pub fn setFeature(feature: FeatureSelector, target: Target) Request {
+    return .{
+        .request_type = .{
+            .recipient = target.recipient(),
+            .kind = .standard,
+            .direction = .host_to_device,
+        },
+        .request_code = .set_feature,
+        .value = @intFromEnum(feature),
+        .index = target.index(),
+        .length = 0,
+    };
+}
+
+// Puts a hi-speed device into the given test mode: a SET_FEATURE request with the test_mode
+// feature selector and the test selector in the high byte of the index field.
+pub fn setTestMode(mode: TestMode) Request {
+    return .{
+        .request_type = .{
+            .recipient = .device,
+            .kind = .standard,
+            .direction = .host_to_device,
+        },
+        .request_code = .set_feature,
+        .value = @intFromEnum(FeatureSelector.test_mode),
+        .index = @as(u16, @intFromEnum(mode)) << 8,
+        .length = 0,
+    };
+}
+
+// Assigns the device its bus address, moving it from the default state to the address
+// state. The device does not answer at the new address until the status stage of this
+// request completes.
+pub fn setAddress(address: DeviceAddress) Request {
+    return .{
+        .request_type = .{
+            .recipient = .device,
+            .kind = .standard,
+            .direction = .host_to_device,
+        },
+        .request_code = .set_address,
+        .value = @intFromEnum(address),
+        .index = 0,
+        .length = 0,
+    };
+}
+
+// Reads a descriptor from the device.
+//   - descriptor_index selects among descriptors of the same type, and is only used for
+//     configuration and string descriptors.
+//   - language_id selects the language of a string descriptor, and is zero otherwise.
+//   - length is the number of bytes to read; a device never returns more than length bytes,
+//     but may return less if the descriptor is shorter.
+pub fn getDescriptor(kind: DescriptorType, descriptor_index: u8, language_id: u16, length: u16) Request {
+    return .{
+        .request_type = .{
+            .recipient = .device,
+            .kind = .standard,
+            .direction = .device_to_host,
+        },
+        .request_code = .get_descriptor,
+        .value = @bitCast(Request.DescriptorValue{ .index = descriptor_index, .kind = kind }),
+        .index = language_id,
+        .length = length,
+    };
+}
+
+// Updates an existing descriptor or adds a new one (optional; many devices do not support
+// this request). The parameters mirror getDescriptor; the descriptor itself is sent in the
+// DATA stage.
+pub fn setDescriptor(kind: DescriptorType, descriptor_index: u8, language_id: u16, length: u16) Request {
+    return .{
+        .request_type = .{
+            .recipient = .device,
+            .kind = .standard,
+            .direction = .host_to_device,
+        },
+        .request_code = .set_descriptor,
+        .value = @bitCast(Request.DescriptorValue{ .index = descriptor_index, .kind = kind }),
+        .index = language_id,
+        .length = length,
+    };
+}
+
+// Reads the currently active configuration: @enumFromInt the byte the device returns into a
+// ConfigurationValue, which is none while the device is not configured.
+pub fn getConfiguration() Request {
+    return .{
+        .request_type = .{
+            .recipient = .device,
+            .kind = .standard,
+            .direction = .device_to_host,
+        },
+        .request_code = .get_configuration,
+        .value = 0,
+        .index = 0,
+        .length = 1,
+    };
+}
+
+// Selects the configuration with the given configuration_value (from
+// ConfigurationDescriptor.configuration_value), moving the device from the address state to
+// the configured state. Selecting none returns the device to the address state.
+pub fn setConfiguration(configuration_value: ConfigurationValue) Request {
+    return .{
+        .request_type = .{
+            .recipient = .device,
+            .kind = .standard,
+            .direction = .host_to_device,
+        },
+        .request_code = .set_configuration,
+        .value = @intFromEnum(configuration_value),
+        .index = 0,
+        .length = 0,
+    };
+}
+
+// Reads the alternate setting currently selected for the given interface: @enumFromInt the
+// byte the device returns into an AlternateSetting.
+pub fn getInterface(interface: InterfaceNumber) Request {
+    return .{
+        .request_type = .{
+            .recipient = .interface,
+            .kind = .standard,
+            .direction = .device_to_host,
+        },
+        .request_code = .get_interface,
+        .value = 0,
+        .index = @intFromEnum(interface),
+        .length = 1,
+    };
+}
+
+// Selects an alternate setting (from InterfaceDescriptor.alternate_setting) for the given
+// interface.
+pub fn setInterface(interface: InterfaceNumber, alternate_setting: AlternateSetting) Request {
+    return .{
+        .request_type = .{
+            .recipient = .interface,
+            .kind = .standard,
+            .direction = .host_to_device,
+        },
+        .request_code = .set_interface,
+        .value = @intFromEnum(alternate_setting),
+        .index = @intFromEnum(interface),
+        .length = 0,
+    };
+}
+
+// Reads the two-byte number of the frame in which the given isochronous endpoint's
+// repeating pattern of transfers begins.
+pub fn syncFrame(endpoint: Request.EndpointIndex) Request {
+    return .{
+        .request_type = .{
+            .recipient = .endpoint,
+            .kind = .standard,
+            .direction = .device_to_host,
+        },
+        .request_code = .sync_frame,
+        .value = 0,
+        .index = @bitCast(endpoint),
+        .length = 2,
+    };
+}
+
+// Class-specific requests. These carry a `kind = .class` request_type and a
+// request_code from the interface's class namespace (not the standard
+// RequestCode set above); the code is written into the same byte field, which
+// is why RequestCode is non-exhaustive. Each is directed at an interface, whose
+// number rides in the index field.
+
+// The HID class request codes (USB HID 1.11 §7.2). Only the ones danos issues
+// are named; the field on the wire is the raw byte.
+pub const HidRequestCode = enum(u8) {
+    get_report = 0x01,
+    get_idle = 0x02,
+    get_protocol = 0x03,
+    set_report = 0x09,
+    set_idle = 0x0A,
+    set_protocol = 0x0B,
+};
+
+// The two protocols a boot-capable HID device can run (USB HID 1.11 §7.2.5).
+// A driver selects `boot` for the simplified fixed-format boot report, usable
+// before a full report-descriptor parser exists.
+pub const HidProtocol = enum(u8) {
+    boot = 0,
+    report = 1,
+};
+
+// SET_PROTOCOL: choose the boot or report protocol on a HID interface.
+pub fn setProtocol(interface: InterfaceNumber, protocol: HidProtocol) Request {
+    return .{
+        .request_type = .{ .recipient = .interface, .kind = .class, .direction = .host_to_device },
+        .request_code = @enumFromInt(@intFromEnum(HidRequestCode.set_protocol)),
+        .value = @intFromEnum(protocol),
+        .index = @intFromEnum(interface),
+        .length = 0,
+    };
+}
+
+// SET_IDLE: bound a HID interface's report rate. `duration` is in 4 ms units
+// (0 means report only on change); `report_id` selects a report (0 = all).
+pub fn setIdle(interface: InterfaceNumber, duration: u8, report_id: u8) Request {
+    return .{
+        .request_type = .{ .recipient = .interface, .kind = .class, .direction = .host_to_device },
+        .request_code = @enumFromInt(@intFromEnum(HidRequestCode.set_idle)),
+        .value = (@as(u16, duration) << 8) | report_id,
+        .index = @intFromEnum(interface),
+        .length = 0,
+    };
+}
+
+// Bulk-Only Mass Storage Reset (USB MSC BOT §3.1): ready a mass-storage
+// interface for the next Command Block Wrapper after a protocol error.
+pub fn bulkOnlyMassStorageReset(interface: InterfaceNumber) Request {
+    return .{
+        .request_type = .{ .recipient = .interface, .kind = .class, .direction = .host_to_device },
+        .request_code = @enumFromInt(0xFF),
+        .value = 0,
+        .index = @intFromEnum(interface),
+        .length = 0,
+    };
+}
+
+// Get Max LUN (USB MSC BOT §3.2): read the highest logical unit number the
+// device supports (0 for a single-LUN flash drive). One byte is returned.
+pub fn getMaxLun(interface: InterfaceNumber) Request {
+    return .{
+        .request_type = .{ .recipient = .interface, .kind = .class, .direction = .device_to_host },
+        .request_code = @enumFromInt(0xFE),
+        .value = 0,
+        .index = @intFromEnum(interface),
+        .length = 1,
+    };
+}
+
+pub const DescriptorType = enum(u8) {
+    device = 1,
+    configuration = 2,
+    string = 3,
+    interface = 4,
+    endpoint = 5,
+    device_qualifier = 6,
+    other_speed_configuration = 7,
+    interface_power = 8,
+    _,
+};
+
+pub const DeviceDescriptor = extern struct {
+    // Size of this descriptor in bytes
+    length: u8,
+    // DEVICE Descriptor Type
+    descriptor_type: DescriptorType,
+    // USB Specification Release Number in Binary-Coded Decimal (i.e, 2.10 is expressed as 210h).
+    // Identifies the release of the USB Specification with with the device and its
+    // descriptors are compliant.
+    bcd_usb: u16 align(1),
+    // Class code (assigned by the USB-IF)
+    //   - This field is reset to zero if each interface within a configuration specifies its own
+    //     class information and the various interfaces operate independently.
+    //   - A value of FFh in this field indicates the device class is vendor-specific.
+    device_class: u8,
+    // Subclass Code (assigned by the USB-IF)
+    //   - The subclass code of a device is qualified by the class code of that device.
+    //   - If device_class is reset to zero, then this field must also be reset to zero.
+    //   - When device_class is not set to FFh, then all values for this field are reserved for
+    //     assignment by the USB-IF.
+    device_subclass: u8,
+    // Protocol code (assigned by the USB-IF)
+    //   - The protocol code of a device is qualified by both the class and subclass codes of
+    //     that device.
+    //   - A value of 00h in this field means that the device may specify class-specific
+    //     protocols on an interface basis, though this is not a requirement.
+    //   - If this field is set to FFh, then the device uses a vendor-specific protocol.
+    device_protocol: u8,
+    // Maximum packet size for endpoint zero (8, 16, 32, or 64 are the only valid options)
+    max_packet_size_0: u8,
+    // Vendor ID (assigned by the USB-IF)
+    vendor_id: u16 align(1),
+    // Product ID (assigned by the USB-IF)
+    product_id: u16 align(1),
+    // Device release number in binary-coded decimal
+    bcd_device: u16 align(1),
+    // Index of STRING descriptor describing manufacturer
+    manufacturer_index: StringIndex,
+    // Index of STRING descriptor describing product
+    product_index: StringIndex,
+    // Index of STRING descriptor describing the device's serial number
+    serial_number_index: StringIndex,
+    // Number of possible configurations
+    configuration_count: u8,
+};
+
+pub const DeviceQualifierDescriptor = extern struct {
+    // Size of this descriptor in bytes
+    length: u8,
+    // DEVICE_QUALIFIER Descriptor Type
+    descriptor_type: DescriptorType,
+    // USB Specification Release Number in Binary-Coded Decimal (i.e, 2.00 is expressed as 200h).
+    // Identifies the release of the USB Specification with with the device and its
+    // descriptors are compliant. This field must be at least 0200h.
+    bcd_usb: u16 align(1),
+    // Class code (assigned by the USB-IF)
+    device_class: u8,
+    // Subclass Code (assigned by the USB-IF)
+    device_subclass: u8,
+    // Protocol code (assigned by the USB-IF)
+    device_protocol: u8,
+    // Maximum packet size for endpoint zero (8, 16, 32, or 64 are the only valid options)
+    max_packet_size_0: u8,
+    // Number of possible configurations
+    configuration_count: u8,
+    // Reserved for future uses, must be zero.
+    reserved: u8,
+};
+
+pub const ConfigurationDescriptor = extern struct {
+    // Size of this descriptor in bytes
+    length: u8,
+    // CONFIGURATION Descriptor Type
+    descriptor_type: DescriptorType,
+    // The total combined length in bytes of all the descriptors returned with the request for
+    // this CONFIGURATION descriptor (including CONFIGURATION, INTERFACE, ENDPOINT, class- and
+    // vendor-specific descriptors).
+    total_length: u16 align(1),
+    // Number of interfaces supported by this configuration
+    interface_count: u8,
+    // Value which when used as an argument in the SET_CONFIGURATION request, causes the device
+    // to assume the configuration described by this descriptor.
+    configuration_value: ConfigurationValue,
+    // Index of STRING descriptor describing this configuration.
+    configuration_index: StringIndex,
+    // Configuration Characteristics
+    attributes: Attributes,
+    // Maximum power consumption of this device from the bus when fully operational and using
+    // this configuration. Expressed in units of 2mA (i.e., a value of 50 in this field
+    // indicates 100mA).
+    //   - A device reports with the attributes field whether the configuration is bus- or
+    //     self-powered, but the device status (retrieved with a GET_STATUS request) reports
+    //     whether the device is currently self-powered.
+    //   - If a device is disconnected from an external power source, it may not draw more
+    //     power from the bus than specified in this field.
+    max_power: u8,
+
+    // Configuration characteristics. Fields are declared least-significant first.
+    pub const Attributes = packed struct(u8) {
+        // Reserved, reset to zero (D4...0)
+        reserved: u5,
+        // Whether Remote Wakeup is supported by this configuration (D5)
+        remote_wakeup: bool,
+        // Self-Powered (D6)
+        //   - false: Device runs on power supplied by the bus
+        //   - true: Device provides a local power source; if max_power is non-zero, the
+        //     device also may use bus power.
+        self_powered: bool,
+        // Reserved, must be set to one for historical reasons (D7)
+        reserved_one: u1,
+    };
+};
+
+// This descriptor describes the configuration of a high-speed device if it were operating at
+// its alternative speed. The structure of the OTHER_SPEED_CONFIGURATION is identical to that
+// of the CONFIGURATION descriptor; the only difference is that the descriptor_type field
+// reflects that the descriptor is an OTHER_SPEED_CONFIGURATION descriptor.
+pub const OtherSpeedConfigurationDescriptor = ConfigurationDescriptor;
+
+pub const InterfaceDescriptor = extern struct {
+    // Size of this descriptor in bytes
+    length: u8,
+    // INTERFACE Descriptor Type
+    descriptor_type: DescriptorType,
+    // Number of this interface. Zero-based value which identifies the index of this interface
+    // in the array of interfaces supported within a configuration.
+    interface_number: InterfaceNumber,
+    // Value used to select the alternate settings described by this INTERFACE descriptor for
+    // the interface with the interface_number in the previous field. This value is zero if
+    // this descriptor describes the default settings for a particular interface.
+    alternate_setting: AlternateSetting,
+    // Number of endpoints used by this interface, not including endpoint zero.
+    endpoint_count: u8,
+    // Class code (assigned by the USB-IF)
+    //   - A value of zero here is reserved for future standardization.
+    //   - If this value is FFh, the interface class is vendor-specific.
+    //   - All other values are reserved for assignment by the USB-IF.
+    interface_class: u8,
+    // Subclass code (assigned by the USB-IF)
+    //   - The subclass code in this field is qualified by the value of the interface_class
+    //     field.
+    //   - If interface_class is reset to zero, then this field must also be reset to zero.
+    //   - If interface_class is not set to the value of FFh, then all values of this field are
+    //     reserved for assignment by the USB-IF.
+    interface_subclass: u8,
+    // Protocol code (assigned by the USB-IF)
+    //   - The protocol code in this field is qualified by the values of the interface_class
+    //     and interface_subclass fields.
+    //   - If an interface supports class-specific requests, then this field identifies the
+    //     protocols that the device uses as defined by the specifications of the device class.
+    //   - If this field is reset to zero, then the device does not use a class-specific
+    //     protocol on this interface.
+    //   - If this field is set to FFh, then the device uses a vendor-specific protocol on
+    //     this interface.
+    interface_protocol: u8,
+    // Index of STRING descriptor describing this interface
+    interface_index: StringIndex,
+};
+
+pub const EndpointDescriptor = extern struct {
+    // Size of this descriptor in bytes
+    length: u8,
+    // ENDPOINT Descriptor Type
+    descriptor_type: DescriptorType,
+    // The address of the endpoint on the USB device described by this descriptor
+    endpoint_address: Address,
+    // The endpoint's attributes
+    attributes: Attributes,
+    // Maximum packet size that this endpoint is capable of sending or receiving. For
+    // isochronous endpoints, this value is used to reserve bus time; the pipe, however, may
+    // not always use all of the reserved bus time.
+    max_packet_size: MaxPacketSize align(1),
+    // Interval for polling a device during a data transfer, expressed in units of microframes
+    // for high-speed devices, and frames for low- and full-speed devices. The exact meaning of
+    // the value in this field depends on the endpoint type and the operating speed of the
+    // device:
+    //   - Full- and High-speed isochronous endpoints, and high-speed interrupt endpoints:
+    //     This field must be in the range from 1 to 16, and is used to calculate the period
+    //     as 2^(interval - 1). That is, a value of 4 calculates to 2^(4 - 1) = 2^3 = 8.
+    //   - Full- and Low-speed interrupt endpoints: This field must be in the range from
+    //     1 to 255.
+    //   - High-speed bulk and control OUT endpoints: This field must be in the range from
+    //     0 to 255, and specifies the maximum NAK rate of the endpoint. A value of zero
+    //     indicates that the endpoint never NAKs; other values indicate at most 1 NAK each
+    //     interval number of microframes.
+    interval: u8,
+
+    // The address of an endpoint. Fields are declared least-significant first.
+    pub const Address = packed struct(u8) {
+        // Endpoint Number (D3...0)
+        number: EndpointNumber,
+        // Reserved, reset to zero (D6...4)
+        reserved: u3,
+        // Direction, ignored for control endpoints (D7)
+        direction: EndpointDirection,
+    };
+
+    // An endpoint's attributes. Fields are declared least-significant first.
+    pub const Attributes = packed struct(u8) {
+        // Transfer Type (D1...0)
+        transfer_type: TransferType,
+        // Synchronization Type; isochronous endpoints only, reserved and reset to zero for
+        // other endpoint types (D3...2)
+        synchronization: Synchronization,
+        // Usage Type; isochronous endpoints only, reserved and reset to zero for other
+        // endpoints (D5...4)
+        usage: Usage,
+        // Reserved, reset to zero (D7...6)
+        reserved: u2,
+    };
+
+    pub const TransferType = enum(u2) {
+        control = 0,
+        isochronous = 1,
+        bulk = 2,
+        interrupt = 3,
+    };
+
+    pub const Synchronization = enum(u2) {
+        none = 0,
+        asynchronous = 1,
+        adaptive = 2,
+        synchronous = 3,
+    };
+
+    pub const Usage = enum(u2) {
+        data = 0,
+        feedback = 1,
+        implicit_feedback_data = 2,
+        _,
+    };
+
+    // The maximum packet size of an endpoint. Fields are declared least-significant first.
+    pub const MaxPacketSize = packed struct(u16) {
+        // Maximum packet size in bytes (bits 10...0)
+        size: u11,
+        // Number of additional transaction opportunities per microframe, for high-speed
+        // isochronous and interrupt endpoints; reserved and reset to zero for other
+        // endpoints (bits 12...11)
+        additional_transactions: AdditionalTransactions,
+        // Reserved, must be reset to zero (bits 15...13)
+        reserved: u3,
+    };
+
+    pub const AdditionalTransactions = enum(u2) {
+        // None (1 transaction per microframe)
+        none = 0,
+        // 1 additional (2 transactions per microframe)
+        one = 1,
+        // 2 additional (3 transactions per microframe)
+        two = 2,
+        _,
+    };
+};
+
+// A STRING descriptor at index zero returns the list of LANGID codes supported by the
+// device; all other indices return a Unicode string. Both forms start with this two-byte
+// header, followed by the variable-length payload:
+//   - index 0: an array of two-byte LANGID codes (wLangID[0] through wLangID[x])
+//   - other indices: a Unicode string of N bytes
+pub const StringDescriptor = extern struct {
+    // Size of this descriptor in bytes
+    length: u8,
+    // STRING Descriptor Type
+    descriptor_type: DescriptorType,
+};
+
+const std = @import("std");
+
+test "wire sizes and offsets match the specification" {
+    const expectEqual = std.testing.expectEqual;
+
+    try expectEqual(8, @sizeOf(Request));
+    try expectEqual(18, @sizeOf(DeviceDescriptor));
+    try expectEqual(10, @sizeOf(DeviceQualifierDescriptor));
+    try expectEqual(9, @sizeOf(ConfigurationDescriptor));
+    try expectEqual(9, @sizeOf(InterfaceDescriptor));
+    try expectEqual(7, @sizeOf(EndpointDescriptor));
+    try expectEqual(2, @sizeOf(StringDescriptor));
+
+    try expectEqual(2, @offsetOf(DeviceDescriptor, "bcd_usb"));
+    try expectEqual(8, @offsetOf(DeviceDescriptor, "vendor_id"));
+    try expectEqual(17, @offsetOf(DeviceDescriptor, "configuration_count"));
+    try expectEqual(2, @offsetOf(ConfigurationDescriptor, "total_length"));
+    try expectEqual(4, @offsetOf(EndpointDescriptor, "max_packet_size"));
+}
+
+test "bitmap packings match the specification" {
+    const expectEqual = std.testing.expectEqual;
+    const expect = std.testing.expect;
+
+    // bmRequestType for GET_DESCRIPTOR: device-to-host | standard | device = 80h
+    const request_type = RequestType{
+        .recipient = .device,
+        .kind = .standard,
+        .direction = .device_to_host,
+    };
+    try expectEqual(0x80, @as(u8, @bitCast(request_type)));
+
+    // wValue for GET_DESCRIPTOR(CONFIGURATION, index 0) = 0200h
+    const descriptor_value = Request.DescriptorValue{ .kind = .configuration };
+    try expectEqual(0x0200, @as(u16, @bitCast(descriptor_value)));
+
+    // wIndex for the IN endpoint 1 = 0081h
+    const endpoint_index = Request.EndpointIndex{ .number = @enumFromInt(1), .direction = .in };
+    try expectEqual(0x0081, @as(u16, @bitCast(endpoint_index)));
+
+    // Endpoint address 81h = IN endpoint 1
+    const address: EndpointDescriptor.Address = @bitCast(@as(u8, 0x81));
+    try expectEqual(1, @intFromEnum(address.number));
+    try expectEqual(.in, address.direction);
+
+    // Endpoint attributes 03h = interrupt transfer
+    const attributes: EndpointDescriptor.Attributes = @bitCast(@as(u8, 0x03));
+    try expectEqual(.interrupt, attributes.transfer_type);
+
+    // wMaxPacketSize 0008h = 8 bytes, no additional transactions
+    const max_packet_size: EndpointDescriptor.MaxPacketSize = @bitCast(@as(u16, 0x0008));
+    try expectEqual(8, max_packet_size.size);
+    try expectEqual(.none, max_packet_size.additional_transactions);
+
+    // Configuration attributes C0h = self-powered, with the historical D7 bit set
+    const configuration_attributes: ConfigurationDescriptor.Attributes = @bitCast(@as(u8, 0xC0));
+    try expect(configuration_attributes.self_powered);
+    try expect(!configuration_attributes.remote_wakeup);
+    try expectEqual(1, configuration_attributes.reserved_one);
+
+    // GET_STATUS words: device 0001h = self-powered; endpoint 0001h = halted
+    const device_status: DeviceStatus = @bitCast(@as(u16, 0x0001));
+    try expect(device_status.self_powered and !device_status.remote_wakeup);
+    const endpoint_status: EndpointStatus = @bitCast(@as(u16, 0x0001));
+    try expect(endpoint_status.halted);
+
+    // DescriptorType is non-exhaustive: class-specific values (HID = 21h) pass through
+    const hid_type: DescriptorType = @enumFromInt(0x21);
+    try expectEqual(0x21, @intFromEnum(hid_type));
+    try expect(hid_type != .device);
+}
+
+pub fn expectRequestBytes(request: Request, expected: [8]u8) !void {
+    try std.testing.expectEqualSlices(u8, &expected, std.mem.asBytes(&request));
+}
+
+test "standard request constructors encode the specification's set-up packets" {
+    try expectRequestBytes(getStatus(.device), .{ 0x80, 0, 0, 0, 0, 0, 2, 0 });
+    try expectRequestBytes(getStatus(.{ .interface = @enumFromInt(3) }), .{ 0x81, 0, 0, 0, 3, 0, 2, 0 });
+    try expectRequestBytes(getStatus(.{ .endpoint = .{ .number = @enumFromInt(2), .direction = .in } }), .{ 0x82, 0, 0, 0, 0x82, 0, 2, 0 });
+    try expectRequestBytes(clearFeature(.endpoint_halt, .{ .endpoint = .{ .number = @enumFromInt(1), .direction = .out } }), .{ 0x02, 1, 0, 0, 0x01, 0, 0, 0 });
+    try expectRequestBytes(setFeature(.device_remote_wakeup, .device), .{ 0x00, 3, 1, 0, 0, 0, 0, 0 });
+    try expectRequestBytes(setTestMode(.test_packet), .{ 0x00, 3, 2, 0, 0, 0x04, 0, 0 });
+    try expectRequestBytes(setAddress(@enumFromInt(5)), .{ 0x00, 5, 5, 0, 0, 0, 0, 0 });
+    try expectRequestBytes(getDescriptor(.device, 0, 0, 18), .{ 0x80, 6, 0, 1, 0, 0, 18, 0 });
+    try expectRequestBytes(getDescriptor(.string, 2, 0x0409, 255), .{ 0x80, 6, 2, 3, 0x09, 0x04, 255, 0 });
+    try expectRequestBytes(setDescriptor(.string, 2, 0x0409, 16), .{ 0x00, 7, 2, 3, 0x09, 0x04, 16, 0 });
+    try expectRequestBytes(getConfiguration(), .{ 0x80, 8, 0, 0, 0, 0, 1, 0 });
+    try expectRequestBytes(setConfiguration(@enumFromInt(1)), .{ 0x00, 9, 1, 0, 0, 0, 0, 0 });
+    try expectRequestBytes(getInterface(@enumFromInt(2)), .{ 0x81, 10, 0, 0, 2, 0, 1, 0 });
+    try expectRequestBytes(setInterface(@enumFromInt(2), @enumFromInt(1)), .{ 0x01, 11, 1, 0, 2, 0, 0, 0 });
+    try expectRequestBytes(syncFrame(.{ .number = @enumFromInt(3), .direction = .in }), .{ 0x82, 12, 0, 0, 0x83, 0, 2, 0 });
+}
+
+test "class request constructors encode the specification's set-up packets" {
+    // bmRequestType for a host-to-device class request to an interface = 0x21;
+    // device-to-host = 0xA1. The request_code byte is the class code, not a
+    // standard one — SET_PROTOCOL 0x0B, SET_IDLE 0x0A, BOT reset 0xFF, Max LUN 0xFE.
+    try expectRequestBytes(setProtocol(@enumFromInt(0), .boot), .{ 0x21, 0x0B, 0, 0, 0, 0, 0, 0 });
+    try expectRequestBytes(setProtocol(@enumFromInt(1), .report), .{ 0x21, 0x0B, 1, 0, 1, 0, 0, 0 });
+    try expectRequestBytes(setIdle(@enumFromInt(1), 0, 0), .{ 0x21, 0x0A, 0, 0, 1, 0, 0, 0 });
+    try expectRequestBytes(bulkOnlyMassStorageReset(@enumFromInt(0)), .{ 0x21, 0xFF, 0, 0, 0, 0, 0, 0 });
+    try expectRequestBytes(getMaxLun(@enumFromInt(0)), .{ 0xA1, 0xFE, 0, 0, 0, 0, 1, 0 });
+}

system/devices/usb-ids.zig

@@ -0,0 +1,307 @@
+//! USB class-code decoding: turn the (class, subclass, protocol) triple a USB device or
+//! interface reports in its descriptors into typed values. The device descriptor carries one
+//! triple for the whole device, and each interface descriptor carries its own; a class code
+//! of zero at the device level defers entirely to the interfaces. Subclass and protocol
+//! codes are qualified by the class code — the same value means different things under
+//! different classes — so there is no single SubClass or Protocol enum: each class with
+//! spec-defined codes gets its own namespace below. Pure reference data (from the USB-IF
+//! defined class codes; see https://www.usb.org/defined-class-codes) — no hardware access —
+//! so it is shared by kernel discovery and any user-space tool (device naming, driver
+//! matching).
+
+// Base class codes (assigned by the USB-IF). The comment on each value notes where the code
+// may legally appear: in the device descriptor, in interface descriptors, or both.
+pub const Class = enum(u8) {
+    // Use class information in the interface descriptors (device descriptor only). Each
+    // interface within a configuration specifies its own class information and the various
+    // interfaces operate independently.
+    per_interface = 0x00,
+    // Audio: speakers, microphones, sound cards (interface)
+    audio = 0x01,
+    // Communications and CDC control: modems, network adapters (both)
+    communications = 0x02,
+    // Human Interface Device: keyboards, mice, game controllers (interface)
+    hid = 0x03,
+    // Physical: force-feedback devices (interface)
+    physical = 0x05,
+    // Image: still-imaging cameras, scanners (interface)
+    image = 0x06,
+    // Printer (interface)
+    printer = 0x07,
+    // Mass storage: flash drives, external disks, card readers (interface)
+    mass_storage = 0x08,
+    // Hub (device descriptor only)
+    hub = 0x09,
+    // CDC-Data: the data interfaces paired with a communications control interface
+    // (interface)
+    cdc_data = 0x0A,
+    // Smart card readers (interface)
+    smart_card = 0x0B,
+    // Content security (interface)
+    content_security = 0x0D,
+    // Video: webcams (interface)
+    video = 0x0E,
+    // Personal healthcare devices (interface)
+    personal_healthcare = 0x0F,
+    // Audio/Video devices (interface)
+    audio_video = 0x10,
+    // Billboard: describes alternate modes a USB Type-C device supports (device descriptor
+    // only)
+    billboard = 0x11,
+    // USB Type-C bridge (interface)
+    type_c_bridge = 0x12,
+    // USB Bulk Display Protocol devices (interface)
+    bulk_display = 0x13,
+    // MCTP over USB protocol endpoint devices (interface)
+    mctp = 0x14,
+    // I3C devices (interface)
+    i3c = 0x3C,
+    // Diagnostic devices (both)
+    diagnostic = 0xDC,
+    // Wireless controllers: Bluetooth adapters (interface)
+    wireless_controller = 0xE0,
+    // Miscellaneous (both)
+    miscellaneous = 0xEF,
+    // Application-specific: firmware upgrade, IrDA bridges, test and measurement
+    // (interface)
+    application_specific = 0xFE,
+    // Vendor-specific (both)
+    vendor_specific = 0xFF,
+    _,
+};
+
+// Subclass and protocol codes qualified by Class.hub. Hubs have no subclass codes; the
+// protocol distinguishes the hub's transaction-translator arrangement.
+pub const hub = struct {
+    pub const Protocol = enum(u8) {
+        // Full-speed hub
+        full_speed = 0x00,
+        // Hi-speed hub with a single transaction translator
+        hi_speed_single_tt = 0x01,
+        // Hi-speed hub with multiple transaction translators
+        hi_speed_multi_tt = 0x02,
+        // SuperSpeed hub (USB 3)
+        super_speed = 0x03,
+        _,
+    };
+};
+
+// Subclass and protocol codes qualified by Class.hid.
+pub const hid = struct {
+    pub const SubClass = enum(u8) {
+        // No subclass
+        none = 0x00,
+        // Boot interface: the device also supports the simplified boot protocol, usable by
+        // firmware before a full HID report-descriptor parser is available
+        boot = 0x01,
+        _,
+    };
+
+    // Only meaningful when the subclass is boot
+    pub const Protocol = enum(u8) {
+        none = 0x00,
+        keyboard = 0x01,
+        mouse = 0x02,
+        _,
+    };
+};
+
+// Subclass and protocol codes qualified by Class.mass_storage. The subclass identifies the
+// command set the device understands; the protocol identifies the transport used to carry
+// commands, data, and status over the bus.
+pub const mass_storage = struct {
+    pub const SubClass = enum(u8) {
+        // SCSI command set not reported; de facto, treat as scsi
+        not_reported = 0x00,
+        // Reduced Block Commands: typically flash devices
+        rbc = 0x01,
+        // MMC-5 (ATAPI): CD and DVD drives
+        atapi = 0x02,
+        // QIC-157 tape drives (obsolete)
+        qic_157 = 0x03,
+        // UFI: floppy disk drives
+        ufi = 0x04,
+        // SFF-8070i (obsolete)
+        sff_8070i = 0x05,
+        // Transparent SCSI command set: the common case for flash drives and disks
+        scsi = 0x06,
+        // LSD FS: negotiated access to large storage devices
+        lsd_fs = 0x07,
+        // IEEE 1667
+        ieee_1667 = 0x08,
+        // Vendor-specific
+        vendor_specific = 0xFF,
+        _,
+    };
+
+    pub const Protocol = enum(u8) {
+        // Control/Bulk/Interrupt with command completion interrupt
+        cbi_completion_interrupt = 0x00,
+        // Control/Bulk/Interrupt without command completion interrupt
+        cbi = 0x01,
+        // Bulk-only transport: the common case for flash drives and disks
+        bulk_only = 0x50,
+        // USB attached SCSI
+        uas = 0x62,
+        // Vendor-specific
+        vendor_specific = 0xFF,
+        _,
+    };
+};
+
+// Subclass and protocol codes qualified by Class.communications (CDC). The protocol codes
+// are model-specific; the useful invariant is the subclass, which selects the control model
+// the interface implements.
+pub const communications = struct {
+    pub const SubClass = enum(u8) {
+        // Direct line control model
+        direct_line = 0x01,
+        // Abstract control model: USB modems and serial adapters
+        abstract_control = 0x02,
+        // Telephone control model
+        telephone = 0x03,
+        // Multi-channel control model
+        multi_channel = 0x04,
+        // CAPI control model
+        capi = 0x05,
+        // Ethernet networking control model
+        ethernet = 0x06,
+        // ATM networking control model
+        atm = 0x07,
+        // Wireless handset control model
+        wireless_handset = 0x08,
+        // Device management
+        device_management = 0x09,
+        // Mobile direct line model
+        mobile_direct_line = 0x0A,
+        // OBEX
+        obex = 0x0B,
+        // Ethernet emulation model
+        ethernet_emulation = 0x0C,
+        // Network control model
+        network_control = 0x0D,
+        _,
+    };
+};
+
+// Subclass and protocol codes qualified by Class.wireless_controller.
+pub const wireless_controller = struct {
+    pub const SubClass = enum(u8) {
+        // Radio frequency controllers
+        radio_frequency = 0x01,
+        _,
+    };
+
+    // Only meaningful when the subclass is radio_frequency
+    pub const Protocol = enum(u8) {
+        // Bluetooth programming interface
+        bluetooth = 0x01,
+        // Ultra-wideband radio control
+        ultra_wideband = 0x02,
+        // Remote NDIS
+        remote_ndis = 0x03,
+        // Bluetooth AMP controller
+        bluetooth_amp = 0x04,
+        _,
+    };
+};
+
+// Subclass and protocol codes qualified by Class.miscellaneous.
+pub const miscellaneous = struct {
+    pub const SubClass = enum(u8) {
+        // Common class
+        common = 0x02,
+        _,
+    };
+
+    // Only meaningful when the subclass is common
+    pub const Protocol = enum(u8) {
+        // Interface association descriptor: at the device level, announces that the
+        // configuration groups interfaces into functions with IADs
+        interface_association = 0x01,
+        _,
+    };
+};
+
+// Subclass and protocol codes qualified by Class.application_specific.
+pub const application_specific = struct {
+    pub const SubClass = enum(u8) {
+        // Device firmware upgrade
+        firmware_upgrade = 0x01,
+        // IrDA bridge
+        irda_bridge = 0x02,
+        // Test and measurement
+        test_and_measurement = 0x03,
+        _,
+    };
+};
+
+/// Pack a (class, subclass, protocol) triple into one 0xCCSSPP value — the
+/// bus-native identity a USB bus driver reports in `ChildAdded.identity` and the
+/// device manager matches on (the USB analog of a packed PCI class code). Mirrors
+/// `pci_class.ClassCode.pack`, so both sides build/decode the identical u64.
+pub fn packTriple(class: u8, subclass: u8, protocol: u8) u64 {
+    return (@as(u64, class) << 16) | (@as(u64, subclass) << 8) | protocol;
+}
+
+/// The inverse of `packTriple`.
+pub fn unpackTriple(triple: u64) struct { class: u8, subclass: u8, protocol: u8 } {
+    return .{
+        .class = @truncate(triple >> 16),
+        .subclass = @truncate(triple >> 8),
+        .protocol = @truncate(triple),
+    };
+}
+
+test "class codes match the USB-IF assignments" {
+    const std = @import("std");
+    const expectEqual = std.testing.expectEqual;
+
+    try expectEqual(0x03, @intFromEnum(Class.hid));
+    try expectEqual(0x09, @intFromEnum(Class.hub));
+    try expectEqual(0xFF, @intFromEnum(Class.vendor_specific));
+
+    // A typical flash drive: mass storage, transparent SCSI, bulk-only transport.
+    try expectEqual(0x06, @intFromEnum(mass_storage.SubClass.scsi));
+    try expectEqual(0x50, @intFromEnum(mass_storage.Protocol.bulk_only));
+
+    // A boot keyboard: HID, boot subclass, keyboard protocol.
+    try expectEqual(0x01, @intFromEnum(hid.SubClass.boot));
+    try expectEqual(0x01, @intFromEnum(hid.Protocol.keyboard));
+
+    // Class codes are non-exhaustive: unlisted values pass through undamaged.
+    const unknown: Class = @enumFromInt(0x42);
+    try expectEqual(0x42, @intFromEnum(unknown));
+
+    _ = hub.Protocol.hi_speed_multi_tt;
+    _ = communications.SubClass.abstract_control;
+    _ = wireless_controller.Protocol.bluetooth;
+    _ = miscellaneous.Protocol.interface_association;
+    _ = application_specific.SubClass.firmware_upgrade;
+}
+
+test "packTriple / unpackTriple round-trip the identity a bus driver reports" {
+    const std = @import("std");
+    const expectEqual = std.testing.expectEqual;
+
+    // A boot keyboard interface: HID / boot / keyboard.
+    const keyboard = packTriple(
+        @intFromEnum(Class.hid),
+        @intFromEnum(hid.SubClass.boot),
+        @intFromEnum(hid.Protocol.keyboard),
+    );
+    try expectEqual(@as(u64, 0x03_01_01), keyboard);
+
+    // A flash drive interface: mass storage / SCSI / bulk-only.
+    const storage = packTriple(
+        @intFromEnum(Class.mass_storage),
+        @intFromEnum(mass_storage.SubClass.scsi),
+        @intFromEnum(mass_storage.Protocol.bulk_only),
+    );
+    try expectEqual(@as(u64, 0x08_06_50), storage);
+
+    const parts = unpackTriple(storage);
+    try expectEqual(@as(u8, 0x08), parts.class);
+    try expectEqual(@as(u8, 0x06), parts.subclass);
+    try expectEqual(@as(u8, 0x50), parts.protocol);
+}

system/drivers/bus/bus.zig

@@ -1,210 +0,0 @@
-//! /system/drivers/bus — a user-space **bus driver**, and the smallest honest example of one.
-//!
-//! A bus driver owns a device that *contains other devices*, enumerates them by some
-//! bus-specific protocol, and publishes each one into the kernel's device table so a
-//! class driver can claim it. PCI walks configuration space; USB walks hub descriptors. Here
-//! the "bus" is the HPET's register block and the "devices" are its comparators, each
-//! a 0x20-byte window at 0x100 + 0x20*n that can be driven independently.
-//!
-//! It's a toy bus, but nothing about the mechanism is: `bus` reads how many children
-//! exist from the hardware (GENERAL_CAP bits [12:8]), publishes one `DeviceDescriptor` per
-//! child with a sub-window of its own MMIO plus the shared IRQ, and the kernel checks
-//! every one of those resources is contained in what `bus` was granted. A comparator
-//! driver then claims a child and maps only *its* registers — not the whole block.
-//!
-//! It also proves the negative: registering a child whose window escapes the parent's
-//! is refused. Without that check, `device_register` would be a system_call for mapping
-//! arbitrary physical memory.
-
-const std = @import("std");
-const runtime = @import("runtime");
-const device = runtime.device;
-
-const register_general_cap = 0x000;
-
-/// Comparator n's registers: configuration+comparator+FSB route, 0x20 bytes.
-fn timerWindow(hpet_base: u64, n: u64) device.ResourceDescriptor {
-    return .{
-        .kind = @intFromEnum(device.ResourceKind.memory),
-        .start = hpet_base + 0x100 + 0x20 * n,
-        .len = 0x20,
-    };
-}
-
-fn findHpet(buffer: []device.DeviceDescriptor) ?device.DeviceDescriptor {
-    const total = device.enumerate(buffer);
-    const n = @min(total, buffer.len);
-    for (buffer[0..n]) |d| {
-        if (d.class != @intFromEnum(device.DeviceClass.timer)) continue;
-        if (d.parent != device.no_parent) continue; // the block, not a comparator child
-        for (0..d.resource_count) |j| {
-            if (d.resources[j].kind == @intFromEnum(device.ResourceKind.memory)) return d;
-        }
-    }
-    return null;
-}
-
-/// The parent's MMIO resource, and its IRQ if it has one.
-fn resourcesOf(d: device.DeviceDescriptor) struct { mmio: device.ResourceDescriptor, irq: ?device.ResourceDescriptor } {
-    var mmio: device.ResourceDescriptor = undefined;
-    var irq: ?device.ResourceDescriptor = null;
-    for (0..d.resource_count) |j| {
-        const r = d.resources[j];
-        if (r.kind == @intFromEnum(device.ResourceKind.memory)) mmio = r;
-        if (r.kind == @intFromEnum(device.ResourceKind.irq)) irq = r;
-    }
-    return .{ .mmio = mmio, .irq = irq };
-}
-
-fn firstChildOf(buffer: []device.DeviceDescriptor, total: usize, parent_id: u64) ?u64 {
-    for (buffer[0..@min(total, buffer.len)]) |d| {
-        if (d.parent == parent_id) return d.id;
-    }
-    return null;
-}
-
-pub fn main() void {
-    const buffer = runtime.allocator().alloc(device.DeviceDescriptor, 64) catch {
-        _ = runtime.system.write("bus: out of memory\n");
-        return;
-    };
-
-    const parent = findHpet(buffer) orelse {
-        _ = runtime.system.write("bus: no HPET\n");
-        return;
-    };
-    const resource = resourcesOf(parent);
-
-    // Claim the bus. Everything below is subdivision of what this claim granted.
-    //
-    // Claims are exclusive, and at a normal boot the kernel spawns every initial_ramdisk
-    // binary — so hpet may own the HPET already. That's not an error, it's the
-    // capability model working: exit quietly and leave the device to its owner. The
-    // `bus` test spawns bus alone, so there it wins the claim.
-    if (!device.claim(parent.id)) {
-        _ = runtime.system.write("bus: HPET already claimed by another driver, nothing to do\n");
-        return;
-    }
-
-    // Enumerate the bus: ask the hardware how many children it has.
-    const base = device.mmioMap(parent.id, 0) orelse {
-        _ = runtime.system.write("bus: mmio_map failed\n");
-        return;
-    };
-    const cap: *volatile u64 = @ptrFromInt(base + register_general_cap);
-    const n_children = ((cap.* >> 8) & 0x1F) + 1;
-
-    // Publish one child per comparator, each owning only its own window.
-    var published: u64 = 0;
-    var n: u64 = 0;
-    while (n < n_children) : (n += 1) {
-        var child = std.mem.zeroes(device.DeviceDescriptor);
-        child.class = @intFromEnum(device.DeviceClass.timer);
-        child.hid_len = 6;
-        child.hid[0..6].* = "hpet-t".*;
-        child.resource_count = 1;
-        child.resources[0] = timerWindow(resource.mmio.start, n);
-        // Comparators share the block's interrupt line; only one child can bind it,
-        // but all of them may legitimately name it.
-        if (resource.irq) |i| {
-            child.resources[child.resource_count] = i;
-            child.resource_count += 1;
-        }
-
-        if (device.register(parent.id, &child) == null) {
-            _ = runtime.system.write("bus: register failed\n");
-            return;
-        }
-        published += 1;
-    }
-
-    // The negative case. A window one byte past the end of the parent's must be
-    // refused — otherwise device_register would be "map any physical page you like".
-    // Confirm the table did not grow, not merely that the call returned null: null
-    // also means NoSpace/BadParent, so a size check is what actually proves the
-    // *containment* rule fired.
-    const before = device.enumerate(buffer);
-    var rogue = std.mem.zeroes(device.DeviceDescriptor);
-    rogue.class = @intFromEnum(device.DeviceClass.unknown);
-    rogue.resource_count = 1;
-    rogue.resources[0] = .{
-        .kind = @intFromEnum(device.ResourceKind.memory),
-        .start = resource.mmio.start + resource.mmio.len,
-        .len = 0x1000,
-    };
-    if (device.register(parent.id, &rogue) != null) {
-        _ = runtime.system.write("bus: FAIL out-of-window child was accepted\n");
-        return;
-    }
-    if (device.enumerate(buffer) != before) {
-        _ = runtime.system.write("bus: FAIL rogue child leaked into the table\n");
-        return;
-    }
-
-    // And confirm the children came back with the right parent and a *narrower*
-    // window than the bus — read from the table, not from our own memory.
-    const total = device.enumerate(buffer);
-    var seen: u64 = 0;
-    for (buffer[0..@min(total, buffer.len)]) |d| {
-        if (d.parent != parent.id) continue;
-        const w = d.resources[0];
-        if (w.start < resource.mmio.start or w.len >= resource.mmio.len) {
-            _ = runtime.system.write("bus: FAIL child window is not inside the bus\n");
-            return;
-        }
-        seen += 1;
-    }
-    if (seen != published) {
-        _ = runtime.system.write("bus: FAIL child count mismatch\n");
-        return;
-    }
-
-    // Delegation, end to end: claim a child and map *it*. A real class driver would be
-    // a different process; here bus plays both parts, which exercises the same path.
-    // The child's window is 0x20 bytes at parent+0x100, so the register it sees at
-    // offset 0 must be the same timer-0 configuration register the bus sees at 0x100.
-    //
-    // (mmio_map rounds to a page, so the child's mapping physically covers the whole
-    // 4 KiB the HPET lives in — the granularity limit documented in docs/drivers.md.
-    // The *resource* is narrow even though the page isn't.)
-    const child_id = firstChildOf(buffer, device.enumerate(buffer), parent.id) orelse {
-        _ = runtime.system.write("bus: FAIL no child to claim\n");
-        return;
-    };
-    if (!device.claim(child_id)) {
-        _ = runtime.system.write("bus: FAIL could not claim own child\n");
-        return;
-    }
-    const child_base = device.mmioMap(child_id, 0) orelse {
-        _ = runtime.system.write("bus: FAIL child mmio_map refused\n");
-        return;
-    };
-    const via_child: *volatile u64 = @ptrFromInt(child_base);
-    const via_bus: *volatile u64 = @ptrFromInt(base + 0x100);
-    if (via_child.* != via_bus.*) {
-        _ = runtime.system.write("bus: FAIL child window does not alias the bus register\n");
-        return;
-    }
-
-    // A descriptor pointer into an unmapped page must fail the call, not fault the
-    // kernel. Grab a page, free it, and register through the stale address: if the
-    // kernel dereferenced it raw (rather than copying in through the page tables) this
-    // would triple-fault QEMU and the test would time out instead of printing ok.
-    const scratch = runtime.system.mmap(0x1000, runtime.system.PROT_READ | runtime.system.PROT_WRITE);
-    if (!runtime.system.mmapFailed(scratch)) {
-        _ = runtime.system.munmap(scratch, 0x1000);
-        const descriptor: *const device.DeviceDescriptor = @ptrFromInt(scratch);
-        if (device.register(parent.id, descriptor) != null) {
-            _ = runtime.system.write("bus: FAIL register accepted an unmapped descriptor\n");
-            return;
-        }
-    }
-
-    _ = runtime.system.write("bus: ok\n");
-    while (true) runtime.system.sleep(1000);
-}
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}

system/drivers/hpet/hpet.zig

@@ -1,195 +0,0 @@
-//! /system/drivers/hpet — a user-space HPET driver. It proves the whole driver model end to
-//! end: enumerate the device table, find the HPET, claim it, map its registers into
-//! this ring-3 address space (strong-uncacheable), **bind its interrupt to an IPC
-//! endpoint**, then sit blocked in `replyWait` until the hardware wakes it.
-//!
-//! Nothing here polls. Between interrupts the process is `.blocked` and off every
-//! scheduler queue; the core runs other work or idles. That is the point of the
-//! exercise — a driver is a process that sleeps until its device has something to
-//! say (see docs/drivers.md).
-//!
-//! The comparator is configured **level-triggered** on purpose. Edge would be
-//! simpler, but level is the discipline every real device line needs, and it forces
-//! the full cycle to be correct:
-//!
-//!   kernel ISR   mask the GSI -> EOI -> notify this endpoint
-//!   hpet        wake, clear GENERAL_INT_STATUS (deasserts the line), re-arm
-//!   hpet        irq_ack -> kernel unmasks the GSI
-//!
-//! Clear the status bit *before* acking, or the line is still asserted when the
-//! kernel unmasks and the I/O APIC redelivers forever.
-//!
-//! Register map (HPET spec 1.0a):
-//!   0x000 GENERAL_CAP     [63:32] fs per tick, [12:8] number timers - 1
-//!   0x010 GENERAL_CONFIGURATION  bit0 ENABLE_CNF, bit1 LEG_RT_CNF
-//!   0x020 GENERAL_INT_STATUS  bit n = timer n asserted (write 1 to clear)
-//!   0x0F0 MAIN_COUNTER
-//!   0x100 TIMER0_CONFIGURATION   bit1 INT_TYPE(1=level) bit2 INT_ENB bit3 TYPE(periodic)
-//!                         bits[13:9] INT_ROUTE, [63:32] INT_ROUTE_CAP
-//!   0x108 TIMER0_COMPARATOR
-
-const runtime = @import("runtime");
-const mmio = @import("mmio");
-const device = runtime.device;
-const ipc = runtime.ipc;
-
-const register_general_cap = 0x000;
-const register_general_configuration = 0x010;
-const register_int_status = 0x020;
-const register_main_counter = 0x0F0;
-const register_timer0_configuration = 0x100;
-const register_timer0_comparator = 0x108;
-
-const configuration_enable: u64 = 1 << 0; // GENERAL_CONFIGURATION.ENABLE_CNF
-const configuration_leg_rt: u64 = 1 << 1; // GENERAL_CONFIGURATION.LEG_RT_CNF
-const tn_int_type_level: u64 = 1 << 1;
-const tn_int_enb: u64 = 1 << 2;
-const tn_type_periodic: u64 = 1 << 3;
-const tn_route_shift = 9;
-const tn_route_mask: u64 = 0x1F << tn_route_shift;
-
-/// Interrupts to observe before declaring victory.
-const target_ticks = 5;
-
-/// Read/write a 64-bit HPET register through the typed volatile MMIO layer (/lib/mmio).
-/// The HPET is pure MMIO with no DMA, and on x86 its grant is strong-uncacheable (so
-/// UC writes are already ordered) — no barriers are needed here; the point is the
-/// typed, arch-portable access every driver should use.
-inline fn rd(base: usize, off: usize) u64 {
-    return mmio.read(u64, base + off);
-}
-inline fn wr(base: usize, off: usize, value: u64) void {
-    mmio.write(u64, base + off, value);
-}
-
-/// A timer-class device exposing both an MMIO window and an IRQ: its id, the two
-/// resource indices, and the GSI discovery chose out of `Tn_INT_ROUTE_CAP`.
-const Found = struct { device_id: u64, mmio: u64, irq: u64, gsi: u64 };
-
-fn findHpet(buffer: []device.DeviceDescriptor) ?Found {
-    const total = device.enumerate(buffer);
-    const n = @min(total, buffer.len);
-    for (buffer[0..n]) |d| {
-        if (d.class != @intFromEnum(device.DeviceClass.timer)) continue;
-        // Skip comparator children a bus driver may have published below the block
-        // (see system/drivers/bus/bus.zig) — we want the register block itself.
-        if (d.parent != device.no_parent) continue;
-        var mmio_index: ?u64 = null;
-        var irq: ?u64 = null;
-        for (0..d.resource_count) |j| {
-            switch (d.resources[j].kind) {
-                @intFromEnum(device.ResourceKind.memory) => mmio_index = mmio_index orelse j,
-                @intFromEnum(device.ResourceKind.irq) => irq = irq orelse j,
-                else => {},
-            }
-        }
-        if (mmio_index) |m| if (irq) |i| {
-            return .{ .device_id = d.id, .mmio = m, .irq = i, .gsi = d.resources[i].start };
-        };
-    }
-    return null;
-}
-
-pub fn main() void {
-    // Enumerate into a heap buffer (too big for the one-page user stack).
-    const buffer = runtime.allocator().alloc(device.DeviceDescriptor, 32) catch {
-        _ = runtime.system.write("hpet: out of memory\n");
-        return;
-    };
-
-    const hpet = findHpet(buffer) orelse {
-        _ = runtime.system.write("hpet: no HPET with an IRQ\n");
-        return;
-    };
-
-    if (!device.claim(hpet.device_id)) {
-        _ = runtime.system.write("hpet: claim failed\n");
-        return;
-    }
-    const base = device.mmioMap(hpet.device_id, hpet.mmio) orelse {
-        _ = runtime.system.write("hpet: mmio_map failed\n");
-        return;
-    };
-
-    // The GSI discovery picked for us out of Tn_INT_ROUTE_CAP. Program the comparator
-    // to raise exactly this line — the kernel will only bind the one it recorded.
-    const gsi = hpet.gsi;
-
-    const endpoint = ipc.createIpcEndpoint() orelse {
-        _ = runtime.system.write("hpet: create_ipc_endpoint failed\n");
-        return;
-    };
-
-    // --- program the hardware ------------------------------------------------
-    // Counter period, so we can arm the comparator a fixed wall-clock distance out.
-    const femtos_per_tick = rd(base, register_general_cap) >> 32;
-    if (femtos_per_tick == 0) {
-        _ = runtime.system.write("hpet: bad HPET period\n");
-        return;
-    }
-    const ticks_per_ms = 1_000_000_000_000 / femtos_per_tick;
-
-    // Stop the counter and take the legacy route off while we reconfigure.
-    wr(base, register_general_configuration, rd(base, register_general_configuration) & ~(configuration_enable | configuration_leg_rt));
-
-    // Timer 0: one-shot, level-triggered, routed to our GSI, interrupt enabled.
-    // One-shot (not periodic) sidesteps the HPET's Tn_value_SET accumulator quirk —
-    // we simply re-arm from the driver on each interrupt, which is what a tickless
-    // timer driver does anyway.
-    var t0 = rd(base, register_timer0_configuration);
-    t0 &= ~(tn_route_mask | tn_type_periodic);
-    t0 |= tn_int_type_level | tn_int_enb | (gsi << tn_route_shift);
-    wr(base, register_timer0_configuration, t0);
-
-    // Clear any stale assertion, then arm ~100 ms out and start the counter.
-    wr(base, register_int_status, 1);
-    wr(base, register_timer0_comparator, rd(base, register_main_counter) + ticks_per_ms * 100);
-    wr(base, register_general_configuration, rd(base, register_general_configuration) | configuration_enable);
-
-    if (!device.irqBind(hpet.device_id, hpet.irq, endpoint)) {
-        _ = runtime.system.write("hpet: irq_bind failed\n");
-        return;
-    }
-    _ = runtime.system.write("hpet: bound, sleeping until the hardware speaks\n");
-
-    // --- the driver loop -----------------------------------------------------
-    // Blocked in replyWait. No polling, no spinning: the next line of this function
-    // runs only because an interrupt fired.
-    var receive: [64]u8 = undefined;
-    var count: usize = 0;
-    while (count < target_ticks) {
-        // Blocked here. The task is `.blocked` and off every scheduler queue; the
-        // next line runs only because the HPET raised its line.
-        const r = ipc.replyWait(endpoint, &.{}, &receive, null);
-        if (!r.isNotification()) continue; // a client request, not our IRQ
-
-        // Quiet the device: write 1 to timer 0's status bit. Until this lands, the
-        // line is still asserted and unmasking would refire immediately.
-        wr(base, register_int_status, 1);
-        count += 1;
-
-        if (count < target_ticks) {
-            wr(base, register_timer0_comparator, rd(base, register_main_counter) + ticks_per_ms * 100);
-        } else {
-            // Last one: stop the source rather than re-arming, so the line is left
-            // both quiet *and* unmasked by the ack below. Re-arming here would leave
-            // a pending interrupt that nobody is waiting for, and the ISR would mask
-            // the line again a moment later.
-            wr(base, register_timer0_configuration, rd(base, register_timer0_configuration) & ~tn_int_enb);
-        }
-
-        _ = runtime.system.write("hpet: irq\n");
-        if (!device.irqAck(hpet.device_id, hpet.irq)) {
-            _ = runtime.system.write("hpet: irq_ack failed\n");
-            return;
-        }
-    }
-
-    _ = runtime.system.write("hpet: ok\n");
-    while (true) runtime.system.sleep(1000);
-}
-
-pub const panic = runtime.panic;
-comptime {
-    _ = &runtime.start._start;
-}

system/drivers/pci-bus/pci-bus.zig

@@ -0,0 +1,265 @@
+//! /system/drivers/pci-bus — the PCI bus driver: enumeration moved out of ring 0
+//! (docs/discovery.md). The device manager matches the `pci_host_bridge`
+//! node and spawns one instance per bridge, the bridge's device id as argv[1] —
+//! the same per-device contract as usb-xhci-bus.
+//!
+//! M19.1 (this increment): claim the bridge, map its ECAM window (resource 0;
+//! the bus range and the MMIO apertures follow it), walk every
+//! bus/device/function config header, and log what the walk finds — ending
+//! with "/system/drivers/pci-bus: N functions found", which the `pci-scan` scenario compares
+//! against the kernel's own enumeration. Registration and reports (M19.2), and
+//! the kernel walk's retirement (M19.3), build on this proven-equivalent scan.
+
+const std = @import("std");
+const runtime = @import("runtime");
+const protocol = runtime.device_manager_protocol;
+const device = runtime.device;
+const pci_class = @import("pci-class");
+
+fn writeLine(comptime fmt: []const u8, arguments: anytype) void {
+    var line: [128]u8 = undefined;
+    _ = runtime.system.write(std.fmt.bufPrint(&line, fmt, arguments) catch return);
+}
+
+/// Log a discovered function with its (class / subclass / prog-IF) triple decoded
+/// to human names — the boot-log breadcrumb that says *what* the hardware is, so
+/// "class 0x01 (Mass Storage Controller) subclass 0x06 (Serial ATA Controller)
+/// progif 0x01 (AHCI 1.0)" reads straight off the log when writing a new driver.
+/// A dedicated wider buffer than `writeLine`'s, since the decoded names are long.
+fn logFunction(bus: u64, dev: u64, function: u64, class_triple: u32) void {
+    const cc = pci_class.ClassCode.unpack(@truncate(class_triple));
+    const pif = pci_class.progIfName(cc.base, cc.subclass, cc.prog_if);
+    var line: [200]u8 = undefined;
+    const text = if (pif.len != 0)
+        std.fmt.bufPrint(&line, "/system/drivers/pci-bus: {d}:{d}.{d} class 0x{x:0>2} ({s})  subclass 0x{x:0>2} ({s})  progif 0x{x:0>2} ({s})\n", .{ bus, dev, function, cc.base, pci_class.className(cc.base), cc.subclass, pci_class.subclassName(cc.base, cc.subclass), cc.prog_if, pif }) catch return
+    else
+        std.fmt.bufPrint(&line, "/system/drivers/pci-bus: {d}:{d}.{d} class 0x{x:0>2} ({s})  subclass 0x{x:0>2} ({s})  progif 0x{x:0>2}\n", .{ bus, dev, function, cc.base, pci_class.className(cc.base), cc.subclass, pci_class.subclassName(cc.base, cc.subclass), cc.prog_if }) catch return;
+    _ = runtime.system.write(text);
+}
+
+var bridge_id: u64 = protocol.no_device;
+var ecam_base: usize = 0;
+var ecam_physical: u64 = 0;
+var start_bus: u64 = 0;
+var bus_count: u64 = 0;
+var manager_handle: runtime.ipc.Handle = 0;
+
+/// One aligned 32-bit read from a function's configuration space.
+fn configRead(bus: u64, dev: u64, function: u64, offset: u64) u32 {
+    const address = ecam_base + (((bus - start_bus) << 20) | (dev << 15) | (function << 12) | offset);
+    const register: *volatile u32 = @ptrFromInt(address);
+    return register.*;
+}
+
+fn configWrite(bus: u64, dev: u64, function: u64, offset: u64, value: u32) void {
+    const address = ecam_base + (((bus - start_bus) << 20) | (dev << 15) | (function << 12) | offset);
+    const register: *volatile u32 = @ptrFromInt(address);
+    register.* = value;
+}
+
+fn configRead16(bus: u64, dev: u64, function: u64, offset: u64) u16 {
+    const word = configRead(bus, dev, function, offset & ~@as(u64, 3));
+    return @truncate(word >> @intCast((offset & 3) * 8));
+}
+
+fn configWrite16(bus: u64, dev: u64, function: u64, offset: u64, value: u16) void {
+    const aligned = offset & ~@as(u64, 3);
+    const shift: u5 = @intCast((offset & 3) * 8);
+    const word = configRead(bus, dev, function, aligned);
+    const mask = @as(u32, 0xFFFF) << shift;
+    configWrite(bus, dev, function, aligned, (word & ~mask) | (@as(u32, value) << shift));
+}
+
+/// Claim the bridge, map the ECAM, hello the manager, then scan.
+fn initialise(endpoint: runtime.ipc.Handle) bool {
+    _ = endpoint;
+    if (!device.claim(bridge_id)) {
+        writeLine("/system/drivers/pci-bus: unable to claim bridge device {d}\n", .{bridge_id});
+        return false;
+    }
+    const buffer = runtime.allocator().alloc(device.DeviceDescriptor, 64) catch {
+        _ = runtime.system.write("/system/drivers/pci-bus: out of memory\n");
+        return false;
+    };
+    const total = device.enumerate(buffer);
+    const descriptor = for (buffer[0..@min(total, buffer.len)]) |d| {
+        if (d.id == bridge_id) break d;
+    } else {
+        writeLine("/system/drivers/pci-bus: device {d} not in the device tree\n", .{bridge_id});
+        return false;
+    };
+    // Resource 0 is the ECAM window (1 MiB of config space per bus); the bus
+    // range rides beside it. The MMIO apertures (M19.0) come after both.
+    if (descriptor.resource_count < 2 or descriptor.resources[0].kind != @intFromEnum(device.ResourceKind.memory)) {
+        _ = runtime.system.write("/system/drivers/pci-bus: bridge has no ECAM window\n");
+        return false;
+    }
+    const bus_range = for (descriptor.resources[0..@intCast(descriptor.resource_count)]) |resource| {
+        if (resource.kind == @intFromEnum(device.ResourceKind.bus_range)) break resource;
+    } else {
+        _ = runtime.system.write("/system/drivers/pci-bus: bridge has no bus range\n");
+        return false;
+    };
+    start_bus = bus_range.start;
+    bus_count = bus_range.len;
+    ecam_physical = descriptor.resources[0].start;
+    ecam_base = device.mmioMap(bridge_id, 0) orelse {
+        _ = runtime.system.write("/system/drivers/pci-bus: ECAM mmio_map failed\n");
+        return false;
+    };
+
+    // The handshake, then the scan (reports join in M19.2).
+    var manager: ?runtime.ipc.Handle = null;
+    var tries: u32 = 0;
+    while (manager == null and tries < 100) : (tries += 1) {
+        manager = runtime.ipc.lookup(.device_manager);
+        if (manager == null) runtime.system.sleep(20);
+    }
+    const h = manager orelse {
+        _ = runtime.system.write("/system/drivers/pci-bus: no device manager to hello\n");
+        return false;
+    };
+    const hello = protocol.Hello{ .role = @intFromEnum(protocol.Role.bus), .device_id = bridge_id };
+    var reply: [protocol.message_maximum]u8 = undefined;
+    const n = runtime.ipc.call(h, std.mem.asBytes(&hello), &reply) catch {
+        _ = runtime.system.write("/system/drivers/pci-bus: hello call failed\n");
+        return false;
+    };
+    if (n < protocol.reply_size or std.mem.bytesToValue(protocol.HelloReply, reply[0..protocol.reply_size]).status != 0) {
+        _ = runtime.system.write("/system/drivers/pci-bus: hello refused\n");
+        return false;
+    }
+    manager_handle = h;
+
+    scan();
+    return true;
+}
+
+/// The brute-force walk the kernel does today, from ring 3: every bus in the
+/// range, 32 devices, 8 functions; vendor id FFFFh means nothing decodes there,
+/// and only multifunction devices get their functions 1..7 probed.
+fn scan() void {
+    var found: u32 = 0;
+    var bus: u64 = start_bus;
+    while (bus < start_bus + bus_count) : (bus += 1) {
+        var dev: u64 = 0;
+        while (dev < 32) : (dev += 1) {
+            const first = configRead(bus, dev, 0, 0);
+            if (first & 0xFFFF == 0xFFFF) continue;
+            const multifunction = (configRead(bus, dev, 0, 0x0C) >> 16) & 0x80 != 0;
+            var function: u64 = 0;
+            while (function < 8) : (function += 1) {
+                if (function != 0 and !multifunction) break;
+                const vendor_device = configRead(bus, dev, function, 0);
+                if (vendor_device & 0xFFFF == 0xFFFF) continue;
+                const class_revision = configRead(bus, dev, function, 0x08);
+                found += 1;
+                logFunction(bus, dev, function, class_revision >> 8);
+                registerAndReport(bus, dev, function, class_revision >> 8);
+            }
+        }
+    }
+    writeLine("/system/drivers/pci-bus: {d} functions found\n", .{found});
+}
+
+/// Register one function under the bridge and report it to the manager. The
+/// descriptor mirrors the kernel's own recording byte for byte — config slice
+/// as resource 0, then the sized BARs — so during coexistence the idempotent
+/// device_register (M19.0) returns the kernel's existing node id rather than
+/// growing a duplicate, and the report carries the id drivers already use.
+fn registerAndReport(bus: u64, dev: u64, function: u64, class_triple: u32) void {
+    var descriptor = std.mem.zeroes(device.DeviceDescriptor);
+    descriptor.class = @intFromEnum(device.DeviceClass.pci_device);
+    descriptor.pci_class = class_triple;
+    descriptor.resources[0] = .{
+        .kind = @intFromEnum(device.ResourceKind.memory),
+        .start = ecam_physical + (((bus - start_bus) << 20) | (dev << 15) | (function << 12)),
+        .len = 4096,
+    };
+    descriptor.resource_count = 1;
+
+    // The standard BAR-sizing probe, exactly as the kernel does it: decode off,
+    // write all-ones, read the writable mask back, restore. Header type 0 only.
+    const header_type = (configRead(bus, dev, function, 0x0C) >> 16) & 0x7F;
+    if (header_type == 0) {
+        const command = configRead16(bus, dev, function, 0x04);
+        configWrite16(bus, dev, function, 0x04, command & ~@as(u16, 0b11));
+        var i: u64 = 0;
+        while (i < 6) : (i += 1) {
+            if (descriptor.resource_count >= 8) break;
+            const off = 0x10 + i * 4;
+            const original = configRead(bus, dev, function, off);
+            if (original == 0) continue;
+            const slot: usize = @intCast(descriptor.resource_count);
+            if (original & 1 != 0) {
+                configWrite(bus, dev, function, off, 0xFFFF_FFFF);
+                const readback = configRead(bus, dev, function, off);
+                configWrite(bus, dev, function, off, original);
+                const mask = readback & 0xFFFF_FFFC;
+                const size: u32 = if (mask == 0) 0 else (~mask +% 1) & 0xFFFF;
+                if (size == 0) continue; // unimplemented BAR — nothing to register
+                descriptor.resources[slot] = .{ .kind = @intFromEnum(device.ResourceKind.io_port), .start = original & 0xFFFF_FFFC, .len = size };
+                descriptor.resource_count += 1;
+            } else if ((original >> 1) & 0x3 == 2) {
+                const original_high = configRead(bus, dev, function, off + 4);
+                configWrite(bus, dev, function, off, 0xFFFF_FFFF);
+                configWrite(bus, dev, function, off + 4, 0xFFFF_FFFF);
+                const lo = configRead(bus, dev, function, off);
+                const hi = configRead(bus, dev, function, off + 4);
+                configWrite(bus, dev, function, off, original);
+                configWrite(bus, dev, function, off + 4, original_high);
+                const readback = (@as(u64, hi) << 32) | (lo & 0xFFFF_FFF0);
+                const size: u64 = if (readback == 0) 0 else ~readback +% 1;
+                i += 1; // consumed the high half regardless
+                if (size == 0) continue;
+                descriptor.resources[slot] = .{ .kind = @intFromEnum(device.ResourceKind.memory), .start = (@as(u64, original_high) << 32) | (original & 0xFFFF_FFF0), .len = size };
+                descriptor.resource_count += 1;
+            } else {
+                configWrite(bus, dev, function, off, 0xFFFF_FFFF);
+                const readback = configRead(bus, dev, function, off);
+                configWrite(bus, dev, function, off, original);
+                const mask = readback & 0xFFFF_FFF0;
+                const size: u32 = if (mask == 0) 0 else ~mask +% 1;
+                if (size == 0) continue;
+                descriptor.resources[slot] = .{ .kind = @intFromEnum(device.ResourceKind.memory), .start = original & 0xFFFF_FFF0, .len = size };
+                descriptor.resource_count += 1;
+            }
+        }
+        configWrite16(bus, dev, function, 0x04, command);
+    }
+
+    const registered = device.register(bridge_id, &descriptor) orelse {
+        writeLine("/system/drivers/pci-bus: register refused for {d}:{d}.{d}\n", .{ bus, dev, function });
+        return;
+    };
+    const report = protocol.ChildAdded{
+        .parent = bridge_id,
+        .bus_address = (bus << 8) | (dev << 3) | function,
+        .identity = class_triple,
+        .device_id = registered,
+    };
+    var reply: [protocol.message_maximum]u8 = undefined;
+    _ = runtime.ipc.call(manager_handle, std.mem.asBytes(&report), &reply) catch {
+        writeLine("/system/drivers/pci-bus: child report for {d}:{d}.{d} failed\n", .{ bus, dev, function });
+    };
+}
+
+fn onMessage(message: []const u8, reply: []u8, sender: u32, capability: ?runtime.ipc.Handle) usize {
+    _ = message;
+    _ = reply;
+    _ = sender;
+    _ = capability;
+    return 0;
+}
+
+pub fn main(init: runtime.process.Init) void {
+    const argument = init.arguments.get(1) orelse return; // bare (ramdisk sweep): stay silent
+    bridge_id = std.fmt.parseInt(u64, argument, 10) catch {
+        writeLine("/system/drivers/pci-bus: malformed bridge device id '{s}'\n", .{argument});
+        return;
+    };
+    runtime.service.run(protocol.message_maximum, .{
+        .init = initialise,
+        .on_message = onMessage,
+    });
+}

system/drivers/ps2-bus/keyboard.zig

@@ -0,0 +1,179 @@
+//! PS/2 Keyboard Driver
+//!
+//! Spawned by the ps2-bus driver once the controller is initialized and the port
+//! has passed its interface test and device reset. The bus driver hands us our
+//! device HID as argv[1] and, optionally, a layout name (`"us"`, `"gb"`, ...) as
+//! argv[2].
+//!
+//! The 8042's ports (0x60/0x64) and IRQ1 live on the PNP0303 node, which the
+//! ps2-bus driver exclusively owns — so this driver never touches the hardware.
+//! Instead it **attaches** to the bus (handing over its endpoint as a capability)
+//! and receives every scancode byte as a forwarded asynchronous message. Each byte
+//! feeds the set-2 decoder; a decoded key becomes input-protocol events:
+//!
+//!   scancode byte -> HID usage keycode -> key_down / key_up
+//!                                      -> xkeyboard-config -> character -> key_press
+
+const std = @import("std");
+const runtime = @import("runtime");
+const xkb = @import("xkeyboard-config");
+const ps2 = @import("ps2-library.zig");
+const scancode = @import("scancode.zig");
+const device = runtime.device;
+const ipc = runtime.ipc;
+const protocol = runtime.input_protocol;
+
+fn writeLine(comptime fmt: []const u8, arguments: anytype) void {
+    var line: [128]u8 = undefined;
+    _ = runtime.system.write(std.fmt.bufPrint(&line, fmt, arguments) catch return);
+}
+
+/// Look up the ps2-bus service, retrying while the bus (which spawned us before
+/// registering) is still coming up.
+fn lookupBus() ?ipc.Handle {
+    var attempts: usize = 0;
+    while (attempts < 100) : (attempts += 1) {
+        if (ipc.lookup(.ps2_bus)) |handle| return handle;
+        runtime.system.sleep(50);
+    }
+    return null;
+}
+
+/// The character a pressed key produces under `modifiers`, or 0 for none. The
+/// layout lookup answers for printable keys; the keys whose keysym has no Unicode
+/// mapping but that every consumer still expects as a character (Enter, Tab,
+/// Backspace, Escape) are given their ASCII control characters here.
+fn characterFor(layout: *const xkb.Layout, usage: u8, modifiers: scancode.ModifierSnapshot) u32 {
+    const mapping = xkb.map(layout, usage, .{
+        .shift = modifiers.shift,
+        .caps_lock = modifiers.caps_lock,
+        .level3 = modifiers.right_alt,
+        .control = modifiers.control,
+    });
+    if (mapping.character) |character| return character;
+    return switch (@as(protocol.Keycode, @enumFromInt(usage))) {
+        .enter, .keypad_enter => '\n',
+        .tab => '\t',
+        .backspace => 0x08,
+        .escape => 0x1B,
+        else => 0,
+    };
+}
+
+/// The input protocol's modifier word for a snapshot.
+fn modifierWord(modifiers: scancode.ModifierSnapshot) u32 {
+    var word: u32 = 0;
+    if (modifiers.shift) word |= protocol.modifier_shift;
+    if (modifiers.control) word |= protocol.modifier_control;
+    if (modifiers.alt) word |= protocol.modifier_alt;
+    return word;
+}
+
+pub fn main(init: runtime.process.Init) void {
+    const hid = init.arguments.get(1).?;
+    if (hid.len == 0) {
+        _ = runtime.system.write("/system/drivers/ps2-bus/keyboard: no HID argument\n");
+        return;
+    }
+    writeLine("/system/drivers/ps2-bus/keyboard: starting for hid {s}\n", .{hid});
+
+    const buffer = runtime.allocator().alloc(device.DeviceDescriptor, 64) catch {
+        _ = runtime.system.write("/system/drivers/ps2-bus/keyboard: out of memory\n");
+        return;
+    };
+    if (device.findDeviceDescriptorByHid(buffer, hid) == null) {
+        writeLine("/system/drivers/ps2-bus/keyboard: no device for hid {s}\n", .{hid});
+        return;
+    }
+
+    // The layout is a spawn argument so a later settings source can choose it;
+    // absent (as today) it defaults to us.
+    const layout_name = init.arguments.get(2) orelse "us";
+    const layout = xkb.byName(layout_name) orelse xkb.us;
+    writeLine("/system/drivers/ps2-bus/keyboard: layout {s}\n", .{layout.name});
+
+    // Attach to the bus: hand it our endpoint, and it forwards every byte the
+    // keyboard sends (it owns the controller; we own the decoding).
+    const bus = lookupBus() orelse {
+        _ = runtime.system.write("/system/drivers/ps2-bus/keyboard: ps2-bus service unavailable\n");
+        return;
+    };
+    const endpoint = ipc.createIpcEndpoint() orelse {
+        _ = runtime.system.write("/system/drivers/ps2-bus/keyboard: no endpoint\n");
+        return;
+    };
+    var attach = ps2.AttachRequest{ .device_type = @intFromEnum(ps2.DeviceType.keyboard) };
+    var attach_reply: [@sizeOf(ps2.AttachReply)]u8 = undefined;
+    const attached = ipc.callCap(bus, std.mem.asBytes(&attach), &attach_reply, endpoint) catch {
+        _ = runtime.system.write("/system/drivers/ps2-bus/keyboard: attach call failed\n");
+        return;
+    };
+    if (attached.len < @sizeOf(ps2.AttachReply) or
+        std.mem.bytesToValue(ps2.AttachReply, attach_reply[0..@sizeOf(ps2.AttachReply)]).status != @intFromEnum(ps2.AttachStatus.ok))
+    {
+        _ = runtime.system.write("/system/drivers/ps2-bus/keyboard: attach refused\n");
+        return;
+    }
+
+    // Broadcast keyboard events through the input service so programs can listen
+    // for them (docs/input.md).
+    var source = runtime.input.connectSource() orelse {
+        _ = runtime.system.write("/system/drivers/ps2-bus/keyboard: input service unavailable\n");
+        return;
+    };
+    _ = runtime.system.write("/system/drivers/ps2-bus/keyboard: ok\n");
+
+    var decoder = scancode.Decoder{};
+    var state = scancode.KeyboardState{};
+    var receive: [@sizeOf(ps2.ForwardedByte)]u8 = undefined;
+    while (true) {
+        const got = ipc.replyWait(endpoint, &.{}, &receive, null);
+        if (!got.isMessage() or got.len < @sizeOf(ps2.ForwardedByte)) continue;
+        const forwarded = std.mem.bytesToValue(ps2.ForwardedByte, receive[0..@sizeOf(ps2.ForwardedByte)]);
+
+        const key = decoder.feed(@intCast(forwarded.byte & 0xFF)) orelse continue;
+        const transition = state.apply(key);
+        const modifiers = modifierWord(transition.modifiers);
+
+        switch (transition.action) {
+            .pressed => {
+                _ = source.publishKeyboardEvent(.{
+                    .kind = @intFromEnum(protocol.EventKind.key_down),
+                    .keycode = key.usage,
+                    .character = 0,
+                    .modifiers = modifiers,
+                });
+                const character = characterFor(layout, key.usage, transition.modifiers);
+                if (character != 0) {
+                    _ = source.publishKeyboardEvent(.{
+                        .kind = @intFromEnum(protocol.EventKind.key_press),
+                        .keycode = key.usage,
+                        .character = character,
+                        .modifiers = modifiers,
+                    });
+                }
+            },
+            // Typematic repeat: the key did not physically go down again, so no
+            // key_down — but it keeps producing its character.
+            .repeated => {
+                const character = characterFor(layout, key.usage, transition.modifiers);
+                if (character != 0) {
+                    _ = source.publishKeyboardEvent(.{
+                        .kind = @intFromEnum(protocol.EventKind.key_press),
+                        .keycode = key.usage,
+                        .character = character,
+                        .modifiers = modifiers,
+                    });
+                }
+            },
+            .released => {
+                _ = source.publishKeyboardEvent(.{
+                    .kind = @intFromEnum(protocol.EventKind.key_up),
+                    .keycode = key.usage,
+                    .character = 0,
+                    .modifiers = modifiers,
+                });
+            },
+        }
+    }
+}

system/drivers/ps2-bus/mouse-packet.zig

@@ -0,0 +1,143 @@
+//! PS/2 mouse packet assembly — the byte stream a streaming mouse sends, turned
+//! into decoded movement/button reports.
+//!
+//! A standard PS/2 mouse in stream mode sends three-byte packets:
+//!
+//!   byte 0: | Y ovf | X ovf | Y sign | X sign | 1 | middle | right | left |
+//!   byte 1: X movement (low eight bits; the sign bit lives in byte 0)
+//!   byte 2: Y movement (likewise)
+//!
+//! Movement is nine-bit two's complement, PS/2 convention: positive X right,
+//! positive Y **up**. The decoded packet converts Y to the screen convention
+//! (positive down), matching what every consumer of relative motion expects.
+//! Bit 3 of byte 0 is always set — the resynchronization anchor: a byte at
+//! packet start with bit 3 clear cannot be a packet header and is dropped.
+//!
+//! Everything here is pure (no imports beyond `std`, no IO), so it is
+//! host-testable: the tests at the bottom run under `zig build test`.
+
+const std = @import("std");
+
+/// One decoded movement/button report, in screen convention (positive dy down).
+pub const Packet = struct {
+    left: bool,
+    right: bool,
+    middle: bool,
+    dx: i16,
+    dy: i16,
+};
+
+const header_always_set: u8 = 1 << 3;
+const header_left: u8 = 1 << 0;
+const header_right: u8 = 1 << 1;
+const header_middle: u8 = 1 << 2;
+const header_x_sign: u8 = 1 << 4;
+const header_y_sign: u8 = 1 << 5;
+const header_x_overflow: u8 = 1 << 6;
+const header_y_overflow: u8 = 1 << 7;
+
+/// Device protocol bytes that can reach the packet stream around bring-up (the
+/// acknowledge to enable-reporting, a reset's self-test result). Both have bit 3
+/// set, so the header check alone cannot reject them; they are recognized only
+/// at packet start, where a real header cannot be one of them in practice.
+const response_acknowledge: u8 = 0xFA;
+const response_self_test_passed: u8 = 0xAA;
+
+/// Accumulates the byte stream into `Packet`s. Feed it every byte the mouse
+/// sends; the third byte of each well-formed packet returns one.
+pub const Assembler = struct {
+    bytes: [3]u8 = undefined,
+    count: u8 = 0,
+
+    pub fn feed(self: *Assembler, byte: u8) ?Packet {
+        if (self.count == 0) {
+            // Resynchronize: a packet must start with a plausible header.
+            if (byte & header_always_set == 0) return null;
+            if (byte == response_acknowledge or byte == response_self_test_passed) return null;
+        }
+        self.bytes[self.count] = byte;
+        self.count += 1;
+        if (self.count < 3) return null;
+        self.count = 0;
+
+        const header = self.bytes[0];
+        // An overflowed count is garbage by definition; discard the packet.
+        if (header & (header_x_overflow | header_y_overflow) != 0) return null;
+
+        return .{
+            .left = header & header_left != 0,
+            .right = header & header_right != 0,
+            .middle = header & header_middle != 0,
+            .dx = movement(self.bytes[1], header & header_x_sign != 0),
+            // PS/2 positive Y is up; screen positive Y is down.
+            .dy = -movement(self.bytes[2], header & header_y_sign != 0),
+        };
+    }
+
+    /// Nine-bit two's complement: the eight movement bits plus the header's sign.
+    fn movement(low: u8, negative: bool) i16 {
+        const value: i16 = low;
+        return if (negative) value - 256 else value;
+    }
+};
+
+// --- tests (host-run via `zig build test`) ------------------------------------
+
+const testing = std.testing;
+
+fn feedAll(assembler: *Assembler, bytes: []const u8) ?Packet {
+    var result: ?Packet = null;
+    for (bytes) |byte| {
+        if (assembler.feed(byte)) |packet| result = packet;
+    }
+    return result;
+}
+
+test "plain motion decodes with screen-convention y" {
+    var assembler = Assembler{};
+    const packet = feedAll(&assembler, &.{ 0x08, 5, 3 }).?;
+    try testing.expectEqual(@as(i16, 5), packet.dx);
+    try testing.expectEqual(@as(i16, -3), packet.dy); // PS/2 up 3 -> screen -3
+    try testing.expect(!packet.left and !packet.right and !packet.middle);
+}
+
+test "negative movement sign-extends through the header bits" {
+    var assembler = Assembler{};
+    // X sign and Y sign set: dx = 0xFB - 256 = -5, dy raw = 0xFE - 256 = -2 -> screen +2.
+    const packet = feedAll(&assembler, &.{ 0x08 | 0x10 | 0x20, 0xFB, 0xFE }).?;
+    try testing.expectEqual(@as(i16, -5), packet.dx);
+    try testing.expectEqual(@as(i16, 2), packet.dy);
+}
+
+test "buttons decode from the header" {
+    var assembler = Assembler{};
+    const packet = feedAll(&assembler, &.{ 0x08 | 0x01 | 0x02, 0, 0 }).?;
+    try testing.expect(packet.left);
+    try testing.expect(packet.right);
+    try testing.expect(!packet.middle);
+}
+
+test "a byte with bit 3 clear at packet start is dropped" {
+    var assembler = Assembler{};
+    // The stray 0x02 cannot be a header; the following packet still decodes.
+    try testing.expectEqual(@as(?Packet, null), assembler.feed(0x02));
+    const packet = feedAll(&assembler, &.{ 0x09, 1, 0 }).?;
+    try testing.expect(packet.left);
+    try testing.expectEqual(@as(i16, 1), packet.dx);
+}
+
+test "protocol bytes at packet start are dropped" {
+    var assembler = Assembler{};
+    try testing.expectEqual(@as(?Packet, null), assembler.feed(0xFA)); // enable-reporting ACK
+    try testing.expectEqual(@as(?Packet, null), assembler.feed(0xAA)); // self-test passed
+    const packet = feedAll(&assembler, &.{ 0x08, 7, 0 }).?;
+    try testing.expectEqual(@as(i16, 7), packet.dx);
+}
+
+test "an overflowed packet is discarded whole" {
+    var assembler = Assembler{};
+    try testing.expectEqual(@as(?Packet, null), feedAll(&assembler, &.{ 0x08 | 0x40, 0xFF, 0xFF }));
+    // The assembler is back at packet start.
+    const packet = feedAll(&assembler, &.{ 0x08, 1, 1 }).?;
+    try testing.expectEqual(@as(i16, 1), packet.dx);
+}

system/drivers/ps2-bus/mouse.zig

@@ -0,0 +1,139 @@
+//! PS/2 Mouse Driver
+//!
+//! Spawned by the ps2-bus driver once the controller is initialized and the port
+//! has passed its interface test and device reset. The bus driver hands us our
+//! device HID as argv[1].
+//!
+//! Like the keyboard, this driver never touches the hardware: the 8042's ports
+//! and both port IRQs are owned by the ps2-bus driver (the auxiliary port's
+//! IRQ12 lives on the PNP0F13 node, which the bus claims alongside the
+//! controller). The driver **attaches** to the bus and receives every byte the
+//! mouse sends as a forwarded asynchronous message. The bytes assemble into
+//! three-byte packets, and each packet becomes input-protocol events:
+//!
+//!   packet -> button transitions -> button_down / button_up
+//!          -> movement            -> motion (dx/dy, screen convention)
+
+const std = @import("std");
+const runtime = @import("runtime");
+const ps2 = @import("ps2-library.zig");
+const mouse_packet = @import("mouse-packet.zig");
+const device = runtime.device;
+const ipc = runtime.ipc;
+const protocol = runtime.input_protocol;
+
+fn writeLine(comptime fmt: []const u8, arguments: anytype) void {
+    var line: [128]u8 = undefined;
+    _ = runtime.system.write(std.fmt.bufPrint(&line, fmt, arguments) catch return);
+}
+
+/// Look up the ps2-bus service, retrying while the bus (which spawned us before
+/// registering) is still coming up.
+fn lookupBus() ?ipc.Handle {
+    var attempts: usize = 0;
+    while (attempts < 100) : (attempts += 1) {
+        if (ipc.lookup(.ps2_bus)) |handle| return handle;
+        runtime.system.sleep(50);
+    }
+    return null;
+}
+
+/// The protocol's pressed-button bitmask for a packet.
+fn buttonMask(packet: mouse_packet.Packet) u32 {
+    var mask: u32 = 0;
+    if (packet.left) mask |= protocol.mouse_button_left;
+    if (packet.right) mask |= protocol.mouse_button_right;
+    if (packet.middle) mask |= protocol.mouse_button_middle;
+    return mask;
+}
+
+pub fn main(init: runtime.process.Init) void {
+    const hid = init.arguments.get(1).?;
+
+    if (hid.len == 0) {
+        _ = runtime.system.write("/system/drivers/ps2-bus/mouse: no HID argument\n");
+        return;
+    }
+    writeLine("/system/drivers/ps2-bus/mouse: starting for hid {s}\n", .{hid});
+
+    const buffer = runtime.allocator().alloc(device.DeviceDescriptor, 64) catch {
+        _ = runtime.system.write("/system/drivers/ps2-bus/mouse: out of memory\n");
+        return;
+    };
+    if (ps2.findMouseDescriptor(buffer) == null) {
+        writeLine("/system/drivers/ps2-bus/mouse: no device for hid {s}\n", .{hid});
+        return;
+    }
+
+    // Attach to the bus: hand it our endpoint, and it forwards every byte the
+    // mouse sends (it owns the controller; we own the decoding).
+    const bus = lookupBus() orelse {
+        _ = runtime.system.write("/system/drivers/ps2-bus/mouse: ps2-bus service unavailable\n");
+        return;
+    };
+    const endpoint = ipc.createIpcEndpoint() orelse {
+        _ = runtime.system.write("/system/drivers/ps2-bus/mouse: no endpoint\n");
+        return;
+    };
+    var attach = ps2.AttachRequest{ .device_type = @intFromEnum(ps2.DeviceType.mouse) };
+    var attach_reply: [@sizeOf(ps2.AttachReply)]u8 = undefined;
+    const attached = ipc.callCap(bus, std.mem.asBytes(&attach), &attach_reply, endpoint) catch {
+        _ = runtime.system.write("/system/drivers/ps2-bus/mouse: attach call failed\n");
+        return;
+    };
+    if (attached.len < @sizeOf(ps2.AttachReply) or
+        std.mem.bytesToValue(ps2.AttachReply, attach_reply[0..@sizeOf(ps2.AttachReply)]).status != @intFromEnum(ps2.AttachStatus.ok))
+    {
+        _ = runtime.system.write("/system/drivers/ps2-bus/mouse: attach refused\n");
+        return;
+    }
+
+    // Broadcast mouse events through the input service so programs can listen
+    // for them (docs/input.md).
+    var source = runtime.input.connectSource() orelse {
+        _ = runtime.system.write("/system/drivers/ps2-bus/mouse: input service unavailable\n");
+        return;
+    };
+    _ = runtime.system.write("/system/drivers/ps2-bus/mouse: ok\n");
+
+    var assembler = mouse_packet.Assembler{};
+    var buttons: u32 = 0;
+    var receive: [@sizeOf(ps2.ForwardedByte)]u8 = undefined;
+    while (true) {
+        const got = ipc.replyWait(endpoint, &.{}, &receive, null);
+        if (!got.isMessage() or got.len < @sizeOf(ps2.ForwardedByte)) continue;
+        const forwarded = std.mem.bytesToValue(ps2.ForwardedByte, receive[0..@sizeOf(ps2.ForwardedByte)]);
+
+        const packet = assembler.feed(@intCast(forwarded.byte & 0xFF)) orelse continue;
+        const new_buttons = buttonMask(packet);
+
+        // A button transition per changed button, carrying the new whole mask.
+        const changed = buttons ^ new_buttons;
+        for ([_]u32{ protocol.mouse_button_left, protocol.mouse_button_right, protocol.mouse_button_middle }) |button| {
+            if (changed & button == 0) continue;
+            const kind: protocol.MouseEventKind = if (new_buttons & button != 0) .button_down else .button_up;
+            _ = source.publishMouseEvent(.{
+                .kind = @intFromEnum(kind),
+                .button = button,
+                .dx = 0,
+                .dy = 0,
+                .scroll_x = 0,
+                .scroll_y = 0,
+                .buttons = new_buttons,
+            });
+        }
+        buttons = new_buttons;
+
+        if (packet.dx != 0 or packet.dy != 0) {
+            _ = source.publishMouseEvent(.{
+                .kind = @intFromEnum(protocol.MouseEventKind.motion),
+                .button = 0,
+                .dx = packet.dx,
+                .dy = packet.dy,
+                .scroll_x = 0,
+                .scroll_y = 0,
+                .buttons = new_buttons,
+            });
+        }
+    }
+}

system/drivers/ps2-bus/ps2-bus.zig

@@ -0,0 +1,310 @@
+//! The PS/2 Controller is located on the mainboard.
+//! In the early days the controller was a single chip (Intel 8042).
+//! As of today it is part of the Advanced Integrated Peripheral.
+//!
+//! It shows up in the device discovery as:
+//! KBD_ [acpi_device] hid=PNP0303 (PS/2 Keyboard)
+//!       - io_port 0x60 len 0x1
+//!        - io_port 0x64 len 0x1
+//!        - irq 0x1 len 0x1
+//!  MOU_ [acpi_device] hid=PNP0F13 (PS/2 Mouse)
+//!        - irq 0xc len 0x1
+const std = @import("std");
+const runtime = @import("runtime");
+const acpi_ids = @import("acpi-ids");
+const ps2 = @import("ps2-library.zig");
+const device = runtime.device;
+const ipc = runtime.ipc;
+
+/// Format one whole log line and emit it in a single `debug_write`, so output
+/// from the child drivers (which run concurrently) can never interleave with it.
+fn writeLine(comptime fmt: []const u8, arguments: anytype) void {
+    var line: [128]u8 = undefined;
+    _ = runtime.system.write(std.fmt.bufPrint(&line, fmt, arguments) catch return);
+}
+
+/// Ask the device on `port` what it is, then spawn the matching driver from the
+/// initial-ramdisk, handing it the device's HID as argv[1]. The driver is chosen
+/// from what the device reports, not from the port number. Returns the identified
+/// type so the forwarding loop can route that port's bytes to the driver once it
+/// attaches, or null if nothing was spawned.
+fn spawnIdentifiedDriver(controller: ps2.Controller, port: ps2.Port) ?ps2.DeviceType {
+    const device_type = controller.identifyDevice(port) orelse {
+        writeLine("/system/drivers/ps2-bus: identify timed out on port {s}\n", .{@tagName(port)});
+        return null;
+    };
+    const driver_name = device_type.driverName() orelse {
+        writeLine("/system/drivers/ps2-bus: unrecognized device on port {s}\n", .{@tagName(port)});
+        return null;
+    };
+    const hid = device_type.hid() orelse "";
+    if (runtime.system.spawnWithArguments(driver_name, &.{hid}) != null) {
+        writeLine("/system/drivers/ps2-bus: port {s} is a {s}, spawned {s}\n", .{ @tagName(port), hid, driver_name });
+        return device_type;
+    }
+    writeLine("/system/drivers/ps2-bus: failed to spawn {s}\n", .{driver_name});
+    return null;
+}
+
+/// Resource index of the controller's IRQ (IRQ1) on the PNP0303 descriptor, found
+/// the way the ports are found in `Controller.init`.
+fn findInterruptResourceIndex(descriptor: device.DeviceDescriptor) ?u64 {
+    for (0..descriptor.resource_count) |index| {
+        if (descriptor.resources[index].kind == @intFromEnum(device.ResourceKind.irq)) return index;
+    }
+    return null;
+}
+
+/// Forwarding endpoints of the attached child drivers, indexed by `ps2.Port`.
+/// Written when a child's `AttachRequest` arrives, read on every forwarded byte.
+var port_endpoints = [_]?ipc.Handle{ null, null };
+
+/// Which device type each port identified as, so an attaching child (which knows
+/// its type, not its port) can be matched to the right port's byte stream.
+var port_device_types = [_]?ps2.DeviceType{ null, null };
+
+/// Handle a child driver's `AttachRequest`: record the endpoint capability it
+/// passed as the forwarding target for the port whose device matches its type.
+/// Writes an `AttachReply` into `out` and returns its length.
+fn handleAttach(message: []const u8, got: ipc.Received, out: []u8) usize {
+    const reply = struct {
+        fn write(buffer: []u8, status: ps2.AttachStatus) usize {
+            const header = ps2.AttachReply{ .status = @intFromEnum(status) };
+            @memcpy(buffer[0..@sizeOf(ps2.AttachReply)], std.mem.asBytes(&header));
+            return @sizeOf(ps2.AttachReply);
+        }
+    };
+
+    if (message.len < @sizeOf(ps2.AttachRequest)) return reply.write(out, .invalid_request);
+    const request = std.mem.bytesToValue(ps2.AttachRequest, message[0..@sizeOf(ps2.AttachRequest)]);
+    const endpoint = got.cap orelse return reply.write(out, .missing_endpoint);
+
+    for (&port_device_types, 0..) |maybe_type, port_index| {
+        const device_type = maybe_type orelse continue;
+        if (@intFromEnum(device_type) != request.device_type) continue;
+        port_endpoints[port_index] = endpoint;
+        writeLine("/system/drivers/ps2-bus: {s} driver attached\n", .{@tagName(device_type)});
+        return reply.write(out, .ok);
+    }
+    return reply.write(out, .no_such_device);
+}
+
+pub fn main() void {
+    const buffer = runtime.allocator().alloc(device.DeviceDescriptor, 64) catch {
+        _ = runtime.system.write("/system/drivers/ps2-bus: out of memory\n");
+        return;
+    };
+
+    var has_two_channels = false;
+    var maybe_controller: ?ps2.Controller = null;
+    var maybe_interrupt_index: ?u64 = null;
+    // The 8042's IO ports (0x60/0x64) are enumerated under the keyboard ACPI node
+    // (PNP0303), so we init the controller from that descriptor — but which device
+    // is on which port is decided later by identify, not by this HID.
+    const maybe_controller_device_descriptor = device.findDeviceDescriptorByHid(buffer, acpi_ids.HardwareId.ps2_keyboard.hid());
+    if (maybe_controller_device_descriptor) |controller_device_descriptor| {
+        _ = runtime.system.write("/system/drivers/ps2-bus: found PS/2 controller\n");
+        _ = runtime.system.write("/system/drivers/ps2-bus: initializing controller\n");
+
+        if (!device.claim(controller_device_descriptor.id)) {
+            _ = runtime.system.write("/system/drivers/ps2-bus: unable to claim controller \n");
+            return;
+        }
+
+        const controller = ps2.Controller.init(controller_device_descriptor) orelse {
+            _ = runtime.system.write("/system/drivers/ps2-bus: controller is missing its IO ports\n");
+            return;
+        };
+        maybe_controller = controller;
+        maybe_interrupt_index = findInterruptResourceIndex(controller_device_descriptor);
+
+        controller.disablePort(.one);
+        controller.disablePort(.two);
+        controller.flushOutputBuffer();
+
+        const current = controller.readConfigurationByte() orelse {
+            _ = runtime.system.write("/system/drivers/ps2-bus: controller configuration timed out\n");
+            return;
+        };
+
+        const update = current & ~(ps2.configuration_first_port_interrupt |
+            ps2.configuration_second_port_interrupt |
+            ps2.configuration_first_port_translation);
+
+        if (controller.writeConfigurationByte(update) == null) {
+            _ = runtime.system.write("/system/drivers/ps2-bus: controller configuration timed out\n");
+            return;
+        }
+
+        if (controller.performSelfTest()) |reply| {
+            if (reply != ps2.response_controller_test_passed) {
+                _ = runtime.system.write("/system/drivers/ps2-bus: perform controller self test failed\n");
+                return;
+            }
+        } else {
+            _ = runtime.system.write("/system/drivers/ps2-bus: controller self test timed out\n");
+            return;
+        }
+
+        has_two_channels = controller.hasTwoChannels() orelse {
+            _ = runtime.system.write("/system/drivers/ps2-bus: controller channels timed out\n");
+            return;
+        };
+
+        if (has_two_channels) {
+            _ = runtime.system.write("/system/drivers/ps2-bus: has two channels\n");
+            // keep the bus quiet until we have tested the ports and are ready to use them
+            controller.disablePort(.two);
+        } else {
+            _ = runtime.system.write("/system/drivers/ps2-bus: has one channel\n");
+        }
+
+        // interface tests: always test port 1, test port 2 only if it exists
+        const port_one_works = (controller.testPort(.one) orelse {
+            _ = runtime.system.write("/system/drivers/ps2-bus: port 1 test timed out\n");
+            return;
+        }) == ps2.response_port_test_passed;
+
+        var port_two_works = false;
+        if (has_two_channels) {
+            port_two_works = (controller.testPort(.two) orelse {
+                _ = runtime.system.write("/system/drivers/ps2-bus: port 2 test timed out\n");
+                return;
+            }) == ps2.response_port_test_passed;
+        }
+
+        if (!port_one_works and !port_two_works) {
+            _ = runtime.system.write("/system/drivers/ps2-bus: no usable ports\n");
+            return;
+        }
+
+        // Enable the working ports. Their interrupts stay off until IRQ1 is bound
+        // below — reset and identify use polled reads, which must never race the
+        // interrupt-driven drain loop for bytes.
+        controller.enablePort(.one);
+        if (port_two_works) controller.enablePort(.two);
+
+        // reset each working device; a failing device is logged but does not
+        // abort bring-up of the other one
+        if (port_one_works) {
+            if (controller.resetDevice(.one)) |passed| {
+                if (!passed) _ = runtime.system.write("/system/drivers/ps2-bus: port 1 device reset failed\n");
+            } else {
+                _ = runtime.system.write("/system/drivers/ps2-bus: port 1 device reset timed out\n");
+            }
+        }
+        if (port_two_works) {
+            if (controller.resetDevice(.two)) |passed| {
+                if (!passed) _ = runtime.system.write("/system/drivers/ps2-bus: port 2 device reset failed\n");
+            } else {
+                _ = runtime.system.write("/system/drivers/ps2-bus: port 2 device reset timed out\n");
+            }
+        }
+
+        // Identify the device on each working port and hand it off to the driver
+        // that matches what it reported — a port is not assumed to be a keyboard
+        // or a mouse by its number.
+        if (port_one_works) port_device_types[@intFromEnum(ps2.Port.one)] = spawnIdentifiedDriver(controller, .one);
+        if (port_two_works) port_device_types[@intFromEnum(ps2.Port.two)] = spawnIdentifiedDriver(controller, .two);
+    } else {
+        _ = runtime.system.write("/system/drivers/ps2-bus: no PS/2 controller found\n");
+        return;
+    }
+
+    const controller = maybe_controller.?;
+    const interrupt_index = maybe_interrupt_index orelse {
+        _ = runtime.system.write("/system/drivers/ps2-bus: controller is missing its IRQ\n");
+        return;
+    };
+
+    // The endpoint the child drivers attach to and IRQ1 wakes. Registered under a
+    // well-known id so the children can find it, the way input subscribers find
+    // the input service.
+    const endpoint = ipc.createIpcEndpoint() orelse {
+        _ = runtime.system.write("/system/drivers/ps2-bus: no endpoint\n");
+        return;
+    };
+    if (!ipc.register(.ps2_bus, endpoint)) {
+        _ = runtime.system.write("/system/drivers/ps2-bus: register failed\n");
+        return;
+    }
+
+    // From here on, only the interrupt path reads the data port. Drop anything a
+    // device sent between enable-scanning and now, bind the IRQs, and only then
+    // let the controller raise them — an interrupt with nobody bound is lost.
+    controller.drainOutputBuffer();
+    if (!device.irqBind(controller.device_id, interrupt_index, endpoint)) {
+        _ = runtime.system.write("/system/drivers/ps2-bus: irq_bind failed\n");
+        return;
+    }
+
+    // Port 2's interrupt (IRQ12) is enumerated on the auxiliary device's own ACPI
+    // node (PNP0F13), not on the controller's — so if port 2 carries a device,
+    // claim that node too and route its IRQ to the same endpoint. The IRQ belongs
+    // to the *port*, whatever device identify found on it.
+    var maybe_auxiliary_interrupt: ?struct { device_id: u64, interrupt_index: u64, gsi: u64 } = null;
+    if (port_device_types[@intFromEnum(ps2.Port.two)] != null) {
+        if (ps2.findMouseDescriptor(buffer)) |descriptor| {
+            if (findInterruptResourceIndex(descriptor)) |auxiliary_index| {
+                if (device.claim(descriptor.id) and device.irqBind(descriptor.id, auxiliary_index, endpoint)) {
+                    maybe_auxiliary_interrupt = .{
+                        .device_id = descriptor.id,
+                        .interrupt_index = auxiliary_index,
+                        .gsi = descriptor.resources[auxiliary_index].start,
+                    };
+                } else {
+                    _ = runtime.system.write("/system/drivers/ps2-bus: auxiliary irq_bind failed\n");
+                }
+            }
+        }
+    }
+
+    var configuration = controller.readConfigurationByte() orelse {
+        _ = runtime.system.write("/system/drivers/ps2-bus: controller configuration timed out\n");
+        return;
+    };
+    if (port_device_types[@intFromEnum(ps2.Port.one)] != null) configuration |= ps2.Port.one.interruptBit();
+    if (maybe_auxiliary_interrupt != null) configuration |= ps2.Port.two.interruptBit();
+    _ = controller.writeConfigurationByte(configuration);
+
+    _ = runtime.system.write("/system/drivers/ps2-bus: ok\n");
+
+    // The forwarding loop: an IRQ1 notification drains the output buffer, routing
+    // each byte to the attached driver of the port it came from; a client message
+    // is a child driver's AttachRequest.
+    var reply_buffer: [@sizeOf(ps2.AttachReply)]u8 = undefined;
+    var reply_len: usize = 0;
+    var receive: [@sizeOf(ps2.AttachRequest)]u8 = undefined;
+    while (true) {
+        const got = ipc.replyWait(endpoint, reply_buffer[0..reply_len], &receive, null);
+        if (got.isNotification()) {
+            reply_len = 0;
+            if (got.isMessage() or got.isChildExit()) continue; // nothing sends us these
+            while (true) {
+                const current_status = ps2.status(controller.device_id, controller.status_index);
+                if (current_status & ps2.status_output_buffer_full == 0) break;
+                const byte = device.ioRead(controller.device_id, controller.data_index, 0, 1) orelse break;
+                const port: ps2.Port = if (current_status & ps2.status_auxiliary_output != 0) .two else .one;
+                if (port_endpoints[@intFromEnum(port)]) |child| {
+                    const forwarded = ps2.ForwardedByte{ .port = @intFromEnum(port), .byte = byte };
+                    _ = ipc.send(child, std.mem.asBytes(&forwarded));
+                }
+                // An unattached port's byte is dropped — e.g. a keystroke before
+                // the keyboard driver has attached.
+            }
+            // Re-arm the line that woke us: the notification badge carries the
+            // GSI, and IRQ1 and IRQ12 are acked through different device claims.
+            if (maybe_auxiliary_interrupt) |auxiliary| {
+                if (got.source() == auxiliary.gsi) {
+                    _ = device.irqAck(auxiliary.device_id, auxiliary.interrupt_index);
+                } else {
+                    _ = device.irqAck(controller.device_id, interrupt_index);
+                }
+            } else {
+                _ = device.irqAck(controller.device_id, interrupt_index);
+            }
+            continue;
+        }
+        reply_len = handleAttach(receive[0..got.len], got, &reply_buffer);
+    }
+}

system/drivers/ps2-bus/ps2-library.zig

@@ -0,0 +1,501 @@
+//! shared definitions between the different PS/2 drivers
+const std = @import("std");
+const runtime = @import("runtime");
+const acpi_ids = @import("acpi-ids");
+const device = runtime.device;
+const system = runtime.system;
+
+/// PS-2 io ports:
+/// The PS/2 Controller itself uses 2 IO ports (usually, IO ports 0x60 and 0x64). Like many IO
+///  ports, reads and writes may access different internal registers.
+///
+/// Historical note: The PC-XT PPI had used port 0x61 to reset the keyboard interrupt request
+/// signal (among other unrelated functions). Port 0x61 has no keyboard related functions on AT and
+/// PS/2 compatibles.
+///
+/// The Data Port (typically IO Port 0x60) is used for reading data that was received from a PS/2
+/// device or from the PS/2 controller itself and writing data to a PS/2 device or to the PS/2
+/// controller itself.
+// Access type: Read/Write
+pub const dataPort = 0x60;
+// Access type: Read
+pub const statusRegisterPort = 0x64;
+// Access type: Write
+pub const CommandRegisterPort = 0x64;
+
+/// How long to poll the status register before giving up. PS/2 controller
+/// responses normally arrive within a few milliseconds.
+pub const default_wait_timeout_nanoseconds: u64 = 10_000_000; // 10 ms
+
+/// A PS/2 device reset (0xFF) runs the device's self-test (BAT), whose reply can
+/// take far longer than an ordinary controller response.
+pub const device_reset_timeout_nanoseconds: u64 = 750_000_000; // 750 ms
+
+/// PS/2 controller commands, written to the command register (port 0x64).
+pub const cmd_read_configuration_byte: u8 = 0x20; // read controller configuration byte (internal RAM byte 0)
+pub const cmd_write_configuration_byte: u8 = 0x60; // write controller configuration byte (internal RAM byte 0)
+pub const cmd_disable_second_port: u8 = 0xA7; // disable second PS/2 port (dual-channel controllers only)
+pub const cmd_enable_second_port: u8 = 0xA8; // enable second PS/2 port (dual-channel controllers only)
+pub const cmd_test_second_port: u8 = 0xA9; // test second PS/2 port
+pub const cmd_test_controller: u8 = 0xAA; // controller self-test
+pub const cmd_test_first_port: u8 = 0xAB; // test first PS/2 port
+pub const cmd_diagnostic_dump: u8 = 0xAC; // read all bytes of internal RAM
+pub const cmd_disable_first_port: u8 = 0xAD; // disable first PS/2 port
+pub const cmd_enable_first_port: u8 = 0xAE; // enable first PS/2 port
+pub const cmd_read_controller_input_port: u8 = 0xC0; // read controller input port
+pub const cmd_read_controller_output_port: u8 = 0xD0; // read controller output port
+pub const cmd_write_controller_output_port: u8 = 0xD1; // write next data byte to the controller output port
+pub const cmd_write_first_port_output: u8 = 0xD2; // write next data byte to the first port output buffer
+pub const cmd_write_second_port_output: u8 = 0xD3; // write next data byte to the second port output buffer
+pub const cmd_write_second_port_input: u8 = 0xD4; // write next data byte to the second port input buffer (to the mouse)
+pub const cmd_pulse_system_reset: u8 = 0xFE; // pulse output line 0 low: resets the CPU
+
+/// PS/2 status register bits (read from the status port, 0x64). Bit 4 is
+/// chipset-specific and intentionally omitted.
+pub const status_output_buffer_full: u8 = 1 << 0; // 1 = a byte is waiting to be read from the data port
+pub const status_input_buffer_full: u8 = 1 << 1; // 1 = the controller has not yet consumed the last write
+pub const status_system_flag: u8 = 1 << 2; // set once the controller passes POST
+pub const status_command_or_data: u8 = 1 << 3; // 1 = last write was a command, 0 = data
+/// Chipset-specific in the original spec, universal in practice on dual-channel
+/// controllers: set = the waiting byte came from the second port (the mouse).
+pub const status_auxiliary_output: u8 = 1 << 5;
+pub const status_timeout_error: u8 = 1 << 6; // 1 = time-out error
+pub const status_parity_error: u8 = 1 << 7; // 1 = parity error
+
+/// Controller configuration byte bits (internal RAM byte 0; read/written via 0x20/0x60).
+pub const configuration_first_port_interrupt: u8 = 1 << 0; // 1 = first port IRQ (IRQ1) enabled
+pub const configuration_second_port_interrupt: u8 = 1 << 1; // 1 = second port IRQ (IRQ12) enabled
+pub const configuration_system_flag: u8 = 1 << 2; // 1 = system passed POST
+pub const configuration_first_port_clock_disabled: u8 = 1 << 4; // 1 = first port clock disabled
+pub const configuration_second_port_clock_disabled: u8 = 1 << 5; // 1 = second port clock disabled
+pub const configuration_first_port_translation: u8 = 1 << 6; // 1 = first port scancode translation enabled
+
+/// Controller output port bits (read/written via 0xD0/0xD1).
+pub const output_port_system_reset: u8 = 1 << 0; // WARNING: keep this 1; writing 0 can lock the machine
+pub const output_port_a20_gate: u8 = 1 << 1; // A20 gate
+pub const output_port_second_port_clock: u8 = 1 << 2; // dual-channel controllers only
+pub const output_port_second_port_data: u8 = 1 << 3; // dual-channel controllers only
+pub const output_port_first_port_output_full: u8 = 1 << 4; // output buffer full from first port (IRQ1)
+pub const output_port_second_port_output_full: u8 = 1 << 5; // output buffer full from second port (IRQ12)
+pub const output_port_first_port_clock: u8 = 1 << 6; // first port clock
+pub const output_port_first_port_data: u8 = 1 << 7; // first port data
+
+/// Controller self-test (0xAA) result codes.
+pub const response_controller_test_passed: u8 = 0x55;
+pub const response_controller_test_failed: u8 = 0xFC;
+
+/// Port test (0xAB / 0xA9) result codes.
+pub const response_port_test_passed: u8 = 0x00;
+pub const response_port_test_clock_stuck_low: u8 = 0x01;
+pub const response_port_test_clock_stuck_high: u8 = 0x02;
+pub const response_port_test_data_stuck_low: u8 = 0x03;
+pub const response_port_test_data_stuck_high: u8 = 0x04;
+
+/// PS/2 device commands, written to the data port (0x60) to reach the attached device.
+pub const device_cmd_identify: u8 = 0xF2; // identify device
+pub const device_cmd_enable_scanning: u8 = 0xF4;
+pub const device_cmd_disable_scanning: u8 = 0xF5;
+pub const device_cmd_reset: u8 = 0xFF; // reset and run the device self-test (BAT)
+
+/// PS/2 device response bytes, read from the data port (0x60).
+pub const device_response_self_test_passed: u8 = 0xAA; // BAT succeeded after a reset
+pub const device_response_echo: u8 = 0xEE;
+pub const device_response_acknowledge: u8 = 0xFA; // ACK
+pub const device_response_self_test_failed_1: u8 = 0xFC; // BAT failure
+pub const device_response_self_test_failed_2: u8 = 0xFD; // BAT failure
+pub const device_response_resend: u8 = 0xFE; // ask the host to resend the last byte
+
+/// PS/2 device identify (0xF2) reply bytes. A keyboard returns a two-byte id
+/// beginning with 0xAB; a mouse returns a single-byte id (0x00/0x03/0x04); an
+/// ancient AT keyboard returns nothing at all.
+pub const identify_keyboard_mf2: u8 = 0xAB; // first byte of a MF2 keyboard id (a subtype byte follows)
+pub const identify_mouse_standard: u8 = 0x00;
+pub const identify_mouse_scroll: u8 = 0x03; // mouse with scroll wheel
+pub const identify_mouse_five_button: u8 = 0x04; // 5-button mouse
+
+fn waitReadable(id: u64, cmd_index: u64, wait_timeout_nanoseconds: u64) bool {
+    const deadline = system.clock() + wait_timeout_nanoseconds;
+    while (system.clock() < deadline) {
+        if (status(id, cmd_index) & status_output_buffer_full != 0) return true; // OBF set -> data ready
+    }
+    return false;
+}
+
+fn waitWritable(id: u64, cmd_index: u64, wait_timeout_nanoseconds: u64) bool {
+    const deadline = system.clock() + wait_timeout_nanoseconds;
+    while (system.clock() < deadline) {
+        if (status(id, cmd_index) & status_input_buffer_full == 0) return true; // IBF clear -> ok to write
+    }
+    return false; // timed out
+}
+
+pub fn status(id: u64, cmd_index: u64) u8 {
+    return @intCast(device.ioRead(id, cmd_index, 0, 1) orelse 0);
+}
+
+pub fn sendCommand(id: u64, cmd_index: u64, byte: u8, timeout_nanoseconds: u64) bool {
+    // wait IBF clear
+    if (!waitWritable(id, cmd_index, timeout_nanoseconds)) return false;
+    return device.ioWrite(id, cmd_index, 0, 1, byte);
+}
+
+pub fn readData(id: u64, status_index: u64, data_index: u64, timeout_nanoseconds: u64) ?u8 {
+    // OBF lives in the status register (0x64); wait for it there, then read the data port (0x60)
+    if (!waitReadable(id, status_index, timeout_nanoseconds)) return null;
+    return @intCast(device.ioRead(id, data_index, 0, 1) orelse 0);
+}
+
+pub fn writeData(id: u64, status_index: u64, data_index: u64, byte: u8, timeout_nanoseconds: u64) bool {
+    // IBF lives in the status register (0x64); wait for it to clear there, then write the data port
+    // (0x60)
+    if (!waitWritable(id, status_index, timeout_nanoseconds)) return false;
+    return device.ioWrite(id, data_index, 0, 1, byte);
+}
+
+pub const Port = enum(u2) {
+    one,
+    two,
+
+    /// Command register byte that disables this port.
+    fn disableCommand(self: Port) u8 {
+        return switch (self) {
+            .one => cmd_disable_first_port,
+            .two => cmd_disable_second_port,
+        };
+    }
+
+    /// Command register byte that enables this port (and its clock).
+    fn enableCommand(self: Port) u8 {
+        return switch (self) {
+            .one => cmd_enable_first_port,
+            .two => cmd_enable_second_port,
+        };
+    }
+
+    /// Command register byte that runs this port's interface test.
+    fn testCommand(self: Port) u8 {
+        return switch (self) {
+            .one => cmd_test_first_port,
+            .two => cmd_test_second_port,
+        };
+    }
+
+    /// Configuration-byte bit that, when set, disables this port's clock.
+    pub fn clockDisabledBit(self: Port) u8 {
+        return switch (self) {
+            .one => configuration_first_port_clock_disabled,
+            .two => configuration_second_port_clock_disabled,
+        };
+    }
+
+    /// Configuration-byte bit that, when set, enables this port's interrupt.
+    pub fn interruptBit(self: Port) u8 {
+        return switch (self) {
+            .one => configuration_first_port_interrupt,
+            .two => configuration_second_port_interrupt,
+        };
+    }
+
+    /// Command register byte that writes the next data byte into this port's
+    /// output buffer (makes a byte appear as if it came from the device).
+    pub fn writeOutputBufferCommand(self: Port) u8 {
+        return switch (self) {
+            .one => cmd_write_first_port_output,
+            .two => cmd_write_second_port_output,
+        };
+    }
+
+    /// Controller command that must prefix a byte destined for this port's
+    /// device. Port 1 is the default target of the data port, so it needs no
+    /// prefix (null); port 2 requires the "write second port input" command.
+    pub fn deviceInputCommand(self: Port) ?u8 {
+        return switch (self) {
+            .one => null,
+            .two => cmd_write_second_port_input,
+        };
+    }
+
+    /// Controller output-port bit driving this port's clock line.
+    pub fn outputPortClockBit(self: Port) u8 {
+        return switch (self) {
+            .one => output_port_first_port_clock,
+            .two => output_port_second_port_clock,
+        };
+    }
+
+    /// Controller output-port bit driving this port's data line.
+    pub fn outputPortDataBit(self: Port) u8 {
+        return switch (self) {
+            .one => output_port_first_port_data,
+            .two => output_port_second_port_data,
+        };
+    }
+
+    /// Controller output-port bit set when this port's output buffer is full
+    /// (wired to the port's IRQ line).
+    pub fn outputPortBufferFullBit(self: Port) u8 {
+        return switch (self) {
+            .one => output_port_first_port_output_full,
+            .two => output_port_second_port_output_full,
+        };
+    }
+};
+
+/// The kind of device attached to a port, as reported by the device itself in
+/// response to the identify command — not assumed from the port number. Fixed
+/// `u32` values because the type also travels in an `AttachRequest`.
+pub const DeviceType = enum(u32) {
+    keyboard = 0,
+    mouse = 1,
+    unknown = 2,
+
+    /// Initial-ramdisk name of the driver that serves this device type, or null
+    /// if we could not classify it.
+    pub fn driverName(self: DeviceType) ?[]const u8 {
+        return switch (self) {
+            .keyboard => "ps2-keyboard",
+            .mouse => "ps2-mouse",
+            .unknown => null,
+        };
+    }
+
+    /// Canonical ACPI HID for this device type, handed to the spawned driver as
+    /// its command-line argument, or null if we could not classify it.
+    pub fn hid(self: DeviceType) ?[]const u8 {
+        return switch (self) {
+            .keyboard => acpi_ids.HardwareId.ps2_keyboard.hid(),
+            .mouse => acpi_ids.HardwareId.ps2_mouse.hid(),
+            .unknown => null,
+        };
+    }
+};
+
+/// The `_HID`s a PS/2 pointing device (the controller's aux channel) can enumerate
+/// under. It is the same 8042 mouse channel whichever id the firmware chose:
+/// QEMU/OVMF report the generic `.ps2_mouse` (PNP0F13), VirtualBox reports
+/// `.microsoft_ps2_mouse` (PNP0F03). Both mean "the mouse on port two".
+pub const mouse_hardware_ids = [_]acpi_ids.HardwareId{ .ps2_mouse, .microsoft_ps2_mouse };
+
+/// Find the aux (mouse) device's ACPI node, whichever of the PS/2-mouse `_HID`s the
+/// firmware used — the bus needs it to bind IRQ12, and the mouse driver to confirm
+/// its device is present. Returns the first match, or null if none is reported.
+pub fn findMouseDescriptor(buffer: []device.DeviceDescriptor) ?device.DeviceDescriptor {
+    for (mouse_hardware_ids) |id| {
+        if (device.findDeviceDescriptorByHid(buffer, id.hid())) |descriptor| return descriptor;
+    }
+    return null;
+}
+
+// --- the bus <-> child-driver forwarding protocol -----------------------------
+//
+// The 8042's ports and IRQ1 live on the PNP0303 node that only the ps2-bus driver
+// claims, so the child device drivers (ps2-keyboard, ps2-mouse) cannot read port
+// 0x60 themselves. Instead each child **attaches**: it calls the bus's well-known
+// `ps2_bus` endpoint with an `AttachRequest`, handing over its own endpoint as the
+// call's capability. From then on the bus forwards every byte the device sends as
+// a `ForwardedByte` via the asynchronous `ipc.send` — the IRQ path in the bus can
+// never block on a slow child, and the child never touches the controller.
+
+/// A child driver registering for its device's bytes. `device_type` is a
+/// `DeviceType` value; the child's receive endpoint travels as the call's
+/// capability (`send_cap`).
+pub const AttachRequest = extern struct {
+    device_type: u32,
+};
+
+/// How the bus answered an `AttachRequest` (`AttachReply.status`).
+pub const AttachStatus = enum(i32) {
+    ok = 0,
+    /// The request was malformed (too short to be an `AttachRequest`).
+    invalid_request = -1,
+    /// The call carried no endpoint capability to forward to.
+    missing_endpoint = -2,
+    /// No port identified a device of the requested type.
+    no_such_device = -3,
+};
+
+/// Reply to an `AttachRequest`. `status` is an `AttachStatus` value.
+pub const AttachReply = extern struct {
+    status: i32,
+    _padding: u32 = 0,
+};
+
+/// One raw byte read from the data port, forwarded to the attached child whose
+/// port it came from (routed by the status register's auxiliary-output bit).
+pub const ForwardedByte = extern struct {
+    /// The `Port` the byte came from, as `@intFromEnum`.
+    port: u32,
+    byte: u32,
+};
+
+/// A single PS/2 (8042) controller. Construct one with `Controller.init` and
+/// drive the controller through its methods; there is only ever one 8042 per
+/// machine, but holding the resolved resource indices in an instance keeps the
+/// call sites free of global state.
+pub const Controller = struct {
+    device_id: u64,
+    /// Resource index of the command/status port (0x64).
+    status_index: u64,
+    /// Resource index of the data port (0x60).
+    data_index: u64,
+
+    /// Resolve the controller's IO-port resource indices from its device
+    /// descriptor. Returns null if either the data or command/status port is
+    /// missing from the descriptor.
+    pub fn init(device_descriptor: device.DeviceDescriptor) ?Controller {
+        var data_index: ?u64 = null;
+        var status_index: ?u64 = null;
+
+        for (device_descriptor.resources, 0..device_descriptor.resource_count) |resource, resource_index| {
+            if (resource.kind != @intFromEnum(device.ResourceKind.io_port)) continue;
+            if (resource.start == dataPort) {
+                data_index = @intCast(resource_index);
+            } else if (resource.start == statusRegisterPort) {
+                status_index = @intCast(resource_index);
+            }
+        }
+
+        return .{
+            .device_id = device_descriptor.id,
+            .data_index = data_index orelse return null,
+            .status_index = status_index orelse return null,
+        };
+    }
+
+    pub fn disablePort(self: Controller, port: Port) void {
+        // port enable/disable are controller commands and go to the command register (0x64)
+        _ = sendCommand(self.device_id, self.status_index, port.disableCommand(), default_wait_timeout_nanoseconds);
+    }
+
+    pub fn enablePort(self: Controller, port: Port) void {
+        // enabling a port also starts its clock
+        _ = sendCommand(self.device_id, self.status_index, port.enableCommand(), default_wait_timeout_nanoseconds);
+    }
+
+    /// Run a port's interface test. Returns the controller's reply — compare it
+    /// to `response_port_test_passed` (0x00) — or null on timeout.
+    pub fn testPort(self: Controller, port: Port) ?u8 {
+        if (!sendCommand(self.device_id, self.status_index, port.testCommand(), default_wait_timeout_nanoseconds)) return null;
+        return readData(self.device_id, self.status_index, self.data_index, default_wait_timeout_nanoseconds);
+    }
+
+    pub fn flushOutputBuffer(self: Controller) void {
+        // flush any stale byte the controller buffered
+        _ = device.ioRead(self.device_id, self.data_index, 0, 1);
+    }
+
+    pub fn readConfigurationByte(self: Controller) ?u8 {
+        // ask the controller to place its configuration byte in the output buffer, then read it
+        if (!sendCommand(self.device_id, self.status_index, cmd_read_configuration_byte, default_wait_timeout_nanoseconds)) return null;
+        return readData(self.device_id, self.status_index, self.data_index, default_wait_timeout_nanoseconds);
+    }
+
+    pub fn writeConfigurationByte(self: Controller, update_byte: u8) ?u8 {
+        // command 0x60 makes the controller store the next data-port byte as its configuration byte
+        if (!sendCommand(self.device_id, self.status_index, cmd_write_configuration_byte, default_wait_timeout_nanoseconds)) return null;
+        if (!writeData(self.device_id, self.status_index, self.data_index, update_byte, default_wait_timeout_nanoseconds)) return null;
+        return update_byte;
+    }
+
+    /// Run the controller self-test. Returns the reply — compare it to
+    /// `response_controller_test_passed` (0x55) — or null on timeout.
+    pub fn performSelfTest(self: Controller) ?u8 {
+        if (!sendCommand(self.device_id, self.status_index, cmd_test_controller, default_wait_timeout_nanoseconds)) return null;
+        return readData(self.device_id, self.status_index, self.data_index, default_wait_timeout_nanoseconds);
+    }
+
+    /// Detect whether this is a dual-channel controller by temporarily enabling
+    /// port 2 and checking whether its clock turned on. Note: this leaves port 2
+    /// enabled; the caller should disable it again to keep the bus quiet until
+    /// device bring-up.
+    pub fn hasTwoChannels(self: Controller) ?bool {
+        self.enablePort(.two);
+        const configuration = self.readConfigurationByte() orelse return null;
+        return (configuration & Port.two.clockDisabledBit()) == 0;
+    }
+
+    /// Reset the device attached to `port` (device command 0xFF) and wait for
+    /// its power-on self-test (BAT) result. Returns true if the device both
+    /// acknowledged and passed, false if it reported a self-test failure, or
+    /// null on timeout. The BAT reply can be slow, so the response reads use
+    /// `device_reset_timeout_nanoseconds`.
+    pub fn resetDevice(self: Controller, port: Port) ?bool {
+        // A byte destined for port 2 must be prefixed with the "write to second
+        // port input buffer" controller command (0xD4); port 1 is the default.
+        if (port.deviceInputCommand()) |prefix| {
+            if (!sendCommand(self.device_id, self.status_index, prefix, default_wait_timeout_nanoseconds)) return null;
+        }
+        if (!writeData(self.device_id, self.status_index, self.data_index, device_cmd_reset, default_wait_timeout_nanoseconds)) return null;
+
+        // A successful reset yields both an ACK (0xFA) and a self-test-passed
+        // byte (0xAA). Their order is not guaranteed, so accept either ordering.
+        var saw_acknowledge = false;
+        var saw_self_test_passed = false;
+        var reads: u8 = 0;
+        while (reads < 2) : (reads += 1) {
+            const reply = readData(self.device_id, self.status_index, self.data_index, device_reset_timeout_nanoseconds) orelse return null;
+            switch (reply) {
+                device_response_acknowledge => saw_acknowledge = true,
+                device_response_self_test_passed => saw_self_test_passed = true,
+                device_response_self_test_failed_1, device_response_self_test_failed_2 => return false,
+                else => {},
+            }
+        }
+        return saw_acknowledge and saw_self_test_passed;
+    }
+
+    /// Send one command byte to the device on `port` (applying the port-2 prefix
+    /// as needed) and consume its acknowledgement. Returns true on ACK (0xFA),
+    /// false on any other reply, or null on timeout.
+    pub fn sendToDevice(self: Controller, port: Port, byte: u8) ?bool {
+        if (port.deviceInputCommand()) |prefix| {
+            if (!sendCommand(self.device_id, self.status_index, prefix, default_wait_timeout_nanoseconds)) return null;
+        }
+        if (!writeData(self.device_id, self.status_index, self.data_index, byte, default_wait_timeout_nanoseconds)) return null;
+        const reply = readData(self.device_id, self.status_index, self.data_index, default_wait_timeout_nanoseconds) orelse return null;
+        return reply == device_response_acknowledge;
+    }
+
+    /// Discard any bytes sitting in the output buffer (for example the device-id
+    /// byte a mouse emits after a reset) so they cannot be mistaken for the reply
+    /// to a subsequent command.
+    pub fn drainOutputBuffer(self: Controller) void {
+        var guard: u8 = 0;
+        while (guard < 16) : (guard += 1) {
+            if (status(self.device_id, self.status_index) & status_output_buffer_full == 0) return;
+            _ = device.ioRead(self.device_id, self.data_index, 0, 1);
+        }
+    }
+
+    /// Ask the device on `port` what it is (command 0xF2) and classify the reply.
+    /// Scanning is disabled around the query so a streaming device cannot inject
+    /// data bytes that look like the identifier. Returns the device type, or null
+    /// if the identify command itself timed out.
+    pub fn identifyDevice(self: Controller, port: Port) ?DeviceType {
+        // Clear any leftover bytes (e.g. a post-reset mouse id) before we start.
+        self.drainOutputBuffer();
+
+        // Stop the device reporting so its data can't be mistaken for the reply.
+        if (self.sendToDevice(port, device_cmd_disable_scanning) == null) return null;
+
+        if (self.sendToDevice(port, device_cmd_identify) == null) return null;
+
+        // After the ACK, the device sends 0, 1, or 2 identifier bytes.
+        const first = readData(self.device_id, self.status_index, self.data_index, default_wait_timeout_nanoseconds);
+        const device_type: DeviceType = if (first) |id| switch (id) {
+            identify_keyboard_mf2 => blk: {
+                // A MF2 keyboard sends a second subtype byte; consume and ignore it.
+                _ = readData(self.device_id, self.status_index, self.data_index, default_wait_timeout_nanoseconds);
+                break :blk .keyboard;
+            },
+            identify_mouse_standard, identify_mouse_scroll, identify_mouse_five_button => .mouse,
+            else => .unknown,
+        } else
+            // No identifier bytes at all is a legacy AT keyboard.
+            .keyboard;
+
+        // Resume scanning so the device works once its driver takes over.
+        _ = self.sendToDevice(port, device_cmd_enable_scanning);
+        return device_type;
+    }
+};

system/drivers/ps2-bus/scancode.zig

@@ -0,0 +1,389 @@
+//! PS/2 scancode set 2 → USB HID usage decoding, plus the keyboard state a driver
+//! needs on top of it (pressed keys, modifier tracking, caps-lock toggle).
+//!
+//! Set 2 is what a keyboard sends when the 8042's legacy set-1 translation is off —
+//! which is how ps2-bus.zig deliberately configures the controller. A key's **make**
+//! code is one byte (two with an `E0` prefix for the "extended" keys added after the
+//! original AT layout); its **break** code is the same code behind an `F0` prefix.
+//! Pause alone is an eight-byte `E1` sequence with no break.
+//!
+//! The output vocabulary is USB HID keyboard-page usages (a=4, enter=40, ...), the
+//! same numbering the input protocol's `Keycode` and the xkeyboard-config layout
+//! tables use — so a decoded usage indexes a layout directly.
+//!
+//! Everything here is pure (no imports beyond `std`, no IO), so it is host-testable:
+//! the tests at the bottom run under `zig build test`.
+
+const std = @import("std");
+
+// --- USB HID usages the state machine itself needs to recognize --------------
+
+pub const usage_caps_lock: u8 = 0x39;
+pub const usage_left_control: u8 = 0xE0;
+pub const usage_left_shift: u8 = 0xE1;
+pub const usage_left_alt: u8 = 0xE2;
+pub const usage_right_control: u8 = 0xE4;
+pub const usage_right_shift: u8 = 0xE5;
+pub const usage_right_alt: u8 = 0xE6; // AltGr — selects XKB level 3
+
+// --- scancode set 2 → HID usage tables ---------------------------------------
+
+/// Single-byte (non-`E0`) make codes. Zero means "no key" — protocol bytes (ACK,
+/// BAT results) and reserved codes land there and decode to nothing.
+pub const set2_base: [256]u8 = blk: {
+    var table = [_]u8{0} ** 256;
+    // function row
+    table[0x01] = 0x42; // F9
+    table[0x03] = 0x3E; // F5
+    table[0x04] = 0x3C; // F3
+    table[0x05] = 0x3A; // F1
+    table[0x06] = 0x3B; // F2
+    table[0x07] = 0x45; // F12
+    table[0x09] = 0x43; // F10
+    table[0x0A] = 0x41; // F8
+    table[0x0B] = 0x3F; // F6
+    table[0x0C] = 0x3D; // F4
+    table[0x78] = 0x44; // F11
+    table[0x83] = 0x40; // F7
+    // letters
+    table[0x1C] = 0x04; // A
+    table[0x32] = 0x05; // B
+    table[0x21] = 0x06; // C
+    table[0x23] = 0x07; // D
+    table[0x24] = 0x08; // E
+    table[0x2B] = 0x09; // F
+    table[0x34] = 0x0A; // G
+    table[0x33] = 0x0B; // H
+    table[0x43] = 0x0C; // I
+    table[0x3B] = 0x0D; // J
+    table[0x42] = 0x0E; // K
+    table[0x4B] = 0x0F; // L
+    table[0x3A] = 0x10; // M
+    table[0x31] = 0x11; // N
+    table[0x44] = 0x12; // O
+    table[0x4D] = 0x13; // P
+    table[0x15] = 0x14; // Q
+    table[0x2D] = 0x15; // R
+    table[0x1B] = 0x16; // S
+    table[0x2C] = 0x17; // T
+    table[0x3C] = 0x18; // U
+    table[0x2A] = 0x19; // V
+    table[0x1D] = 0x1A; // W
+    table[0x22] = 0x1B; // X
+    table[0x35] = 0x1C; // Y
+    table[0x1A] = 0x1D; // Z
+    // digit row
+    table[0x16] = 0x1E; // 1
+    table[0x1E] = 0x1F; // 2
+    table[0x26] = 0x20; // 3
+    table[0x25] = 0x21; // 4
+    table[0x2E] = 0x22; // 5
+    table[0x36] = 0x23; // 6
+    table[0x3D] = 0x24; // 7
+    table[0x3E] = 0x25; // 8
+    table[0x46] = 0x26; // 9
+    table[0x45] = 0x27; // 0
+    // control and whitespace
+    table[0x5A] = 0x28; // Enter
+    table[0x76] = 0x29; // Escape
+    table[0x66] = 0x2A; // Backspace
+    table[0x0D] = 0x2B; // Tab
+    table[0x29] = 0x2C; // Space
+    // punctuation
+    table[0x4E] = 0x2D; // - _
+    table[0x55] = 0x2E; // = +
+    table[0x54] = 0x2F; // [ {
+    table[0x5B] = 0x30; // ] }
+    table[0x5D] = 0x31; // \ | (non-US hash on ISO boards, same position)
+    table[0x4C] = 0x33; // ; :
+    table[0x52] = 0x34; // ' "
+    table[0x0E] = 0x35; // ` ~
+    table[0x41] = 0x36; // , <
+    table[0x49] = 0x37; // . >
+    table[0x4A] = 0x38; // / ?
+    table[0x61] = 0x64; // non-US backslash (the extra ISO key between shift and Z)
+    // locks
+    table[0x58] = usage_caps_lock;
+    table[0x77] = 0x53; // Num Lock
+    table[0x7E] = 0x47; // Scroll Lock
+    // keypad
+    table[0x7C] = 0x55; // keypad *
+    table[0x7B] = 0x56; // keypad -
+    table[0x79] = 0x57; // keypad +
+    table[0x69] = 0x59; // keypad 1
+    table[0x72] = 0x5A; // keypad 2
+    table[0x7A] = 0x5B; // keypad 3
+    table[0x6B] = 0x5C; // keypad 4
+    table[0x73] = 0x5D; // keypad 5
+    table[0x74] = 0x5E; // keypad 6
+    table[0x6C] = 0x5F; // keypad 7
+    table[0x75] = 0x60; // keypad 8
+    table[0x7D] = 0x61; // keypad 9
+    table[0x70] = 0x62; // keypad 0
+    table[0x71] = 0x63; // keypad .
+    // modifiers
+    table[0x14] = usage_left_control;
+    table[0x12] = usage_left_shift;
+    table[0x11] = usage_left_alt;
+    table[0x59] = usage_right_shift;
+    break :blk table;
+};
+
+/// `E0`-prefixed make codes. `E0 12` is the "fake shift" the keyboard wraps around
+/// Print Screen and navigation keys when a real shift is involved; it maps to zero
+/// here, so it decodes to nothing and only the real key comes through.
+pub const set2_extended: [256]u8 = blk: {
+    var table = [_]u8{0} ** 256;
+    table[0x11] = usage_right_alt;
+    table[0x14] = usage_right_control;
+    table[0x1F] = 0xE3; // left GUI
+    table[0x27] = 0xE7; // right GUI
+    table[0x2F] = 0x65; // application (menu)
+    table[0x7C] = 0x46; // Print Screen (arrives as E0 12 E0 7C; the E0 12 decodes to nothing)
+    table[0x4A] = 0x54; // keypad /
+    table[0x5A] = 0x58; // keypad Enter
+    table[0x70] = 0x49; // Insert
+    table[0x6C] = 0x4A; // Home
+    table[0x7D] = 0x4B; // Page Up
+    table[0x71] = 0x4C; // Delete
+    table[0x69] = 0x4D; // End
+    table[0x7A] = 0x4E; // Page Down
+    table[0x74] = 0x4F; // right arrow
+    table[0x6B] = 0x50; // left arrow
+    table[0x72] = 0x51; // down arrow
+    table[0x75] = 0x52; // up arrow
+    break :blk table;
+};
+
+// --- the byte-stream decoder --------------------------------------------------
+
+/// One decoded key transition: which key (as a USB HID usage) and whether this is
+/// a make (press or typematic repeat) or a break (release).
+pub const DecodedKey = struct {
+    usage: u8,
+    make: bool,
+};
+
+/// Turns the raw set-2 byte stream into `DecodedKey`s. Feed it every byte the
+/// keyboard sends; most bytes complete a key and return one, prefix bytes return
+/// null and arm the state machine for the next byte.
+pub const Decoder = struct {
+    const State = enum {
+        idle,
+        extended, // saw E0
+        break_prefix, // saw F0
+        extended_break, // saw E0 F0
+        pause_skip, // inside the 8-byte E1 Pause sequence
+    };
+
+    state: State = .idle,
+    /// Bytes still to swallow in `pause_skip`.
+    skip: u8 = 0,
+
+    /// The whole Pause make sequence is `E1 14 77 E1 F0 14 F0 77` — seven bytes
+    /// after the leading `E1`, and no break sequence ever follows.
+    const pause_bytes_after_e1: u8 = 7;
+
+    pub fn feed(self: *Decoder, byte: u8) ?DecodedKey {
+        switch (self.state) {
+            .idle => switch (byte) {
+                0xE0 => self.state = .extended,
+                0xF0 => self.state = .break_prefix,
+                0xE1 => {
+                    self.state = .pause_skip;
+                    self.skip = pause_bytes_after_e1;
+                },
+                // Anything else is a make code — or a protocol byte (0xFA ACK,
+                // 0xAA BAT-passed, 0xEE echo, ...), which the tables map to zero.
+                else => return decoded(set2_base[byte], true),
+            },
+            .extended => switch (byte) {
+                0xF0 => self.state = .extended_break,
+                else => {
+                    self.state = .idle;
+                    return decoded(set2_extended[byte], true);
+                },
+            },
+            .break_prefix => {
+                self.state = .idle;
+                return decoded(set2_base[byte], false);
+            },
+            .extended_break => {
+                self.state = .idle;
+                return decoded(set2_extended[byte], false);
+            },
+            .pause_skip => {
+                self.skip -= 1;
+                if (self.skip == 0) self.state = .idle;
+            },
+        }
+        return null;
+    }
+
+    fn decoded(usage: u8, make: bool) ?DecodedKey {
+        if (usage == 0) return null; // unmapped or a protocol byte
+        return .{ .usage = usage, .make = make };
+    }
+};
+
+// --- driver-side keyboard state -----------------------------------------------
+
+/// What a key transition did, plus the modifier state to stamp on the resulting
+/// events (snapshotted after the transition was applied).
+pub const Transition = struct {
+    pub const Action = enum {
+        pressed, // physical make of a key that was up
+        repeated, // typematic make of a key already down — no new key_down
+        released, // physical break
+    };
+    action: Action,
+    modifiers: ModifierSnapshot,
+};
+
+/// The modifier state at one instant, in both vocabularies a driver needs: the
+/// input protocol's coarse bits (shift/control/alt) and the level-selection
+/// inputs xkeyboard-config takes (shift, caps_lock, AltGr as level3).
+pub const ModifierSnapshot = struct {
+    shift: bool, // either shift held
+    control: bool, // either control held
+    alt: bool, // either alt held (including AltGr)
+    right_alt: bool, // AltGr specifically — the XKB level-3 selector
+    caps_lock: bool, // the toggle, not the key
+};
+
+/// Tracks which keys are physically down and the caps-lock toggle, and classifies
+/// each decoded transition. Pure state — no IO — so repeat detection and modifier
+/// snapshots are host-testable.
+pub const KeyboardState = struct {
+    /// One bit per HID usage: set while the key is physically down.
+    pressed: [32]u8 = [_]u8{0} ** 32,
+    caps_lock: bool = false,
+
+    pub fn apply(self: *KeyboardState, key: DecodedKey) Transition {
+        const already_down = self.isPressed(key.usage);
+        if (key.make) {
+            if (!already_down) {
+                self.setPressed(key.usage, true);
+                if (key.usage == usage_caps_lock) self.caps_lock = !self.caps_lock;
+            }
+            return .{
+                .action = if (already_down) .repeated else .pressed,
+                .modifiers = self.snapshot(),
+            };
+        }
+        self.setPressed(key.usage, false);
+        return .{ .action = .released, .modifiers = self.snapshot() };
+    }
+
+    pub fn isPressed(self: *const KeyboardState, usage: u8) bool {
+        return self.pressed[usage / 8] & (@as(u8, 1) << @intCast(usage % 8)) != 0;
+    }
+
+    fn setPressed(self: *KeyboardState, usage: u8, down: bool) void {
+        const bit = @as(u8, 1) << @intCast(usage % 8);
+        if (down) {
+            self.pressed[usage / 8] |= bit;
+        } else {
+            self.pressed[usage / 8] &= ~bit;
+        }
+    }
+
+    fn snapshot(self: *const KeyboardState) ModifierSnapshot {
+        const right_alt = self.isPressed(usage_right_alt);
+        return .{
+            .shift = self.isPressed(usage_left_shift) or self.isPressed(usage_right_shift),
+            .control = self.isPressed(usage_left_control) or self.isPressed(usage_right_control),
+            .alt = self.isPressed(usage_left_alt) or right_alt,
+            .right_alt = right_alt,
+            .caps_lock = self.caps_lock,
+        };
+    }
+};
+
+// --- tests (host-run via `zig build test`) ------------------------------------
+
+const testing = std.testing;
+
+/// Feed `bytes` and return the single DecodedKey they should produce (fails the
+/// test if they produce none or more than one).
+fn feedOne(decoder: *Decoder, bytes: []const u8) !DecodedKey {
+    var result: ?DecodedKey = null;
+    for (bytes) |byte| {
+        if (decoder.feed(byte)) |key| {
+            try testing.expect(result == null);
+            result = key;
+        }
+    }
+    return result orelse error.TestExpectedResult;
+}
+
+fn feedNone(decoder: *Decoder, bytes: []const u8) !void {
+    for (bytes) |byte| try testing.expectEqual(@as(?DecodedKey, null), decoder.feed(byte));
+}
+
+test "base make and break: A" {
+    var decoder = Decoder{};
+    try testing.expectEqual(DecodedKey{ .usage = 0x04, .make = true }, try feedOne(&decoder, &.{0x1C}));
+    try testing.expectEqual(DecodedKey{ .usage = 0x04, .make = false }, try feedOne(&decoder, &.{ 0xF0, 0x1C }));
+}
+
+test "extended make and break: right arrow" {
+    var decoder = Decoder{};
+    try testing.expectEqual(DecodedKey{ .usage = 0x4F, .make = true }, try feedOne(&decoder, &.{ 0xE0, 0x74 }));
+    try testing.expectEqual(DecodedKey{ .usage = 0x4F, .make = false }, try feedOne(&decoder, &.{ 0xE0, 0xF0, 0x74 }));
+}
+
+test "pause: the E1 sequence is consumed silently" {
+    var decoder = Decoder{};
+    try feedNone(&decoder, &.{ 0xE1, 0x14, 0x77, 0xE1, 0xF0, 0x14, 0xF0, 0x77 });
+    // The decoder is back in idle: an ordinary key still decodes.
+    try testing.expectEqual(DecodedKey{ .usage = 0x04, .make = true }, try feedOne(&decoder, &.{0x1C}));
+}
+
+test "protocol bytes decode to nothing" {
+    var decoder = Decoder{};
+    try feedNone(&decoder, &.{ 0xFA, 0xAA, 0xEE }); // ACK, BAT-passed, echo
+}
+
+test "print screen: the fake-shift E0 12 decodes to nothing" {
+    var decoder = Decoder{};
+    try feedNone(&decoder, &.{ 0xE0, 0x12 });
+    try testing.expectEqual(DecodedKey{ .usage = 0x46, .make = true }, try feedOne(&decoder, &.{ 0xE0, 0x7C }));
+}
+
+test "typematic repeat is classified, not re-pressed" {
+    var state = KeyboardState{};
+    const a = DecodedKey{ .usage = 0x04, .make = true };
+    try testing.expectEqual(Transition.Action.pressed, state.apply(a).action);
+    try testing.expectEqual(Transition.Action.repeated, state.apply(a).action);
+    try testing.expectEqual(Transition.Action.repeated, state.apply(a).action);
+    try testing.expectEqual(Transition.Action.released, state.apply(.{ .usage = 0x04, .make = false }).action);
+    try testing.expectEqual(Transition.Action.pressed, state.apply(a).action);
+}
+
+test "shift held shows in the snapshot of other keys" {
+    var state = KeyboardState{};
+    _ = state.apply(.{ .usage = usage_left_shift, .make = true });
+    const transition = state.apply(.{ .usage = 0x04, .make = true });
+    try testing.expect(transition.modifiers.shift);
+    try testing.expect(!transition.modifiers.control);
+    _ = state.apply(.{ .usage = usage_left_shift, .make = false });
+    _ = state.apply(.{ .usage = 0x04, .make = false });
+    try testing.expect(!state.apply(.{ .usage = 0x04, .make = true }).modifiers.shift);
+}
+
+test "right alt reports both alt and the level-3 selector" {
+    var state = KeyboardState{};
+    _ = state.apply(.{ .usage = usage_right_alt, .make = true });
+    const transition = state.apply(.{ .usage = 0x04, .make = true });
+    try testing.expect(transition.modifiers.alt);
+    try testing.expect(transition.modifiers.right_alt);
+}
+
+test "caps lock toggles on make, not on repeat or break" {
+    var state = KeyboardState{};
+    try testing.expect(state.apply(.{ .usage = usage_caps_lock, .make = true }).modifiers.caps_lock);
+    try testing.expect(state.apply(.{ .usage = usage_caps_lock, .make = true }).modifiers.caps_lock); // repeat
+    try testing.expect(state.apply(.{ .usage = usage_caps_lock, .make = false }).modifiers.caps_lock);
+    try testing.expect(!state.apply(.{ .usage = usage_caps_lock, .make = true }).modifiers.caps_lock); // second press: off
+}

system/drivers/usb-hid/hid-report.zig

@@ -0,0 +1,191 @@
+//! Pure decoders for USB HID **boot-protocol** reports — the simplified,
+//! fixed-format reports a boot keyboard and boot mouse send, the USB analog of
+//! the PS/2 scancode and mouse-packet decoders. No I/O: these turn report bytes
+//! into make/break transitions and motion, which the usb-hid drivers publish to
+//! the input service. Host-testable in isolation (like mouse-packet.zig).
+//!
+//! "Boot protocol" is a USB HID term (USB HID 1.11 §B) — the device reports in
+//! this fixed layout after SET_PROTOCOL(boot); it has nothing to do with system
+//! boot.
+
+const std = @import("std");
+
+// --- keyboard ---------------------------------------------------------------
+
+/// The 8-byte boot keyboard report: a modifier bitmap, a reserved byte, and up
+/// to six concurrently-pressed key usages.
+pub const KeyboardReport = extern struct {
+    modifiers: u8 = 0,
+    reserved: u8 = 0,
+    keys: [6]u8 = .{ 0, 0, 0, 0, 0, 0 },
+};
+
+// The modifier byte's bits (HID keyboard boot report).
+pub const modifier_left_control: u8 = 1 << 0;
+pub const modifier_left_shift: u8 = 1 << 1;
+pub const modifier_left_alt: u8 = 1 << 2;
+pub const modifier_left_gui: u8 = 1 << 3;
+pub const modifier_right_control: u8 = 1 << 4;
+pub const modifier_right_shift: u8 = 1 << 5;
+pub const modifier_right_alt: u8 = 1 << 6;
+pub const modifier_right_gui: u8 = 1 << 7;
+
+pub const TransitionKind = enum { pressed, released };
+
+/// One key going down or up. `usage` is a HID keyboard-page usage — modifier keys
+/// map to usages 224..231 — which is exactly the input protocol's `Keycode`.
+pub const Transition = struct { kind: TransitionKind, usage: u8 };
+
+// A report can change at most all 8 modifiers and all 6 keys at once.
+pub const max_transitions = 8 + 6;
+
+pub const Transitions = struct {
+    items: [max_transitions]Transition = undefined,
+    count: usize = 0,
+
+    fn add(self: *Transitions, transition: Transition) void {
+        if (self.count < self.items.len) {
+            self.items[self.count] = transition;
+            self.count += 1;
+        }
+    }
+
+    pub fn slice(self: *const Transitions) []const Transition {
+        return self.items[0..self.count];
+    }
+};
+
+/// Turns a stream of boot keyboard reports into make/break transitions by diffing
+/// each report against the last.
+pub const KeyboardDecoder = struct {
+    previous: KeyboardReport = .{},
+
+    pub fn feed(self: *KeyboardDecoder, current: KeyboardReport) Transitions {
+        var out = Transitions{};
+
+        // Rollover: 0x01 (ErrorRollOver) means more keys are held than the report
+        // can carry, so the key array is invalid. Emit nothing and keep the prior
+        // state (so the eventual releases still resolve against real keys).
+        for (current.keys) |key| {
+            if (key == 0x01) return out;
+        }
+
+        // Modifiers: one make/break per changed bit; modifier usages are 224..231.
+        const changed = current.modifiers ^ self.previous.modifiers;
+        var bit: u3 = 0;
+        while (true) : (bit += 1) {
+            const mask = @as(u8, 1) << bit;
+            if (changed & mask != 0) {
+                out.add(.{
+                    .kind = if (current.modifiers & mask != 0) .pressed else .released,
+                    .usage = 224 + @as(u8, bit),
+                });
+            }
+            if (bit == 7) break;
+        }
+
+        // Keys made: present now, absent before.
+        for (current.keys) |key| {
+            if (key != 0 and !contains(&self.previous.keys, key)) out.add(.{ .kind = .pressed, .usage = key });
+        }
+        // Keys broken: present before, absent now.
+        for (self.previous.keys) |key| {
+            if (key != 0 and !contains(&current.keys, key)) out.add(.{ .kind = .released, .usage = key });
+        }
+
+        self.previous = current;
+        return out;
+    }
+};
+
+fn contains(keys: *const [6]u8, value: u8) bool {
+    for (keys) |key| {
+        if (key == value) return true;
+    }
+    return false;
+}
+
+// --- mouse ------------------------------------------------------------------
+
+/// A decoded boot mouse report: the button bitmap and relative motion. The wheel
+/// byte is present only on 4-byte reports (QEMU's usb-mouse sends one).
+pub const MouseReport = struct {
+    buttons: u8 = 0,
+    dx: i8 = 0,
+    dy: i8 = 0,
+    wheel: i8 = 0,
+    has_wheel: bool = false,
+};
+
+pub const mouse_button_left: u8 = 1 << 0;
+pub const mouse_button_right: u8 = 1 << 1;
+pub const mouse_button_middle: u8 = 1 << 2;
+
+/// Parse a 3- or 4-byte boot mouse report. Note HID reports Y in screen
+/// convention (positive = down), so — unlike PS/2 — `dy` is NOT negated.
+pub fn parseMouse(bytes: []const u8) ?MouseReport {
+    if (bytes.len < 3) return null;
+    return .{
+        .buttons = bytes[0],
+        .dx = @bitCast(bytes[1]),
+        .dy = @bitCast(bytes[2]),
+        .wheel = if (bytes.len >= 4) @bitCast(bytes[3]) else 0,
+        .has_wheel = bytes.len >= 4,
+    };
+}
+
+// --- tests ------------------------------------------------------------------
+
+test "keyboard diff produces make and break transitions" {
+    var decoder = KeyboardDecoder{};
+
+    // Press 'a' (usage 4).
+    var t = decoder.feed(.{ .keys = .{ 4, 0, 0, 0, 0, 0 } });
+    try std.testing.expectEqual(@as(usize, 1), t.count);
+    try std.testing.expectEqual(TransitionKind.pressed, t.items[0].kind);
+    try std.testing.expectEqual(@as(u8, 4), t.items[0].usage);
+
+    // Hold 'a', press 'b' (usage 5): only 'b' is new.
+    t = decoder.feed(.{ .keys = .{ 4, 5, 0, 0, 0, 0 } });
+    try std.testing.expectEqual(@as(usize, 1), t.count);
+    try std.testing.expectEqual(@as(u8, 5), t.items[0].usage);
+
+    // Release everything: 'a' and 'b' both break.
+    t = decoder.feed(.{ .keys = .{ 0, 0, 0, 0, 0, 0 } });
+    try std.testing.expectEqual(@as(usize, 2), t.count);
+    try std.testing.expectEqual(TransitionKind.released, t.items[0].kind);
+
+    // Press Left Shift (modifier bit 1 -> usage 225).
+    t = decoder.feed(.{ .modifiers = modifier_left_shift });
+    try std.testing.expectEqual(@as(usize, 1), t.count);
+    try std.testing.expectEqual(@as(u8, 225), t.items[0].usage);
+    try std.testing.expectEqual(TransitionKind.pressed, t.items[0].kind);
+}
+
+test "rollover report is ignored but state is preserved" {
+    var decoder = KeyboardDecoder{};
+    _ = decoder.feed(.{ .keys = .{ 4, 0, 0, 0, 0, 0 } }); // press 'a'
+
+    const rollover = decoder.feed(.{ .keys = .{ 0x01, 0x01, 0x01, 0x01, 0x01, 0x01 } });
+    try std.testing.expectEqual(@as(usize, 0), rollover.count);
+
+    // 'a' is still considered down, so releasing all keys now breaks it.
+    const release = decoder.feed(.{ .keys = .{ 0, 0, 0, 0, 0, 0 } });
+    try std.testing.expectEqual(@as(usize, 1), release.count);
+    try std.testing.expectEqual(@as(u8, 4), release.items[0].usage);
+    try std.testing.expectEqual(TransitionKind.released, release.items[0].kind);
+}
+
+test "mouse report parses motion without inverting Y" {
+    const three = parseMouse(&.{ mouse_button_left, 5, 0xFB }).?; // dy = -5
+    try std.testing.expectEqual(mouse_button_left, three.buttons);
+    try std.testing.expectEqual(@as(i8, 5), three.dx);
+    try std.testing.expectEqual(@as(i8, -5), three.dy);
+    try std.testing.expect(!three.has_wheel);
+
+    const four = parseMouse(&.{ 0, 0, 0, 0xFF }).?; // wheel = -1
+    try std.testing.expect(four.has_wheel);
+    try std.testing.expectEqual(@as(i8, -1), four.wheel);
+
+    try std.testing.expect(parseMouse(&.{ 0, 0 }) == null); // too short
+}

system/drivers/usb-hid/keyboard.zig

@@ -0,0 +1,169 @@
+//! USB HID boot keyboard driver.
+//!
+//! Spawned by the device manager when the xHCI bus driver reports a HID / boot /
+//! keyboard interface (class 3, subclass 1, protocol 1); its assigned device id
+//! arrives as argv[1] and an optional layout name ("us", "gb", ...) as argv[2].
+//! It owns no hardware: it opens its device through the USB transfer protocol
+//! (`runtime.usb`), asks the device for the boot protocol, subscribes to its
+//! interrupt-IN endpoint, and turns each 8-byte boot report into input-protocol
+//! events, published to the input service — the USB analogue of ps2-bus/keyboard.
+//!
+//!   interrupt report -> hid-report diff -> key_down / key_up
+//!                                       -> xkeyboard-config -> character -> key_press
+//!
+//! Because a USB keyboard's usages ARE the input protocol's keycodes (both are
+//! HID keyboard page 0x07), the decode is nearly 1:1 — no scancode translation.
+
+const std = @import("std");
+const runtime = @import("runtime");
+const usb_abi = @import("usb-abi");
+const xkb = @import("xkeyboard-config");
+const hid = @import("hid-report.zig");
+const ipc = runtime.ipc;
+const process = runtime.process;
+const input_protocol = runtime.input_protocol;
+
+fn writeLine(comptime fmt: []const u8, arguments: anytype) void {
+    var line: [128]u8 = undefined;
+    _ = runtime.system.write(std.fmt.bufPrint(&line, fmt, arguments) catch return);
+}
+
+// The modifier state a character lookup needs — derived from the report's
+// modifier byte, plus the driver-tracked caps-lock toggle.
+const ModifierSnapshot = struct {
+    shift: bool,
+    control: bool,
+    right_alt: bool,
+    caps_lock: bool,
+};
+
+/// The character a key produces under `modifiers`, or 0 for none — the layout
+/// lookup for printable keys, with ASCII control characters for the keys every
+/// consumer expects (Enter, Tab, Backspace, Escape), exactly as ps2-bus/keyboard.
+fn characterFor(layout: *const xkb.Layout, usage: u8, modifiers: ModifierSnapshot) u32 {
+    const mapping = xkb.map(layout, usage, .{
+        .shift = modifiers.shift,
+        .caps_lock = modifiers.caps_lock,
+        .level3 = modifiers.right_alt,
+        .control = modifiers.control,
+    });
+    if (mapping.character) |character| return character;
+    return switch (@as(input_protocol.Keycode, @enumFromInt(usage))) {
+        .enter, .keypad_enter => '\n',
+        .tab => '\t',
+        .backspace => 0x08,
+        .escape => 0x1B,
+        else => 0,
+    };
+}
+
+fn modifierWord(modifiers: u8) u32 {
+    var word: u32 = 0;
+    if (modifiers & (hid.modifier_left_shift | hid.modifier_right_shift) != 0) word |= input_protocol.modifier_shift;
+    if (modifiers & (hid.modifier_left_control | hid.modifier_right_control) != 0) word |= input_protocol.modifier_control;
+    if (modifiers & (hid.modifier_left_alt | hid.modifier_right_alt) != 0) word |= input_protocol.modifier_alt;
+    return word;
+}
+
+pub fn main(init: runtime.process.Init) void {
+    const argument = init.arguments.get(1) orelse {
+        _ = runtime.system.write("/system/drivers/usb-hid/keyboard: missing device id (argv[1])\n");
+        return;
+    };
+    const device_id = std.fmt.parseInt(u64, argument, 10) catch {
+        writeLine("/system/drivers/usb-hid/keyboard: malformed device id '{s}'\n", .{argument});
+        return;
+    };
+    const layout = xkb.byName(init.arguments.get(2) orelse "us") orelse xkb.us;
+
+    // Hello the manager first (meet the spawn deadline), then open the device.
+    if (!runtime.usb.helloManager(device_id)) {
+        _ = runtime.system.write("/system/drivers/usb-hid/keyboard: hello to device manager failed\n");
+        return;
+    }
+    var device = runtime.usb.open(device_id) orelse {
+        writeLine("/system/drivers/usb-hid/keyboard: could not open device {d}\n", .{device_id});
+        return;
+    };
+    const endpoint = device.findEndpoint(runtime.usb.transfer_type_interrupt, true) orelse {
+        _ = runtime.system.write("/system/drivers/usb-hid/keyboard: no interrupt-IN endpoint\n");
+        return;
+    };
+
+    // Ask for the boot protocol and an indefinite idle (report only on change).
+    _ = device.controlOut(@bitCast(usb_abi.setProtocol(@enumFromInt(device.interface_number), .boot)));
+    _ = device.controlOut(@bitCast(usb_abi.setIdle(@enumFromInt(device.interface_number), 0, 0)));
+
+    if (!device.subscribeInterrupt(endpoint.address, endpoint.max_packet_size)) {
+        _ = runtime.system.write("/system/drivers/usb-hid/keyboard: interrupt subscribe failed\n");
+        return;
+    }
+
+    var source = runtime.input.connectSource() orelse {
+        _ = runtime.system.write("/system/drivers/usb-hid/keyboard: input service unavailable\n");
+        return;
+    };
+    _ = process.bindSignals(device.endpoint);
+    writeLine("/system/drivers/usb-hid/keyboard: ok (device {d}, interface {d}, layout {s})\n", .{ device_id, device.interface_number, layout.name });
+
+    var decoder = hid.KeyboardDecoder{};
+    var caps_lock = false;
+    var receive: [64]u8 = undefined;
+    while (true) {
+        const got = ipc.replyWait(device.endpoint, &.{}, &receive, null);
+        if (!got.isNotification()) continue;
+        if (process.signalsFrom(got.badge)) |signals| {
+            if (signals.has(.terminate)) return;
+            continue;
+        }
+        if (!got.isMessage() or got.len < @sizeOf(runtime.usb.InterruptReport)) continue;
+
+        const message = std.mem.bytesToValue(runtime.usb.InterruptReport, receive[0..@sizeOf(runtime.usb.InterruptReport)]);
+        if (message.length < @sizeOf(hid.KeyboardReport)) continue;
+        const report = std.mem.bytesToValue(hid.KeyboardReport, message.data[0..@sizeOf(hid.KeyboardReport)]);
+        const transitions = decoder.feed(report);
+
+        // Caps Lock toggles on its own key-down (a stateful lock, not a modifier).
+        for (transitions.slice()) |transition| {
+            if (transition.kind == .pressed and @as(input_protocol.Keycode, @enumFromInt(transition.usage)) == .caps_lock) caps_lock = !caps_lock;
+        }
+
+        const modifiers = ModifierSnapshot{
+            .shift = report.modifiers & (hid.modifier_left_shift | hid.modifier_right_shift) != 0,
+            .control = report.modifiers & (hid.modifier_left_control | hid.modifier_right_control) != 0,
+            .right_alt = report.modifiers & hid.modifier_right_alt != 0,
+            .caps_lock = caps_lock,
+        };
+        const modifier_word = modifierWord(report.modifiers);
+
+        for (transitions.slice()) |transition| {
+            switch (transition.kind) {
+                .pressed => {
+                    _ = source.publishKeyboardEvent(.{
+                        .kind = @intFromEnum(input_protocol.EventKind.key_down),
+                        .keycode = transition.usage,
+                        .character = 0,
+                        .modifiers = modifier_word,
+                    });
+                    const character = characterFor(layout, transition.usage, modifiers);
+                    if (character != 0) {
+                        _ = source.publishKeyboardEvent(.{
+                            .kind = @intFromEnum(input_protocol.EventKind.key_press),
+                            .keycode = transition.usage,
+                            .character = character,
+                            .modifiers = modifier_word,
+                        });
+                    }
+                },
+                .released => {
+                    _ = source.publishKeyboardEvent(.{
+                        .kind = @intFromEnum(input_protocol.EventKind.key_up),
+                        .keycode = transition.usage,
+                        .character = 0,
+                        .modifiers = modifier_word,
+                    });
+                },
+            }
+        }
+    }
+}

system/drivers/usb-hid/mouse.zig

@@ -0,0 +1,135 @@
+//! USB HID boot mouse driver.
+//!
+//! Spawned by the device manager when the xHCI bus driver reports a HID / boot /
+//! mouse interface (class 3, subclass 1, protocol 2); its assigned device id
+//! arrives as argv[1]. Like the keyboard driver it owns no hardware: it opens its
+//! device through the USB transfer protocol (`runtime.usb`), asks for the boot
+//! protocol, subscribes to its interrupt-IN endpoint, and turns each 3- or 4-byte
+//! boot report into input-protocol mouse events published to the input service.
+//!
+//! Unlike PS/2, HID reports Y in screen convention (positive = down), so motion
+//! is passed straight through (the decode in hid-report.zig does not negate it).
+
+const std = @import("std");
+const runtime = @import("runtime");
+const usb_abi = @import("usb-abi");
+const hid = @import("hid-report.zig");
+const ipc = runtime.ipc;
+const process = runtime.process;
+const input_protocol = runtime.input_protocol;
+
+fn writeLine(comptime fmt: []const u8, arguments: anytype) void {
+    var line: [128]u8 = undefined;
+    _ = runtime.system.write(std.fmt.bufPrint(&line, fmt, arguments) catch return);
+}
+
+// The current pressed-button bitmask in input-protocol terms.
+fn buttonMask(buttons: u8) u32 {
+    var mask: u32 = 0;
+    if (buttons & hid.mouse_button_left != 0) mask |= input_protocol.mouse_button_left;
+    if (buttons & hid.mouse_button_right != 0) mask |= input_protocol.mouse_button_right;
+    if (buttons & hid.mouse_button_middle != 0) mask |= input_protocol.mouse_button_middle;
+    return mask;
+}
+
+pub fn main(init: runtime.process.Init) void {
+    const argument = init.arguments.get(1) orelse {
+        _ = runtime.system.write("/system/drivers/usb-hid/mouse: missing device id (argv[1])\n");
+        return;
+    };
+    const device_id = std.fmt.parseInt(u64, argument, 10) catch {
+        writeLine("/system/drivers/usb-hid/mouse: malformed device id '{s}'\n", .{argument});
+        return;
+    };
+
+    if (!runtime.usb.helloManager(device_id)) {
+        _ = runtime.system.write("/system/drivers/usb-hid/mouse: hello to device manager failed\n");
+        return;
+    }
+    var device = runtime.usb.open(device_id) orelse {
+        writeLine("/system/drivers/usb-hid/mouse: could not open device {d}\n", .{device_id});
+        return;
+    };
+    const endpoint = device.findEndpoint(runtime.usb.transfer_type_interrupt, true) orelse {
+        _ = runtime.system.write("/system/drivers/usb-hid/mouse: no interrupt-IN endpoint\n");
+        return;
+    };
+
+    _ = device.controlOut(@bitCast(usb_abi.setProtocol(@enumFromInt(device.interface_number), .boot)));
+
+    if (!device.subscribeInterrupt(endpoint.address, endpoint.max_packet_size)) {
+        _ = runtime.system.write("/system/drivers/usb-hid/mouse: interrupt subscribe failed\n");
+        return;
+    }
+
+    var source = runtime.input.connectSource() orelse {
+        _ = runtime.system.write("/system/drivers/usb-hid/mouse: input service unavailable\n");
+        return;
+    };
+    _ = process.bindSignals(device.endpoint);
+    writeLine("/system/drivers/usb-hid/mouse: ok (device {d}, interface {d})\n", .{ device_id, device.interface_number });
+
+    var previous_buttons: u8 = 0;
+    var receive: [64]u8 = undefined;
+    while (true) {
+        const got = ipc.replyWait(device.endpoint, &.{}, &receive, null);
+        if (!got.isNotification()) continue;
+        if (process.signalsFrom(got.badge)) |signals| {
+            if (signals.has(.terminate)) return;
+            continue;
+        }
+        if (!got.isMessage() or got.len < @sizeOf(runtime.usb.InterruptReport)) continue;
+
+        const message = std.mem.bytesToValue(runtime.usb.InterruptReport, receive[0..@sizeOf(runtime.usb.InterruptReport)]);
+        const length = @min(message.length, message.data.len);
+        const report = hid.parseMouse(message.data[0..length]) orelse continue;
+        const mask = buttonMask(report.buttons);
+
+        // Button transitions: one event per changed button bit.
+        const changed = report.buttons ^ previous_buttons;
+        inline for (.{
+            .{ hid.mouse_button_left, input_protocol.mouse_button_left },
+            .{ hid.mouse_button_right, input_protocol.mouse_button_right },
+            .{ hid.mouse_button_middle, input_protocol.mouse_button_middle },
+        }) |pair| {
+            if (changed & pair[0] != 0) {
+                _ = source.publishMouseEvent(.{
+                    .kind = @intFromEnum(if (report.buttons & pair[0] != 0) input_protocol.MouseEventKind.button_down else input_protocol.MouseEventKind.button_up),
+                    .button = pair[1],
+                    .dx = 0,
+                    .dy = 0,
+                    .scroll_x = 0,
+                    .scroll_y = 0,
+                    .buttons = mask,
+                });
+            }
+        }
+        previous_buttons = report.buttons;
+
+        // Relative motion (dy straight through — HID Y is already screen convention).
+        if (report.dx != 0 or report.dy != 0) {
+            _ = source.publishMouseEvent(.{
+                .kind = @intFromEnum(input_protocol.MouseEventKind.motion),
+                .button = 0,
+                .dx = report.dx,
+                .dy = report.dy,
+                .scroll_x = 0,
+                .scroll_y = 0,
+                .buttons = mask,
+            });
+        }
+
+        // Wheel (4-byte reports only): positive = scroll up.
+        if (report.has_wheel and report.wheel != 0) {
+            _ = source.publishMouseEvent(.{
+                .kind = @intFromEnum(input_protocol.MouseEventKind.scroll),
+                .button = 0,
+                .dx = 0,
+                .dy = 0,
+                .scroll_x = 0,
+                .scroll_y = report.wheel,
+                .buttons = mask,
+            });
+        }
+    }
+}

system/drivers/usb-storage/bulk-only-transport.zig

@@ -0,0 +1,73 @@
+//! USB Mass Storage Bulk-Only Transport (BOT) wire structures — the Command and
+//! Command Status Wrappers that bracket every command (USB MSC BOT §5). Pure data
+//! definitions, host-testable in isolation. The command inside the CBW is a SCSI
+//! CDB (see scsi.zig); the transport here just carries it and reports status.
+//!
+//! One command is three bulk transfers: CBW out, an optional data stage, CSW in.
+
+const std = @import("std");
+
+/// "USBC" — the signature at the head of every Command Block Wrapper.
+pub const cbw_signature: u32 = 0x43425355;
+/// "USBS" — the signature at the head of every Command Status Wrapper.
+pub const csw_signature: u32 = 0x53425355;
+
+/// CBW `flags`: set for a device-to-host (IN) data stage, clear for OUT.
+pub const flag_data_in: u8 = 0x80;
+
+/// The 31-byte Command Block Wrapper, sent on the bulk-OUT endpoint.
+pub const CommandBlockWrapper = extern struct {
+    signature: u32 align(1) = cbw_signature,
+    tag: u32 align(1),
+    data_transfer_length: u32 align(1),
+    flags: u8,
+    lun: u8,
+    cdb_length: u8,
+    cdb: [16]u8 = [_]u8{0} ** 16,
+};
+
+/// A device's answer to a command (the CSW `status` byte).
+pub const CommandStatus = enum(u8) {
+    passed = 0,
+    failed = 1,
+    phase_error = 2,
+    _,
+};
+
+/// The 13-byte Command Status Wrapper, read from the bulk-IN endpoint.
+pub const CommandStatusWrapper = extern struct {
+    signature: u32 align(1) = csw_signature,
+    tag: u32 align(1),
+    data_residue: u32 align(1),
+    status: u8,
+};
+
+comptime {
+    std.debug.assert(@sizeOf(CommandBlockWrapper) == 31);
+    std.debug.assert(@sizeOf(CommandStatusWrapper) == 13);
+}
+
+test "wrapper sizes and signatures match the specification" {
+    const cbw = CommandBlockWrapper{
+        .tag = 0x11223344,
+        .data_transfer_length = 512,
+        .flags = flag_data_in,
+        .lun = 0,
+        .cdb_length = 10,
+    };
+    const bytes = std.mem.asBytes(&cbw);
+    try std.testing.expectEqual(@as(usize, 31), bytes.len);
+    // "USBC" little-endian.
+    try std.testing.expectEqualSlices(u8, "USBC", bytes[0..4]);
+    try std.testing.expectEqual(flag_data_in, bytes[12]);
+
+    const csw = std.mem.bytesToValue(CommandStatusWrapper, &[_]u8{
+        0x55, 0x53, 0x42, 0x53, // "USBS"
+        0x44, 0x33, 0x22, 0x11, // tag
+        0x00, 0x00, 0x00, 0x00, // residue
+        0x00, // passed
+    });
+    try std.testing.expectEqual(csw_signature, csw.signature);
+    try std.testing.expectEqual(@as(u32, 0x11223344), csw.tag);
+    try std.testing.expectEqual(@as(u8, @intFromEnum(CommandStatus.passed)), csw.status);
+}