USB driver stack: xHCI transfers, HID keyboard/mouse, mass storage

Flesh out the xHCI host-controller driver into a full transfer engine and build
the three USB class drivers on top, all verified end to end under QEMU.

- xHCI engine (usb-xhci-library.zig): controller reset, command/event rings with
  cycle-bit bookkeeping (gated on a No-Op-command proof), device slots, Address
  Device, control transfers, full chapter-9 enumeration, Configure Endpoint, and
  interrupt/bulk transfers. Each interface is device_registered with its
  (class,subclass,protocol) identity, unique per (port,interface).
- Bus<->class transfer protocol (usb-transfer-protocol.zig + runtime.usb): open /
  control / interrupt-subscribe (async report pump on a poll timer) / bulk-by-
  physical-address, so sector data never crosses the 256-byte IPC limit.
- USB HID keyboard + mouse (usb-hid/): decode boot-protocol reports and publish
  to the input service. A USB usage is already the input protocol's keycode.
- USB mass storage (usb-storage/): Bulk-Only Transport + transparent SCSI,
  serving a block device under the new .block service id (block-protocol).
- device-manager matches USB interfaces to class drivers (usbDriverForIdentity).
- usb-abi / usb-ids made importable modules; add HID and mass-storage class
  requests, packTriple, and a usb_device DeviceClass.
- Fix test/qemu_test.py on macOS: the QMP unix-socket path was built from the
  deep worktree path and exceeded the 104-byte sun_path limit, so QEMU exited
  before booting. It now lives under a short temp path.

Tests: usb-report, usb-hid, usb-storage pass under python3 test/qemu_test.py;
host units (usb-abi, usb-ids, hid-report, bulk-only-transport, scsi) green.

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

