build: keep test fixtures out of a no-option build

A plain `zig build` was baking all 11 /test/system/services fixtures into the
production image. Split the bundle: the production set always, the userspace test
fixtures only when -Dtest-case is set — which the QEMU harness passes for every
scenario, exactly when the fixtures are needed on the boot volume. So `zig build`
with no options now ships a clean image (no test binaries in the manifest,
capsule, or FAT tree) and assumes neither -Dtest-case nor -Ddiagnose (the
diagnose display-omission was already gated by the init.csv selection).

Verified: a plain build has zero /test entries in the manifest; -Dtest-case=smoke
includes all fixtures; the args/vfs/device-list QEMU scenarios still pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KJqSiLLchDUUCoXn5jsiwd

build.zig

@@ -284,6 +284,19 @@ pub fn build(b: *std.Build) void {
     const pci_class_module = b.addModule("pci-class", .{
         .root_source_file = b.path("library/device/pci/pci-class.zig"),
     });
+    // Shared CSV helpers (comment stripping, field iteration) for the /etc/*.csv
+    // config files — the device registry and the init service list both parse them.
+    const csv_module = b.addModule("csv", .{
+        .root_source_file = b.path("library/csv/csv.zig"),
+    });
+    // The device registry: parse /etc/devices.csv into match rules and bind a
+    // reported device to a driver — the data-driven, authoritative replacement for
+    // the manager's hand-written switch tables. Pure logic (no hardware, no
+    // syscalls), so it unit-tests on the host; the manager imports it.
+    const device_registry_module = b.addModule("device-registry", .{
+        .root_source_file = b.path("library/device/registry/device-registry.zig"),
+        .imports = &.{.{ .name = "csv", .module = csv_module }},
+    });
     // 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
@@ -639,6 +652,8 @@ pub fn build(b: *std.Build) void {
     // started in ring 3 by the kernel's user-ELF loader.
     const init_exe = addUserBinary(b, kernel_target, &default_imports, "init", "system/services/init/init.zig");
     programModule(init_exe).addImport("power-protocol", power_protocol_module);
+    // init parses its boot service list from /etc/init.csv with the shared csv helpers.
+    programModule(init_exe).addImport("csv", csv_module);
     // 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
@@ -646,7 +661,8 @@ pub fn build(b: *std.Build) void {
     // the heartbeat stays present under test.
     const init_options = b.addOptions();
     init_options.addOption(bool, "serial", serial);
-    init_options.addOption(bool, "diagnose", diagnose);
+    // Which services init starts is no longer a comptime option: it reads /etc/init.csv,
+    // and -Ddiagnose selects which init.csv is bundled (see the `bundled` list below).
     programModule(init_exe).addImport("build_options", init_options.createModule());
 
     // --- the rest of the boot tree: /system services and drivers, /test fixtures ---
@@ -729,12 +745,10 @@ pub fn build(b: *std.Build) void {
     if (discovery == .acpi) programModule(discovery_exe).addImport("device-manager-protocol", device_manager_protocol_module);
     if (discovery == .acpi) programModule(discovery_exe).addImport("power-protocol", power_protocol_module);
     const device_manager_exe = addUserBinary(b, kernel_target, &default_imports, "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);
     programModule(device_manager_exe).addImport("device-manager-protocol", device_manager_protocol_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);
+    // Driver matching is data-driven: the manager parses /etc/devices.csv into this
+    // module's rules and binds each reported device by most-specific match.
+    programModule(device_manager_exe).addImport("device-registry", device_registry_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, &default_imports, "input", "system/services/input/input.zig");
@@ -755,7 +769,11 @@ pub fn build(b: *std.Build) void {
     // structure is the single source of truth. Entry names (and hence argv[0] and
     // task names) are these paths with a leading slash. Test fixtures mirror their
     // repo home: test/system/services/<name> in the source tree IS the boot path.
-    const bundled = [_]BundledBinary{
+    // init's boot service list is data (/etc/init.csv). -Ddiagnose selects the
+    // variant that omits the display stack (so the kernel's boot transcript stays
+    // on screen); both are bundled at the same /etc/init.csv path.
+    const init_csv_source = if (diagnose) "etc/init-diagnose.csv" else "etc/init.csv";
+    const production_bundled = [_]BundledBinary{
         .{ .path = "system/services/init", .binary = init_exe.getEmittedBin() },
         .{ .path = "system/services/fat", .binary = fat_exe.getEmittedBin() },
         .{ .path = "system/services/display", .binary = display_exe.getEmittedBin() },
@@ -764,6 +782,13 @@ pub fn build(b: *std.Build) void {
         .{ .path = "system/services/input", .binary = input_exe.getEmittedBin() },
         .{ .path = "system/services/discovery", .binary = discovery_exe.getEmittedBin() },
         .{ .path = "system/services/logger", .binary = logger_exe.getEmittedBin() },
+        // A data file, not a binary: the device registry the manager reads at boot.
+        // Packing it under /etc makes the kernel auto-mount /etc as a read-only
+        // initrd tree (system/kernel/vfs.zig setInitialRamdisk), so the manager can
+        // fs.open("/etc/devices.csv") with no filesystem service running.
+        .{ .path = "etc/devices.csv", .binary = b.path("etc/devices.csv") },
+        // init's service list, likewise read from the kernel-served initrd /etc.
+        .{ .path = "etc/init.csv", .binary = b.path(init_csv_source) },
         .{ .path = "system/drivers/ps2-bus", .binary = ps2_bus_exe.getEmittedBin() },
         .{ .path = "system/drivers/ps2-keyboard", .binary = ps2_keyboard_exe.getEmittedBin() },
         .{ .path = "system/drivers/ps2-mouse", .binary = ps2_mouse_exe.getEmittedBin() },
@@ -773,6 +798,13 @@ pub fn build(b: *std.Build) void {
         .{ .path = "system/drivers/usb-storage", .binary = usb_storage_exe.getEmittedBin() },
         .{ .path = "system/drivers/virtio-gpu", .binary = virtio_gpu_exe.getEmittedBin() },
         .{ .path = "system/drivers/pci-bus", .binary = pci_bus_exe.getEmittedBin() },
+    };
+    // The userspace test fixtures under /test. A plain `zig build` produces a clean
+    // image WITHOUT them; they are bundled only for a test build — which the QEMU
+    // harness signals by passing -Dtest-case=<name> for every scenario, exactly when
+    // these fixtures must be on the boot volume. Merely building this array never
+    // forces a compile: the fixture exes build only if `bundled` (below) includes them.
+    const test_bundled = [_]BundledBinary{
         .{ .path = "test/system/services/vfs-test", .binary = vfstest_exe.getEmittedBin() },
         .{ .path = "test/system/services/fat-test", .binary = fat_test_exe.getEmittedBin() },
         .{ .path = "test/system/services/shared-memory-server", .binary = shared_memory_server_exe.getEmittedBin() },
@@ -785,6 +817,13 @@ pub fn build(b: *std.Build) void {
         .{ .path = "test/system/services/process-test", .binary = process_test_exe.getEmittedBin() },
         .{ .path = "test/system/services/thread-test", .binary = thread_test_exe.getEmittedBin() },
     };
+    // A no-option build assumes neither -Dtest-case nor -Ddiagnose: it ships the
+    // production set only. Test fixtures join in only under -Dtest-case; the
+    // diagnose display-omission is already handled by init_csv_source above.
+    var bundled_list: std.ArrayListUnmanaged(BundledBinary) = .empty;
+    bundled_list.appendSlice(b.allocator, &production_bundled) catch @panic("OOM");
+    if (test_case != null) bundled_list.appendSlice(b.allocator, &test_bundled) catch @panic("OOM");
+    const bundled = bundled_list.items;
 
     // The boot manifest: the FHS path of every bundled binary, one per line. The
     // EFI loader reads THIS by name and opens each listed path by name — FAT
@@ -867,7 +906,7 @@ pub fn build(b: *std.Build) void {
     // binaries at their FHS paths. 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(), manifest_file, capsule_img, &bundled);
+    const fat_image = addBootImage(b, exe.getEmittedBin(), efiexe.getEmittedBin(), manifest_file, capsule_img, bundled);
     const fat_image_install = b.addInstallFile(fat_image, "danos-usb.img");
     b.getInstallStep().dependOn(&fat_image_install.step);
 
@@ -876,7 +915,7 @@ pub fn build(b: *std.Build) void {
     // 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(), manifest_file, capsule_img, &bundled);
+    const fat_image_serial = addBootImage(b, exe_serial.getEmittedBin(), efiexe.getEmittedBin(), manifest_file, capsule_img, bundled);
 
     // `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).
@@ -1078,6 +1117,7 @@ pub fn build(b: *std.Build) void {
         "library/device/acpi/aml/aml.zig", // AML parse + interpret, incl. Notify dispatch (M21)
         "library/device/usb/usb-abi.zig", // wire sizes + bit packings + set-up packet encodings
         "library/device/usb/usb-ids.zig", // class/subclass/protocol code assignments
+        "library/csv/csv.zig", // shared /etc/*.csv comment-strip + field-split helpers
         "library/device/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
@@ -1102,6 +1142,19 @@ pub fn build(b: *std.Build) void {
         test_step.dependOn(&b.addRunArtifact(mod_tests).step);
     }
 
+    // The device registry imports the shared `csv` module, so its tests need that
+    // import wired and don't fit the plain loop above. These prove the /etc/devices.csv
+    // parse + most-specific driver match (incl. virtio 1AF4:1050 beating a class rule).
+    const device_registry_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("library/device/registry/device-registry.zig"),
+            .target = target,
+            .optimize = optimize,
+            .imports = &.{.{ .name = "csv", .module = csv_module }},
+        }),
+    });
+    test_step.dependOn(&b.addRunArtifact(device_registry_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.

docs/device-driver-development/device-manager.md

@@ -91,6 +91,9 @@ mechanism), replacing first-come-first-served `device_claim` with policy. Identi
 `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.
+(Since the registry landed, `child_added` also carries a `bus` discriminator and
+the numeric `vendor`/`device`/`subsystem` ids the finer match levels need —
+see [/etc/devices.csv](devices-csv.md).)
 
 ## Supervision and restart
 
@@ -169,9 +172,15 @@ published exit events, signals + `process`). On top of those:
 - **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` were
-  honest at two bus types; the third was expected to trigger the manifest (a driver
-  declares what it binds: a PCI class triple, a USB class triple, an ACPI `_HID`).
-  (Since then: the third bus — USB — arrived and is matched in code too. Today's
-  matchers are `pciDriverForIdentity`, `hidDriverFor`, and `usbDriverForIdentity`;
-  the manifest waits until code matching actually hurts.)
+- **Matching is a registry, not code (resolved 2026-07-26).** `driverFor`/
+  `pciDriverFor` were honest at two bus types; the third (USB) was matched in code
+  too, and then the switch tables started to hurt — they keyed PCI matches on the
+  class triple alone, so a virtio-gpu could only be matched as a generic display
+  function and the driver had to re-confirm its `1AF4:1050` identity from config
+  space after being spawned. The manifest the earlier note anticipated landed as a
+  human-readable registry: **[/etc/devices.csv](devices-csv.md)**, parsed by the
+  pure `device-registry` module and read by the manager at boot. A row binds a
+  driver to a device by any of base / subclass / prog-IF / vendor / device /
+  subsystem / `_HID`, most-specific match winning; it is authoritative (no
+  compiled-in fallback — an unmatched device is logged, never guessed).
+  `pciDriverForIdentity`, `hidDriverFor`, and `usbDriverForIdentity` are gone.

docs/device-driver-development/devices-csv.md

@@ -0,0 +1,102 @@
+# /etc/devices.csv — the device registry
+
+**Status: built (2026-07-26).** The device manager reads `/etc/devices.csv` at
+boot and binds every device a bus driver reports to the driver the registry
+names. It replaces the three hand-written `switch` tables that used to live in
+the manager (`pciDriverForIdentity`, `hidDriverFor`, `usbDriverForIdentity`) —
+the "manifest" [device-manager.md](device-manager.md) anticipated once code
+matching started to hurt. The parser and matcher are the pure, unit-tested
+`device-registry` module (`library/device/registry/device-registry.zig`).
+
+## Why a registry
+
+The switch tables keyed PCI matches on the 24-bit class/subclass/prog-IF triple
+alone. That is too coarse: a virtio-gpu is just "display / other" by class, so it
+could only be *class-matched* and the driver had to re-confirm its real
+`1AF4:1050` identity from config space **after** the manager had already spawned
+it. The registry lets a rule bind on the full identity — down to vendor, device,
+and subsystem — so the manager makes the precise decision itself, and the driver
+comes up already knowing it is the right one.
+
+It is also **data, not code**: teaching the system new hardware is a line in a
+file, not an edit-and-recompile of the manager. And it is **greppable** — one
+place to read "what binds what," the same idea as Linux's `modules.alias`.
+
+## The file
+
+One rule per line, nine comma-separated fields; `#` starts a comment (whole-line
+or trailing); blank lines are ignored. Whitespace around a field is trimmed, so
+columns may be padded for readability.
+
+```
+# bus   base class prog_if vendor device subsystem hid       driver
+pci,    0C,  03,   30,     *,     *,     *,        *,        /system/drivers/usb-xhci-bus
+pci,    03,  00,   00,     *,     *,     *,        *,        /system/drivers/display
+pci,    03,  80,   *,      1AF4,  1050,  *,        *,        /system/drivers/virtio-gpu
+usb,    03,  01,   01,     *,     *,     *,        *,        /system/drivers/usb-hid-keyboard
+acpi,   *,   *,    *,      *,     *,     *,        PNP0303,  /system/drivers/ps2-bus
+```
+
+| Field | Meaning | Notes |
+|---|---|---|
+| `bus` | `pci` \| `usb` \| `acpi` | which bus reported the device; picks the namespace for the id columns |
+| `base` | PCI base class / USB class | hex |
+| `class` | PCI subclass / USB subclass | hex |
+| `prog_if` | PCI prog-IF / USB protocol | hex |
+| `vendor` | PCI vendor / USB idVendor | hex |
+| `device` | PCI device / USB idProduct | hex |
+| `subsystem` | PCI subsystem, `(ssvid<<16)\|ssid` | hex; blank for usb/acpi |
+| `hid` | ACPI `_HID` (e.g. `PNP0303`) | blank for pci/usb |
+| `driver` | full ramdisk path to spawn | e.g. `/system/drivers/virtio-gpu` |
+
+`*` or an empty field is a **wildcard** — it matches anything and adds nothing to
+a rule's specificity.
+
+## Levels of detection: most-specific-wins
+
+Several rows may match one device. The manager picks the **most specific** — the
+one that pins the finest-grained fields. Specificity weights double from the
+coarsest level so each outweighs all coarser levels combined:
+
+```
+base(1) < class(2) < prog_if(4) < vendor(8) < subsystem(16) < device(32) ≈ hid(32)
+```
+
+So the generic `pci, 03, 00, 00, …/display` rule and the precise
+`pci, 03, 80, *, 1AF4, 1050, …/virtio-gpu` rule coexist: the virtio card
+(vendor 1AF4, device 1050) takes the specific rule; a plain VGA adapter still
+falls to the generic one. Two rules that match a device with the *same*
+specificity are a registry authoring error — the manager logs it loudly and binds
+the first, so the shadowed rule is visible rather than silently dropped.
+
+## Authoritative — no code fallback
+
+There is no compiled-in default table behind the registry. A device that no row
+matches goes **unbound** and is logged; the manager never guesses. A missing or
+empty `/etc/devices.csv` therefore means nothing matches — which is loud at boot,
+not a silent half-working system.
+
+## How the manager reads it
+
+`/etc/devices.csv` is bundled into the initial ramdisk (`build.zig`'s `bundled`
+list). The kernel serves the initrd's `/etc` tree directly — the `fat` service is
+spawned *after* the device manager and is irrelevant to `/etc` — so the manager
+reads the file with a plain `fs.open("/etc/devices.csv")` + `read`, with no
+filesystem service running and no boot-ordering dependency. It parses the bytes
+once in `initialise`, before any bus driver can report a device to match.
+
+## Feeding the matcher: the widened report
+
+Finer-grained matching needs identity the old ABI threw away. Two things carry it
+now: `child_added` (and `DeviceDescriptor`) grew `vendor` / `device` /
+`subsystem` fields, filled by the PCI bus driver from config space (offsets
+0x00 and 0x2C); and each bus driver states its `bus` in the report (a `BusKind`),
+so the manager reads a PCI class triple and a USB class triple — the same 24 bits
+in different namespaces — against the right `bus` column.
+
+## Adding a driver
+
+1. Build the driver binary and bundle it at `/system/drivers/<name>` (build.zig).
+2. Add a row to `etc/devices.csv` naming the identity it binds and its full path.
+
+No device-manager change is required — the registry is the seam.

etc/devices.csv

@@ -0,0 +1,33 @@
+# /etc/devices.csv — the device→driver registry.
+#
+# The device manager reads this at boot and binds each device a bus driver
+# reports to the driver named here. It is AUTHORITATIVE: a device that no row
+# matches goes unbound (logged), never guessed. Edit this file to teach the
+# system new hardware — no recompile of the device manager required.
+#
+# One rule per line, nine comma-separated fields. '#' starts a comment
+# (whole-line or trailing); blank lines are ignored. Whitespace around a field
+# is trimmed, so columns may be padded for readability.
+#
+#   bus      which bus reported the device: pci | usb | acpi
+#   base     PCI base class  / USB class          (hex)
+#   class    PCI subclass    / USB subclass        (hex)
+#   prog_if  PCI prog-IF     / USB protocol         (hex)
+#   vendor   PCI vendor id   / USB idVendor          (hex)
+#   device   PCI device id   / USB idProduct          (hex)
+#   subsystem PCI subsystem, packed (ssvid<<16)|ssid   (hex)
+#   hid      ACPI _HID string (e.g. PNP0303); blank for pci/usb
+#   driver   full ramdisk path of the driver to spawn
+#
+# '*' or an empty field is a wildcard. When several rows match one device the
+# MOST SPECIFIC wins (pinning vendor/device/hid beats pinning only a class), so
+# a generic class rule and a precise vendor:device rule can coexist.
+#
+# bus   base class prog_if vendor device subsystem hid       driver
+pci,    0C,  03,   30,     *,     *,     *,        *,        /system/drivers/usb-xhci-bus
+pci,    03,  80,   *,      1AF4,  1050,  *,        *,        /system/drivers/virtio-gpu
+usb,    03,  01,   01,     *,     *,     *,        *,        /system/drivers/usb-hid-keyboard
+usb,    03,  01,   02,     *,     *,     *,        *,        /system/drivers/usb-hid-mouse
+usb,    08,  06,   50,     *,     *,     *,        *,        /system/drivers/usb-storage
+acpi,   *,   *,    *,      *,     *,     *,        PNP0303,  /system/drivers/ps2-bus
+acpi,   *,   *,    *,      *,     *,     *,        PNP0F13,  /system/drivers/ps2-bus

etc/init-diagnose.csv

@@ -0,0 +1,12 @@
+# /etc/init.csv — diagnose variant (-Ddiagnose), bundled at /etc/init.csv.
+#
+# The display stack (display, display-demo) is omitted so the kernel's timestamped
+# on-screen boot transcript is never suppressed — the bring-up timeline (USB,
+# storage, logger) stays readable on real hardware with no serial. See etc/init.csv
+# for the format; this file must otherwise track it.
+#
+# service                          args...
+/system/services/input
+/system/services/device-manager
+/system/services/fat
+/system/services/logger

etc/init.csv

@@ -0,0 +1,20 @@
+# /etc/init.csv — the services init (PID 1) starts at boot, in order.
+#
+# init reads this at startup and spawns each service supervised (restarting it on
+# a crash, up to a cap). Startup order is top->bottom; shutdown is the reverse, so
+# the logger (last) goes down first and its final drain still has the fat server
+# and the whole storage chain alive underneath it. It is AUTHORITATIVE — there is
+# no hardcoded fallback list; a missing file means no services are started.
+#
+# '#' starts a comment (whole-line or trailing); blank lines are ignored. The
+# first field is the service binary path; any fields after it are the service's
+# argv. Drivers are absent on purpose — the device manager discovers hardware and
+# spawns those (see /etc/devices.csv).
+#
+# service                          args...
+/system/services/input
+/system/services/device-manager
+/system/services/fat
+/system/services/display
+/system/services/display-demo
+/system/services/logger

library/csv/csv.zig

@@ -0,0 +1,56 @@
+//! Minimal CSV helpers shared by the `/etc/*.csv` config files — the device
+//! registry (`/etc/devices.csv`) and the init service list (`/etc/init.csv`).
+//! Freestanding, no allocator: returned fields are slices into the source line,
+//! so the source must outlive them. `#` starts a comment (whole-line or trailing);
+//! whitespace around a field is trimmed, so columns may be padded for alignment.
+
+const std = @import("std");
+
+/// Strip a trailing `#` comment and surrounding whitespace from one raw line.
+/// A blank or comment-only line returns "" (length 0) — the caller's skip signal.
+pub fn stripComment(raw: []const u8) []const u8 {
+    const body = if (std.mem.indexOfScalar(u8, raw, '#')) |hash| raw[0..hash] else raw;
+    return std.mem.trim(u8, body, " \t\r\n");
+}
+
+/// Iterate the comma-separated fields of a line body, each trimmed of spaces and
+/// tabs. Build it from a `stripComment`ed body.
+pub const Fields = struct {
+    inner: std.mem.SplitIterator(u8, .scalar),
+
+    /// The next field, trimmed, or null when the row is exhausted.
+    pub fn next(self: *Fields) ?[]const u8 {
+        const field = self.inner.next() orelse return null;
+        return std.mem.trim(u8, field, " \t");
+    }
+};
+
+pub fn fields(body: []const u8) Fields {
+    return .{ .inner = std.mem.splitScalar(u8, body, ',') };
+}
+
+// --- tests -------------------------------------------------------------------
+
+const testing = std.testing;
+
+test "stripComment trims and drops comments" {
+    try testing.expectEqualStrings("a, b", stripComment("  a, b  # trailing\r\n"));
+    try testing.expectEqualStrings("", stripComment("   # whole-line comment"));
+    try testing.expectEqualStrings("", stripComment("   \t "));
+    try testing.expectEqualStrings("x", stripComment("x"));
+}
+
+test "fields splits and trims each column" {
+    var it = fields(stripComment("pci,  03 , 80  ,  /system/drivers/x  # note"));
+    try testing.expectEqualStrings("pci", it.next().?);
+    try testing.expectEqualStrings("03", it.next().?);
+    try testing.expectEqualStrings("80", it.next().?);
+    try testing.expectEqualStrings("/system/drivers/x", it.next().?);
+    try testing.expect(it.next() == null);
+}
+
+test "a single field yields one column then null" {
+    var it = fields(stripComment("/system/services/input"));
+    try testing.expectEqualStrings("/system/services/input", it.next().?);
+    try testing.expect(it.next() == null);
+}

library/device/model/device-abi.zig

@@ -125,6 +125,15 @@ pub const DeviceDescriptor = extern struct {
     // `pci_device` is (an xHCI controller, an AHCI controller) — decode the triple into
     // names with the pci-class module.
     pci_class: u64,
+    // Numeric identity beyond the class triple, mirrored in the bus report's
+    // ChildAdded so /etc/devices.csv can bind on it: `vendor`/`device` are the PCI
+    // vendor/device (or USB idVendor/idProduct), `subsystem` is the PCI subsystem id
+    // packed `(subsystem_vendor << 16) | subsystem_device`. Zero where the bus has no
+    // such concept. Defaulted so existing descriptor literals keep compiling and lay
+    // out identically until they choose to set them.
+    vendor: u16 = 0,
+    device: u16 = 0,
+    subsystem: u32 = 0,
     hid_len: u64,
     resource_count: u64,
     hid: [8]u8,

library/device/registry/device-registry.zig

@@ -0,0 +1,343 @@
+//! The device registry: parse `/etc/devices.csv` into match rules and bind a
+//! reported device to a driver. This is the data-driven replacement for the
+//! device manager's three hand-written `switch` tables (`pciDriverForIdentity`,
+//! `hidDriverFor`, `usbDriverForIdentity`); the registry is now **authoritative**
+//! — a device that no row matches goes unbound (logged), never guessed.
+//!
+//! Pure logic: no hardware access, no syscalls, no allocator. `parse` fills a
+//! caller-provided `[]Rule` whose string fields (`hid`, `driver`) are slices
+//! *into the CSV source*, so the source buffer must outlive the rules (the
+//! manager holds it in a static buffer for the life of the process — zero-copy).
+//! That keeps this module freestanding and unit-testable with plain `zig test`.
+//!
+//! The file format (docs/device-driver-development/device-manager.md, and the
+//! `/etc/devices.csv` header itself): one rule per line, nine comma-separated
+//! fields, `#` starts a comment (whole-line or trailing), blank lines ignored.
+//!
+//!     bus, base, class, prog_if, vendor, device, subsystem, hid, driver
+//!
+//! `bus` is `pci`/`usb`/`acpi`; the numeric fields are hex (with or without a
+//! `0x` prefix); `*` or an empty field is a wildcard (matches anything). For PCI
+//! the class triple is base/subclass/prog-IF; for USB it is class/subclass/
+//! protocol with vendor/device the idVendor/idProduct; ACPI matches on `hid`
+//! (e.g. "PNP0303") with the triple left blank. `driver` is a full ramdisk path.
+
+const std = @import("std");
+const csv = @import("csv");
+
+/// Which bus a rule or a reported device belongs to. `unknown` is what an
+/// unrecognised `bus` token parses to — such a rule never matches (its bus
+/// equals no real device's), so a typo fails safe rather than binding wrongly.
+pub const Bus = enum {
+    pci,
+    usb,
+    acpi,
+    unknown,
+
+    pub fn fromToken(token: []const u8) Bus {
+        if (std.mem.eql(u8, token, "pci")) return .pci;
+        if (std.mem.eql(u8, token, "usb")) return .usb;
+        if (std.mem.eql(u8, token, "acpi")) return .acpi;
+        return .unknown;
+    }
+};
+
+/// A reported device's full identity, as the manager assembles it from a
+/// `child_added`: the bus-native class triple plus the numeric ids the widened
+/// ABI now carries, or the ACPI `_HID` string. Fields a given bus does not have
+/// are zero / empty (a PCI function has no `hid`; an ACPI device has no vendor).
+pub const Identity = struct {
+    bus: Bus,
+    base: u8 = 0,
+    subclass: u8 = 0,
+    prog_if: u8 = 0,
+    vendor: u16 = 0,
+    device: u16 = 0,
+    subsystem: u32 = 0,
+    hid: []const u8 = "",
+};
+
+/// One parsed registry row. A `null` field is a wildcard — it matches any value
+/// and contributes nothing to specificity. String fields point into the CSV
+/// source that was parsed (see the module doc).
+pub const Rule = struct {
+    bus: Bus,
+    base: ?u8 = null,
+    subclass: ?u8 = null,
+    prog_if: ?u8 = null,
+    vendor: ?u16 = null,
+    device: ?u16 = null,
+    subsystem: ?u32 = null,
+    hid: ?[]const u8 = null,
+    driver: []const u8,
+};
+
+/// Specificity weights: how much each pinned field counts toward "most specific
+/// wins". Doubling from the coarsest (`base`) so that each level outweighs *all*
+/// coarser levels combined (1+2+4+8+16 = 31 < 32) — a rule that pins `device`
+/// always beats any rule that does not, no matter how many coarse fields the
+/// latter pins. `hid` and `device` share the top tier (the user's "hid and
+/// device weigh heaviest"); they never co-occur, since `hid` is ACPI-only and
+/// `device` is a PCI/USB numeric id.
+const weight_base: u32 = 1;
+const weight_subclass: u32 = 2;
+const weight_prog_if: u32 = 4;
+const weight_vendor: u32 = 8;
+const weight_subsystem: u32 = 16;
+const weight_device: u32 = 32;
+const weight_hid: u32 = 32;
+
+/// The outcome of `matchDriver`: the winning rule's driver path, its specificity,
+/// and whether another rule tied it at that specificity. `ambiguous` is a
+/// registry authoring error (two equally-specific rules claiming one device); the
+/// manager logs it loudly and binds the first, so a shadowed rule is visible
+/// rather than silently dropped.
+pub const Match = struct {
+    driver: []const u8,
+    specificity: u32,
+    ambiguous: bool,
+};
+
+/// Whether `rule` matches `id`: same bus, and every pinned (non-wildcard) field
+/// equal. `hid` compares as a string; the rest as integers.
+fn matches(rule: Rule, id: Identity) bool {
+    if (rule.bus != id.bus) return false;
+    if (rule.base) |b| if (b != id.base) return false;
+    if (rule.subclass) |s| if (s != id.subclass) return false;
+    if (rule.prog_if) |p| if (p != id.prog_if) return false;
+    if (rule.vendor) |v| if (v != id.vendor) return false;
+    if (rule.device) |d| if (d != id.device) return false;
+    if (rule.subsystem) |s| if (s != id.subsystem) return false;
+    if (rule.hid) |h| if (!std.mem.eql(u8, h, id.hid)) return false;
+    return true;
+}
+
+/// The specificity score of a rule — the sum of the weights of its pinned fields.
+fn specificity(rule: Rule) u32 {
+    var score: u32 = 0;
+    if (rule.base != null) score += weight_base;
+    if (rule.subclass != null) score += weight_subclass;
+    if (rule.prog_if != null) score += weight_prog_if;
+    if (rule.vendor != null) score += weight_vendor;
+    if (rule.device != null) score += weight_device;
+    if (rule.subsystem != null) score += weight_subsystem;
+    if (rule.hid != null) score += weight_hid;
+    return score;
+}
+
+/// Bind a reported device to a driver: of every rule that matches `id`, return
+/// the most specific. `null` when nothing matches (the device goes unbound —
+/// the authoritative registry does not guess). On an exact specificity tie the
+/// first such rule in file order wins and `ambiguous` is set.
+pub fn matchDriver(rules: []const Rule, id: Identity) ?Match {
+    var best: ?Match = null;
+    for (rules) |rule| {
+        if (!matches(rule, id)) continue;
+        const score = specificity(rule);
+        if (best) |current| {
+            if (score > current.specificity) {
+                best = .{ .driver = rule.driver, .specificity = score, .ambiguous = false };
+            } else if (score == current.specificity) {
+                // Two equally-specific rules claim this device — keep the first,
+                // flag the ambiguity for the manager to log.
+                best.?.ambiguous = true;
+            }
+        } else {
+            best = .{ .driver = rule.driver, .specificity = score, .ambiguous = false };
+        }
+    }
+    return best;
+}
+
+// --- parsing -----------------------------------------------------------------
+
+/// What one CSV line parsed to. `malformed` is a non-comment, non-blank line the
+/// parser could not read (wrong field count, unparsable number, empty driver) —
+/// the manager counts these and logs, so a broken registry is loud, not silent.
+const Line = union(enum) {
+    rule: Rule,
+    ignorable, // blank or comment
+    malformed,
+};
+
+/// The result of `parse`: how many rules landed in the caller's buffer, and how
+/// many non-ignorable lines were malformed (for the manager to log). `truncated`
+/// is set if there were more valid rules than the buffer could hold.
+pub const ParseResult = struct {
+    count: usize,
+    malformed: usize,
+    truncated: bool,
+};
+
+/// Parse one hex field into `T`, honouring `*`/empty as a wildcard (`null`) and
+/// an optional `0x` prefix. Returns an error only for a genuinely unparsable
+/// non-wildcard token, so the caller can mark the whole line malformed.
+fn parseHexField(comptime T: type, field: []const u8) !?T {
+    const token = std.mem.trim(u8, field, " \t");
+    if (token.len == 0 or std.mem.eql(u8, token, "*")) return null;
+    const digits = if (std.mem.startsWith(u8, token, "0x") or std.mem.startsWith(u8, token, "0X"))
+        token[2..]
+    else
+        token;
+    return try std.fmt.parseInt(T, digits, 16);
+}
+
+/// Parse a wildcard-or-string field (the `hid` column): `*`/empty → wildcard.
+fn parseStringField(field: []const u8) ?[]const u8 {
+    const token = std.mem.trim(u8, field, " \t");
+    if (token.len == 0 or std.mem.eql(u8, token, "*")) return null;
+    return token;
+}
+
+/// Classify and (if a rule) parse one line. Split out from `parse` so it can be
+/// unit-tested directly. `line` is the raw line including no newline.
+fn parseLine(line: []const u8) Line {
+    const body = csv.stripComment(line);
+    if (body.len == 0) return .ignorable;
+
+    // Nine comma-separated fields (csv.fields trims each): bus, base, class,
+    // prog_if, vendor, device, subsystem, hid, driver.
+    var cols: [9][]const u8 = undefined;
+    var count: usize = 0;
+    var it = csv.fields(body);
+    while (it.next()) |field| {
+        if (count >= cols.len) return .malformed; // too many columns
+        cols[count] = field;
+        count += 1;
+    }
+    if (count != cols.len) return .malformed; // too few columns
+
+    const bus = Bus.fromToken(cols[0]);
+    if (bus == .unknown) return .malformed;
+
+    const driver = cols[8];
+    if (driver.len == 0) return .malformed;
+
+    return .{ .rule = .{
+        .bus = bus,
+        .base = parseHexField(u8, cols[1]) catch return .malformed,
+        .subclass = parseHexField(u8, cols[2]) catch return .malformed,
+        .prog_if = parseHexField(u8, cols[3]) catch return .malformed,
+        .vendor = parseHexField(u16, cols[4]) catch return .malformed,
+        .device = parseHexField(u16, cols[5]) catch return .malformed,
+        .subsystem = parseHexField(u32, cols[6]) catch return .malformed,
+        .hid = parseStringField(cols[7]),
+        .driver = driver,
+    } };
+}
+
+/// Parse a whole `/etc/devices.csv` into `out_rules`. The string fields of the
+/// returned rules point into `source`, which must outlive them.
+pub fn parse(source: []const u8, out_rules: []Rule) ParseResult {
+    var result: ParseResult = .{ .count = 0, .malformed = 0, .truncated = false };
+    var lines = std.mem.splitScalar(u8, source, '\n');
+    while (lines.next()) |line| {
+        switch (parseLine(line)) {
+            .ignorable => {},
+            .malformed => result.malformed += 1,
+            .rule => |rule| {
+                if (result.count >= out_rules.len) {
+                    result.truncated = true;
+                    continue;
+                }
+                out_rules[result.count] = rule;
+                result.count += 1;
+            },
+        }
+    }
+    return result;
+}
+
+// --- tests -------------------------------------------------------------------
+
+const testing = std.testing;
+
+// The worked example from the design: a specific virtio-gpu rule (pins vendor +
+// device) and a generic display rule (class only) both match the virtio card;
+// the specific one must win. And a plain VGA adapter still falls to the generic
+// rule. This is the whole point of widening the ABI to carry vendor/device.
+test "virtio device rule beats the generic display rule" {
+    const text =
+        \\# bus, base, class, prog_if, vendor, device, subsystem, hid, driver
+        \\pci, 03, 00, 00, *, *, *, *, /system/drivers/display
+        \\pci, 03, 80, *, 1AF4, 1050, *, *, /system/drivers/virtio-gpu
+    ;
+    var rules: [8]Rule = undefined;
+    const parsed = parse(text, &rules);
+    try testing.expectEqual(@as(usize, 2), parsed.count);
+    try testing.expectEqual(@as(usize, 0), parsed.malformed);
+
+    // The virtio-gpu function: display / other, vendor 1AF4 device 1050.
+    const virtio = matchDriver(rules[0..parsed.count], .{
+        .bus = .pci, .base = 0x03, .subclass = 0x80, .prog_if = 0x00,
+        .vendor = 0x1AF4, .device = 0x1050,
+    }).?;
+    try testing.expect(!virtio.ambiguous);
+    try testing.expectEqualStrings("/system/drivers/virtio-gpu", virtio.driver);
+
+    // A plain VGA adapter (display / VGA) still binds the generic display driver.
+    const vga = matchDriver(rules[0..parsed.count], .{
+        .bus = .pci, .base = 0x03, .subclass = 0x00, .prog_if = 0x00,
+        .vendor = 0x1234, .device = 0x1111,
+    }).?;
+    try testing.expectEqualStrings("/system/drivers/display", vga.driver);
+}
+
+test "no matching row leaves the device unbound" {
+    const text = "pci, 0C, 03, 30, *, *, *, *, /system/drivers/usb-xhci-bus\n";
+    var rules: [8]Rule = undefined;
+    const parsed = parse(text, &rules);
+    try testing.expectEqual(@as(usize, 1), parsed.count);
+
+    // An AHCI controller (mass storage / SATA / AHCI) has no row — unbound.
+    const unmatched = matchDriver(rules[0..parsed.count], .{
+        .bus = .pci, .base = 0x01, .subclass = 0x06, .prog_if = 0x01,
+    });
+    try testing.expect(unmatched == null);
+}
+
+test "acpi rows match on hid" {
+    const text =
+        \\acpi, *, *, *, *, *, *, PNP0303, /system/drivers/ps2-bus
+        \\acpi, *, *, *, *, *, *, PNP0F13, /system/drivers/ps2-bus
+    ;
+    var rules: [8]Rule = undefined;
+    const parsed = parse(text, &rules);
+    try testing.expectEqual(@as(usize, 2), parsed.count);
+
+    const keyboard = matchDriver(rules[0..parsed.count], .{ .bus = .acpi, .hid = "PNP0303" }).?;
+    try testing.expectEqualStrings("/system/drivers/ps2-bus", keyboard.driver);
+    const nothing = matchDriver(rules[0..parsed.count], .{ .bus = .acpi, .hid = "PNP0A03" });
+    try testing.expect(nothing == null);
+}
+
+test "equally specific rules flag ambiguity" {
+    const text =
+        \\pci, 03, 00, 00, *, *, *, *, /system/drivers/display-a
+        \\pci, 03, 00, 00, *, *, *, *, /system/drivers/display-b
+    ;
+    var rules: [8]Rule = undefined;
+    const parsed = parse(text, &rules);
+    const hit = matchDriver(rules[0..parsed.count], .{
+        .bus = .pci, .base = 0x03, .subclass = 0x00, .prog_if = 0x00,
+    }).?;
+    try testing.expect(hit.ambiguous);
+    try testing.expectEqualStrings("/system/drivers/display-a", hit.driver); // first wins
+}
+
+test "comments, blanks, and malformed lines" {
+    const text =
+        \\# a header comment
+        \\
+        \\pci, 0C, 03, 30, *, *, *, *, /system/drivers/usb-xhci-bus  # trailing comment
+        \\pci, ZZ, 03, 30, *, *, *, *, /system/drivers/broken
+        \\pci, 03, 00, 00, *, *, *, *,
+        \\bogus-bus, *, *, *, *, *, *, *, /system/drivers/x
+    ;
+    var rules: [8]Rule = undefined;
+    const parsed = parse(text, &rules);
+    try testing.expectEqual(@as(usize, 1), parsed.count); // only the xhci row is valid
+    try testing.expectEqual(@as(usize, 3), parsed.malformed); // bad hex, empty driver, bad bus
+    try testing.expectEqualStrings("/system/drivers/usb-xhci-bus", rules[0].driver);
+    try testing.expect(rules[0].hid == null); // trailing comment stripped, hid still wildcard
+}

library/protocol/device-manager/device-manager-protocol.zig

@@ -11,6 +11,19 @@
 /// startup instead of quiet corruption later.
 pub const version: u16 = 1;
 
+/// Which bus a `child_added` came from — stated by the reporting bus driver so
+/// the manager's /etc/devices.csv matcher knows how to read the report's identity
+/// (a PCI class triple vs a USB class triple are the same 24 bits but different
+/// namespaces) and which `bus` column a rule must name to bind it. `unknown` is
+/// the zero default, so an un-upgraded reporter fails to match rather than
+/// binding to the wrong bus's rule.
+pub const BusKind = enum(u8) {
+    unknown = 0,
+    pci = 1,
+    usb = 2,
+    acpi = 3,
+};
+
 /// What kind of driver is talking (docs/driver-model.md's shapes).
 pub const Role = enum(u8) {
     /// Owns a controller and reports the devices behind it (`child_added`).
@@ -66,7 +79,9 @@ pub const reply_size = @sizeOf(HelloReply);
 /// restarted instance rediscovers and re-reports.
 pub const ChildAdded = extern struct {
     operation: u8 = @intFromEnum(Operation.child_added),
-    reserved0: u8 = 0,
+    /// A `BusKind` value: which bus reported this child, so the manager reads the
+    /// identity in the right namespace and matches against the right `bus` column.
+    bus: u8 = @intFromEnum(BusKind.unknown),
     reserved1: u16 = 0,
     reserved2: u32 = 0,
     /// The reporting driver's own device (the controller) — the child's parent.
@@ -80,6 +95,18 @@ pub const ChildAdded = extern struct {
     /// manager hands a matched driver as its argv assignment — or `no_device`
     /// for an unregistered leaf (a USB port before the descriptor track).
     device_id: u64 = no_device,
+    /// The vendor id (PCI vendor / USB idVendor), or 0 when the bus has no such
+    /// concept (ACPI). Carried so the manager's /etc/devices.csv matcher can bind
+    /// on vendor — a level the bus-native `identity` (a class triple) cannot express.
+    vendor: u16 = 0,
+    /// The device id (PCI device / USB idProduct), or 0. The most specific numeric
+    /// level: this is what lets one virtio-gpu (1AF4:1050) be told from any other
+    /// virtio display function without the driver re-confirming after it is spawned.
+    device: u16 = 0,
+    /// The PCI subsystem id, packed `(subsystem_vendor << 16) | subsystem_device`
+    /// (so it reads vendor-first, matching the CSV's `ssvid:ssid`), or 0 when the
+    /// device has no subsystem id (a bridge, or a non-PCI bus).
+    subsystem: u32 = 0,
     /// The ACPI hardware id (`_HID`), EISA-decoded (e.g. "PNP0303"), for devices
     /// discovered by firmware string rather than a numeric bus identity. Empty
     /// (all zero) otherwise. Widens for FDT `compatible` strings later.

system/drivers/display/display.zig

@@ -1,59 +0,0 @@
-//! /system/drivers/display - the generic display engine driver.
-//! This driver is a non official driver for GPU vendors like Intel, NVIDIA, AMD. It provides basic
-//! display engine features to the display engine protocol used by the display server, compositor
-//! and graphical user interface libraries like Zooeee.
-//!
-//! This driver is acts like BUS driver, in that it detects the GPU, its capabilities and loads
-//! sub-drivers for each device detected. Similar The device manager
-//! finds display adaptor e.g. over the PCI/ACPI, and passes the buck on to this driver to handle.
-//!
-//! The display driver provides the low level part of identifying the device and launching the
-//! generic device driver for a GPU vendor.
-//!
-//!  It takes over the framebuffer feature that was setup during system boot.
-const std = @import("std");
-const device = @import("driver");
-const ipc = @import("ipc");
-const process = @import("process");
-const service = @import("service");
-const device_manager = @import("driver");
-const logging = @import("logging");
-const mmio = @import("mmio");
-const display_protocol = @import("display-protocol");
-const scanout_protocol = @import("scanout-protocol");
-var device_id: u64 = 0;
-
-fn initialise(endpoint: ipc.Handle) bool {
-    _ = endpoint;
-    // Hello the device manager (role: device — we claim one GPU's PCI function
-    // and serve its display engine; we report no children). Best-effort: without a
-    // manager the driver still runs standalone; when present, the manager marks us
-    // up before the hello deadline and restarts us if we die.
-    _ = device_manager.hello(.device, device_id);
-    return true;
-}
-
-fn onMessage(message: []const u8, reply: []u8, sender: u32, capability: ?ipc.Handle) usize {
-    _ = sender;
-    _ = capability;
-    _ = reply;
-
-    if (message.len < scanout_protocol.request_size) return 0;
-    return 0;
-}
-
-pub fn main(init: process.Init) void {
-    const argument = init.arguments.get(1) orelse {
-        _ = logging.write("display: missing device id (argv[1])\n");
-        return;
-    };
-    device_id = std.fmt.parseInt(u64, argument, 10) catch {
-        std.log.info("malformed device id '{s}'", .{argument});
-        return;
-    };
-    service.run(256, .{
-        .service = .scanout,
-        .init = initialise,
-        .on_message = onMessage,
-    });
-}

system/drivers/display/intel-integrated/intel-integrated.zig

@@ -1,69 +0,0 @@
-//! /system/drivers/display/intel-integrated - the intel 985 family display engine driver.
-const std = @import("std");
-const device = @import("driver");
-const ipc = @import("ipc");
-const process = @import("process");
-const service = @import("service");
-const logging = @import("logging");
-const mmio = @import("mmio");
-const display_protocol = @import("display-protocol");
-const scanout_protocol = @import("scanout-protocol");
-const device_manager_protocol = @import("device-manager-protocol");
-var device_id: u64 = 0;
-
-
-fn initialise(endpoint: ipc.Handle) bool {
-    _ = endpoint;
-    return true;
-}
-
-fn onMessage(message: []const u8, reply: []u8, sender: u32, capability: ?ipc.Handle) usize {
-    _ = sender;
-    _ = capability;
-    _ = reply;
-
-    if (message.len < scanout_protocol.request_size) return 0;
-    const request = std.mem.bytesToValue(scanout_protocol.Request, message[0..scanout_protocol.request_size]);
-    switch (request.operation) {
-        _ => return 0,
-        // TODO:
-        // @intFromEnum(sp.Operation.present) => return scanoutStatus(reply, presentFull()),
-        // @intFromEnum(sp.Operation.get_modes) => {
-        //     var response = sp.ModesReply{ .status = 0, .count = offered_modes.len, .modes = undefined };
-        //     for (0..sp.max_modes) |i| {
-        //         response.modes[i] = if (i < offered_modes.len)
-        //             .{ .width = offered_modes[i].width, .height = offered_modes[i].height }
-        //         else
-        //             .{ .width = 0, .height = 0 };
-        //     }
-        //     @memcpy(reply[0..sp.modes_reply_size], std.mem.asBytes(&response));
-        //     return sp.modes_reply_size;
-        // },
-        // @intFromEnum(sp.Operation.set_mode) => {
-        //     const w = request.width;
-        //     const h = request.height;
-        //     if (w == 0 or h == 0 or w > max_width or h > max_height) return scanoutStatus(reply, false);
-        //     current_width = w;
-        //     current_height = h;
-        //     return scanoutStatus(reply, setScanoutRect());
-        // },
-        else => return 0,
-    }
-    return 0;
-}
-
-pub fn main(init: process.Init) void {
-    const argument = init.arguments.get(1) orelse {
-        _ = logging.write("display/intel-985: missing device id (argv[1])\n");
-        return;
-    };
-    device_id = std.fmt.parseInt(u64, argument, 10) catch {
-        std.log.info("malformed device id '{s}'", .{argument});
-        return;
-    };
-    service.run(256, .{
-        .service = .scanout,
-        .init = initialise,
-        .on_message = onMessage,
-    });
-}

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

@@ -21,19 +21,20 @@ const logging = @import("logging");
 const device_manager_protocol = @import("device-manager-protocol");
 const pci_class = @import("pci-class");
 
-/// 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 {
+/// Log a discovered function as its would-be /etc/devices.csv columns (bus, base,
+/// class, prog_if, vendor, device, subsystem) followed by the human-readable
+/// class/subclass/prog-IF names — so a row for a new driver reads straight off the
+/// boot log. `subsystem` prints as `*` when the function has none, matching the CSV
+/// wildcard. All read unclaimed, through the bridge's ECAM: the enumerator never
+/// claims the functions it probes (pci.zig's header — the device-owned pci.Function
+/// view is what needs a claim, not this one). A wide buffer: the names are long.
+fn logFunction(bus: u64, dev: u64, function: u64, class_triple: u32, vendor_id: u16, product_id: u16, subsystem: 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;
+    var sub_buffer: [8]u8 = undefined;
+    const sub = if (subsystem == 0) "*" else std.fmt.bufPrint(&sub_buffer, "{X:0>8}", .{subsystem}) catch "*";
+    var line: [320]u8 = undefined;
+    const text = std.fmt.bufPrint(&line, "/system/drivers/pci-bus: {d}:{d}.{d}  bus=pci base={X:0>2} class={X:0>2} prog_if={X:0>2} vendor={X:0>4} device={X:0>4} subsystem={s}  —  {s} / {s}{s}{s}\n", .{ bus, dev, function, cc.base, cc.subclass, cc.prog_if, vendor_id, product_id, sub, pci_class.className(cc.base), pci_class.subclassName(cc.base, cc.subclass), if (pif.len != 0) " / " else "", pif }) catch return;
     _ = logging.write(text);
 }
 
@@ -136,7 +137,6 @@ fn scan() void {
                 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);
             }
         }
@@ -153,6 +153,12 @@ 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;
+    // Vendor/device from the first config dword (0x00): low half vendor, high half
+    // device. These carry to the manager's /etc/devices.csv matcher so a function
+    // can bind on its exact 1AF4:1050 identity, not just its class triple.
+    const vendor_device = configRead(bus, dev, function, 0x00);
+    descriptor.vendor = @truncate(vendor_device);
+    descriptor.device = @truncate(vendor_device >> 16);
     descriptor.resources[0] = .{
         .kind = @intFromEnum(device.ResourceKind.memory),
         .start = ecam_physical + (((bus - start_bus) << 20) | (dev << 15) | (function << 12)),
@@ -164,6 +170,11 @@ fn registerAndReport(bus: u64, dev: u64, function: u64, class_triple: u32) void
     // 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) {
+        // Subsystem id lives at 0x2C only on type-0 (device) headers, not on
+        // bridges: dword low half is subsystem-vendor, high half subsystem-device.
+        // Repack vendor-first so it reads like the CSV's `ssvid:ssid`.
+        const subsystem_dword = configRead(bus, dev, function, 0x2C);
+        descriptor.subsystem = (@as(u32, @truncate(subsystem_dword)) << 16) | @as(u32, @truncate(subsystem_dword >> 16));
         const command = configRead16(bus, dev, function, 0x04);
         configWrite16(bus, dev, function, 0x04, command & ~@as(u16, 0b11));
         var i: u64 = 0;
@@ -210,15 +221,23 @@ fn registerAndReport(bus: u64, dev: u64, function: u64, class_triple: u32) void
         configWrite16(bus, dev, function, 0x04, command);
     }
 
+    // The devices.csv-column + friendly-name breadcrumb, now that vendor/device/
+    // subsystem are read. Every discovered function is logged, matched or not.
+    logFunction(bus, dev, function, class_triple, descriptor.vendor, descriptor.device, descriptor.subsystem);
+
     const registered = device.register(bridge_id, &descriptor) orelse {
         std.log.info("register refused for {d}:{d}.{d}", .{ bus, dev, function });
         return;
     };
     const report = device_manager_protocol.ChildAdded{
+        .bus = @intFromEnum(device_manager_protocol.BusKind.pci),
         .parent = bridge_id,
         .bus_address = (bus << 8) | (dev << 3) | function,
         .identity = class_triple,
         .device_id = registered,
+        .vendor = descriptor.vendor,
+        .device = descriptor.device,
+        .subsystem = descriptor.subsystem,
     };
     var reply: [device_manager_protocol.message_maximum]u8 = undefined;
     _ = ipc.call(manager_handle, std.mem.asBytes(&report), &reply) catch {

system/drivers/usb-xhci-bus/usb-xhci-bus.zig

@@ -379,6 +379,7 @@ fn reportInterface(manager: ipc.Handle, port: u32, interface: library.InterfaceI
     };
 
     const report = device_manager_protocol.ChildAdded{
+        .bus = @intFromEnum(device_manager_protocol.BusKind.usb),
         .parent = controller_id,
         .bus_address = (@as(u64, port) << 8) | interface.number,
         .identity = identity,
@@ -389,13 +390,16 @@ fn reportInterface(manager: ipc.Handle, port: u32, interface: library.InterfaceI
         std.log.info("child report for port {d} interface {d} failed", .{ port, interface.number });
         return null;
     };
-    std.log.info("port {d} interface {d}: {s} ({d}/{d}/{d}) registered as device {d}", .{
+    // The devices.csv columns (bus=usb, and the class triple as base/class/prog_if)
+    // then the human-readable interface name — a would-be /etc/devices.csv row read
+    // straight off the boot log.
+    std.log.info("port {d} interface {d}  bus=usb base={X:0>2} class={X:0>2} prog_if={X:0>2}  —  {s}  registered as device {d}", .{
         port,
         interface.number,
-        usb_ids.interfaceName(interface.class, interface.subclass, interface.protocol),
         interface.class,
         interface.subclass,
         interface.protocol,
+        usb_ids.interfaceName(interface.class, interface.subclass, interface.protocol),
         registered,
     });
     return registered;

system/drivers/virtio-gpu/virtio-gpu.zig

@@ -33,11 +33,6 @@ const vg = @import("virtio-gpu-protocol.zig");
 /// the compositor in the announce so it packs colours in the surface's byte order.
 const display_format_bgrx: u32 = 1;
 
-/// The PCI vendor/device ids of a modern virtio-gpu (Red Hat / virtio; GPU is a
-/// virtio-1.0-only device, so the id is always the modern 0x1050 — no legacy variant).
-const virtio_vendor: u16 = 0x1AF4;
-const virtio_gpu_device: u16 = 0x1050;
-
 /// The scanout resource + shared surface are sized to the *largest* mode we offer; a mode
 /// change (V5) re-points the scanout rectangle within it, so the resource, its backing, and
 /// the shared surface never churn — and the surface's row stride is always `max_width`, which
@@ -210,19 +205,15 @@ fn initialise(endpoint: ipc.Handle) bool {
         return false;
     };
 
-    // Config space is resource 0. Confirm it really is a virtio-gpu, then enable memory-space
-    // decode + bus mastering (the device DMAs the ring and backing out of RAM); pci-bus only
-    // preserves whatever the firmware left, and a secondary display is often left disabled.
+    // Config space is resource 0. The registry (/etc/devices.csv) bound this driver by the
+    // exact virtio-gpu identity (vendor 0x1AF4 / device 0x1050), so there is no re-confirm to
+    // do here any more — map config space and enable memory-space decode + bus mastering (the
+    // device DMAs the ring and backing out of RAM; pci-bus only preserves whatever the firmware
+    // left, and a secondary display is often left disabled).
     var function = pci.Function.map(device_id, descriptor) orelse {
         std.log.info("config-space map failed", .{});
         return false;
     };
-    const vendor = function.vendorId();
-    const dev = function.deviceId();
-    if (vendor != virtio_vendor or dev != virtio_gpu_device) {
-        std.log.info("not a virtio-gpu (vendor 0x{x} device 0x{x})", .{ vendor, dev });
-        return false;
-    }
     function.enableMemoryAndBusMaster();
 
     // Walk the capability list for the virtio common-config and notify structures (V3 needs

system/services/acpi/acpi.zig

@@ -214,13 +214,15 @@ fn onInit(endpoint: ipc.Handle) bool {
     while (i < registered_count) : (i += 1) {
         const entry = registered[i];
         const hid = entry.hid[0..entry.hid_len];
+        // The devices.csv columns (bus=acpi, hid) then the human-readable name — a
+        // would-be /etc/devices.csv row read straight off the boot log.
         const desc = acpi_ids.description(hid);
         if (desc.len != 0)
-            std.log.info("reported {s} (device {d}, {d} resources) — {s}", .{ hid, entry.device_id, entry.resource_count, desc })
+            std.log.info("device {d}  bus=acpi hid={s}  —  {s}  ({d} resources)", .{ entry.device_id, hid, desc, entry.resource_count })
         else
-            std.log.info("reported {s} (device {d}, {d} resources)", .{ hid, entry.device_id, entry.resource_count });
+            std.log.info("device {d}  bus=acpi hid={s}  ({d} resources)", .{ entry.device_id, hid, entry.resource_count });
         if (manager) |h| {
-            var report = device_manager_protocol.ChildAdded{ .parent = node_id, .bus_address = entry.device_id, .identity = 0, .device_id = entry.device_id };
+            var report = device_manager_protocol.ChildAdded{ .bus = @intFromEnum(device_manager_protocol.BusKind.acpi), .parent = node_id, .bus_address = entry.device_id, .identity = 0, .device_id = entry.device_id };
             @memcpy(report.hid[0..entry.hid_len], entry.hid[0..entry.hid_len]);
             var reply: [device_manager_protocol.message_maximum]u8 = undefined;
             _ = ipc.call(h, std.mem.asBytes(&report), &reply) catch {};

system/services/device-manager/device-manager.zig

@@ -23,86 +23,66 @@ const service = @import("service");
 const time = @import("time");
 const memory = @import("memory");
 const logging = @import("logging");
-const acpi_ids = @import("acpi-ids");
-const pci_class = @import("pci-class");
-const usb_ids = @import("usb-ids");
 const device_manager_protocol = @import("device-manager-protocol");
+const registry = @import("device-registry");
+const fs = @import("file-system");
 
-/// The PCI class/subclass/prog-IF triple of an xHCI (USB 3) host controller —
-/// Serial Bus Controller / USB Controller / XHCI — named from pci-class.zig rather
-/// than written as the bare 0x0C0330 (docs/coding-standards.md, "Named values").
-const xhci_pci_class: u64 = pci_class.ClassCode.pack(.{
-    .base = @intFromEnum(pci_class.BaseClass.serial_bus),
-    .subclass = @intFromEnum(pci_class.serial_bus.SubClass.usb),
-    .prog_if = @intFromEnum(pci_class.serial_bus.usb.ProgIf.xhci),
-});
+// --- the device registry ------------------------------------------------------
+// Driver matching is data-driven and authoritative: /etc/devices.csv (parsed by
+// the device-registry module) names, per bus, which driver binds a reported
+// device, the most-specific match winning. There is no compiled-in fallback — a
+// device no row matches goes unbound and is logged. This retired the hand-kept
+// pciDriverForIdentity / hidDriverFor / usbDriverForIdentity switch tables
+// (docs/device-manager.md: "matching stays code until the third bus").
 
-/// The PCI class triple of a virtio-gpu — Display Controller / Other (0x80) / 0. The class
-/// alone cannot tell it from any other display/other function, so the driver re-confirms
-/// vendor 0x1AF4 / device 0x1050 from config space once spawned; this only gets it spawned.
-const virtio_gpu_pci_class: u64 = pci_class.ClassCode.pack(.{
-    .base = @intFromEnum(pci_class.BaseClass.display),
-    .subclass = 0x80, // "Other" — no named SubClass member (PCI convention)
-    .prog_if = 0,
-});
+/// The CSV bytes, held for the life of the process because the parsed rules'
+/// string fields (hid, driver) slice into this buffer.
+var registry_source: [8192]u8 = undefined;
+var registry_rules: [64]registry.Rule = undefined;
+var registry_count: usize = 0;
 
-
-const vga_compatible_gpu_pci_class: u64 = pci_class.ClassCode.pack(.{
-    .base = @intFromEnum(pci_class.BaseClass.display),
-    .subclass = @intFromEnum(pci_class.display.SubClass.vga_compatible),
-    .prog_if = 0,
-});
-
-/// The driver that serves a *reported* PCI function (M19.3: matching moved
-/// from the boot snapshot to the bus reports), or null. A machine can carry
-/// several identical controllers — one driver instance per reported device,
-/// its registered id as argv[1].
-fn pciDriverForIdentity(identity: u64) ?[]const u8 {
-    return switch (identity) {
-        xhci_pci_class => "/system/drivers/usb-xhci-bus",
-        vga_compatible_gpu_pci_class => "/system/drivers/display",
-        virtio_gpu_pci_class => "/system/drivers/virtio-gpu",
-        else => null,
+/// Read and parse /etc/devices.csv once at boot. The file lives in the initial
+/// ramdisk, which the kernel serves directly — no filesystem service need be up
+/// (fat is spawned after the manager), so this is a plain fs.open + read.
+fn loadRegistry() void {
+    var file = fs.open("/etc/devices.csv", .{}) orelse {
+        _ = logging.write("/system/services/device-manager: /etc/devices.csv missing — nothing will match\n");
+        return;
     };
+    defer file.close();
+    var used: usize = 0;
+    while (used < registry_source.len) {
+        const n = file.read(registry_source[used..]) orelse break;
+        if (n == 0) break;
+        used += n;
+    }
+    const result = registry.parse(registry_source[0..used], &registry_rules);
+    registry_count = result.count;
+    if (result.malformed != 0) std.log.info("/etc/devices.csv: {d} malformed line(s) skipped", .{result.malformed});
+    if (result.truncated) _ = logging.write("/system/services/device-manager: /etc/devices.csv has more rules than the table holds\n");
+    std.log.info("/etc/devices.csv: {d} rule(s) loaded", .{registry_count});
 }
 
-/// The driver that serves a *reported* ACPI device by its `_HID` (M20.3:
-/// ps2-bus now binds the PS/2 nodes the acpi service reports, not boot-snapshot
-/// nodes the kernel used to build). ps2-bus is a singleton that finds both its
-/// devices by hid once spawned, so keyboard and mouse map to the same name.
-fn hidDriverFor(hid: []const u8) ?[]const u8 {
-    if (std.mem.eql(u8, hid, "PNP0303")) return "/system/drivers/ps2-bus"; // PS/2 keyboard
-    if (std.mem.eql(u8, hid, "PNP0F13")) return "/system/drivers/ps2-bus"; // PS/2 mouse
-    return null;
-}
-
-/// The driver that serves a *reported* USB interface by its (class, subclass,
-/// protocol) triple — the third bus after PCI and ACPI (docs/device-manager.md:
-/// matching stays code until the third bus). The xHCI bus driver reports each
-/// interface with this packed triple as its identity; the matched class driver is
-/// spawned with the interface's registered id as argv[1], which it presents to the
-/// bus driver to open the device.
-fn usbDriverForIdentity(identity: u64) ?[]const u8 {
-    const keyboard = comptime usb_ids.packTriple(
-        @intFromEnum(usb_ids.Class.hid),
-        @intFromEnum(usb_ids.hid.SubClass.boot),
-        @intFromEnum(usb_ids.hid.Protocol.keyboard),
-    );
-    const mouse = comptime usb_ids.packTriple(
-        @intFromEnum(usb_ids.Class.hid),
-        @intFromEnum(usb_ids.hid.SubClass.boot),
-        @intFromEnum(usb_ids.hid.Protocol.mouse),
-    );
-    const storage = comptime usb_ids.packTriple(
-        @intFromEnum(usb_ids.Class.mass_storage),
-        @intFromEnum(usb_ids.mass_storage.SubClass.scsi),
-        @intFromEnum(usb_ids.mass_storage.Protocol.bulk_only),
-    );
-    return switch (identity) {
-        keyboard => "/system/drivers/usb-hid-keyboard",
-        mouse => "/system/drivers/usb-hid-mouse",
-        storage => "/system/drivers/usb-storage",
-        else => null,
+/// Build a registry Identity from a bus driver's report: the bus it named, the
+/// class triple unpacked from `identity` (0xCCSSPP — the same packing for a PCI
+/// class code and a USB class triple), the widened numeric ids, and the ACPI hid.
+fn identityFromReport(report: device_manager_protocol.ChildAdded) registry.Identity {
+    const bus: registry.Bus = switch (report.bus) {
+        @intFromEnum(device_manager_protocol.BusKind.pci) => .pci,
+        @intFromEnum(device_manager_protocol.BusKind.usb) => .usb,
+        @intFromEnum(device_manager_protocol.BusKind.acpi) => .acpi,
+        else => .unknown,
+    };
+    const hid_len = std.mem.indexOfScalar(u8, &report.hid, 0) orelse report.hid.len;
+    return .{
+        .bus = bus,
+        .base = @truncate(report.identity >> 16),
+        .subclass = @truncate(report.identity >> 8),
+        .prog_if = @truncate(report.identity),
+        .vendor = report.vendor,
+        .device = report.device,
+        .subsystem = report.subsystem,
+        .hid = report.hid[0..hid_len],
     };
 }
 
@@ -365,6 +345,10 @@ fn sweepDeadlines() void {
 fn initialise(endpoint: ipc.Handle) bool {
     manager_endpoint = endpoint;
 
+    // Load the authoritative driver-match registry before any bus driver can
+    // report a device to match against it.
+    loadRegistry();
+
     // Enumerate into a heap buffer (too big for the one-page user stack).
     const buffer = memory.allocator().alloc(device.DeviceDescriptor, 64) catch {
         _ = logging.write("/system/services/device-manager: out of memory\n");
@@ -459,24 +443,22 @@ fn onChildAdded(message: []const u8, reply: []u8, sender: u32) usize {
         if (!addChild(report.parent, report.bus_address, report.identity, report.device_id, sender)) status = -1;
         std.log.info("child added (device {d} port {d}, identity {d}) by {s}", .{ report.parent, report.bus_address, report.identity, driver.name() });
         if (status == 0) publishEvent(message[0..device_manager_protocol.child_added_size]);
-        // Matching from reports (M19.3): a registered child whose identity
-        // names a driver gets one, once — re-reports after a bus restart
-        // dedupe on the registered id, exactly like the registrations do.
+        // Matching from reports (M19.3), now data-driven via the /etc/devices.csv
+        // registry: a registered child gets the most-specific driver its identity
+        // matches, once — re-reports after a bus restart dedupe on the registered
+        // id, exactly like the registrations do.
         if (status == 0 and report.device_id != device_manager_protocol.no_device) {
-            if (pciDriverForIdentity(report.identity)) |child_driver| {
-                if (!driverForDevice(report.device_id)) addDriver(child_driver, report.device_id, true);
-            }
-            // USB interface match: the reported identity is the packed class triple,
-            // and the class driver is spawned with the interface's registered id.
-            if (usbDriverForIdentity(report.identity)) |usb_driver| {
-                if (!driverForDevice(report.device_id)) addDriver(usb_driver, report.device_id, true);
-            }
-            // ACPI _HID match (M20.3): ps2-bus is a singleton that finds its own
-            // devices by hid, so spawn it once, without a device assignment.
-            const hid_len = std.mem.indexOfScalar(u8, &report.hid, 0) orelse report.hid.len;
-            if (hid_len != 0) {
-                if (hidDriverFor(report.hid[0..hid_len])) |hid_driver| {
-                    if (!alreadySupervised(hid_driver)) addDriver(hid_driver, device_manager_protocol.no_device, false);
+            const id = identityFromReport(report);
+            if (registry.matchDriver(registry_rules[0..registry_count], id)) |match| {
+                if (match.ambiguous)
+                    std.log.info("/etc/devices.csv: multiple equally-specific rules match the device {s} reported; binding {s}", .{ driver.name(), match.driver });
+                if (id.bus == .acpi) {
+                    // An hid-matched driver (ps2-bus) is a singleton that finds its
+                    // own devices once spawned — spawn it once, no device assignment.
+                    if (!alreadySupervised(match.driver)) addDriver(match.driver, device_manager_protocol.no_device, false);
+                } else {
+                    // A per-device driver: one instance, the registered id as argv[1].
+                    if (!driverForDevice(report.device_id)) addDriver(match.driver, report.device_id, true);
                 }
             }
         }

system/services/init/init.zig

@@ -25,42 +25,88 @@ const memory = @import("memory");
 const logging = @import("logging");
 const power_protocol = @import("power-protocol");
 const build_options = @import("build_options");
+const fs = @import("file-system");
+const csv = @import("csv");
 
-/// The system services init brings up at boot, in order, by binary path. This is
-/// init's policy — the microkernel keeps such choices in user space, not the
-/// kernel. Drivers are absent on purpose: the device manager owns those. (A
-/// future init reads this from a manifest under /system/services instead of a
-/// hardcoded list.)
-const boot_services = if (build_options.diagnose) [_][]const u8{
-    // The diagnose boot: no display service, so the kernel's on-screen boot
-    // transcript is never suppressed — the timestamped timeline (USB bring-up,
-    // storage, logger) stays readable on real hardware with no serial.
-    "/system/services/input",
-    "/system/services/device-manager",
-    "/system/services/fat",
-    "/system/services/logger",
-} else [_][]const u8{
-    "/system/services/input",
-    "/system/services/device-manager",
-    "/system/services/fat",
-    "/system/services/display",
-    "/system/services/display-demo",
-    // Last: at shutdown children stop in reverse order, so the logger goes down
-    // FIRST — its final drain still has the fat server (and the whole storage
-    // chain) alive underneath it.
-    "/system/services/logger",
+/// The system services init brings up at boot are init's policy, not the kernel's —
+/// and that policy is now data: `/etc/init.csv` (see `loadServices`), read at
+/// startup instead of a hardcoded list. Drivers are absent on purpose: the device
+/// manager owns those.
+///
+/// The most services `/etc/init.csv` can list, and the most argv entries (beyond the
+/// path) each may carry. Fixed caps because init parses the list into static storage —
+/// the freestanding, no-allocator counterpart to the device manager's registry table.
+const max_services = 16;
+const max_service_args = 4;
+
+/// One service init starts, parsed from a row of `/etc/init.csv`: its binary path
+/// and argv, both slices into `init_csv` (held for the life of the process).
+const Service = struct {
+    path: []const u8 = "",
+    arg_buffer: [max_service_args][]const u8 = undefined,
+    arg_count: usize = 0,
+    fn arguments(self: *const Service) []const []const u8 {
+        return self.arg_buffer[0..self.arg_count];
+    }
 };
 
-/// The live process id of each boot service (0 = not running), indexed by its position
-/// in `boot_services`, plus how many times init has restarted it. init supervises these:
-/// it spawns them against `supervision_endpoint` and, on a child's death, restarts it (up
-/// to `maximum_restarts`) — the reincarnation half of resilience (docs/resilience.md), the
-/// service-level counterpart to the device manager's driver restarts.
-var child_ids: [boot_services.len]u32 = .{0} ** boot_services.len;
-var restart_counts: [boot_services.len]u32 = .{0} ** boot_services.len;
+/// The `/etc/init.csv` bytes, held because the parsed services slice into them.
+var init_csv: [4096]u8 = undefined;
+var services: [max_services]Service = .{Service{}} ** max_services;
+var service_count: usize = 0;
+
+/// The live process id of each service (0 = not running) and its restart count,
+/// indexed by position in `services`. init supervises these: it spawns them against
+/// `supervision_endpoint` and, on a child's death, restarts it (up to
+/// `maximum_restarts`) — the reincarnation half of resilience (docs/resilience.md),
+/// the service-level counterpart to the device manager's driver restarts.
+var child_ids: [max_services]u32 = .{0} ** max_services;
+var restart_counts: [max_services]u32 = .{0} ** max_services;
 var shutting_down = false;
 var supervision_endpoint: ipc.Handle = 0;
 
+/// Parse `/etc/init.csv` into `services`, in file order (startup order; shutdown is
+/// the reverse). Each row is a binary path followed by its argv, comma-separated;
+/// `#` comments and blank lines are ignored. The file lives in the initial ramdisk,
+/// which the kernel serves directly, so init — PID 1, running before any filesystem
+/// service — reads it with a plain fs.open, the same mechanism the device manager
+/// uses for /etc/devices.csv. A missing file means no services (the no-ramdisk
+/// isolation test): loud, but not fatal.
+fn loadServices() void {
+    var file = fs.open("/etc/init.csv", .{}) orelse {
+        _ = logging.write("/system/services/init: /etc/init.csv missing — no services started\n");
+        return;
+    };
+    defer file.close();
+    var used: usize = 0;
+    while (used < init_csv.len) {
+        const n = file.read(init_csv[used..]) orelse break;
+        if (n == 0) break;
+        used += n;
+    }
+    var lines = std.mem.splitScalar(u8, init_csv[0..used], '\n');
+    while (lines.next()) |line| {
+        const body = csv.stripComment(line);
+        if (body.len == 0) continue;
+        if (service_count >= services.len) {
+            _ = logging.write("/system/services/init: /etc/init.csv has more services than the table holds\n");
+            break;
+        }
+        var it = csv.fields(body);
+        const path = it.next() orelse continue;
+        if (path.len == 0) continue;
+        var service: Service = .{ .path = path };
+        while (it.next()) |argument| {
+            if (argument.len == 0) continue; // padding, or a trailing comma
+            if (service.arg_count >= max_service_args) break;
+            service.arg_buffer[service.arg_count] = argument;
+            service.arg_count += 1;
+        }
+        services[service_count] = service;
+        service_count += 1;
+    }
+}
+
 /// Give up restarting a service after this many crashes — a crash-loop cap, so a service
 /// that faults immediately on every spawn doesn't respawn forever.
 const maximum_restarts = 3;
@@ -89,11 +135,12 @@ pub fn main() void {
     };
     _ = process.bindSignals(supervision_endpoint);
 
-    // Bring up the boot services, supervised so init can stop them cleanly.
-    // Best-effort and silent: each service announces its own readiness, and in
-    // an isolation test with no initial-ramdisk the spawns simply no-op.
-    for (boot_services, 0..) |service, i| {
-        if (process.spawnSupervised(service, &.{}, supervision_endpoint)) |id| child_ids[i] = id;
+    // Load the service list, then bring each up supervised so init can stop them
+    // cleanly. Best-effort and silent: each service announces its own readiness,
+    // and with no /etc/init.csv (an isolation test) the loop starts nothing.
+    loadServices();
+    for (services[0..service_count], 0..) |*service, i| {
+        if (process.spawnSupervised(service.path, service.arguments(), supervision_endpoint)) |id| child_ids[i] = id;
     }
 
     // Subscribe to power events (retry: the power service registers well after
@@ -141,22 +188,22 @@ pub fn main() void {
 /// iron rule 1); init only decides whether to bring it back.
 fn restartChild(id: u32) void {
     if (shutting_down) return; // deaths during the stop sequence are expected, not crashes
-    for (boot_services, 0..) |service, i| {
+    for (services[0..service_count], 0..) |*service, i| {
         if (child_ids[i] != id) continue;
         child_ids[i] = 0;
         // An unknown reason (the record aged out) is treated as a crash worth restarting.
         const reason = process.exitReason(id) orelse .fault;
         if (reason == .exited) {
-            std.log.info("{s} exited cleanly; not restarting", .{service});
+            std.log.info("{s} exited cleanly; not restarting", .{service.path});
             return;
         }
         restart_counts[i] += 1;
         if (restart_counts[i] > maximum_restarts) {
-            std.log.info("{s} keeps crashing; giving up after {d} restarts", .{ service, maximum_restarts });
+            std.log.info("{s} keeps crashing; giving up after {d} restarts", .{ service.path, maximum_restarts });
             return;
         }
-        std.log.info("{s} died ({s}); restarting ({d}/{d})", .{ service, @tagName(reason), restart_counts[i], maximum_restarts });
-        if (process.spawnSupervised(service, &.{}, supervision_endpoint)) |new_id| child_ids[i] = new_id;
+        std.log.info("{s} died ({s}); restarting ({d}/{d})", .{ service.path, @tagName(reason), restart_counts[i], maximum_restarts });
+        if (process.spawnSupervised(service.path, service.arguments(), supervision_endpoint)) |new_id| child_ids[i] = new_id;
         return;
     }
     // An untracked child (e.g. the log-flush one-shot): nothing to restart.
@@ -190,7 +237,7 @@ fn shutDown() void {
     // Log persistence is the logger service's job: it is the LAST boot service,
     // so the reverse-order stop below terminates it first and its final drain
     // runs while the whole storage chain is still alive.
-    var i = boot_services.len;
+    var i = service_count;
     while (i > 0) {
         i -= 1;
         if (child_ids[i] != 0) process.stop(child_ids[i], 2000, supervision_endpoint);

test/qemu_test.py

@@ -628,7 +628,7 @@ CASES = [
     {"name": "acpi-ps2",
      "smp":    4,
      "timeout": 150,
-     "expect": r"discovery: reported PNP0303[\s\S]*"
+     "expect": r"discovery: device \d+\s+bus=acpi hid=PNP0303[\s\S]*"
                r"device-manager: spawned \S*ps2-bus[\s\S]*"
                r"ps2-bus: keyboard driver attached",
      "fail":   r"DANOS-TEST-RESULT: FAIL"},
@@ -675,8 +675,8 @@ CASES = [
     {"name": "acpi-report",
      "smp":    4,
      "timeout": 150,
-     "expect": r"discovery: reported PNP0303 \(device \d+, 3 resources\)[\s\S]*"
-               r"discovery: reported PNP0F13 \(device \d+, 1 resources\)",
+     "expect": r"discovery: device \d+\s+bus=acpi hid=PNP0303[^\n]*\(3 resources\)[\s\S]*"
+               r"discovery: device \d+\s+bus=acpi hid=PNP0F13[^\n]*\(1 resources\)",
      "fail":   r"DANOS-TEST-RESULT: FAIL"},
     # M19.1/M19.3: the ring-3 PCI scan. pci-bus walks the ECAM through its mmio_map
     # grant and registers every function it finds; the kernel's own walk retired, so