reorg: extract library/device/pci — the claimed-function view

New pci logic module (library/device/pci/pci.zig): a device driver's view of
the one PCI function it has claimed — Function.map (config space = resource 0),
vendorId/deviceId/command/status, enableMemoryAndBusMaster, mapBar (BAR decode
+ resource correlation + mmio_map, cached), and a capabilities() iterator. The
generic PCI mechanics every leaf PCI driver used to re-derive inline.

The config-space layout it needs — header offsets, the command MEM|bus-master
bits, the status capabilities-list bit, the capability-pointer mask, and the
BAR bit fields — is named in the pci-class data module (a "Configuration-space
layout" section), so the bus enumerator can share the same constants later.

virtio-gpu is the first consumer: its inline mapBar + walkCapabilities + config
header reads are gone, replaced by pci.Function; only the virtio-specific
cfg_type dispatch (and the virtio common-config cfgRead/cfgWrite, which are NOT
PCI config space) stay in the driver. The generic display driver will use the
same module. pci-bus's enumerator (arbitrary-function probing) is untouched.

zig build + test green; virtio-gpu, display-native, display-reattach, pci-scan pass.

library/device/pci/pci-class.zig

@@ -41,6 +41,35 @@ pub const ClassCode = struct {
     }
 };
 
+// --- Configuration-space layout ---------------------------------------------------------
+// The offsets and bit layouts of the PCI configuration header (PCI spec; see
+// https://wiki.osdev.org/PCI). Pure data — named here so both a device driver's view of
+// its own claimed function (library/device/pci/pci.zig) and the bus enumerator name the
+// same bytes instead of scattering bare 0x04/0x34/0xFFFF_FFF0 magic across the tree.
+
+/// Header field offsets (byte offsets into the 256-byte configuration space).
+pub const config_vendor_id: usize = 0x00;
+pub const config_device_id: usize = 0x02;
+pub const config_command: usize = 0x04;
+pub const config_status: usize = 0x06;
+pub const config_capabilities_pointer: usize = 0x34;
+pub const config_bar0: usize = 0x10; // BAR0; BAR n is at config_bar0 + n*4
+
+/// Command register: Memory-Space enable (bit 1) | Bus-Master enable (bit 2).
+pub const command_memory_and_bus_master: u16 = 0x06;
+/// Status register bit 4: a capability list is present at config_capabilities_pointer.
+pub const status_capabilities_list: u16 = 0x10;
+/// Capability pointers are dword-aligned; the low two bits are reserved.
+pub const capability_pointer_mask: u8 = 0xFC;
+
+/// BAR bit layout: bit 0 selects I/O (1) vs memory (0) space; for a memory BAR, bits 2:1
+/// give the type (00 = 32-bit, 10 = 64-bit spanning the next BAR), and the base address is
+/// the dword with the low 4 flag bits masked off.
+pub const bar_io_space: u32 = 0x1;
+pub const bar_type_mask: u32 = 0x6;
+pub const bar_type_64bit: u32 = 0x4;
+pub const bar_memory_base_mask: u32 = 0xFFFF_FFF0;
+
 /// Base class (config byte 0x0B). Non-exhaustive: an unlisted code is a real but
 /// unnamed class, decoded as "Unknown" rather than rejected.
 pub const BaseClass = enum(u8) {

library/device/pci/pci.zig

@@ -0,0 +1,109 @@
+//! library/device/pci/pci.zig — a device driver's view of the ONE PCI function it has
+//! claimed. Config space is mapped as resource 0; this gives header-field accessors, BAR
+//! decode + map, and a capability-list iterator, so a driver never re-derives the
+//! config-space layout by hand.
+//!
+//! This is the *device-owned* view: read my own function's live config, map my own BARs.
+//! The bus enumerator's view — probing arbitrary, not-yet-claimed functions and sizing
+//! their BARs — is a different mechanism and lives in the pci-bus driver. The pure
+//! config-space layout both need (offsets, BAR bit fields) is named once in the `pci-class`
+//! data module; this logic module adds the parts that need `mmio` + `runtime.device`.
+
+const std = @import("std");
+const runtime = @import("runtime");
+const mmio = @import("mmio");
+const pci_class = @import("pci-class");
+const device = runtime.device;
+
+/// A claimed PCI function whose configuration space is mapped (resource 0). `descriptor`
+/// must outlive the Function — the driver's `device.enumerate` buffer does, for the whole
+/// bring-up. Header reads and the capability walk hit live config space; `mapBar` caches.
+pub const Function = struct {
+    device_id: u64,
+    descriptor: *const device.DeviceDescriptor,
+    config: usize, // virtual base of mapped resource 0
+    bar_virtual: [6]usize = .{ 0, 0, 0, 0, 0, 0 }, // per-BAR mmio_map cache
+
+    /// Map config space (resource 0) of the already-claimed `device_id`. null if the map
+    /// fails (not claimed, or no config resource).
+    pub fn map(device_id: u64, descriptor: *const device.DeviceDescriptor) ?Function {
+        const base = device.mmioMap(device_id, 0) orelse return null;
+        return .{ .device_id = device_id, .descriptor = descriptor, .config = base };
+    }
+
+    pub fn vendorId(self: *const Function) u16 {
+        return mmio.read(u16, self.config + pci_class.config_vendor_id);
+    }
+    pub fn deviceId(self: *const Function) u16 {
+        return mmio.read(u16, self.config + pci_class.config_device_id);
+    }
+    pub fn command(self: *const Function) u16 {
+        return mmio.read(u16, self.config + pci_class.config_command);
+    }
+    pub fn status(self: *const Function) u16 {
+        return mmio.read(u16, self.config + pci_class.config_status);
+    }
+
+    /// Set Memory-Space + Bus-Master enable in the command register. Firmware often leaves
+    /// a secondary display's decode off; a bus-mastering device must enable both.
+    pub fn enableMemoryAndBusMaster(self: *const Function) void {
+        const at = self.config + pci_class.config_command;
+        mmio.write(u16, at, mmio.read(u16, at) | pci_class.command_memory_and_bus_master);
+    }
+
+    /// Decode BAR `bar` (0..5) and map it: read the BAR register, reject I/O-space BARs,
+    /// combine the high dword for a 64-bit BAR, mask the base, then correlate that physical
+    /// base with one of the descriptor's memory resources and `mmio_map` it — a BAR names a
+    /// *number*, while `mmio_map` takes a *resource index*, and gaps/config-space shift the
+    /// numbering. Cached per BAR. null if the BAR is I/O-space or is not a mapped resource.
+    pub fn mapBar(self: *Function, bar: u8) ?usize {
+        if (bar >= 6) return null;
+        if (self.bar_virtual[bar] != 0) return self.bar_virtual[bar];
+
+        const low = mmio.read(u32, self.config + pci_class.config_bar0 + @as(usize, bar) * 4);
+        if (low & pci_class.bar_io_space != 0) return null; // an I/O-space BAR
+        var base: u64 = low & pci_class.bar_memory_base_mask;
+        if ((low & pci_class.bar_type_mask) == pci_class.bar_type_64bit) { // 64-bit: high half is the next dword
+            const high = mmio.read(u32, self.config + pci_class.config_bar0 + (@as(usize, bar) + 1) * 4);
+            base |= @as(u64, high) << 32;
+        }
+
+        for (self.descriptor.resources[0..@intCast(self.descriptor.resource_count)], 0..) |resource, index| {
+            if (resource.kind == @intFromEnum(device.ResourceKind.memory) and resource.start == base) {
+                const v = device.mmioMap(self.device_id, index) orelse return null;
+                self.bar_virtual[bar] = v;
+                return v;
+            }
+        }
+        return null;
+    }
+
+    /// Iterate the capability list. Empty when the function advertises none.
+    pub fn capabilities(self: *const Function) CapabilityIterator {
+        const present = self.status() & pci_class.status_capabilities_list != 0;
+        const first = if (present)
+            mmio.read(u8, self.config + pci_class.config_capabilities_pointer) & pci_class.capability_pointer_mask
+        else
+            0;
+        return .{ .config = self.config, .cursor = first };
+    }
+};
+
+/// One capability header. `offset` is the ABSOLUTE virtual address of the header, so the
+/// caller reads its body with `mmio.read(T, cap.offset + n)`.
+pub const Capability = struct { id: u8, offset: usize };
+
+pub const CapabilityIterator = struct {
+    config: usize,
+    cursor: u8,
+    guard: u32 = 0, // bounds a malformed/looping chain (48 = the 256-byte space in dwords)
+
+    pub fn next(self: *CapabilityIterator) ?Capability {
+        if (self.cursor == 0 or self.guard >= 48) return null;
+        self.guard += 1;
+        const at = self.config + self.cursor;
+        const id = mmio.read(u8, at + 0);
+        self.cursor = mmio.read(u8, at + 1) & pci_class.capability_pointer_mask;
+        return .{ .id = id, .offset = at };
+    }
+};