@@ -0,0 +1,159 @@
+//! The USB transfer protocol: what a USB class driver (a keyboard, mouse, or
+//! mass-storage driver) says to the xHCI bus driver over its well-known
+//! `.usb_bus` endpoint to drive its device. The class driver owns no hardware —
+//! it reaches its device entirely through these messages, the way a PS/2 keyboard
+//! driver reaches the 8042 through the ps2-bus. Extern-struct messages tagged by
+//! `Operation`, the vfs-protocol / device-manager-protocol pattern.
+//!
+//! The shape:
+//!   - **open** (a capability-passing `ipc.callCap`): the class driver hands over
+//!     its own endpoint (for asynchronous interrupt reports) and its assigned
+//!     device id, and receives a `device_token` plus its interface's endpoints.
+//!   - **control / bulk** (synchronous `ipc.call`): one transfer, answered when
+//!     it completes. Control data travels inline (descriptors, HID/MSC class
+//!     requests are all small); bulk data travels by **physical address** — the
+//!     class driver's own `dma_alloc`'d buffer — so a 512-byte sector never has
+//!     to cross the 256-byte IPC boundary.
+//!   - **interrupt_subscribe** (synchronous): arm periodic IN polling of an
+//!     interrupt endpoint; each report the device produces is then pushed to the
+//!     class driver's endpoint as an asynchronous `InterruptReport` (`ipc.send`),
+//!     exactly how the input service delivers events.
+//!
+//! Single controller assumption: one `.usb_bus` singleton serves QEMU's one xHCI.
+//! A multi-controller machine would need a per-controller endpoint (the device
+//! manager handing each class driver the right one); noted, not built.
+
+/// Fits one synchronous IPC message (kernel MESSAGE_MAXIMUM).
+pub const message_maximum: usize = 256;
+
+/// The largest inline control-transfer payload. Sized so a whole message
+/// (header + data) stays under `message_maximum`: descriptors and HID/MSC class
+/// requests are all far smaller.
+pub const max_inline_data: usize = 200;
+
+/// The largest interrupt report pushed asynchronously. Sized so `InterruptReport`
+/// fits an `ipc_send` payload slot (POST_MAXIMUM = 64): boot keyboard reports are
+/// 8 bytes, boot mouse reports 3–4.
+pub const max_report_data: usize = 48;
+
+/// Endpoints per interface reported back in an open reply (a boot HID interface
+/// has one interrupt endpoint, a mass-storage interface two bulk endpoints).
+pub const max_reported_endpoints: usize = 4;
+
+pub const Operation = enum(u32) {
+    open = 0,
+    control = 1,
+    interrupt_subscribe = 2,
+    bulk = 3,
+};
+
+/// The endpoint facts a class driver needs, lifted from the endpoint descriptor
+/// the bus driver already parsed during enumeration.
+pub const Endpoint = extern struct {
+    /// EndpointDescriptor address: direction in bit 7, number in bits 3:0.
+    address: u8,
+    /// 0 control, 1 isochronous, 2 bulk, 3 interrupt.
+    transfer_type: u8,
+    max_packet_size: u16,
+    interval: u8,
+    reserved: [3]u8 = .{ 0, 0, 0 },
+};
+
+/// open: the class driver's receive endpoint rides as the call's capability, and
+/// `device_id` is the interface's assigned id (its argv[1]).
+pub const OpenRequest = extern struct {
+    operation: u32 = @intFromEnum(Operation.open),
+    reserved: u32 = 0,
+    device_id: u64,
+};
+
+/// The answer to open: a token scoping every later request to this device, the
+/// interface's class triple (a sanity check), and its endpoints.
+pub const OpenReply = extern struct {
+    status: i32,
+    endpoint_count: u32,
+    device_token: u64,
+    interface_class: u8,
+    interface_subclass: u8,
+    interface_protocol: u8,
+    interface_number: u8,
+    reserved2: u32 = 0,
+    endpoints: [max_reported_endpoints]Endpoint = [_]Endpoint{.{ .address = 0, .transfer_type = 0, .max_packet_size = 0, .interval = 0 }} ** max_reported_endpoints,
+};
+
+/// control: one EP0 control transfer. `setup` is a bit-cast `usb_abi.Request`.
+/// For an OUT transfer `data[0..data_length]` is sent; for an IN transfer the
+/// reply carries up to `data_length` bytes back.
+pub const ControlRequest = extern struct {
+    operation: u32 = @intFromEnum(Operation.control),
+    reserved: u32 = 0,
+    device_token: u64,
+    setup: [8]u8,
+    direction_in: u8, // 1 = device-to-host (IN), 0 = host-to-device (OUT)
+    reserved2: u8 = 0,
+    data_length: u16,
+    reserved3: u32 = 0,
+    data: [max_inline_data]u8 = [_]u8{0} ** max_inline_data,
+};
+
+pub const ControlReply = extern struct {
+    status: i32, // 0 success, negative on failure/stall
+    actual_length: u32,
+    data: [max_inline_data]u8 = [_]u8{0} ** max_inline_data,
+};
+
+/// interrupt_subscribe: begin periodic IN polling of an interrupt endpoint. Each
+/// report the device returns is pushed to the caller's endpoint (handed over at
+/// open) as an asynchronous `InterruptReport`.
+pub const InterruptSubscribeRequest = extern struct {
+    operation: u32 = @intFromEnum(Operation.interrupt_subscribe),
+    reserved: u32 = 0,
+    device_token: u64,
+    endpoint_address: u8,
+    reserved2: u8 = 0,
+    max_length: u16, // bytes to request per poll (the endpoint's max packet size)
+};
+
+pub const InterruptSubscribeReply = extern struct {
+    status: i32,
+    reserved: u32 = 0,
+};
+
+/// bulk: one bulk IN or OUT transfer. `physical_address` is the class driver's own
+/// `dma_alloc`'d buffer — the controller DMAs straight to/from it, so the bulk
+/// data never crosses IPC. `endpoint_address`'s bit 7 selects IN vs OUT.
+pub const BulkRequest = extern struct {
+    operation: u32 = @intFromEnum(Operation.bulk),
+    reserved: u32 = 0,
+    device_token: u64,
+    physical_address: u64,
+    length: u32,
+    endpoint_address: u8,
+    reserved2: u8 = 0,
+    reserved3: u16 = 0,
+};
+
+pub const BulkReply = extern struct {
+    status: i32,
+    actual_length: u32,
+};
+
+/// An asynchronous interrupt report, pushed with `ipc.send` to a subscriber's
+/// endpoint. `Received.isMessage()` is set; there is no reply owed.
+pub const InterruptReport = extern struct {
+    device_token: u64,
+    endpoint_address: u8,
+    length: u8,
+    reserved: u16 = 0,
+    data: [max_report_data]u8 = [_]u8{0} ** max_report_data,
+};
+
+comptime {
+    const std = @import("std");
+    // Every synchronous message must fit one IPC message; the async report must
+    // fit an ipc_send payload slot.
+    std.debug.assert(@sizeOf(ControlRequest) <= message_maximum);
+    std.debug.assert(@sizeOf(ControlReply) <= message_maximum);
+    std.debug.assert(@sizeOf(OpenReply) <= message_maximum);
+    std.debug.assert(@sizeOf(InterruptReport) <= 64);
+}

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

