Discovery-migration prerequisites (M19.0)

The host bridge now carries MMIO apertures derived from the boot memory
map's gaps below 4 GiB (largest three, sort-merged; a single after-the-
last-region hole dies on OVMF's flash at the top) plus one aperture above
the described space — so a user-space device_register of PCI functions
with BAR resources can pass containment. The discovery test asserts
every PCI memory resource lies inside a bridge window and names any
escapee. device_register is idempotent on exact (parent, class, identity,
resources) match — a restarted registering bus cannot duplicate its
children; proven directly against the broker in the bus test.
ChildAdded gains device_id so a report can carry the registered kernel
id a matched driver needs as its assignment.

system/devices/acpi.zig

@@ -384,8 +384,9 @@ const PciHeader = extern struct {
 /// Discover hardware from the ACPI tables rooted at `rsdp_physical` and populate
 /// `device_tree`. `hal` provides MMIO mapping (for PCIe ECAM) and port I/O. Also parses the
 /// FADT and the AML sleep-state (`_Sx`) packages into `power_information` for the power service.
-pub fn discover(rsdp_physical: u64, device_tree: *DeviceTree, hal: Hal) !void {
+pub fn discover(rsdp_physical: u64, memory_regions: []const boot_handoff.MemoryRegion, device_tree: *DeviceTree, hal: Hal) !void {
     if (rsdp_physical == 0) return error.NoRsdp;
+    boot_memory_regions = memory_regions;
 
     // Start clean so a re-run doesn't accumulate stale state.
     power_information = .{};
@@ -551,11 +552,74 @@ fn parseMcfg(device_tree: *DeviceTree, hal: Hal, header: *const SystemDescriptor
         // ECAM window: 1 MiB of configuration space per bus.
         _ = bridge.addResource(.memory, alloc.base_address, bus_count << 20);
         _ = bridge.addResource(.bus_range, alloc.start_bus, bus_count);
+        addBridgeApertures(bridge);
 
         try enumeratePci(device_tree, bridge, hal, alloc.*);
     }
 }
 
+/// The boot memory map, stored at discover() entry for the aperture derivation
+/// below (and, in M20, for the acpi-tables node's containment windows).
+var boot_memory_regions: []const boot_handoff.MemoryRegion = &.{};
+
+/// The bridge's MMIO apertures, derived from the boot memory map's holes
+/// (docs/m19-m20-plan.md decision 2): registered PCI functions carry BAR
+/// resources, and `device_register` containment demands the bridge own windows
+/// that cover them. Everything the firmware described is "not hole"; the low
+/// aperture runs from the end of the described space below 4 GiB up to the
+/// I/O-APIC region, the high one from 4 GiB (or the end of RAM above it) to
+/// the 46-bit line. Coarse, mechanical, and AML-free — available at boot no
+/// matter what later moved to user space.
+fn addBridgeApertures(bridge: *device_model.Device) void {
+    // Below 4 GiB the described regions are sparse (RAM low, firmware flash
+    // and tables high), so the holes are the *gaps between* them — a single
+    // "after the last region" rule dies on OVMF's flash at the very top.
+    // Sort-merge the described ranges, then keep the three largest gaps
+    // (resource slots are bounded at 8 per device; ECAM + bus range + 3 + the
+    // high aperture fits). Above 4 GiB one aperture runs from the end of the
+    // described space to the 46-bit line.
+    const Range = struct { base: u64, end: u64 };
+    var below: [64]Range = undefined;
+    var below_count: usize = 0;
+    var high_end: u64 = 1 << 32;
+    for (boot_memory_regions) |region| {
+        const end = region.base + region.pages * 4096;
+        if (end > high_end) high_end = end;
+        if (region.base >= (1 << 32) or below_count == below.len) continue;
+        below[below_count] = .{ .base = region.base, .end = @min(end, 1 << 32) };
+        below_count += 1;
+    }
+    // Insertion sort by base (the map is small and this runs once at boot).
+    for (1..below_count) |i| {
+        const key = below[i];
+        var j = i;
+        while (j > 0 and below[j - 1].base > key.base) : (j -= 1) below[j] = below[j - 1];
+        below[j] = key;
+    }
+    // Walk the sorted ranges, collecting inter-region gaps of at least 1 MiB.
+    var gaps: [3]Range = .{Range{ .base = 0, .end = 0 }} ** 3;
+    var cursor: u64 = 0;
+    var index: usize = 0;
+    while (index <= below_count) : (index += 1) {
+        const gap_end = if (index == below_count) (1 << 32) else below[index].base;
+        if (gap_end > cursor and gap_end - cursor >= (1 << 20)) {
+            // Keep the three largest, replacing the smallest kept so far.
+            var smallest: usize = 0;
+            for (gaps, 0..) |gap, gi| {
+                if (gap.end - gap.base < gaps[smallest].end - gaps[smallest].base) smallest = gi;
+            }
+            if (gap_end - cursor > gaps[smallest].end - gaps[smallest].base) {
+                gaps[smallest] = .{ .base = cursor, .end = gap_end };
+            }
+        }
+        if (index < below_count and below[index].end > cursor) cursor = below[index].end;
+    }
+    for (gaps) |gap| {
+        if (gap.end > gap.base) _ = bridge.addResource(.memory, gap.base, gap.end - gap.base);
+    }
+    _ = bridge.addResource(.memory, high_end, (@as(u64, 1) << 46) - high_end);
+}
+
 /// Brute-force scan the ECAM window's bus range for present PCI functions. No
 /// bridge recursion yet: on the ECAM path the host bridge decodes every bus in
 /// the window, so scanning the declared range finds everything QEMU exposes.