pci: full driver-side library (MSI/MSI-X, power, FLR, extended caps); xhci goes interrupt-driven

library/device/pci is now the complete generic floor a leaf PCI driver
needs, instead of just what virtio-gpu used:

- pci-class: capability IDs, MSI/MSI-X/power-management/PCI-Express
  register layouts, extended-capability header decode (host-tested),
  per-bit command constants, remaining header offsets.
- pci.Function: header accessors, disableBusMaster + interrupt-disable
  helpers, findCapability, programMsi/disableMsi, MsiX vector-table
  struct, ensurePowerStateD0, functionLevelReset (BAR save/restore),
  extended-capability iterator.

Proven by the new pci-caps QEMU case: a pci-cap-test fixture claims an
extra e1000e (PM+MSI+PCIe+MSI-X, no danos driver) and readback-verifies
every surface, including the first driver-side use of msi_bind.

usb-xhci-bus converts from 8 ms event-ring polling to message-signalled
interrupts: plain MSI where offered (real Intel xHC), MSI-X entry 0
otherwise (qemu-xhci has no MSI capability), byte-identical polling as
fallback. The timer survives as a 250 ms port-reconcile/lost-edge tick —
real-hardware USB2 hub debounce still needs it. MSI setup runs BEFORE
controller bring-up: QEMU's xhci only registers the MSI-X vector as used
when IMAN.IE is written while MSI-X is already enabled; interrupts are
silently dropped otherwise (real hardware does not care about the order).

101/101 QEMU cases green; real-hardware smoke passed (mouse works,
boot 2026-07-23T174805Z, plain-MSI branch, vector 33).

build.zig

@@ -531,15 +531,18 @@ pub fn build(b: *std.Build) void {
         },
     });
     // A device driver's view of its claimed PCI function: config-space header fields, BAR
-    // decode + map, and the capability walk (library/device/pci/pci.zig). The generic PCI
+    // decode + map, capability walks (legacy + extended), MSI/MSI-X programming, power
+    // state, and function-level reset (library/device/pci/pci.zig). The generic PCI
     // mechanics every leaf PCI driver used to re-derive inline. Imports the driver (device
-    // access) client + mmio + the pci-class data module (config-space layout constants).
+    // access) client + mmio + the pci-class data module (config-space layout constants) +
+    // time (the D0 and FLR settle delays).
     const pci_module = b.addModule("pci", .{
         .root_source_file = b.path("library/device/pci/pci.zig"),
         .imports = &.{
             .{ .name = "driver", .module = driver_module },
             .{ .name = "mmio", .module = mmio_module },
             .{ .name = "pci-class", .module = pci_class_module },
+            .{ .name = "time", .module = time_module },
         },
     });
 
@@ -677,6 +680,8 @@ pub fn build(b: *std.Build) void {
     programModule(ps2_mouse_exe).addImport("input-protocol", input_protocol_module);
     const usb_xhci_bus_exe = addUserBinary(b, kernel_target, &default_imports, "usb-xhci-bus", "system/drivers/usb-xhci-bus/usb-xhci-bus.zig");
     programModule(usb_xhci_bus_exe).addImport("device-manager-protocol", device_manager_protocol_module);
+    // MSI setup: the claimed-function view (enable bits + MSI capability programming).
+    programModule(usb_xhci_bus_exe).addImport("pci", pci_module);
     // The xHCI bus driver builds chapter-9 requests and decodes descriptors from
     // usb-abi, and reports each interface's (class,subclass,protocol) identity via
     // usb-ids.packTriple.
@@ -727,6 +732,11 @@ pub fn build(b: *std.Build) void {
     programModule(crash_test_exe).addImport("device-manager-protocol", device_manager_protocol_module);
     const device_list_exe = addUserBinary(b, kernel_target, &default_imports, "device-list", "test/system/services/device-list/device-list.zig");
     programModule(device_list_exe).addImport("device-manager-protocol", device_manager_protocol_module);
+    // A test fixture: claims the pci-caps case's extra unclaimed NIC and exercises the
+    // driver-side PCI library surface (capabilities, MSI, MSI-X, power, FLR) against it.
+    const pci_cap_test_exe = addUserBinary(b, kernel_target, &default_imports, "pci-cap-test", "test/system/services/pci-cap-test/pci-cap-test.zig");
+    programModule(pci_cap_test_exe).addImport("pci", pci_module);
+    programModule(pci_cap_test_exe).addImport("pci-class", pci_class_module);
     // The discovery service: one swappable process per firmware
     // (docs/discovery.md), bundled under the neutral ramdisk name
     // "discovery" so the device manager never learns which firmware it is on.
@@ -811,6 +821,7 @@ pub fn build(b: *std.Build) void {
         .{ .path = "test/system/services/shared-memory-client", .binary = shared_memory_client_exe.getEmittedBin() },
         .{ .path = "test/system/services/crash-test", .binary = crash_test_exe.getEmittedBin() },
         .{ .path = "test/system/services/device-list", .binary = device_list_exe.getEmittedBin() },
+        .{ .path = "test/system/services/pci-cap-test", .binary = pci_cap_test_exe.getEmittedBin() },
         .{ .path = "test/system/services/input-source", .binary = input_source_exe.getEmittedBin() },
         .{ .path = "test/system/services/input-test", .binary = input_test_exe.getEmittedBin() },
         .{ .path = "test/system/services/args-echo", .binary = args_echo_exe.getEmittedBin() },