@@ -17,6 +17,52 @@ const std = @import("std");
 const runtime = @import("runtime");
 const protocol = runtime.device_manager_protocol;
 const device = runtime.device;
+const usb_ids = @import("usb-ids");
+const usb_abi = @import("usb-abi");
+const transfer = @import("usb-transfer-protocol");
+const library = @import("usb-xhci-library.zig");
+
+/// The controller engine (reset, rings, transfers), stood up in `initialise`.
+var controller: ?library.Controller = null;
+
+/// This driver's service endpoint (registered as `.usb_bus`), where class-driver
+/// requests, signals, and the interrupt-poll timer all arrive.
+var service_endpoint: runtime.ipc.Handle = 0;
+
+/// How often the driver drains the event ring for interrupt reports (~125 Hz),
+/// re-armed each tick. Frequent enough for responsive input.
+const poll_interval_ms: u64 = 8;
+
+/// The class driver endpoints that opened each device, so interrupt reports can
+/// be pushed back to them. Keyed by the device token (the interface's device id).
+const Open = struct {
+    used: bool = false,
+    device_token: u64 = 0,
+    report_endpoint: usize = 0,
+};
+var opens = [_]Open{.{}} ** 16;
+
+fn recordOpen(device_token: u64, report_endpoint: usize) void {
+    for (&opens) |*open| {
+        if (open.used and open.device_token == device_token) {
+            open.report_endpoint = report_endpoint;
+            return;
+        }
+    }
+    for (&opens) |*open| {
+        if (!open.used) {
+            open.* = .{ .used = true, .device_token = device_token, .report_endpoint = report_endpoint };
+            return;
+        }
+    }
+}
+
+fn reportEndpointFor(device_token: u64) ?usize {
+    for (&opens) |*open| {
+        if (open.used and open.device_token == device_token) return open.report_endpoint;
+    }
+    return null;
+}
 
 /// Format one whole log line and emit it in a single `debug_write`, so
 /// concurrent instances (one per controller) can never interleave mid-line.
@@ -31,7 +77,7 @@ var controller_id: u64 = protocol.no_device;
 /// manager. Any failure returns false: the process exits cleanly, which the
 /// manager reads as "meant to stop" — a missing assignment is not a crash loop.
 fn initialise(endpoint: runtime.ipc.Handle) bool {
-    _ = endpoint;
+    service_endpoint = endpoint;
     if (!device.claim(controller_id)) {
         writeLine("/system/drivers/usb-xhci-bus: unable to claim controller device {d}\n", .{controller_id});
         return false;
@@ -72,6 +118,26 @@ fn initialise(endpoint: runtime.ipc.Handle) bool {
         return false;
     };
 
+    // Bring the controller up: reset it, stand up the command and event rings,
+    // and start it running (the hardware half lives in usb-xhci-library.zig).
+    controller = library.Controller.init(register_base) orelse {
+        _ = runtime.system.write("/system/drivers/usb-xhci-bus: controller reset/bring-up failed\n");
+        return false;
+    };
+    writeLine("/system/drivers/usb-xhci-bus: controller running ({d} slots, {d}-byte contexts)\n", .{
+        controller.?.max_slots,
+        controller.?.context_size,
+    });
+    // The proof of life: a No-Op command round-trips the command ring, the event
+    // ring, the doorbell, and the cycle-bit bookkeeping. If this completes, the
+    // engine is sound; transfers build on exactly this machinery.
+    if (controller.?.noOpCommand()) {
+        _ = runtime.system.write("/system/drivers/usb-xhci-bus: command ring running (no-op ok)\n");
+    } else {
+        _ = runtime.system.write("/system/drivers/usb-xhci-bus: no-op command did not complete\n");
+        return false;
+    }
+
     // The handshake: role, protocol version, assignment — inside the manager's
     // deadline (the lookup retries cover the manager still registering).
     var manager: ?runtime.ipc.Handle = null;
@@ -97,17 +163,15 @@ fn initialise(endpoint: runtime.ipc.Handle) bool {
     _ = runtime.system.write("/system/drivers/usb-xhci-bus: hello acknowledged\n");
 
     scanPorts(h);
+
+    // Arm the poll timer that drains interrupt reports from the event ring. It is
+    // re-armed on each tick in onNotification; class drivers subscribe later.
+    _ = runtime.system.timerOnce(service_endpoint, poll_interval_ms);
     return true;
 }
 
 var register_base: usize = 0;
 
-/// One 32-bit volatile register read at `offset` from the mapped window.
-fn readRegister(offset: usize) u32 {
-    const register: *volatile u32 = @ptrFromInt(register_base + offset);
-    return register.*;
-}
-
 /// The xHCI default Protocol Speed IDs (the PORTSC port-speed field, bits 13:10)
 /// decoded to human names — the boot-log breadcrumb for what actually enumerated on
 /// a port, the USB analog of the pci-bus class-code line. A controller may redefine
@@ -124,50 +188,217 @@ fn speedName(speed: u32) []const u8 {
     };
 }
 
-/// The root-hub port scan: read the capability registers for the port count
-/// and the operational-register offset, then one PORTSC per port. The connect
-/// bit (CCS) and the speed field reflect hardware state directly — no
-/// controller reset or run needed to *see* the devices; driving them needs the
-/// rings (the USB track).
+/// The root-hub scan and enumeration: for each connected port, bring the device
+/// up (reset → enable slot → address), read its descriptors, and register +
+/// report one child per interface — carrying the interface's (class, subclass,
+/// protocol) triple as identity, which is what the device manager matches a
+/// class driver against.
 fn scanPorts(manager: runtime.ipc.Handle) void {
-    // Capability registers: CAPLENGTH is byte 0 of the first dword; HCSPARAMS1
-    // carries MaxPorts in bits 31:24.
-    const capability_length = readRegister(0) & 0xFF;
-    const structural = readRegister(0x04);
-    const maximum_ports: u32 = structural >> 24;
-    writeLine("/system/drivers/usb-xhci-bus: {d} root-hub ports\n", .{maximum_ports});
+    const engine = if (controller) |*c| c else {
+        _ = runtime.system.write("/system/drivers/usb-xhci-bus: controller not initialised\n");
+        return;
+    };
+    writeLine("/system/drivers/usb-xhci-bus: {d} root-hub ports\n", .{engine.max_ports});
 
-    // PORTSC registers: operational base + 0x400 + 0x10 per port (1-based).
     var port: u32 = 1;
     var connected: u32 = 0;
-    while (port <= maximum_ports) : (port += 1) {
-        const port_status = readRegister(capability_length + 0x400 + 0x10 * (port - 1));
+    while (port <= engine.max_ports) : (port += 1) {
+        const port_status = engine.portStatus(port);
         if (port_status & 1 == 0) continue; // CCS: nothing connected
         connected += 1;
         const speed = (port_status >> 10) & 0xF; // the PORTSC port-speed class
         writeLine("/system/drivers/usb-xhci-bus: port {d} connected — {s} (speed class {d})\n", .{ port, speedName(speed), speed });
 
-        const report = protocol.ChildAdded{
-            .parent = controller_id,
-            .bus_address = port,
-            .identity = speed,
-        };
-        var reply: [protocol.message_maximum]u8 = undefined;
-        _ = runtime.ipc.call(manager, std.mem.asBytes(&report), &reply) catch {
-            writeLine("/system/drivers/usb-xhci-bus: child report for port {d} failed\n", .{port});
+        const usb_device = engine.setupDevice(port, speed) orelse {
+            writeLine("/system/drivers/usb-xhci-bus: port {d} device setup failed\n", .{port});
             continue;
         };
+        if (!engine.enumerate(usb_device)) {
+            writeLine("/system/drivers/usb-xhci-bus: port {d} enumeration failed\n", .{port});
+            continue;
+        }
+        writeLine("/system/drivers/usb-xhci-bus: port {d} device vendor 0x{x:0>4} product 0x{x:0>4}, {d} interface(s)\n", .{
+            port,
+            usb_device.device_descriptor.vendor_id,
+            usb_device.device_descriptor.product_id,
+            usb_device.interface_count,
+        });
+
+        for (usb_device.interfaces[0..usb_device.interface_count]) |*interface| {
+            // Record the id each interface was registered as, so a class driver
+            // opening the interface (by that id) resolves to it.
+            if (reportInterface(manager, port, interface.*)) |registered| {
+                interface.registered_device_id = registered;
+            }
+        }
     }
     if (connected == 0) _ = runtime.system.write("/system/drivers/usb-xhci-bus: no devices connected\n");
 }
 
-/// No bus protocol to serve yet — transfer requests arrive with the USB track.
+/// Register one interface as a resource-less child of the controller and report
+/// it to the device manager. The identity is the packed USB class triple, so the
+/// manager can match a class driver (HID keyboard, mouse, mass storage); the
+/// registered device id becomes that driver's argv[1] assignment. Returns the
+/// registered device id, or null if registration or the report failed.
+fn reportInterface(manager: runtime.ipc.Handle, port: u32, interface: library.InterfaceInfo) ?u64 {
+    const identity = usb_ids.packTriple(interface.class, interface.subclass, interface.protocol);
+
+    // A USB device is reached through its controller, not by MMIO, so the child
+    // carries no resources; register() allows that. Its bus-local identity — the
+    // (port, interface) address, written as a short "P<port>I<interface>" tag in
+    // the hid field — makes each interface a distinct kernel node (the register
+    // dedup keys on class/pci_class/hid/resources, all otherwise identical here)
+    // and keeps re-registration idempotent across a bus restart: the same port
+    // and interface always map back to the same device id.
+    var descriptor = std.mem.zeroes(device.DeviceDescriptor);
+    descriptor.class = @intFromEnum(device.DeviceClass.usb_device);
+    descriptor.pci_class = device.no_pci_class;
+    descriptor.resource_count = 0;
+    var hid_buffer: [8]u8 = undefined;
+    const hid_text = std.fmt.bufPrint(&hid_buffer, "P{d}I{d}", .{ port, interface.number }) catch "";
+    descriptor.hid_len = hid_text.len;
+    @memcpy(descriptor.hid[0..hid_text.len], hid_text);
+    const registered = device.register(controller_id, &descriptor) orelse {
+        writeLine("/system/drivers/usb-xhci-bus: register refused for port {d} interface {d}\n", .{ port, interface.number });
+        return null;
+    };
+
+    const report = protocol.ChildAdded{
+        .parent = controller_id,
+        .bus_address = (@as(u64, port) << 8) | interface.number,
+        .identity = identity,
+        .device_id = registered,
+    };
+    var reply: [protocol.message_maximum]u8 = undefined;
+    _ = runtime.ipc.call(manager, std.mem.asBytes(&report), &reply) catch {
+        writeLine("/system/drivers/usb-xhci-bus: child report for port {d} interface {d} failed\n", .{ port, interface.number });
+        return null;
+    };
+    writeLine("/system/drivers/usb-xhci-bus: port {d} interface {d} class {d}/{d}/{d} registered as device {d}\n", .{
+        port,
+        interface.number,
+        interface.class,
+        interface.subclass,
+        interface.protocol,
+        registered,
+    });
+    return registered;
+}
+
+/// Serve the USB transfer protocol: a class driver opens its device, then issues
+/// control / interrupt-subscribe / bulk requests against it.
 fn onMessage(message: []const u8, reply: []u8, sender: u32, capability: ?runtime.ipc.Handle) usize {
-    _ = message;
-    _ = reply;
     _ = sender;
-    _ = capability;
-    return 0;
+    if (message.len < 4) return 0;
+    const operation = std.mem.readInt(u32, message[0..4], .little);
+    return switch (operation) {
+        @intFromEnum(transfer.Operation.open) => handleOpen(message, reply, capability),
+        @intFromEnum(transfer.Operation.control) => handleControl(message, reply),
+        @intFromEnum(transfer.Operation.interrupt_subscribe) => handleSubscribe(message, reply),
+        @intFromEnum(transfer.Operation.bulk) => handleBulk(message, reply),
+        else => 0,
+    };
+}
+
+fn writeReply(reply: []u8, value: anytype) usize {
+    const bytes = std.mem.asBytes(&value);
+    @memcpy(reply[0..bytes.len], bytes);
+    return bytes.len;
+}
+
+/// open: resolve the assigned device id to an interface, remember the caller's
+/// endpoint (for interrupt reports), and answer with a device token + the
+/// interface's endpoints so the class driver need not re-read the config.
+fn handleOpen(message: []const u8, reply: []u8, capability: ?runtime.ipc.Handle) usize {
+    if (message.len < @sizeOf(transfer.OpenRequest)) return writeReply(reply, transfer.OpenReply{ .status = -1, .endpoint_count = 0, .device_token = 0, .interface_class = 0, .interface_subclass = 0, .interface_protocol = 0, .interface_number = 0 });
+    const request = std.mem.bytesToValue(transfer.OpenRequest, message[0..@sizeOf(transfer.OpenRequest)]);
+    const engine = if (controller) |*c| c else return writeReply(reply, transfer.OpenReply{ .status = -1, .endpoint_count = 0, .device_token = 0, .interface_class = 0, .interface_subclass = 0, .interface_protocol = 0, .interface_number = 0 });
+    const found = engine.findInterface(request.device_id) orelse return writeReply(reply, transfer.OpenReply{ .status = -1, .endpoint_count = 0, .device_token = 0, .interface_class = 0, .interface_subclass = 0, .interface_protocol = 0, .interface_number = 0 });
+
+    if (capability) |endpoint| recordOpen(request.device_id, endpoint);
+
+    var open_reply = transfer.OpenReply{
+        .status = 0,
+        .endpoint_count = found.interface.endpoint_count,
+        .device_token = request.device_id,
+        .interface_class = found.interface.class,
+        .interface_subclass = found.interface.subclass,
+        .interface_protocol = found.interface.protocol,
+        .interface_number = found.interface.number,
+    };
+    const count = @min(found.interface.endpoint_count, transfer.max_reported_endpoints);
+    for (found.interface.endpoints[0..count], 0..) |endpoint, index| {
+        open_reply.endpoints[index] = .{
+            .address = endpoint.address,
+            .transfer_type = endpoint.transfer_type,
+            .max_packet_size = endpoint.max_packet_size,
+            .interval = endpoint.interval,
+        };
+    }
+    return writeReply(reply, open_reply);
+}
+
+/// control: one EP0 control transfer, small data inline both ways.
+fn handleControl(message: []const u8, reply: []u8) usize {
+    if (message.len < @sizeOf(transfer.ControlRequest)) return writeReply(reply, transfer.ControlReply{ .status = -1, .actual_length = 0 });
+    const request = std.mem.bytesToValue(transfer.ControlRequest, message[0..@sizeOf(transfer.ControlRequest)]);
+    const engine = if (controller) |*c| c else return writeReply(reply, transfer.ControlReply{ .status = -1, .actual_length = 0 });
+    const found = engine.findInterface(request.device_token) orelse return writeReply(reply, transfer.ControlReply{ .status = -1, .actual_length = 0 });
+
+    const setup = std.mem.bytesToValue(usb_abi.Request, &request.setup);
+    const direction_in = request.direction_in != 0;
+    const data_length = @min(request.data_length, transfer.max_inline_data);
+    var data: [transfer.max_inline_data]u8 = undefined;
+    if (!direction_in) @memcpy(data[0..data_length], request.data[0..data_length]);
+
+    const ok = engine.controlTransfer(found.device, setup, data[0..data_length], direction_in);
+    var control_reply = transfer.ControlReply{ .status = if (ok) 0 else -1, .actual_length = if (ok) data_length else 0 };
+    if (ok and direction_in) @memcpy(control_reply.data[0..data_length], data[0..data_length]);
+    return writeReply(reply, control_reply);
+}
+
+/// interrupt_subscribe: arm periodic IN polling; reports flow back asynchronously.
+fn handleSubscribe(message: []const u8, reply: []u8) usize {
+    if (message.len < @sizeOf(transfer.InterruptSubscribeRequest)) return writeReply(reply, transfer.InterruptSubscribeReply{ .status = -1 });
+    const request = std.mem.bytesToValue(transfer.InterruptSubscribeRequest, message[0..@sizeOf(transfer.InterruptSubscribeRequest)]);
+    const engine = if (controller) |*c| c else return writeReply(reply, transfer.InterruptSubscribeReply{ .status = -1 });
+    const found = engine.findInterface(request.device_token) orelse return writeReply(reply, transfer.InterruptSubscribeReply{ .status = -1 });
+    const endpoint = library.Controller.endpointForAddress(found.interface, request.endpoint_address) orelse return writeReply(reply, transfer.InterruptSubscribeReply{ .status = -1 });
+    const report_endpoint = reportEndpointFor(request.device_token) orelse return writeReply(reply, transfer.InterruptSubscribeReply{ .status = -1 });
+    const ok = engine.subscribeInterrupt(found.device, endpoint, request.device_token, report_endpoint);
+    return writeReply(reply, transfer.InterruptSubscribeReply{ .status = if (ok) 0 else -1 });
+}
+
+/// bulk: one bulk transfer to/from the class driver's own DMA buffer (by physical
+/// address), so sector-sized data never crosses IPC.
+fn handleBulk(message: []const u8, reply: []u8) usize {
+    if (message.len < @sizeOf(transfer.BulkRequest)) return writeReply(reply, transfer.BulkReply{ .status = -1, .actual_length = 0 });
+    const request = std.mem.bytesToValue(transfer.BulkRequest, message[0..@sizeOf(transfer.BulkRequest)]);
+    const engine = if (controller) |*c| c else return writeReply(reply, transfer.BulkReply{ .status = -1, .actual_length = 0 });
+    const found = engine.findInterface(request.device_token) orelse return writeReply(reply, transfer.BulkReply{ .status = -1, .actual_length = 0 });
+    const endpoint = library.Controller.endpointForAddress(found.interface, request.endpoint_address) orelse return writeReply(reply, transfer.BulkReply{ .status = -1, .actual_length = 0 });
+    const transferred = engine.bulkTransfer(found.device, endpoint, request.physical_address, request.length);
+    return writeReply(reply, transfer.BulkReply{ .status = if (transferred != null) 0 else -1, .actual_length = transferred orelse 0 });
+}
+
+/// The poll timer landed: drain any interrupt reports off the event ring and push
+/// each to the class driver that subscribed, then re-arm the timer.
+fn onNotification(badge: u64) void {
+    if (badge & runtime.ipc.notify_timer_bit == 0) return;
+    if (controller) |*engine| {
+        engine.pump();
+        while (engine.takeReport()) |report| {
+            var message = transfer.InterruptReport{
+                .device_token = report.device_token,
+                .endpoint_address = report.endpoint_address,
+                .length = @intCast(@min(report.length, transfer.max_report_data)),
+            };
+            const n = @min(report.length, transfer.max_report_data);
+            @memcpy(message.data[0..n], report.data[0..n]);
+            _ = runtime.ipc.send(report.report_endpoint, std.mem.asBytes(&message));
+        }
+    }
+    _ = runtime.system.timerOnce(service_endpoint, poll_interval_ms);
 }
 
 pub fn main(init: runtime.process.Init) void {
@@ -179,9 +410,11 @@ pub fn main(init: runtime.process.Init) void {
         writeLine("/system/drivers/usb-xhci-bus: malformed controller device id '{s}'\n", .{argument});
         return;
     };
-    runtime.service.run(protocol.message_maximum, .{
+    runtime.service.run(transfer.message_maximum, .{
+        .service = .usb_bus,
         .init = initialise,
         .on_message = onMessage,
+        .on_notification = onNotification,
     });
 }