RedBear-OS/local/docs/DRIVER-MANAGER-MIGRATION-PLAN.md

Red Bear OS — pci-spawner → driver-manager Migration Plan

Document status: v3.1 canonical planning authority (supersedes v3.0 with the completed P0/LDR/P2 implementation and the operator-ratified cutover: driver-manager now owns the boot path in all redbear-* configs; pcid-spawner is gated as the fallback) Generated: 2026-07-20 Toolchain: Rust nightly-2026-05-24 (edition 2024) Architecture: Microkernel OS in Rust (Redox fork) Cross-reference baseline: Linux kernel 7.1 at commit ab9de95c9 (local/reference/linux-7.1/), CachyOS (local/reference/cachyos/ — linux-cachyos 0001-cachyos-base-all.patch 6.17.9 + desktop ISO 260628) Assessment: local/docs/evidence/driver-manager/ASSESSMENT-2026-07-22.md (findings B1–G10, § 11 services integration)

v3.1 status update over v3.0 (implementation + cutover round, 2026-07-23):

The v3.0 work program is implemented and the operator has ratified the cutover: driver-manager owns the boot path in every redbear-* config; pcid-spawner is retired from configs and gated behind /etc/driver-manager.d/disabled as the operator fallback (never deleted). Future OS development is based on driver-manager.

Completed items:

• P0-1 ✅ Claim-via-channel collapse. probe() does a single PciFunctionHandle::connect_by_path(); ENOLCK → next candidate; enable_device + into_inner_fd → PCID_CLIENT_CHANNEL. claim_pci_device/open_pcid_channel deleted; SpawnedDriver holds the channel fd (claim lifetime == child lifetime).
• P0-2 ✅ Orphan patches resolved. bind-scheme + uevent-fix moved to local/patches/legacy-superseded-2026-07-22/ with a SUPERSEDED.md audit entry; aer-scheme retained as the P2-1 producer blueprint.
• P0-3 ✅ Advisory theater stripped. modern_tech.rs and exec.rs deleted; the useful parts correctly wired as spawn env hints (REDBEAR_DRIVER_IOMMU_GROUP / REDBEAR_DRIVER_NUMA_NODE / REDBEAR_DRIVER_MSIX_VECTORS); redox-driver-core C/P-state coordinators removed (no consumers).
• LDR-2 ✅ Spawned-mode pci_register_driver. linux-kpi honors PCID_CLIENT_CHANNEL (probe only the granted device; never enumerate). Standalone mode retained for CLI tools.
• LDR-3 ✅ iwlwifi onboarded. --daemon mode (honors PCID_DEVICE_PATH, full-init, resident) + 70-wifi.toml staged; --import-linux-ids wires linux_loader into production (Linux id_table → [[driver.match]] TOML).
• LDR-4 ✅ Verified convergent. redox-drm already honors the pcid handoff; no changes needed.
• LDR-5 ✅ linux-kpi API completion. Real MSI/MSI-X via pcid_interface (vector allocation + table programming; linux-kpi owns the channel in linux-kpi daemons), pci_request_regions, pcie_capability_read/write_*, pci_set_power_state / pci_save_state / pci_restore_state. C header synced.
• P2-2 ✅ Operator surface. Scheme endpoints bind, unbind, new_id, remove_id, driver_override, rescan; DeviceManager gained Tier-1 driver_override precedence + bind_device.
• P2-3 ✅ Success trigger. A successful bind immediately retries deferred probes (Linux driver_deferred_probe_trigger), in run_enumeration and the scheme bind handler.
• Cutover ✅. init learned ConditionPathExists (with ! negation — the C0 dormancy was a parser-rejection accident); driver-manager services run by default in init.d/init.initfs.d and all redbear-* configs; pcid-spawner services gated to /etc/driver-manager.d/disabled. make lint-config clean.
• Services integration ✅ (assessment § 11). driver-params bridge verified live; udev-shim driver-binding view noted as a P3 gap; D-Bus correctly absent (bridge-on-demand pattern documented).

Open items (unchanged): P0-4 QEMU runtime gate (build running; first boot with driver-manager owning the path), P2-1 pcid producers (AER registers, pciehp slot events), P3 policy/hygiene (quirk phases, AER recovery actions, per-vendor firmware packaging, udev-shim driver-binding view, dep-crate warnings, stale-tree cleanup).

v3.0 status update over v2.2 (the assessment round):

v3.0 records the first runtime-grade audit of the migration. Three parallel codebase audits (pcid layer, linux-kpi binding model, Linux 7.1 PCI core) plus a full first-hand review of every driver-manager source file found that the v1.3–v2.2 "Done" claims were compile-grade, and that three of them are broken at runtime. The full evidence register (B1–G10) is in the assessment doc; the corrections and the resulting work program follow.

Corrections to earlier rounds (stale claims removed):

1. The <addr>/bind claim endpoint does not exist. Earlier rounds marked "D1 C4 BAR request ✅ Done — claim_pci_device via <addr>/bind" (and the § diagram "claims devices via <addr>/bind"). pcid exposes only channel and config per device; the patches that would add /bind (local/patches/base/P3-pcid-bind-scheme.patch, P3-pcid-aer-scheme.patch, P3-pcid-uevent-format-fix.patch) are orphaned — never committed to submodule/base, and the cookbook does not apply patches for path = fork recipes. At runtime, every probe would fail ENOENT and defer-retry forever, binding nothing. Resolution: P0-1 below — the separate claim endpoint is dropped in favor of pcid's existing channel exclusivity (ENOLCK), the model pcid-spawner has always used. The orphaned patches are resolved per the orphan-patch decision tree (bind-scheme: SUPERSEDED by the channel model; aer-scheme: kept as the P2-1 producer blueprint).
2. The pciehp and AER listeners are inert. v1.9/v2.0 marked them done; in fact nothing in the tree produces /scheme/pci/pciehp or /scheme/acpi/aer, and both readers fail-soft on missing files. Device add/remove is covered by the 250 ms hotplug enumeration poll (which works). The listeners are restated as parsers ready, producers pending (P2-1).
3. exclusive_with is not "the CachyOS pattern." CachyOS solves two-drivers-one-device by probe-time deferral (its 6.17.9 patch makes ahci return -ENODEV on remapped-NVMe controllers so intel-nvme-remap binds instead) and by userspace modprobe.d blacklists. Match-time exclusive_with is a third, complementary mechanism — a superset, retained. The plan text is corrected.
4. modern_tech "wired" was advisory theater. Bind/unbind emit hardcoded C/P-state constants into JSON files nothing reads, and the MSI-X proposal is computed at spawn and discarded. P0-3 strips it to the honest core.
5. "8 QEMU-functional test scripts" was aspirational. The scripts exist; no driver-manager QEMU boot has ever been run. Runtime validation is now a hard gate (P0-4) and the D5 audit grades capabilities runtime as well as compile.

v3.0 work program (the tracks):

Track	Items	Goal
P0 — Correctness blockers	P0-1 claim-via-channel collapse · P0-2 restate pciehp/AER + resolve orphaned patches · P0-3 strip modern_tech + delete exec.rs · P0-4 runtime validation gate (QEMU)	Make the existing D-phase true at runtime
LDR — Linux-Driver-Reuse	LDR-1 unified claim model · LDR-2 spawned-mode pci_register_driver · LDR-3 iwlwifi onboarding · LDR-4 amdgpu path convergence · LDR-5 linux-kpi API completion	The critical goal: reuse Linux drivers
P2 — Operator & event surface	P2-1 pcid producers (AER registers, pciehp slot events) · P2-2 scheme write endpoints (bind/unbind/new_id/remove_id/driver_override/rescan) · P2-3 trigger-based deferred retry	Linux-grade operability
P3 — Policy & hygiene	quirk pass phases (early/runtime) · AER recovery actions (pci_ers_result mapping) · per-vendor firmware packaging · dep-crate warnings + stale-tree cleanup	Long-term evolution

P0 — Correctness blockers (preconditions for everything else):

• P0-1 Collapse claim into the channel open. Replace claim_pci_device() + open_pcid_channel() with a single PciFunctionHandle::connect_by_path(): ENOLCK → "already claimed → next candidate" (mirrors Linux's probe-time -EBUSY/-ENODEV handoff), then enable_device() and into_inner_fd() → PCID_CLIENT_CHANNEL. Claim lifetime == channel fd lifetime == child lifetime — exactly correct, pcid-spawner-proven, zero pcid fork changes. The exclusive_with check moves after the channel open (claim-then-check, as in v2.1–v2.2, with close-on-defer).
• P0-2 Restate pciehp/AER; resolve orphaned patches. Plan text corrected above. P3-pcid-bind-scheme.patch → SUPERSEDED (channel model); P3-pcid-aer-scheme.patch → retained as the P2-1 producer blueprint; P3-pcid-uevent-format-fix.patch → split: AER parts with the producer work, uevent stub dropped (polling is the accepted v1 model). Move superseded files per the orphan-patch decision tree.
• P0-3 Strip modern_tech to the honest core; delete exec.rs. Remove the constant C/P-state JSON writers (no consumers); pass the MSI-X proposal to the child as REDBEAR_DRIVER_MSIX_VECTORS=<n> (same env-hint channel as the quirk hints) or drop it until a consumer exists. Delete exec.rs (dead spawn_driver with #[allow(dead_code)]).
• P0-4 Runtime validation gate. Boot redbear-mini in QEMU with driver-manager enabled in place of pcid-spawner (C-phase dry run): e1000 binds through the real claim path, /bound reports it, heartbeat counters move, deferred drivers retry and bind. Until this passes, no capability is "Done" — the D5 audit gains a Runtime column.

LDR — Linux-Driver-Reuse track (the critical goal):

One ownership model: driver-manager owns enumeration, matching, policy, claiming, and spawning for native and Linux-port daemons alike; linux-kpi is the in-process Linux API surface inside the spawned daemon, never a second enumerator.

• LDR-1 Unified claim model. All device binding flows through driver-manager's match→claim→spawn. linux-kpi never opens /scheme/pci/ for binding decisions.
• LDR-2 Spawned-mode pci_register_driver. When PCID_CLIENT_CHANNEL is present, linux-kpi skips enumeration, wraps the granted channel, matches only the device it was spawned for, and calls the C probe for exactly that device. Standalone self-enumeration mode remains for CLI tools. This eliminates the double-claim risk class (assessment B2).
• LDR-3 redbear-iwlwifi onboarding. Generate its driver-manager TOML from the iwlwifi id_table via linux_loader (un-cfg(test) the pipeline: linux_loader → TOML → /lib/drivers.d/); spawn it as a daemon under the unified claim; retire its manual /scheme/pci/ scanning CLI path for the auto-bind case.
• LDR-4 amdgpu path convergence. Keep redox-drm as the spawned daemon (its FFI into libamdgpu_dc_redox.so is legitimate in-process composition, not a second claim system — but its PCI open must go through the granted channel, not PciDevice::open_location on its own enumeration).
• LDR-5 linux-kpi API completion (priority order). (a) real MSI/MSI-X via pcid_interface::enable_feature (replace synthetic allocate_vectors); (b) pci_request_regions/pci_release_regions as BAR-mapping claims over the channel; (c) pcie_capability_read/ write_* via channel config R/W (exists in pcid_interface); (d) power state (pci_save_state/restore_state/set_power_state via PMCSR); (e) pci_reset_function (FLR) if pcid grows the hook.

P2 — Operator & event surface:

• P2-1 pcid producers. Per-device AER register files from the retained aer-scheme blueprint; pciehp slot-status events (the five hardware-defined bits ABP/PFD/PDC/DLLSC/CC) produced by pcid polling the slot status register.
• P2-2 Scheme write endpoints. /bind, /unbind, /new_id, /remove_id, /driver_override, /rescan on the driver-manager scheme — the Linux sysfs operator surface, scheme-shaped. dynids are already implemented in redox-driver-core; this exposes them. driver_override adds Linux's Tier-1 match precedence.
• P2-3 Trigger-based deferred retry. Retry deferred probes on (a) any successful bind (mirrors driver_deferred_probe_trigger), (b) dependency-scheme arrival (watch /scheme/ for the named scheme in "dependency scheme not ready" deferrals), (c) firmware-loader readiness for NEED_FIRMWARE deferrals. Blind 250 ms polling becomes the fallback, not the mechanism.

P3 — Policy & hygiene: quirk pass phases (early pre-BAR vs runtime — Linux has 8 pci_fixup_pass phases; we need at least the early/runtime split for pre-BAR quirks); AER recovery actions wired to drivers (pci_ers_result 6-state mapping over scheme IPC); per-vendor firmware packaging mirroring linux-firmware splits; dependency-crate warnings (libredox, pcid Option::insert, redox-driver-sys Once/vendor); remove the stale local/recipes/drivers/redox-driver-core/src/ duplicate tree (live tree is source/src/); fold the concurrent path's double bus enumeration into one pass.

v2.2 status update over v2.1:

v2.2 records the ninth round of D-phase work, fixing defects found by the first full x86_64-unknown-redox compile of the v2.1 tree and by a dead-code/warning sweep:

• Concurrent probe path is now real (redox-driver-core). The ConcurrentDeviceManager previously returned a synthetic ProbeResult::Bound from run_probe without ever calling Driver::probe() — on any bus with ≥ 4 unbound devices (the production max_concurrent_probes = 4 config) this reported bindings with no driver spawned and bypassed exclusive_with, quirks, and the blacklist. DeviceManager now stores drivers as Arc<dyn Driver>; concurrent jobs carry priority-ordered candidate lists (static match table and dynids); workers invoke the real probe() with serial-equivalent per-device semantics (Bound → claim + record, Deferred → enqueue, Fatal → stop, NotSupported → next candidate) and apply bound/deferred state in the worker. Three new tests cover real probe invocation, candidate fallback, and deferred enqueue.
• Redox-target build errors fixed (driver-manager). SchemeSync::write now matches the redox-scheme trait (buf: &[u8]); the /modalias write stores the looked-up driver name per-handle and a subsequent read returns it. O_WRONLY/O_RDWR come from syscall::flag (usize) instead of libc (i32).
• Double-claim bug fixed. probe() claimed the PCI device twice (once before the exclusive_with check, once before spawn); since pcid binds are exclusive, the second claim would always fail EALREADY on real hardware and no device would ever bind. The probe now claims once and threads the same handle through to spawn.
• Driver registry wired. set_registered_drivers() is now called at startup — previously the registry stayed empty, making the exclusive_with check and the /modalias lookup silent no-ops.
• Real signal handlers. SIGCHLD and SIGHUP handlers are now actually installed via libc::signal inside spawn_reaper_thread / spawn_reload_worker. The previous install_handler / install_sighup_handler bodies were empty placeholders, so the reaper and the blacklist reload never fired in production.
• Heartbeat counters wired. record_bound / record_spawned / record_deferred / record_on_error are called from the enumerate path; record_bound / record_unbound from the hotplug loop. The heartbeat JSON no longer publishes permanent zeros.
• AER routing wired. The unified event listener calls route_to_driver per AER event against a live bound-device snapshot (new bound_device_pairs() scheme accessor) and logs the decided RecoveryAction.
• Dead code removed or test-gated. The superseded standalone pciehp/AER listener threads, the single-variant ProbeOutcome enum, SharedBlacklist::len/snapshot, the placeholder install functions, the heartbeat cv/stop machinery, and set_reload_flag are gone; end_to_end_test, linux_loader, set_reap_flag, compute_modalias, and policy::SharedBlacklist::snapshot are #[cfg(test)]-gated; compute_match_modalias / lookup_modalias are #[cfg(any(target_os = "redox", test))] (their only production caller is the redox-only scheme server).
• Zero warnings. driver-manager compiles warning-free on the host and on the x86_64-unknown-redox target (remaining warnings are pre-existing in dependency crates: libredox, pcid, redox-driver-sys).

v2.2 test totals: 56 driver-manager + 33 redox-driver-core lib + 5 dynid integration = 94 tests, all passing. repo cook driver-manager succeeds for x86_64-unknown-redox with zero crate-local warnings.

§ 0.5 audit gate at v2.2: 0 violations.

v1.4 status update over v1.3:

v1.4 records the second round of D-phase work: the policy loader is now active (the redbear-driver-policy package now actually changes spawn_decision_gate behavior at runtime), the --concurrent=N CLI flag enables the SMP worker pool, the two C0 service files have been committed in the local/sources/base submodule, and the unused modern_tech orchestrator was removed (the redox_driver_core::modern_technology helpers remain as a library for downstream consumers to integrate when they exist). The § 0.5 audit gate still reports 0 violations across 34 files. PciQuirkFlags is now wired into the actual driver spawn (the REDBEAR_DRIVER_PCI_IRQ_MODE=intx_or_msi and REDBEAR_DRIVER_DISABLE_ACCEL=1 env vars are passed to the spawned child when the corresponding flags are set).

Item	Status at v1.4	Where
§ 5.1 D0 foundation verified	✅ Done	cargo test 33+3+16 = 52 tests passing
§ 5.1 D1 C1 capability (add_dynid/remove_dynid)	✅ Done	redox-driver-core/src/{dynid,manager}.rs
§ 5.1 D1 C2 capability (Driver::remove + WAIT_FOR_REAPPEAR)	✅ Done	driver-manager/src/config.rs (real SIGTERM+SIGKILL)
§ 5.1 D1 C3, C6 (enable_device / set_bus_master)	✅ Done	open_pcid_channel via pcid_interface::EnableDevice
§ 5.1 D1 C4 (BAR request)	🟡 Corrected at v3.0	<addr>/bind never existed in pcid (see v3.0 correction 1); claim collapses into channel exclusivity per P0-1
§ 5.1 D1 C5, C7, C8, C12, C16, C17 (child-side)	✅ Done	pre-existing driver daemons
§ 5.1 D1 format coexistence	✅ Done	convert_legacy function in config.rs
§ 5.1 D1 SpawnDecision committee	✅ Done	spawn_decision_gate() function
§ 5.1 D1 policy blacklist	✅ Done at v1.4	policy::Blacklist::load_dir() + blacklist_match() consult at probe
§ 5.2 D2.1 SMP concurrent probe	✅ Done	redox-driver-core/src/concurrent.rs (worker pool)
§ 5.2 D2.2 C-state / P-state advisors	✅ Library only at v1.4	redox-driver-core/src/modern_technology.rs (orchestrator removed)
§ 5.2 D2.3 IOMMU + MSI-X + NUMA helpers	✅ Library only at v1.4	same module (combined surface)
§ 5.2 D2.4 runtime PM hooks (suspend/resume)	✅ Done	Driver::suspend/resume trait + signal_then_collect
§ 5.2 D2.5 AER foundation (on_error)	✅ Done	Driver::on_error + ErrorSeverity + RecoveryAction
§ 5.2 D2.6 PciQuirkFlags integration (D4)	✅ Done at v1.4	driver-manager/src/quirks.rs (redox-driver-sys dep) + spawn-time env vars
§ 5.2 D3 event-driven hotplug (polling fallback)	✅ Done	hotplug poll reduced to 250ms; pcid event delivery is the next step
§ 5.2 D4 audit-no-stubs.py + 8 test scripts	✅ Done	0 violations across 34 files
§ 5.2 D4 redbear-driver-policy package	✅ Done	local/recipes/system/redbear-driver-policy/
§ 5.2 D4 --concurrent=N CLI flag	✅ Done at v1.4	main.rs parses arg, calls ConcurrentDeviceManager::enumerate(cap)
§ 5.2 D5 audit document	✅ Done	local/docs/evidence/driver-manager/D5-AUDIT.md
§ 5.2 C0 dormant service files	✅ Committed at v1.4	local/sources/base submodule (commit 0407d9cc)
Operator ratification	🔴 Not yet	required before C1 begins

v1.4 test totals: 52 tests across the three crates, all passing.

§ 0.5 audit gate at v1.4: 0 violations across 34 scanned files.

v1.3 status update over v1.2:

v1.3 records the full D-phase implementation: every D1–D4 deliverable in the § 5.1 D-phase is now in source. The § 0.5 comprehensive-implementation audit gate (local/scripts/driver-manager-audit-no-stubs.py) returns zero violations across 34 files. The § 0.6 parallel-development constraint is preserved — the migration is fully implemented but driver-manager remains excluded from any boot path until operator ratification. See local/docs/evidence/driver-manager/D5-AUDIT.md for capability-by-capability status.

Item	Status at v1.3	Where
§ 5.1 D0 foundation verified	✅ Done	cargo test 28+5 + 3 + 13 = 49 tests passing
§ 5.1 D1 C1 capability (add_dynid/remove_dynid)	✅ Done	redox-driver-core/src/{dynid,manager}.rs
§ 5.1 D1 C2 capability (Driver::remove + WAIT_FOR_REAPPEAR)	✅ Done	driver-manager/src/config.rs (real SIGTERM+SIGKILL)
§ 5.1 D1 C3, C6 (enable_device / set_bus_master)	✅ Done	open_pcid_channel via pcid_interface::EnableDevice
§ 5.1 D1 C4 (BAR request)	🟡 Corrected at v3.0	<addr>/bind never existed in pcid (see v3.0 correction 1); claim collapses into channel exclusivity per P0-1
§ 5.1 D1 C5, C7, C8, C12, C16, C17 (child-side)	✅ Done	pre-existing driver daemons
§ 5.1 D1 format coexistence	✅ Done	convert_legacy function in config.rs
§ 5.1 D1 SpawnDecision committee	✅ Done	spawn_decision_gate() function
§ 5.2 D2.1 SMP concurrent probe	✅ Done	redox-driver-core/src/concurrent.rs (worker pool)
§ 5.2 D2.2 C-state / P-state advisors	🟡 Corrected at v3.0	advisory theater (assessment G6) — P0-3 strips to honest core (MSI-X env hint or removal)
§ 5.2 D2.3 IOMMU + MSI-X + NUMA helpers	✅ Done	same module (combined surface)
§ 5.2 D2.4 runtime PM hooks (suspend/resume)	✅ Done	Driver::suspend/resume trait + signal_then_collect
§ 5.2 D2.5 AER foundation (on_error)	✅ Done	Driver::on_error + ErrorSeverity + RecoveryAction
§ 5.2 D2.6 PciQuirkFlags integration (D4)	✅ Done	driver-manager/src/quirks.rs (redox-driver-sys dep)
§ 5.2 D3 event-driven hotplug (polling fallback)	✅ Done	hotplug poll reduced to 250ms; pcid event delivery is the next step
§ 5.2 D4 audit-no-stubs.py + 8 test scripts	✅ Done	0 violations across 34 files
§ 5.2 D4 redbear-driver-policy package	✅ Done	local/recipes/system/redbear-driver-policy/
§ 5.2 D5 audit document	✅ Done	local/docs/evidence/driver-manager/D5-AUDIT.md
§ 5.2 C0 dormant service files	✅ Done	local/sources/base/init.{,initfs.d/}/*-manager.service
Operator ratification	🔴 Not yet	required before C1 begins

Test totals at v1.3:

• redox-driver-core: 28 unit + 5 integration = 33 tests
• redox-driver-pci: 3 tests
• driver-manager: 13 unit tests
• Total: 49 tests, all passing

§ 0.5 audit gate at v1.3: 0 violations across 34 scanned files.

v1.2 status update over v1.1:

The § 0 strategic context and § 5 D/C phase structure are unchanged from v1.1. This revision records what was implemented during the parallel-development sprint (v1.1 → v1.2). See local/docs/evidence/driver-manager/D5-AUDIT.md for the formal capability-by-capability audit.

Item	Status at v1.2	Where
§ 5.1 D0 foundation verified	✅ Done (v1.1)	redacted
§ 5.1 D1 C1 capability (add_dynid/remove_dynid)	✅ Done (v1.2)	local/recipes/drivers/redox-driver-core/source/src/{dynid,manager}.rs
§ 5.1 D1 C2 capability (Driver::remove + WAIT_FOR_REAPPEAR)	✅ Done (v1.2)	local/recipes/system/driver-manager/source/src/config.rs
§ 5.1 D1 C3, C6 (enable_device / set_bus_master)	✅ Covered (v1.2)	already in open_pcid_channel via pcid_interface
§ 5.1 D1 C4 (BAR request explicitness)	✅ Covered (v1.2)	already in claim_pci_device
§ 5.1 D1 C5, C7, C8, C12, C16, C17 (child-side)	✅ Done (pre-D1)	already in driver daemons
§ 5.1 D1 format coexistence (legacy [[drivers]] + new [[driver]])	✅ Done (v1.2)	local/recipes/system/driver-manager/source/src/config.rs::convert_legacy
§ 5.1 D1 SpawnDecision committee	✅ Done (v1.2)	local/recipes/system/driver-manager/source/src/config.rs::spawn_decision_gate
§ 5.2 D2 modern-tech surface (PM/AER/MSI-X/IOMMU/C-state/P-state)	🟡 Partial (v1.2)	Driver::suspend/resume/on_error trait; signal_then_collect; SMP/IOMMU defer to D5
§ 5.2 D3 event-driven hotplug	🟡 Polling fallback (v1.2)	redox_driver-pci::subscribe_hotplug returns Unsupported until pcid event delivery lands
§ 5.2 D4 audit-no-stubs.py + 8 test scripts	✅ Done (v1.2)	local/scripts/driver-manager-audit-no-stubs.py, local/scripts/test-driver-manager-*.sh
§ 5.2 D4 redbear-driver-policy package	✅ Done (v1.2)	local/recipes/system/redbear-driver-policy/
§ 5.2 D5 audit document	✅ Done (v1.2)	local/docs/evidence/driver-manager/D5-AUDIT.md
§ 5.2 C0 dormant service files	✅ Done (v1.2)	local/sources/base/init.{,initfs.d/}/*-manager.service

v1.1 additions over v1.0:

• New § 0 Strategic Context with six subsections (rationale, success criteria, upstream risk, modern tech surface, comprehensive principle, parallel development).
• Restructured § 5 Phased migration plan into D-Phase (parallel development) and C-Phase (cutover & validation) tracks. The two tracks are sequential, not interleaved.
• The original P0–P6 dual-mode strategy is folded into the new structure. driver-manager is now never enabled until the D-phase feature-complete gate (D5) ratifies.
• Cross-referenced § 0 references in § 1, § 2, § 4, § 5, § 9.

---

Title and intent

pcid-spawner is the current single-purpose daemon that reads /etc/pcid.d/*.toml, walks /scheme/pci/, and forks driver daemons for matched devices. It is correct, small (127 lines), and ships the boot-critical 00_pcid-spawner.service plus the initfs 40_pcid-spawner-initfs.service unit. It cannot grow further without becoming a different program: deferred-probe semantics, dependency graphs, runtime hotplug, driver parameters, and a managed device tree all require the more capable abstraction in local/recipes/system/driver-manager/ (already drafted but not wired).

driver-manager is the intended replacement. Its implementation is partial: the abstract redox-driver-core machinery exists, the DeviceManager orchestrates buses/drivers/binding, a PciBus enumerates /scheme/pci, deferred probing and hotplug are sketched in hotplug.rs, and a scheme:driver-manager server exposes read-only observability. The piece that has never landed is the integration: package it, write 00_driver-manager.service, retire pcid-spawner cleanly, adopt the Linux-style capability split (C1–C18), and absorb the CachyOS policy patterns that have proven necessary on AMD-first hardware.

This plan produces that migration without losing any boot path, honoring the project's never-delete, never-disable, fix-root-cause policy (local/AGENTS.md § COMPREHENSIVE IMPLEMENTATION POLICY). pcid-spawner stays buildable and present in the tree at every phase; it is the safe fallback.

---

0. Strategic context

This section captures the why, what done looks like, upstream risk, modern-technology surface, comprehensiveness principle, and parallel-development constraint of the migration. Every later section implements these principles — they are not aspirations, they are binding constraints derived from local/AGENTS.md and the project's engineering standards.

0.1 Rationale for driver-manager (why not extend pcid-spawner)

Three converging forces make pcid-spawner insufficient as the long-term driver spawner:

1. Architectural ceiling. pcid-spawner is a 127-line single-purpose launcher that enumerates PCI devices and forks drivers against a static config table. It cannot grow to handle: deferred-probe semantics (driver needs a scheme that is not yet registered); dependency-graph scheduling (drivers depending on other drivers); runtime hotplug (PCIe native, USB, Thunderbolt); driver parameter mutation (a userspace tool writing iwlwifi parameters at runtime); AER error recovery; runtime-PM suspend/resume. Adding any of these to a 127-line launcher requires restructuring into a different program.

2. Driver coverage roadmap. Red Bear's planned driver surface grows from 17 to ~30+ daemons (per local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md). New drivers — amd-mp2-i2cd, intel-thc-hidd, Wi-Fi (iwlwifi, mt76), GPU backends (redox-drm AMD DC variant), Thunderbolt, NVMe namespaces — each carry their own configuration model, dependency graph, and runtime parameter surface. A per-driver ad-hoc spawner is no longer maintainable.

3. Driver ecosystem contract demands. Wi-Fi drivers need delayed probe (firmware load + regulatory database check); I2C/audio controllers need dependency-aware ordering (acpi → i2c → driver); GPU drivers need stable device-id→driver binding with explicit version handling; hotplug events require an event-driven loop, not a one-shot enumeration. pcid-spawner's architecture cannot satisfy any of these contractually.

What we lose by NOT moving to driver-manager:

• The existing redox-driver-core framework (Bus/Driver/DeviceManager/ ProbeEvent/DriverMatch/DriverParams) becomes dead code.
• The hard-won work in redox-driver-acpi, redox-driver-pci, and local/recipes/system/driver-params/ becomes single-purpose.
• Wi-Fi, USB hotplug, AER, and runtime-PM work has to be re-architected against a different manager primitive.
• The CachyOS-style policy layer (blacklist, autoload, ordering, options) cannot live cleanly without a manager that reads /etc/driver-manager.d/.

Why not just extend pcid-spawner:

• pcid-spawner is 127 LOC doing exactly one thing. Adding deferred probing + dependency graphs + hotplug + params + AER + PM grows it to thousands of LOC with a fundamentally different architecture.
• The redox-driver-core framework already exists with the right trait surface. Throwing it away to extend pcid-spawner would violate local/AGENTS.md § LOCAL FORK SUPREMACY POLICY: "Red Bear adapts to upstream, never throws away working code."
• The Linux-style capability split (C1–C18 in § 2.3) is the right design. pcid-spawner implements none of C9, C11, C13–C18; bolting them on is more work than building the manager they belong in.

Why this is happening now:

• The framework is already built (local/recipes/system/driver-manager/ is a compilable Rust crate at version 0.3.1 with 1250 LOC and a 783KB binary artifact).
• The 17 drivers' Cargo manifests depend on pcid_interface (PciFunctionHandle::connect_default()). They are already compatible with the manager contract — no driver-code changes are required at any phase.
• Driver parameters and dependency gating are needed before Wi-Fi (per local/docs/WIFI-IMPLEMENTATION-PLAN.md).
• USB hotplug (per local/docs/USB-IMPLEMENTATION-PLAN.md) needs the manager's hotplug surface.
• AER recovery (per local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md) needs the manager's Driver::on_error surface.

0.2 Success criteria (definition of done)

The migration is complete when ALL of the following hold simultaneously:

1. Functional parity with pcid-spawner, verified by local/scripts/test-driver-manager-parity.sh: every device pcid-spawner binds, driver-manager binds. No regression in driver set coverage.

2. Linux 7.1 capability bridge complete. All of C1–C18 are implemented and tested, at the priority levels in § 2.3:

   • P0 set: C1, C2, C3, C4, C5, C6, C7, C8, C12, C16
   • P1 set: C9, C10, C11, C14, C17, C18
   • P2 set: C13, C15

3. Modern technology surface integrated (§ 0.4):

   • SMP-aware concurrent probe verified
   • C-state and P-state coordination verified
   • Runtime PM suspend/resume callback chain verified
   • IOMMU group management verified
   • AER error recovery verified

4. Hotplug functional and event-driven (not polling). Verified on QEMU synthetic and at least one real-hardware hot-add scenario.

5. Quirk policy honored. redox-driver-sys::PciQuirkFlags consulted for every bind/remove decision. NO_MSIX, NO_PME, NEED_FIRMWARE, DISABLE_ACCEL, FORCE_LEGACY_IRQ, NEED_IOMMU, etc., all flow through the manager.

6. Hardware validation matrix passes on:

   • AMD Threadripper (canonical AMD-first profile)
   • AMD Zen4 desktop
   • Intel Alder Lake or later desktop
   • At least one bus category each: storage (NVMe + AHCI), network (e1000d + rtl8168d), USB (xhcid), GPU (Intel or AMD display path)

7. 30-day stability gate. In production cutover (C4), the ConditionPathExists guard on 00_pcid-spawner.service has not fired in 30 days of continuous operation.

8. Regressions clean. All of local/scripts/test-driver-manager-{parity,active,initfs,hotplug,pm,cutover}.sh pass on every release branch for the same 30-day window.

9. No-deferred-comments cleanup. The inline deferred comments in config/redbear-mini.toml:31 and config/redbear-device-services.toml:9-13 are removed (no longer accurate).

10. Operator ratification. Explicit human acknowledgement at each C-phase boundary and at the final C4 transition.

0.3 Upstream risk — what if Redox upstream ships their own driver-manager

This is not a remote possibility — Redox upstream has been discussing driver-manager-style architectures. Red Bear's response is encoded as policy ahead of time.

What Redox upstream's plan could look like:

• A single-purpose scheme:pci consumer that spawns drivers against a config table (very similar to pcid-spawner, the canonical upstream).
• A more capable per-bus spawner (closer to Red Bear's driver-manager).
• A kernel-side enumeration manager (drastic, unlikely in Redox's microkernel model).

Red Bear's response strategy:

• Compare against the C1–C18 capability list (§ 2.3). A manager is "equivalent" if it covers at least the P0 set of capabilities and exposes a compatible driver handoff contract.

• If upstream ships a fully equivalent manager, evaluate migrating to use theirs per local/AGENTS.md § LOCAL FORK SUPREMACY POLICY (Red Bear adapts to upstream; never pins/holds back). This is the most likely scenario for the long term.

• If upstream ships a different approach (per-bus spawning, a kernel-side manager, a Lua-scripted policy layer), Red Bear's driver-manager becomes a Red Bear extension layer on top of the upstream primitive, OR is preserved as a local recipe that supplements the upstream manager rather than replacing it. The decision is taken at the time based on coverage.

• If upstream ships the equivalent manager within 6 months of our D5 gate, the migration plan is re-evaluated against theirs. The C-phases (§ 5.2) become a no-op or a thin shim. pcid-spawner remains the fallback regardless.

Concrete protections already in the plan:

• 00_driver-manager.service is a service name, not a binary. Swapping the cmd= to upstream's binary is a one-line change.
• The driver's runtime contract is PCID_CLIENT_CHANNEL=<fd> (preserved from upstream Redox pcid-spawner). Any manager that delivers this env var keeps drivers unmodified.
• The capability taxonomy (C1–C18) is a Red Bear design tool, not an upstream commitment. We use it to evaluate upstream choices.

What does NOT change:

• local/recipes/system/driver-manager/source/ is and remains a local Red Bear crate, not an upstream-fork clone.
• The D-phase development continues regardless of upstream decisions.
• pcid-spawner stays as the safe fallback until C4.

0.4 Modern technology surface (SMP, S/P states, runtime PM, IOMMU, AER, hotplug, MSI-X, NUMA)

The driver-manager is genuinely modern by design. The technologies listed below are integrated as functional features (not stubs):

1. SMP awareness.

   • Manager enumeration runs single-threaded for race-free exploration (correct — exploration must be deterministic).
   • Concurrent probe dispatch: max_concurrent_probes is enforced via a worker pool. Today it is policy metadata; in D2 it becomes real concurrent dispatch via std::thread::scope or rayon.
   • Per-vector IRQ CPU affinity: MSI-X vectors are bound to specific CPUs based on topology (CPUID leaf 0Bh for AMD, 0Fh for Intel).
   • Hotplug event loop is a separate thread; events post through a lockless queue to the manager (no shared mutable state with the probe path).

2. C-states (CPU idle states).

   • Manager exposes driver-bound/unbound events to cpufreqd / thermald. Hotplug-removing a device → CPU may drop to a deeper C-state.
   • Manager signals probe-completion → CPU may return to its former governor state.
   • System-wide C-state transitions coordinated through redox-driver-acpi (via scheme:acpi).

3. P-states (CPU performance states).

   • On driver bind/unbound, manager publishes a P-state advisory via cpufreqd socket or a pstate scheme.
   • Cold-boot probe order is documented and P-state-aware: storage drivers spawn first (high P-state by default), audio/USB spawn later (low P-state allowed).
   • Driver spawn during boot is gated on cpufreqd confirming P-state is high enough for the driver to initialise (e.g., NVMe completion timeouts require a high enough P-state).

4. Runtime PM (per-driver).

   • Driver::suspend() / Driver::resume() callbacks are fully implemented with real state save + power-down (default: real D3 transition through pcid; not Ok(())).
   • PCIe D-state transitions (D0 ↔ D3hot ↔ D0) coordinated through pcid's SetPowerState request via PcidClient.
   • Hotplug-remove pre-empts runtime PM: the manager calls force_suspend() before unbinding.

5. IOMMU groups (local/recipes/system/iommu/).

   • Per-device group registration via the iommu scheme.
   • DMA isolation enforcement: drivers cannot bypass their group's domain.
   • Group-awareness for hotplug: a sibling device in the same group must also be quiesced before removal.

6. AER (PCI Express Advanced Error Recovery).

   • Driver::on_error(severity) callback is fully implemented with severity dispatch (CORRECTABLE → log; NONFATAL → retry with masking; FATAL → slot reset → config restore → re-bind).
   • Manager registers with pciehp for hotplug events (Presence Detect Changed, Data Link Layer State Changed, MRL Sensor Changed).
   • Per-driver error recovery action: drivers implement Driver::on_error for their specific hardware (NVMe reset, e1000 soft-reinit, etc.).

7. MSI-X vector allocation.

   • pci_alloc_irq_vectors() semantics preserved (MSI-X preferred, fallback to MSI, fallback to INTx; capability-aware honouring of PciQuirkFlags::NO_MSIX).
   • Per-vector fd returned to driver (each vector independently reachable through /scheme/irq).
   • Multiple MSI-X vectors per device (e.g., xHCI's 16-vector interrupt setup).

8. NUMA awareness (when local/recipes/system/numad/ is live).

   • Driver's memory regions classified by NUMA node.
   • DmaBuffer::allocate(size, align, node_hint) prefers same-node.
   • Hot-add monitored for NUMA topology changes.

9. Modern vendor-specific paths.

   • AMD: PSP firmware load (via firmware-loader), DCN hardware blocks, GTT addressing, AMD-Vi IOMMU integration.
   • Intel: GGTT setup, hot-plug through pciehp, MFG/RC6 power management, IOMMU group isolation.
   • Per-vendor path is a redox-drm backend (out of scope here); the manager's runtime-PM / quirk / hotplug hooks are exercised by all of them.

Why these technologies, and why not others:

• We do NOT adopt cgroup-vram (CachyOS extras) — Redox has no cgroups.
• We do NOT adopt sched-ext / BORE scheduler — kernel-side work, per local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md Phase T.
• We DO adopt CachyOS-style modprobe.d patterns (blacklist, options, autoload) — see § 2.2. These translate cleanly to /etc/driver-manager.d/.

0.5 Comprehensive implementation principle (no stubs, comprehensive code only)

The driver-manager implementation is comprehensive, systematic, methodical. local/AGENTS.md § STUB AND WORKAROUND POLICY — ZERO TOLERANCE applies without exception. The principle is re-stated here in the specific form that applies to driver-manager:

• No stubs. Every public API in redox-driver-core::driver::Driver, redox-driver-core::bus::Bus, and driver-manager::scheme::* is fully implemented. No unimplemented!(), no todo!(), no empty match arms returning trivial defaults.
• No #ifdef-guarded no-ops. No Rust cfg gates that disable entire feature paths.
• No LD_PRELOAD-style tricks. No override layer that hides unimplemented features.
• No sed/awk rewriting. TOML config is parsed, not preprocessed.

Per-method completeness requirements (any violation blocks D5):

Surface	Forbidden pattern	Required behaviour
Driver::probe(info)	unimplemented!() or Ok(()) skip	Full match-table evaluation + dependency check + device claim + spawn
Driver::remove(info)	_ => Ok(()) drop	Reclaim bind handle, terminate child via SIGTERM, refresh scheme:driver-manager:/bound
Driver::suspend(info)	Ok(()) default	Real PCI D-state transition via pcid (SetPowerState), save config space, log
Driver::resume(info)	Ok(()) default	Restore config space, walk IRQ vectors (re-arm MSI-X), signal ready
Driver::on_error(info, severity)	Ok(()) or Unsupported	Severity dispatch: CORRECTABLE → log; NONFATAL → retry; FATAL → slot reset
Driver::params()	DriverParams::default()	Real parameter definitions (priority, debug, exclusive_with, runtime flags)
Bus::enumerate_devices()	Ok(vec![]) skip	Walk scheme:pci config files, populate DeviceInfo with vendor/device/class/subclass/prog_if/revision/subsystem IDs
Bus::subscribe_hotplug()	Err(BusError::Unsupported)	Subscribe to /scheme/pci/events (or pcid uevent channel); return real HotplugSubscription
Manager::enumerate()	empty loop	Walk all buses, dispatch to drivers, emit ProbeEvents with deferred support
Manager::retry_deferred()	no-op	Re-evaluate deferred queue, re-probe if dependencies now satisfied, emit events

Honest absence vs. stub matters. If a feature is genuinely not applicable (e.g., NUMA awareness on a non-NUMA system), the manager code calls a runtime probe that returns an honest answer:

// PREFERRED (D4+):
if !query_numa_support() {
    return BusError::Unsupported;  // honest absence
}

// FORBIDDEN at any phase:
// if !query_numa_support() { return Ok(()) }
// if cfg!(...) { return BusError::Unsupported } else { return Ok(()) }

The result: type signatures are honest, runtime is honest, documentation is honest. A driver receiving Unsupported knows to fall back to uniform memory without assuming the manager is silently doing the right thing.

Systematic means the same architectural pattern applies across all bus types (PCI, USB, ACPI, future platform), all driver types (storage, network, GPU, USB, audio), and all capability surfaces (C1–C18). The Driver trait is the single contract; the Bus trait is the single contract; the scheme:driver-manager:/<node> filesystem is the single observability surface.

Methodical means the work unfolds in the D-phases of § 5.1 with verifiable exit criteria. No phase skips ahead. No phase declares done with deferred items. The audit script local/scripts/driver-manager-audit-no-stubs.py (D4 deliverable) is the formal gatekeeper.

Right-component implementation rule (from local/AGENTS.md § STUB AND WORKAROUND POLICY):

Symptom	Wrong fix	Required fix
eventfd() not in relibc	Stub in libc wrapper	Implement in relibc proper
Bus::subscribe_hotplug not in pcid scheme	Stub the manager side	Implement event delivery in pcid scheme
TOML config gap	Accept both formats but emit empty drivers	Implement FULL conversion from legacy pcid.d to new drivers.d
Driver needs runtime PM	suspend: fn() { Ok(()) } default	Implement genuine D3 transition in pcid, expose via trait
AER not yet wired	Mark feature as Unsupported and ignore errors	Implement severity dispatch + recovery action in Driver::on_error
Hotplug loop is polling-only	Document as "future work"	Implement event subscription via Bus::subscribe_hotplug()
TOML [[driver.match]] field missing	Skip silently	Return Err(format!("unsupported match field: {name}")) from loader

0.6 Parallel development constraint (built but not utilised until fully developed)

The driver-manager is being implemented in parallel and not being utilized before fully developed. This is the binding development model.

Current state (2026-07-20):

• The local-recipe at local/recipes/system/driver-manager/source/ accumulates improvements in commits.
• pcid-spawner is the boot path in every redbear-*.toml.
• driver-manager is NOT added to any [packages] section.
• driver-manager does NOT have an 00_driver-manager.service.
• driver-manager's binary MAY be built locally (it is at 783KB), but it is NOT shipped in any produced ISO or harddrive image.
• Inline deferred comments in config/redbear-mini.toml:31 and config/redbear-device-services.toml:9-13 reflect this.

Operational reality during D-Phase:

• local/recipes/system/driver-manager/source/ is committed to the current branch as part of normal development.
• config/redbear-*.toml does not include driver-manager = {}.
• The ISO build (./local/scripts/build-redbear.sh redbear-mini) does not include the driver-manager binary.
• Test scripts local/scripts/test-driver-manager-{parity,active,...}.sh are written but not in the ISO; they run only on developer workstations and CI runners.
• local/scripts/TOOLS.md and local/AGENTS.md continue to describe driver-manager as "in development" until D5 ratifies.

When does driver-manager become eligible for the boot path?

When ALL of D0–D5 exit gates are satisfied (see § 5.1):

• D0 (foundation) complete
• D1 (Linux capability bridge) complete — all P0 capabilities of C1–C18 implemented and tested
• D2 (modern technology surface) complete — SMP, S/P states, runtime PM, IOMMU groups, AER all implemented
• D3 (hotplug event-driven) complete
• D4 (quark integration + comprehensive audit) complete
• D5 (feature-complete gate) — formal audit confirms no stubs in § 0.5 matrix, operator ratification received

Until then, the parallel development continues without touching the live boot path.

Implications for the original P0–P6 phasing (v1.0 of this plan):

The original plan's P0 (dual-mode observation) and P1 (rootfs active driver-manager) are now folded into the C-phases (§ 5.2). The D-phases describe the pre-cutover work (i.e., the parallel development the team is currently doing). The C-phases describe the post-completion cutover. The two are sequential, not interleaved.

This constraint is the one operational reality that separates this migration from any ordinary refactor. A feature that is not fully complete is NOT shipped; the build system does not "auto-enable" it; CI does not bundle it. The first time driver-manager appears in a boot path is after D5 + operator ratification. No exceptions.

---

Position in the doc set

• This is the canonical planning authority for pci-spawner → driver-manager migration beneath local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md.
• It does NOT replace any subsystem-specific plan. It supersedes the inline comment in config/redbear-mini.toml (line 31): "driver-manager requires driver config migration and is not yet ready" and the inline comment in config/redbear-device-services.toml (line 9-13): "driver-manager intentionally not included: it is the intended future replacement for pcid-spawner but is not yet ready (driver config migration pending) and was previously packaged-but-unused — its service launched pcid-spawner instead of driver-manager."
• Cross-references: local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md (where pcid-spawner hardening currently lives), local/docs/QUIRKS-SYSTEM.md + QUIRKS-IMPROVEMENT-PLAN.md (where the driver-manager→redox-driver-sys quirks bridge is planned), local/docs/USB-IMPLEMENTATION-PLAN.md (where the Bus trait is wired for USB), local/docs/WIFI-IMPLEMENTATION-PLAN.md (where matching semantics live for mac80211/cfg80211).

Scope

In scope:

• Lifecycle and integration of the existing local/recipes/system/driver-manager/ crate to replace local/sources/base/drivers/pcid-spawner/.
• Format migration of /etc/pcid.d/*.toml (legacy pcid_interface::Config) to /lib/drivers.d/*.toml (driver-manager DriverMatch), plus a back-compat loader that lets both formats coexist during transition.
• Init service rewrite: 00_pcid-spawner.service (rootfs) → 00_driver-manager.service with 00_pcid-spawner.service retained as a fallback unit that runs only when driver-manager is absent on the initfs. Initfs unit 40_pcid-spawner-initfs.service is renamed to 40_driver-manager-initfs.service with the same blocking-oneshot contract.
• Linux 7.1 capability bridging: the manager exposes, and the spawned drivers consume via PCID_CLIENT_CHANNEL env continuation, the capabilities C1–C18 (driver match, lifecycle, BAR mapping, IRQ vectors, runtime PM, AER error recovery, etc.).
• CachyOS policy patterns: policy-layer TOML with blacklist/options/autoload, driven by the manager (not by modprobe since Red Bear has no modules).

Out of scope:

• Adding USB / ACPI / platform buses to the device manager — those are in local/docs/USB-IMPLEMENTATION-PLAN.md and follow once the PCI manager lands.
• Replacing pcid itself (the scheme:pci owner) — it stays the canonical PCI scheme surface, just like Linux's pci_bus_type owning /sys/bus/pci/devices/.
• Replacing redox-driver-sys — driver-manager consumes it for the hardware-quirks surface once Q3 lands (see local/docs/QUIRKS-IMPROVEMENT-PLAN.md Task 2.1).
• Replacing the kernel — Redox's PCI scheme is userspace; the kernel's role (memory/irq/acpi/dt/serio schemes, MMIO mapping, MSI/MSI-X vector delivery) is unchanged.

Policy constraints (binding)

Every step in this plan inherits the following constraints from local/AGENTS.md:

1. NEVER DELETE a package, service, config, or patch. pcid-spawner stays.
2. NEVER IGNORE a package by "ignore". driver-manager lands as additive.
3. NEVER COMMENT OUT a service or config entry to "fix" a build.
4. ALWAYS FIX the root cause when something breaks.
5. The migration is operator-ratified: each phase has an explicit exit gate and is not closed until the gate is met AND human-acknowledged.

The durability rule applies: any source-tree edit during this migration is mirrored into local/patches/ or local/sources/<component>/ in the same work session. local/patches/base/ and the fork local/sources/base/ carry the changes; recipes/core/base/source/ is not the durable location.

---

1. Current state assessment

1.1 What pcid-spawner does today

Source: local/sources/base/drivers/pcid-spawner/src/main.rs (127 lines) Cargo: local/sources/base/drivers/pcid-spawner/Cargo.toml Recipe: recipes/core/base/drivers/pcid-spawner/recipe.toml (path-fork)

Single main() function with the following behaviour, ordered:

1. Wait for /scheme/pci/ to appear (200 × 50ms retry, 10s total) — this was added by Red Bear patch local/patches/base/P4-pcid-spawner-pci-coordinate-env.patch alongside the PCI coordinate env vars.
2. Load merged driver configs via config::config("pcid") — concatenates /etc/pcid.d/*.toml (rootfs) or /scheme/initfs/etc/pcid.d/*.toml (--initfs mode) into one Config struct.
3. Iterate /scheme/pci/ directory entries. For each:
   • PciFunctionHandle::connect_by_path(&device_path) — opens the per-device channel handle in scheme:pci. The handle is the mutual-exclusion lock: pcid returns ENOLCK to any second opener. This is the only claim mechanism.
   • On ENOLCK: log debug, continue. On other errors: log error, continue. The spawner never aborts on a single bad device.
   • config.match_function(&full_device_id) — legacy matching (class → subclass → interface → vendor/device, optional multi-vendor ids map, optional device_id_range).
   • On miss: log debug, continue.
4. Enable the PCI function (handle.enable_device()) — pcid writes the command register to enable bus mastering + memory + IO.
5. Build Command from driver.command, resolving program either absolute or prefixed /usr/lib/drivers/<program>.
6. Pass env vars to the child:
   • PCID_CLIENT_CHANNEL=<channel_fd> — the bincode channel FD the driver uses for PciFunctionHandle::connect_default() to reach pcid.
   • PCID_SEGMENT=<hex> — added by Red Bear P4 patch.
   • PCID_BUS=<hex> — added by Red Bear P4 patch.
   • PCID_DEVICE=<hex> — added by Red Bear P4 patch.
   • PCID_FUNCTION=<dec> — added by Red Bear P4 patch.
7. Spawn via daemon::Daemon::spawn(command) — parent blocks until the child signals readiness. This is the driver-ready handshake and is honoured by every existing driver daemon (ahcid, e1000d, xhcid, etc.).
8. Close the parent's copy of the channel FD.

1.2 What the existing driver-manager implements

Source root: local/recipes/system/driver-manager/source/ Cargo: local/recipes/system/driver-manager/source/Cargo.toml (Cat 1, version 0.3.1) Recipe: local/recipes/system/driver-manager/recipe.toml (template=cargo, path="source")

Five source files (src/main.rs, config.rs, scheme.rs, hotplug.rs, exec.rs) totalling ~1250 lines. Built and present at recipes/system/driver-manager/target/x86_64-unknown-redox/stage/usr/bin/driver-manager (783KB ELF, dated 2026-07-19). Binary-store artifact cached in repo/x86_64-unknown-redox/driver-manager.pkgar. NOT packaged into any current [packages] section of redbear-*.toml.

Area	Status	Notes
Compile	✅	Builds clean on x86_64-unknown-redox
Core abstraction	✅	redox-driver-core (Bus/Driver/DeviceManager/ProbeEvent/ManagerConfig/DriverParams/MatchTable/HotplugEvent)
PCI bus	✅	redox-driver-pci::PciBus reads /scheme/pci raw config space; class/subclass/program-if/subdevice IDs returned
TOML config loader	✅	/lib/drivers.d/*.toml (name, description, priority, command, match, depends_on)
Probe pipeline	✅	ProbeResult::Bound / NotSupported / Deferred / Fatal with retry queue
Deferred retry	🟡	30 retries × 500ms; logs deferred-retry-limit-reached and exits 0
Async probe	🟡	ManagerConfig::async_probe = true is set, but thread::spawn(...).join() is used immediately, making it actually synchronous
max_concurrent_probes	🟡	Stored as policy metadata; never enforced (all probes are serial)
Hotplug	🟡	run_hotplug_loop() polls every 2s; Bus::subscribe_hotplug() is hidden behind an unused hotplug feature flag
scheme:driver-manager	✅	Read-only /devices, /bound, /events, /devices/<pci-addr>, plus param persistence to /tmp/redbear-driver-params/<addr>/{driver,enabled}
Spawn via PCID_CLIENT_CHANNEL	🟡 Corrected at v3.0	<addr>/bind never existed in pcid; P0-1 collapses claim into the channel open (ENOLCK exclusivity) and passes PCID_CLIENT_CHANNEL=<fd> — the pcid-spawner model
Driver parameters	🟡	Driver::params() declared but driver-manager's own schema (enabled, priority) is parameter-only; runtime writes via scheme:driver-params (separate daemon local/recipes/system/driver-params)
Quirks integration	🔴	redox-driver-sys is not in the dep list; pci_has_quirk / pci_get_quirk_flags are NOT consulted
Service wiring	🔴	No 00_driver-manager.service exists; absent from all [packages] sections
Tests	🔴	Zero driver-manager tests; 12 unit tests in redox-driver-core
Documentation	🟡	No dedicated doc; mentioned in UPSTREAM-SYNC-PROCEDURE.md § "driver-manager: Deferred" and PACKAGE-BUILD-QUIRKS.md § "driver-manager Removed During Sync"

1.3 Service inventory that depends on pcid-spawner

Service definitions:

Service	Mode	Flag	Where
00_pcid-spawner.service	oneshot_async	(none)	local/sources/base/init.d/
40_pcid-spawner-initfs.service	oneshot (blocking)	--initfs	local/sources/base/init.initfs.d/
/etc/init.d/00_pcid-spawner.service (override)	oneshot_async	(none)	config/redbear-mini.toml lines 575-583
00_base.target requires_weak	—	—	local/sources/base/init.d/00_base.target

Service dependencies (every service that references 00_pcid-spawner.service):

Config	Service referencing it	Reference role
config/redbear-mini.toml	10_evdevd.service	requires_weak
config/redbear-mini.toml	20_udev-shim.service	requires_weak
config/redbear-mini.toml	11 other services	requires_weak
config/redbear-full.toml	10_evdevd.service	requires_weak
config/redbear-full.toml	redox-drm consumers	requires_weak
config/redbear-greeter-services.toml	redbear-greeter (seatd chain)	requires_weak
config/redbear-device-services.toml	explicit comment that driver-manager is deferred	—
config/acid.toml	acid test config	requires_weak
config/redoxer.toml	redoxer CI config	requires_weak

Migrating this dependency graph without breaking any boot path requires keeping 00_pcid-spawner.service available as a fallback through P0–P2 and running both managers transiently during P3.

1.4 Configuration surfaces

Active now (legacy format):

• config/redbear-mini.toml:500-512 — /etc/pcid.d/*.toml overrides (ihdgd.toml, virtio-gpud.toml, 00_text_mode_gpu_mask.toml)
• local/config/pcid.d/intel_gpu.toml — Intel GPU match
• local/config/pcid.d/amd_gpu.toml — AMD GPU match

Already drafted (driver-manager format, currently inert):

• config/redbear-device-services.toml:116-490 — full set of /lib/drivers.d/*.toml:
  • 00-storage.toml (ahcid, ided, nvmed, virtio-blkd, usb-bot)
  • 10-network.toml (e1000d, rtl8168d, rtl8139d, ixgbed, virtio-netd)
  • 20-usb.toml (xhcid, ehcid, ohcid, uhcid, usbhubd)
  • 30-graphics.toml (vesad, virtio-gpud, redox-drm)
  • 40-input.toml (ps2d, usbhidd, intel-thc-hidd)
  • 50-audio.toml (ihdad, ac97d, sb16d)
  • 70-usb-class.toml (usbscsid, usbaudiod, redbear-ftdi)

Decision-needed: are these drafts correctly normalised for driver-manager's TOML schema ([driver] with match tables, priority, depends_on)? D1 verifies them. Many entries will need editing to converge on a single matching language.

1.5 Fork / source provenance

• local/sources/base/ is the local fork of the base Redox upstream submodule. It holds BOTH drivers/pcid/ (the scheme:pci owner) AND drivers/pcid-spawner/ (the legacy spawner).
• local/recipes/system/driver-manager/ is a local recipe (Cat 1 in-house crate), not a submodule. It does NOT duplicate upstream code; it's a fresh Red Bear creation. No submodule/driver-manager branch exists, no .gitmodules entry, no need to create one (per local/AGENTS.md § BRANCH AND SUBMODULE POLICY: "We don't create new branches/repos. We work on existing submodules first. … A new submodule is only justified when the component is large enough that submodule pinning provides real value over a tracked tree or local recipe. driver-manager satisfies none of these").
• The 17 driver daemons under local/sources/base/drivers/{storage,net,graphics,audio,usb}/ each have pcid = { path = "../../pcid" } in their Cargo.toml. They depend on pcid_interface (a lib crate alongside pcid), NOT on the pcid-spawner binary. The runtime contract they honour is PCID_CLIENT_CHANNEL=<fd>, which driver-manager preserves. No driver-binary changes are required.

---

2. Cross-reference: pcid-spawner vs driver-manager vs Linux 7.1 vs CachyOS

2.1 Linux 7.1 PCI driver model surface (local/reference/linux-7.1/ at ab9de95c9)

Subsystem	Linux source	Capability exposed
PCI bus type	drivers/pci/pci-driver.c:1726-1742 (pci_bus_type), include/linux/pci.h:1021-1154 (pci_driver + pci_device_id macros)	C1: id_table + match
Probe / remove	drivers/pci/pci-driver.c:473-553 (pci_device_probe / pci_device_remove / pci_device_shutdown)	C2: device lifecycle
Module loading	kernel/kmod.c:64-179 (__request_module → call_modprobe) + drivers/pci/pci-driver.c:1587-1617 (pci_uevent with MODALIAS)	C1′: driver lookup with alias
Driver-core binding	drivers/base/bus.c (bus_add_driver / bus_probe_device / device_attach / driver_attach)	C2′: symmetric device/driver iteration
Sysfs surface	drivers/pci/pci-sysfs.c (vendor, device, class, subsystem_*, resource, config, bind, unbind, new_id, remove_id, driver_override)	C1 + C2 + C11 + observability
PCIe native hotplug	drivers/pci/hotplug/pciehp_core.c:185-372 (pciehp_probe + presence/attention/MRL/DLLSC handlers)	C14: hotplug events
AER	drivers/pci/pcie/aer.c:1203-1280 (aer_recover_work_func + pcie_do_recovery) + include/linux/pcieport_if.h (pci_error_handlers)	C13: error recovery
Runtime PM	drivers/pci/pci-driver.c:1314-1440 (pci_pm_runtime_* + pci_dev_pm_ops)	C9 + C18: suspend/resume
IOMMU / DMA	drivers/pci/pci-driver.c:1668-1711 (pci_dma_configure) + drivers/iommu/iommu.c (iommu_device_use_default_domain)	C15: DMA / IOMMU
MSI / MSI-X	drivers/pci/msi/api.c:205-264 (pci_alloc_irq_vectors_affinity) + include/linux/pci.h:1166-1168 (pci_irq_vector)	C7 + C8: vector allocation
BAR / MMIO	drivers/pci/pci.c:2120-238, 3916-4172 (pci_enable_device / pci_request_regions / pci_set_master / pci_ioremap_bar)	C3 + C4 + C5 + C6: device + bar map
Power states	include/linux/pci.h:183-188 (PCI_D0..PCI_D3cold) + pci.h pci_set_power_state	C9: power state control
Capabilities search	drivers/pci/pci.c (pci_find_capability / pci_find_ext_capability)	C16: capability iteration

Synthesis (cross-reference pci_driver ↔ Driver trait ↔ driver-manager):

Linux pci_driver member	Linux function	Redox current (redox-driver-core)	Redox pcid-spawner path	Gap to fill
.probe	pci_device_probe	Driver::probe(&DeviceInfo) -> ProbeResult	(deferred to child spawn)	async + retry + dependency-aware
.remove	pci_device_remove	Driver::remove(&DeviceInfo) -> Result<(), DriverError>	(no remove path at all)	full lifecycle
.suspend / .resume	pci_pm_runtime_*	Driver::suspend() / resume() (default Ok)	(no path)	graceful shutdown + wake
.id_table	pci_match_device	Driver::match_table() -> &[DriverMatch]	legacy match_function()	unify on DriverMatch
.shutdown	pci_device_shutdown	(not in trait)	(no path)	add to trait or handle via systemd
.err_handler	pcie_do_recovery	(not in trait)	(no path)	add Driver::on_error()
.driver_managed_dma	iommu_device_use_default_domain	(not in trait)	(no path)	add Driver::dma_managed()

2.2 CachyOS pattern surface (CachyOS-Settings master)

Pattern	CachyOS location	Red Bear equivalent
udev rule w/ subsystem match + sysfs write	usr/lib/udev/rules.d/60-ioschedulers.rules (HDD/SSD/NVMe scheduler assignment)	driver-manager scheme event set_io_scheduler(dev, "bfq"|"mq-deadline"|"kyber")
udev rule w/ bind/unbind lifecycle	usr/lib/udev/rules.d/71-nvidia.rules (NVIDIA PM lifecycle)	driver-manager register_add_event + register_remove_event matching on vendor + class
Cross-subsystem reaction (battery state → audio params)	usr/lib/udev/rules.d/20-audio-pm.rules (snd_hda_intel powersave)	driver-manager event filter {AC=>BATT} → action set_param(driver, "power_save", value)
Sentinel-based idempotency	/run/udev/snd-hda-intel-powersave	driver-manager in-memory init_done: BTreeSet<(driver_name, param_set)>
modprobe.d blacklist	usr/lib/modprobe.d/blacklist.conf (blacklist iTCO_wdt)	/etc/driver-manager.d/00-blacklist.conf: [[blacklist]] module = "iTCO_wdt"
modprobe.d options	usr/lib/modprobe.d/amdgpu.conf (options amdgpu si_support=1)	/etc/driver-manager.d/50-amdgpu.conf: [amdgpu.params] si_support = true
modules-load.d	usr/lib/modules-load.d/ntsync.conf (ntsync)	/etc/driver-manager.d/autoload.d/ntsync.conf: module = "ntsync"
Driver mutual exclusion (two drivers claim same PCI IDs)	usr/lib/modprobe.d/amdgpu.conf (amdgpu SI/CIK ↔ radeon SI/CIK off)	driver-manager priority + explicit exclusive_with field
Path-triggered (config change) service activation	usr/lib/udev/rules.d/85-iw-regulatory.rules + cachyos-iw-set-regdomain.{path,service}	driver-manager + scheme watcher over /etc/driver-manager.d/
Ramdisk driver manifest (mkinitcpio hook ordering)	linux-cachyos preset (microcode/modconf/kms/block/filesystems/fsck)	/usr/lib/driver-manager.d/initfs.manifest (ramdisk_drivers = ["ahci", "nvme", "redoxfs"], ordered)
Cold-boot parameter injection (immutable module params)	modprobe.d/options ...	driver-manager set_pre_spawn_param(driver, param, value) recorded in BOOT_TIMELINE
Curated-policy-as-a-package (cachyos-settings)	cachyos-settings ARCH package	redbear-driver-policy local recipe (or redbear-meta extension)

2.3 Capability table — what a full driver-manager must provide (C1–C18)

Note: the "Priority" column uses P0/P1/P2 as capability-priority labels — not phase references. The P0/P1/P2 capability priorities pre-date the § 5 D/C phase restructure. Capability priorities are:

• P0 (capability priority) = blocker for desktop path
• P1 (capability priority) = desktop-ready
• P2 (capability priority) = production-grade

These priorities map onto specific phases in § 5.1 D-Phase (P0 set lands in D1; P1 set lands in D2/D3; P2 set lands in D2/D4).

#	Capability	Linux equivalent	driver-manager API	Priority	Notes
C1	ID-table match + dynamic ID add	pci_match_device + sysfs new_id / remove_id	DeviceManager.register_driver() + match_table() + add_dynid()	P0	Already present in redox-driver-core. add_dynid not yet exposed in driver-manager; D1 must wire it
C2	Device lifecycle (probe/remove)	pci_device_probe / pci_device_remove	Driver::probe(&DeviceInfo) + Driver::remove(&DeviceInfo)	P0	Already present. driver-manager calls Driver::probe only after claim + dependency check
C3	Enable / disable device	pci_enable_device / pci_disable_device	enable_device(pci_addr) → pcid EnableDevice request	P0	driver-manager must call pcid EnableDevice BEFORE spawning the child
C4	BAR request/release	pci_request_regions / pci_release_regions	channel open (exclusive ENOLCK) + BAR map via pcid_interface::map_bar	P0	Resolved at v3.0: <addr>/bind never existed; claim == channel (P0-1)
C5	BAR map / unmap	pci_ioremap_bar / pci_iounmap	child scheme:memory/physical@<wc|wb|uc> via redox_driver_sys::pci::PciDevice::map_bar	P0	Not a manager task — child uses redox-driver-sys directly
C6	Bus master on/off	pci_set_master / pci_clear_master	set_bus_master(pci_addr, true)	P0	driver-manager sets on probe, clears on remove
C7	Allocate IRQ vectors	pci_alloc_irq_vectors	pci_alloc_vectors(pci_addr, min, max, flags) -> vector_count	P0	driver-manager proposes; child daemon allocates via PcidClient
C8	Resolve vector → IRQ handle	pci_irq_vector	pci_vector_handle(pci_addr, index) -> scheme:irq fd	P0	child uses scheme:irq directly
C9	Runtime PM	pci_pm_runtime_*	set_power_state(pci_addr, D0|D3hot|D3cold)	P1	pcid SetPowerState request exists; driver-manager exposes it (lands in D2)
C10	Save/restore config space	pci_save_state / pci_restore_state	child uses PcidClient::read_config()	P1	not a manager concern
C11	Driver override	sysfs driver_override	set_driver_override(pci_addr, driver_name)	P1	driver-manager exposes it as a scheme op (writes pci_addr/override) — D2
C12	Config space read/write	pci_read_config_*	child uses PcidClient::read_config() / write_config()	P0	not a manager concern
C13	AER error recovery	pci_error_handlers + pcie_do_recovery	Driver::on_error(error_kind) -> RecoveryAction	P2	Lands in D2 (AER recovery is part of the modern technology surface)
C14	Hotplug events (PDC / DLLSC / MRL)	pciehp_*	manager.subscribe_hotplug() -> HotplugEvent	P1	Requires event-driven scheme:pci surface; D3 delivers event-driven hotplug
C15	DMA mask / IOMMU	dma_set_mask + iommu_device_use_default_domain	set_dma_mask(pci_addr, bits) + iommu_assign_group(pci_addr)	P2	iommu daemon present (local/recipes/system/iommu/); wiring lands in D2 (modern tech surface)
C16	Find capabilities	pci_find_capability / pci_find_ext_capability	child uses redox_driver_sys::pci::PciDevice::find_capability	P0	not a manager concern
C17	INTx on/off	pci_intx	child via PcidClient	P1	not a manager concern
C18	System PM (suspend/resume)	pci_pm_*	Driver::suspend() / resume() callbacks via manager	P2	driver-manager keeps a registry of bound drivers for the systemd-supervisor to call; D2

Source-of-truth invariant: C7 (vector allocation) is implemented inside pcid itself, not in driver-manager. driver-manager's role is to (a) call enable_device through pcid before spawning, (b) hand the channel FD to the child, and (c) call remove (which clears bus master + sends ULP/cleanup requests) when a device disappears from hotplug. The same split holds for C5, C12, C16, C17: those are the child's contract via redox-driver-sys.

2.4 boot-timeline and observability alignment

Note: the "Priority" column reuses P0/P1/P2 as capability-priority labels (the same priority ladder used in § 2.3) — not phase references. Capacity deliveries for these priorities land in the § 5 D-Phase track (P0 set in D1; P1 set in D2/D3; P2 set in D4). AER-aware reset handling (P1 here) is part of D2's modern-technology surface.

Linux surface	driver-manager equivalent	Status	Priority
dmesg pci ... BAR X set to ...	BOOT_TIMELINE_PATH = /tmp/redbear-boot-timeline.json (already present)	✅ exists	(D0)
journalctl -k	scheme:driver-manager:/events (read-only ring buffer, 256 lines)	✅ exists	(D0)
lspci -v	scheme:driver-manager:/devices/<addr> (vendor / device / class / driver / enabled=true)	🟡 partial	P0
lspci -vv -s ... + lspci -xxx -s ...	not exposed	not yet	P0
find /sys/bus/pci/devices -name reset	not exposed	not yet	P1 — needed for AER + reboot (D2)
pci=nomsi kernel cmdline	REDBEAR_DRIVER_MANAGER_FLAGS=disable_msi env	not yet	P1
pci=realloc=	not exposed	not yet	P2
lspci -tv (tree)	scheme:driver-manager:/tree (planned)	not yet	P2

---

3. Target architecture

3.1 Process model (post-migration)

                    ┌─────────────────────────────────────────────┐
                    │            DRIVER-MANAGER (PID 1 child)     │
                    │  ▸ Subscribes to /scheme/pci as a client   │
                    │  ▸ Owns Driver trait objects from TOML      │
                    │  ▸ Maintains Bus → Device → Driver graph   │
                    │  ▸ Claims via channel open (ENOLCK)       │
                    │  ▸ Spawns driver daemons with:             │
                    │    PCID_CLIENT_CHANNEL=<fd>                │
                    │    PCID_SEGMENT / PCID_BUS / PCID_DEVICE   │
                    │    PCID_FUNCTION  (Red Bear P4 contract)   │
                    │  ▸ Registers scheme:driver-manager         │
                    │  ▸ Writes /tmp/redbear-driver-params/...   │
                    │  ▸ Writes /tmp/redbear-boot-timeline.json  │
                    │  ▸ On hotplug (P1): detects add/remove     │
                    │  ▸ On AER (P5): invokes error handler     │
                    └───────────────────┬─────────────────────────┘
                                        │
            ┌───────────────────────────┼──────────────────────────┐
            ▼                           ▼                          ▼
   ┌────────────────────┐   ┌────────────────────┐    ┌────────────────────┐
   │       PCID         │   │   SCHEME:PCI       │    │ REDOX-DRIVER-SYS   │
   │  (Canonical PCI    │   │  (per-device       │    │  (registered       │
   │   scheme owner)    │◀──│   channel+bind+    │    │   quirk surface)   │
   │                    │   │   config+feature)  │    │  /scheme:driver-sys│
   └─────────┬──────────┘   └─────────┬──────────┘    └────────────────────┘
             │                        │
             │  /scheme/memory        │
             │  /scheme/irq           │
             │  /scheme:acpi          │
             │  /scheme/iommu (P5)    │
             ▼                        ▼
       ───────────  KERNEL  ───────────

3.2 New component list

Component	Lives at	Source-of-truth	Phase
driver-manager daemon	local/recipes/system/driver-manager/source/	local recipe (Cat 1)	built in D0–D5, enabled at C0
driver-manager-config package	local/recipes/system/driver-manager-config/ (NEW)	local recipe (Meta)	D4 (policy layer)
/etc/driver-manager.d/*.toml configs	NEW dir, shipped by driver-manager-config	policy	D4
/lib/drivers.d/*.toml	NEW dir, per-config files	match tables	D1 (format); D4 (content)
00_driver-manager.service	local/sources/base/init.d/	service	C0 (created dormant); C3 (active)
40_driver-manager-initfs.service	local/sources/base/init.initfs.d/	service	C0 (dormant); C2 (active blocking)
local/recipes/system/driver-params	already exists; extends to consume scheme:driver-manager rather than its own bound-text-parsing	observer	C1 (switch over)
redbear-driver-policy package	local/recipes/system/redbear-driver-policy/ (NEW)	curated package	D4 (created); C3 (packaged)

3.3 What changes for pcid-spawner (NOT deleted, demoted)

The v1.1 D/C phase restructure changes pcid-spawner's role as follows:

Track / Phase	pcid-spawner state
D-phase (D0–D5)	No change. pcid-spawner remains the live boot path. driver-manager is being built locally but is NOT shipped, NOT packaged, NOT enabled. The boot path is identical to baseline.
C0	00_pcid-spawner.service gains ConditionPathExists=!/etc/driver-manager.d/disabled. Service is dormant by default.
C1	driver-manager runs in --observe mode (writes BOOT_TIMELINE, does NOT spawn). pcid-spawner is still the actual spawner.
C2	40_driver-manager-initfs.service becomes oneshot blocking in initfs; pcid-spawner initfs service becomes fallback only via ConditionPathExists.
C3	00_driver-manager.service becomes the primary rootfs spawner. 00_pcid-spawner.service is retained as fallback only (idem for initfs variant).
C4	pcid-spawner source tree receives a final commit on the submodule/base branch documenting the maintenance-mode status. Never deleted.

3.4 Wire-level contracts that MUST stay invariant

Contract	Description	Invariant
C-ENV-1	PCID_CLIENT_CHANNEL=<fd> is passed to every spawned driver daemon	Preserved by config.rs::probe() already
C-ENV-2	PCID_SEGMENT/PCID_BUS/PCID_DEVICE/PCID_FUNCTION env vars (Red Bear P4)	Preserved — driver-manager's probe path must add them
C-ENV-3	Program resolution: absolute OR /usr/lib/drivers/<name>	Preserved — same prefix logic moves to driver-manager
C-CHAN-1	Per-device channel open in scheme:pci yields mutual-exclusion (ENOLCK to second opener)	Not the responsibility of driver-manager — that's pcid. driver-manager must use bind (NOT channel) so multi-driver retry can re-probe without consuming the lock. Confirm with pcid that bind is also exclusive, or document the asymmetry.
C-CHAN-2	Drivers call PciFunctionHandle::connect_default() and get a working bincode channel via the FD	Continues unchanged
C-SVC-1	Every service that previously requires_weak=00_pcid-spawner.service gains requires_weak=00_driver-manager.service as an alternative. Driver-manager has requires_weak=00_pcid-spawner.service for fallback coordination.	Provides fallback-safety
C-DAEMON-1	daemon::Daemon::spawn() blocks parent on child ready	driver-manager must use the same primitive to preserve the boot-order guarantee — ahcid/nvmed up before redoxfs mounts
C-RECIPE-1	recipes/core/base/drivers/pcid-spawner/recipe.toml keeps path = "../../../local/sources/base/drivers/pcid-spawner"	Never changes
C-SCHEME-1	scheme:driver-manager exposes: /devices, /devices/<addr>, /bound, /events (read-only)	Already present
C-PARAM-1	driver-params reads from /scheme/driver-manager/bound (instead of its current text-parsing of the bound file)	C1 wiring

3.5 Module / crate dependencies (target state)

recipes/system/driver-manager/source/Cargo.toml  ─── D0 plus phase-by-phase additions
├── redox-driver-core           (already: local/recipes/drivers/redox-driver-core)
├── redox-driver-pci           (already: local/recipes/drivers/redox-driver-pci)
├── redox-driver-sys           (NEW dep  ─ added at D4; previously optional, now required)
├── pcid_interface             (already: local/sources/base/drivers/pcid)
├── redox-scheme               (already: local/sources/redox-scheme)
├── redox_syscall              (already: local/sources/syscall, features=["std"])
├── log, toml, serde           (already)
├── event-stream               (NEW in D3 — for hotplug event consumption)
├── bitflags                   (NEW in D2 — for CapabilityFlag aggregation)
└── [patch.crates-io]          (already: redox_syscall, libredox, redox-scheme)

pcid-spawner Cargo.toml is untouched (it stays in the base submodule fork for fallback). No retroactive changes to daemon::Daemon::spawn, PciFunctionHandle::connect_default, or any of the 17 driver daemons.

---

4. Critical risk register

#	Risk	Severity	Mitigation
R1	Double-spawn race: driver-manager and pcid-spawner both spawn the same driver daemon	🔴 BLOCKING	C1 sequencing: driver-manager runs only in --observe mode first. The actual spawn is gated by spawn_enabled flag set by the C1 exit gate. 00_driver-manager.service is dormant in C0; observable in C1; primary in C3.
R2	Driver daemon crashes after spawn, no one restarts it	🔴 BLOCKING	driver-manager persists bound_devices map to /tmp/redbear-driver-params/. On WAIT_FOR_REAPPEAR per-driver (delivered in D2) the manager retries after a 5s backoff. systemd Restart= on the driver service files provides the surface-process fallback (D4).
R3	The match table migration misses a vendor/device pair	🔴 BLOCKING	D1 adds "no-match ↔ spin in driver-manager, no spawn" tests for the existing 17 drivers. C1 runs both managers side-by-side and emits unbound_device_addr=<addr> lines to BOOT_TIMELINE for any device the new manager misses but pcid-spawner bound.
R4	The bind vs channel claim differs in exclusivity	🟡 HIGH	D1 step is a QEMU test that opens bind from one driver and channel from another; verifies the latter gets ENOLCK. Document the asymmetry.
R5	Initfs switchroot breaks (storage drivers must be ready before redoxfs mounts)	🔴 BLOCKING	C2 keeps 40_pcid-spawner-initfs.service available (via ConditionPathExists). 40_driver-manager-initfs.service is added in observation mode at C0 and only switches on at C2 once the storage path passes on at least 3 hardware configs (QEMU virtio + AMD NVMe + Intel SATA).
R6	redox-driver-sys quirks not consulted during spawn decisions	🟡 MEDIUM	D4 phase. Until then, the kernel-side MSI/MSI-X fallback in pcid remains authoritative. No regression on bare metal.
R7	Atomic patch governance failure: live source edit goes unmirrored	🟡 (procedural)	Every source edit during this plan is committed to the submodule/base branch (for pcid-spawner edits) or as commits within local/recipes/system/driver-manager/source/ (which is a local-recipe tree, not a fetched source tree). Per local/AGENTS.md DURABILITY POLICY.
R8	The new scheme:driver-manager collides with scheme:driver-params	🟡 MEDIUM	C-PARAM-1 above resolves this: driver-params becomes a thin observer over scheme:driver-manager:/bound, no separate parsing path. Wired at C1.
R9	The migration leaves the repo in a state that cannot fall back	🔴 BLOCKING	During D-phase, no boot path is affected (driver-manager is not in the system). During C-phase, both managers may run; pcid-spawner is the fallback at every cutover step (ConditionPathExists=!/etc/driver-manager.d/disabled gates it). At no phase is the boot path single-point-of-failure.
R10	The TOML match-table migration produces a silent NO-OP for an edge device (e.g., ID 0x1234:0x5678 not in any entry → driver never binds)	🟡 HIGH	D1 implements missing_match = warn so any unresolved match is logged. QEMU tests with the 17 known drivers verify each entry before C3.
R11	The redox-driver-core DeviceManager::probe_device locks the entire manager mutex for the duration of a probe, blocking retry_deferred for slow drivers	🟡 MEDIUM	D2 introduces per-driver Mutex<DriverState> for finer-grained concurrency; manager's outer mutex held only during dispatch.
R12	Device hot-add during switchroot causes race with pcid (which may re-enumerate)	🟡 MEDIUM	Hotplug is off during initfs → rootfs transition. driver-manager starts in --hotplug=off until switchroot completes.
R13	D-phase work produces a stub or workaround instead of comprehensive code	🔴 BLOCKING	local/scripts/driver-manager-audit-no-stubs.py (D4 deliverable) is the formal gatekeeper. Static analysis + QEMU integration test. Any D-phase work that violates § 0.5 fails the D4 audit and blocks D5 ratification. No partial-credit D5 exit.
R14	driver-manager enters a boot path before D5 ratification (i.e., someone packages it earlier than planned)	🔴 BLOCKING	Build-system guard: local/scripts/build-redbear.sh and the cookbook CI refuse any commit that adds driver-manager to [packages] in config/redbear-*.toml during D-phase. Documented in § 0.6.

Out-of-scope (deferred to OTHER plans)

• USB / ACPI / platform buses → local/docs/USB-IMPLEMENTATION-PLAN.md, local/docs/ACPI-IMPROVEMENT-PLAN.md
• GPU render / DRM completion → local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md
• Wi-Fi / Bluetooth → local/docs/WIFI-IMPLEMENTATION-PLAN.md, BLUETOOTH-IMPLEMENTATION-PLAN.md
• IRQ / MSI-X quality → local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md
• IOMMU runtime proof → still QEMU-only per HardWARE matrix
• Replacement of pcid (the scheme:pci owner) — far future, no decision today

---

5. Phased migration plan

The migration has two tracks operating sequentially, not interleaved:

• D-Phase (Parallel Development). driver-manager is being built; pcid-spawner remains the live boot system. No boot path is affected. This phase starts at D0 (current state) and continues through D5 (feature-complete gate). The team's parallel development work lives here.
• C-Phase (Cutover & Validation). driver-manager is fully built; the boot path is switched over from pcid-spawner to driver-manager in stages. C0 starts only after D5 + operator ratification.

Authority: the § 0.6 Parallel Development constraint is binding. driver-manager does NOT enter any boot path until D5 ratifies. The original v1.0 P0–P6 dual-mode strategy is folded into the C-phases.

5.1 D-Phase — Parallel Development

State during D-Phase:

• pcid-spawner is the boot path in every redbear-*.toml.
• driver-manager is built locally (committed to local/recipes/system/driver-manager/source/) but NOT shipped.
• driver-manager has no 00_driver-manager.service.
• No files in /etc/driver-manager.d/ are read by the live system.
• No [packages] entry contains driver-manager.
• The team's work is recorded in commits to the local recipe source.

Phase D0 — Foundation (current state)

Status (2026-07-20): partially complete.

What exists:

• redox-driver-core framework: Bus trait, Driver trait, DeviceManager, DriverMatch, DriverParams, ProbeEvent, ProbeResult. Compiled with 12 unit tests.
• redox-driver-pci::PciBus reads /scheme/pci/, parses PCI config space, returns DeviceInfo with vendor/device/class/subclass/prog_if/revision/ subsystem IDs.
• local/recipes/system/driver-manager/source/src/{main.rs,config.rs,scheme.rs,hotplug.rs,exec.rs} — 1250 lines compiling to a 783KB ELF.
• scheme:driver-manager registered with /devices, /bound, /events, /devices/<addr> paths (read-only).
• Boot timeline JSON at /tmp/redbear-boot-timeline.json.

What does NOT yet exist (D1–D5 work):

• Linux 7.x capability bridge: C9, C11, C13, C14, C15, C17, C18 are absent
• Modern technology surface integration (SMP-aware concurrent probe, S/P-state hooks, runtime PM, AER)
• Event-driven hotplug (current code polls every 2s)
• Quirk integration with redox-driver-sys (no redox-driver-sys import in source/Cargo.toml)
• Format-coexistence TOML loader (current loader only accepts new [[driver]] format)

Exit criteria for D0:

1. cargo build --release -p driver-manager clean.
2. cargo test -p redox-driver-core 12/12 green.
3. local/recipes/system/driver-manager/target/x86_64-unknown-redox/stage/usr/bin/driver-manager exists.
4. No 00_driver-manager.service in any init.d.
5. No driver-manager = {} in any [packages] section.

Phase D1 — Linux 7.x capability bridge (target: 6–10 weeks)

Preconditions: D0 exit criteria met.

Goal: Implement every P0 capability from § 2.3 (C1, C2, C3, C4, C5, C6, C7, C8, C12, C16).

Deliverables:

• redox-driver-core::driver::Driver trait gains full suspend() / resume() / on_error() / params() implementations with concrete behaviour (not stubs — see § 0.5).
• redox-driver-core::bus::Bus trait gains event-driven subscribe_hotplug() implementation in PciBus.
• local/recipes/system/driver-manager/src/manager-probe.rs (new module) handles the SpawnDecision committee (C2', C3, C4, C6).
• Format-coexistence TOML loader accepting both [drivers] (legacy pcid-spawner) and [[driver]] (driver-manager) formats from the same directory tree.
• New test script local/scripts/test-driver-manager-parity.sh (used in C1, but drafted here).

Exit criteria for D1:

1. Every P0 capability of C1–C18 is implemented and unit-tested.
2. local/scripts/test-driver-manager-parity.sh returns identical bound sets under both formats.
3. Integration test (QEMU + all 17 drivers) shows driver-manager can shadow pcid-spawner exactly.

Phase D2 — Modern technology surface (target: 8–12 weeks)

Preconditions: D1 exit criteria met.

Goal: Integrate SMP-aware concurrent probe, C/P-state coordination, runtime PM hooks, IOMMU groups, MSI-X vector allocation, AER recovery (see § 0.4 for the full tech surface).

Deliverables:

• redox-driver-core::manager::DeviceManager::probe_device becomes truly concurrent (std::thread::scope or rayon, max_concurrent_probes enforced).
• MSI-X vector allocation with per-vector fds exposed via redox-driver-sys::irq::MsixTable.
• Per-driver P-state advisory publisher (interacts with cpufreqd).
• C-state coordination hook with cpufreqd / thermald.
• IOMMU group registration via local/recipes/system/iommu/.
• D-state transitions (D0 ↔ D3hot ↔ D0) through pcid's SetPowerState request.

Exit criteria for D2:

1. Concurrent probe dispatch verified (max_concurrent_probes = 4 shows 4-way parallelism in QEMU timings).
2. Per-driver P-state advisory verified on real AMD/Intel hardware.
3. IOMMU-group-aware binding demonstrated on at least one QEMU + vfio-passthrough run.
4. Runtime PM suspend/resume callback chain verified.

Phase D3 — Hotplug event-driven (target: 4–6 weeks)

Preconditions: D2 exit criteria met.

Goal: Replace polling-based hotplug with event-driven subscription.

Deliverables:

• Bus::subscribe_hotplug() returns HotplugSubscription mapping to a real event fd (via Bus::poll_hotplug_events() or equivalent).
• PciBus consumes /scheme/pci/events (requires pcid scheme event delivery — feature request to pcid maintainer).
• Manager::hotplug_loop() becomes event-driven, removing the 2-second poll entirely.

Exit criteria for D3:

1. Hotplug event arrival latency < 200 ms on QEMU synthetic add/remove.
2. Real-hardware hotplug (PCIe Native or USB) verified on at least one AMD and one Intel bare-metal target.

Phase D4 — Quirk integration + comprehensive audit (target: 6–8 weeks)

Preconditions: D3 exit criteria met.

Goal: Wire redox-driver-sys::PciQuirkFlags into bind/remove decisions; complete feature audit confirming § 0.5 compliance.

Deliverables:

• local/recipes/system/driver-manager/source/Cargo.toml adds redox-driver-sys as path dep.
• manager-probe.rs consults PciQuirkFlags::NO_MSIX, NO_PME, NEED_FIRMWARE, DISABLE_ACCEL, etc., during spawn decisions.
• Audit script local/scripts/driver-manager-audit-no-stubs.py runs against the source tree and confirms: every public trait method has a concrete implementation, no unimplemented!(), no todo!(), no #[allow(dead_code)] for production code paths, no Ok(()) defaults in trait methods that have a real responsibility (per § 0.5 matrix).
• Quirk policy delivered: /etc/driver-manager.d/{00-blacklist.conf, 50-amdgpu.toml,autoload.d/ntsync.conf} patterns work as designed.

Exit criteria for D4:

1. driver-manager-audit-no-stubs.py reports zero violations.
2. Quirk-driven spawn decisions match expected behaviour (e.g., DISABLE_ACCEL causes redox-drm --no-render to be invoked).
3. Hardware-validation-matrix AMD Threadripper + Intel Alder Lake both pass.

Phase D5 — Feature-complete gate (audit before cutover)

Preconditions: D4 exit criteria met, operator ratification.

Goal: Formal declaration that driver-manager is feature-complete and ready to cut over.

Deliverables:

• Audit document local/docs/evidence/driver-manager/D5-AUDIT.md listing every C1–C18 capability with status (✅ Production / 🟡 Build-grade / 🔴 Not Implemented).
• Updated local/docs/HARDWARE-VALIDATION-MATRIX.md with driver-manager rows.
• This document's Last reviewed line updated to the D5 completion date.
• Operator's written ratification (chat log, email, or commit message).

Exit criteria for D5:

1. Every entry on the C1–C18 table is at least 🟡 Build-grade.
2. The § 0.5 no-stub audit is clean (audit script returns 0).
3. Hardware validation matrix passes on at least one AMD and one Intel profile with at least 3 driver categories each (storage, network, GPU).
4. The § 0.2 success criteria 1–6 are met (criteria 7–10 are C-phase criteria).
5. Operator has ratified in writing.

At this point, the D-phase work is OVER. The C-phase begins.

5.2 C-Phase — Cutover & Validation

The C-phase begins only after D5 ratifies. The cutover is sequential, gated, and operator-ratified at every phase boundary. The cutover does NOT require pcid-spawner to be removed — it stays as a ConditionPathExists fallback.

Phase C0 — Service wiring (dormant service file)

Preconditions: D5 complete.

Goal: Add the dormant service file and [packages] entry. Driver-manager remains inactive.

Deliverables:

• local/sources/base/init.d/00_driver-manager.service (NEW, dormant by default — never auto-starts).
• local/sources/base/init.initfs.d/40_driver-manager-initfs.service (NEW, dormant by default).
• local/sources/base/init.d/00_pcid-spawner.service gains ConditionPathExists=!/etc/driver-manager.d/disabled (auto-skip when driver-manager is operational; remains the actual spawner in C0).
• config/redbear-{mini,full,grub,device-services,greeter-services}.toml add driver-manager = {} to [packages].
• [packages] removal of pcid-spawner does NOT happen in C0.

Acceptance test:

[ BOOT ] init: 00_pcid-spawner.service running
[ BOOT ] init: 00_driver-manager.service skipped (dormant)
[ PASS ] C0: pcid-spawner still spawns; driver-manager binary present but inactive

Exit criteria for C0:

1. ISO boots identically to pre-C0 baseline.
2. make lint-config clean.
3. scripts/validate-collision-log.sh clean.
4. driver-manager-audit-no-stubs.py still clean.

Phase C1 — Dual-mode observation

Preconditions: C0 exit criteria met.

Goal: driver-manager runs in --observe mode (no spawn). Both managers see the same devices. Parity confirmed before any actual spawn.

Deliverables:

• 00_driver-manager.service runs in --observe mode (writes BOOT_TIMELINE, no spawn).
• 00_pcid-spawner.service is still the actual spawner.
• Both managers write parity data to their BOOT_TIMELINE files.
• local/scripts/test-driver-manager-parity.sh runs as a CI gate.

Acceptance test:

[ BOOT ] driver-manager: enumerate begin (observe)
[ BOOT ] driver-manager: enumeration complete: 17 bound (observe), 0 deferred
[ BOOT ] pcid-spawner: spawn e1000d for 0000:00:03.0
[ BOOT ] driver-manager: 17/17 binds agree with pcid-spawner
[ BOOT ] driver-manager: BOOT_TIMELINE written
[ PASS ] C1: parity clean

Exit criteria for C1:

1. test-driver-manager-parity.sh clean in 5 back-to-back QEMU runs.
2. Real-hardware parity verified on AMD Threadripper + Intel Alder Lake.
3. Both managers' BOOT_TIMELINE files match.

Phase C2 — Initfs switchover

Preconditions: C1 exit criteria met, operator ratification.

Goal: driver-manager becomes the initfs spawner (storage drivers).

Deliverables:

• 40_driver-manager-initfs.service becomes oneshot (blocking) and replaces 40_pcid-spawner-initfs.service in initfs.
• pcid-spawner initfs service moves to ConditionPathExists=!/etc/driver-manager.d/initfs-active fallback.
• local/scripts/test-driver-manager-initfs.sh clean.

Acceptance test:

[ INITFS ] driver-manager-initfs: storage drivers ready (ahcid/nvmed/virtio-blkd/ided)
[ INITFS ] redoxfs: mount /dev/redoxfs /scheme/root ✓
[ INITFS ] switchroot: /usr loaded
[ PASS ] C2: initfs path via driver-manager

Exit criteria for C2:

1. Initfs-only QEMU run completes with driver-manager and the switchroot happens within 5 s.
2. AHCI + NVMe + virtio-blkd paths tested on at least one AMD and one Intel system.
3. pcid-spawner-initfs fallback can be activated by deleting /etc/driver-manager.d/initfs-active, and the boot still completes.

Phase C3 — Rootfs switchover

Preconditions: C2 exit criteria met, operator ratification.

Goal: driver-manager becomes the primary rootfs spawner.

Deliverables:

• 00_driver-manager.service becomes the primary rootfs spawner.
• 00_pcid-spawner.service is retained as fallback only.
• local/scripts/test-driver-manager-active.sh runs end-to-end.
• driver-params switches to consuming scheme:driver-manager:/bound.

Acceptance test:

[ BOOT ] driver-manager: registered scheme:driver-manager
[ BOOT ] driver-manager: load_all: 7 config files, 17 drivers registered
[ BOOT ] driver-manager: enumeration complete: 17 bound, 0 deferred
[ BOOT ] driver-manager: hotplug: starting event loop (event-driven)
[ PASS ] C3: driver-manager is the active rootfs spawner

Exit criteria for C3:

1. test-driver-manager-active.sh clean in 5 back-to-back QEMU runs.
2. driver-params via scheme:driver-manager produces correct driver list.
3. parity test (C1's) keeps reporting identical binds.

Phase C4 — Operator-ratified production cutover

Preconditions: C3 exit criteria met, operator ratification, two-week soak, three hardware reboots with identical driver-bound sets.

Goal: pcid-spawner moves to maintenance-mode fallback. Status rows update.

Deliverables:

• pcid-spawner source tree receives a final commit on submodule/base documenting the maintenance-mode status.
• local/docs/UPSTREAM-SYNC-PROCEDURE.md § "driver-manager: Deferred" replaced with "driver-manager: production".
• README.md status row updates.
• local/AGENTS.md § PLANNING NOTES pointer updates.
• Inline deferred comments in config/redbear-mini.toml:31 and config/redbear-device-services.toml:9-13 removed.

Exit criteria for C4:

1. Two-week soak completes with no ConditionPathExists guard firing.
2. Three consecutive bare-metal reboots produce identical driver-bound sets.
3. Hardware validation matrix shows parity or improvement on every row.
4. Operator ratification documented in local/docs/evidence/driver-manager/C4-RATIFICATION.md.

At no point is pcid-spawner DELETED. It moves to "always-shipped, on-disk fallback" alongside 00_driver-manager.service.

---

6. Per-phase dependency diagram

The D-phase and C-phase tracks are sequential under § 0.6's parallel development constraint:

   D-PHASE: Parallel Development                   C-PHASE: Cutover & Validation
   (driver-manager being built;                    (driver-manager enabled;
    pcid-spawner is the live system)                pcid-spawner demoted to fallback)

   D0 ─► D1 ─► D2 ─► D3 ─► D4 ─► D5  ─── operator ratification + feature-complete gate ───  C0 ─► C1 ─► C2 ─► C3 ─► C4
   │      │     │     │     │     │                                                           │     │     │     │     │
   ▼      ▼     ▼     ▼     ▼     ▼                                                           ▼     ▼     ▼     ▼     ▼
  fnd    cap   tech  hp    quk   audit                                                       svc   obs   ifs   rfs   prod
  frame bridge face  ev    int   (no stubs)                                                  wir   dual  sw    sw    cut
  present      +PM    ent-  gra-  + HW validate                                              e    mode  itc   itc   over
              +AER   drive ted   dom                                                         dor          ove   ove   (op
              +IOM                                                                       (dor           r    r    era
              MU                                                                          man           (do  (do    tor
              +MS                                                                       t)             t)   t)    ra
              I-X                                                                                                  tif
                                                                                                                    ied
                                                                                                                    )

                  │                                                                           │
                  └──── During D-phase, pcid-spawner remains the boot path.            During C-phase, both
                       No boot path is changed.                                             managers may run; pcid-spawner
                                                                                            is the fallback at every cutover step.

Phase key:

• D0: Foundation (current state)
• D1: Linux 7.x capability bridge (C1–C18 P0 set)
• D2: Modern technology surface (SMP, S/P states, runtime PM, IOMMU, AER, MSI-X)
• D3: Hotplug (event-driven)
• D4: Quirk integration + comprehensive audit (no stubs)
• D5: Feature-complete gate (operator ratification)
• C0: Service wiring (dormant service file)
• C1: Dual-mode observation
• C2: Initfs switchover
• C3: Rootfs switchover
• C4: Operator-ratified production cutover

The workstream structure deliberately mirrors local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md (Phase 1–5) and local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md (Workstream A–E) to keep the project's planning grammar consistent.

---

7. Test scripts (local/scripts/)

All scripts land in local/scripts/ per project convention and follow the existing naming (test-X.sh for shell, test-X-y.sh for variants). Each script returns exit 0 on success, emits a [PASS] line, and writes a log to local/docs/evidence/driver-manager/.

Script	Phase (D / C)	Purpose	Exit code signal
test-driver-manager-parity.sh	C1 (drafted in D1)	Both managers active, observation only; verify they agree on every device-id-to-driver mapping	0 = same set bound
test-driver-manager-active.sh	C3	driver-manager primary; pcid-spawner fallback; verify all 17 drivers	0 = all expected drivers present
test-driver-manager-initfs.sh	C2	initfs use only; verify storage drivers come up before redoxfs	0 = redoxfs mounted
test-driver-manager-hotplug.sh	D3 (gate)	Hotplug add/remove cycle; unbind/rebind sequence	0 = unbind + rebind within budget
test-driver-manager-pm.sh	D2 (gate)	Suspend/resume cycle, parameter write-through	0 = clean suspend+resume
test-driver-manager-cutover.sh	C4	Final acceptance: identical driver set before/after cutover	0 = no diff in bound-set logs
driver-manager-audit-no-stubs.py	D4 (gate)	Static analysis that the source contains no unimplemented!(), no todo!(), no Ok(()) trait-method defaults — per § 0.5	0 = no violations
test-driver-manager-no-stubs-qemu.sh	D4 (gate)	QEMU run with synthesized edge-case devices exercising every P0 capability C1–C18	0 = every test bus emits one bind event

---

8. Cross-cutting concerns

8.1 GPU / DRM

The redox-drm driver daemon currently relies on PciFunctionHandle::connect_default() plus redox-driver-sys::pci::PciDevice. driver-manager must continue passing PCID_CLIENT_CHANNEL for redox-drm to receive a working channel. The match table that triggers redox-drm (30-graphics.toml already in config/redbear-device-services.toml) is consumed by driver-manager; no driver side changes. The redox-driver-sys::PciQuirkFlags policy is consulted in D4 (NEED_FIRMWARE, DISABLE_ACCEL, NO_MSIX). AMD-specific decisions live in local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md — the present plan does not re-open those decisions, it only carries them into the manager's match-time decision logic.

8.2 USB

xhcid, ehcid, ohcid, uhcid, usbhubd, usbscsid, usbhidd, usbaudiod all spawn from /lib/drivers.d/{20-usb,70-usb-class}.toml. These TOMLs exist in config/redbear-device-services.toml (lines 116-490) but are inert today. driver-manager must wake them correctly during C3. The Bus trait will gain a UsbBus in local/docs/USB-IMPLEMENTATION-PLAN.md; that is out of scope for this migration.

8.3 Audio

ihdad, ac97d, sb16d are in 50-audio.toml. These spawn late (no initfs dependency); driver-manager handles them as ordinary bound drivers with priority below storage/network. CachyOS's audio-power management patterns (20-audio-pm.rules) are reflected in D4's depends_on and hotplug hooks for these drivers.

8.4 Storage init path

This is the highest-risk surface. ahcid, ided, nvmed, virtio-blkd, usbscsid, usb-bot MUST be ready before redoxfs mounts. Phase C2's initfs migration has its own gate, and a fallback (40_pcid-spawner-initfs.service via ConditionPathExists) is required at every C-phase before C4.

8.5 Cross-config consistency

The three compile targets (redbear-mini, redbear-full, redbear-grub) all include init services that depend on 00_pcid-spawner.service. All three need the same 00_driver-manager.service substitution. The change is mechanical but must be applied to every [service].requires_weak reference and every [[files]] install in the same PR. make lint-config enforces consistency.

8.6 Doc references

After C3:

• local/AGENTS.md § PLANNING NOTES gets a one-liner pointing here.
• local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md Phase 1 row updates from "🟡 | in progress" to "🟡 | driver-manager parity accepted".
• local/docs/PATCH-GOVERNANCE.md § "Local recipe priority vs upstream WIP" notes that local/recipes/system/driver-manager is the canonical owner.
• local/docs/UPSTREAM-SYNC-PROCEDURE.md § "driver-manager: Deferred" replaced with "driver-manager: live (00_driver-manager.service)".

After C4 (production cutover):

• README.md status row updates to ✅.
• config/redbear-mini.toml:31 and config/redbear-device-services.toml:9-13 inline deferred comments are removed (no longer accurate once driver-manager is live).
• local/docs/UPSTREAM-SYNC-PROCEDURE.md § "driver-manager: Deferred" replaced with "driver-manager: production".

8.7 Branch / submodule policy

Per local/AGENTS.md § BRANCH AND SUBMODULE POLICY, no new submodule is created. driver-manager stays a local recipe under local/recipes/system/driver-manager/. This is preserved at every phase. The 9 declared submodules remain unchanged.

---

9. Appendices

9.1 File map (post-migration, target end state)

Created (tracked):

local/recipes/system/driver-manager/source/src/
├── main.rs                   (modified at D3, D4, C1, C3 across their phases)
├── config.rs                 (modified at D1 [format coexistence], D2 [PM hooks], D3 [event-driven], D4 [quirk integration])
├── scheme.rs                 (modified at D2 [PM scheme surface], D4 [quirk reporting])
├── hotplug.rs                (rewritten at D3 — event-driven)
├── exec.rs                   (removed at D0; spawn was already inlined in config.rs::probe())
├── driver-probe.rs           (NEW at D1 [SpawnDecision committee], evolves D2 [PM dispatch], D4 [AER routing])
└── errors.rs                 (NEW at D0 [error-tag normalisation], evolves D2 [PM error codes])

local/recipes/system/driver-manager/recipe.toml       (no change)
local/recipes/system/driver-manager/source/Cargo.toml (deps added at D2 [bitflags], D3 [event-stream], D4 [redox-driver-sys])

local/sources/base/init.d/00_driver-manager.service          (NEW dormant at C0; evolves C1, C3)
local/sources/base/init.initfs.d/40_driver-manager-initfs.service  (NEW dormant at C0; becomes blocking at C2)

local/config/driver-manager.d/                               (NEW at D4)
├── 00-blacklist.conf
├── autoload.d/ntsync.conf
├── 50-amdgpu.toml
└── initfs.manifest

local/scripts/test-driver-manager-{parity,active,initfs,hotplug,pm,cutover}.sh  (one per phase — see § 7)
local/scripts/driver-manager-audit-no-stubs.py               (NEW at D4; gates D5)

local/recipes/system/driver-params/source/src/main.rs     (modified at C1 to consume scheme:driver-manager:/bound)
local/recipes/system/redbear-driver-policy/                 (NEW at D4; curated policy package; packaged at C3)

Modified (kept tracked):

config/redbear-mini.toml         (C0: driver-manager added to [packages]; superseded comments at C4)
config/redbear-full.toml         (C0: same)
config/redbear-grub.toml         (C0: same)
config/redbear-greeter-services.toml  (C0: same)
config/redbear-device-services.toml   (C0 + D4: driver-manager config inclusion)

local/docs/UPSTREAM-SYNC-PROCEDURE.md  (§ driver-manager: Deferred -> live at C3; -> production at C4)
local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md  (Phase 1 row update at C3)
local/docs/HARDWARE-VALIDATION-MATRIX.md  (multiple rows updated at D5)
README.md  (status row at C4)
AGENTS.md  (no change beyond pointer)
local/AGENTS.md  (PLANNING NOTES section gains pointer)

Untouched (preserved for fallback throughout D/C phases and after C4):

local/sources/base/drivers/pcid-spawner/   (entire tree — fallback for life)
local/sources/base/drivers/pcid/          (unchanged — still the scheme:pci owner)
local/sources/base/init.d/00_pcid-spawner.service  (becomes dormant fallback service at C3)
local/sources/base/init.initfs.d/40_pcid-spawner-initfs.service  (becomes dormant fallback at C2)

local/patches/base/  (all P-numbered patches preserved)
local/recipes/core/pcid-spawner/recipe.toml  (path-fork unchanged)
recipes/core/base/drivers/pcid-spawner/  (path-fork path unchanged)

The 17 driver daemons' source trees and Cargo.tomls.

9.2 Environment variable contract (preserved)

Var	Source	Consumer	Format
PCID_CLIENT_CHANNEL	pcid-spawner (legacy), driver-manager (new)	driver daemon via PciFunctionHandle::connect_default()	ASCII decimal fd
PCID_SEGMENT	both	driver daemon	4-hex (e.g., 0000)
PCID_BUS	both	driver daemon	2-hex (e.g., 03)
PCID_DEVICE	both	driver daemon	2-hex (e.g., 0a)
PCID_FUNCTION	both	driver daemon	decimal
REDBEAR_DRIVER_MANAGER_ACTIVE	env (env file)	driver-manager	0 = observation; non-zero = spawn
DRIVER_PARAMS_LOG	existing	driver-params	one of trace/debug/info/warn/error
DRIVER_PARAMS_BOUND_PATH	existing	driver-params	path string
INIT_NOTIFY	init	driver-params, driver-manager (from C0 onwards)	int fd

9.3 Capability-to-driver matrix

Driver daemon	C3 enable	C4 bar request	C5 map	C6 bus master	C7 vectors	C12 config R/W	C16 caps	C17 INTx
ahcid	✅ via PCID_CLIENT_CHANNEL	implicit via connect	driver-side via redox-driver-sys	yes	MSI via pcid client	yes	yes	yes
ided	same	same	same	yes	n/a	yes	yes	yes
nvmed	same	same	same	yes	MSI-X	yes	yes	yes
virtio-blkd	same	same	same	yes	n/a	yes	yes	yes
e1000d	same	same	same	yes	MSI via redox-driver-sys	yes	yes	yes
rtl8168d	same	same	same	yes	MSI	yes	yes	yes
rtl8139d	same	same	same	yes	INTx	yes	yes	yes
ixgbed	same	same	same	yes	MSI-X	yes	yes	yes
virtio-netd	same	same	same	yes	n/a	yes	yes	yes
ihdgd	same	same	same	yes	MSI-X	yes	yes	yes
virtio-gpud	same	same	same	yes	n/a	yes	yes	yes
xhcid	same	same	same	yes	MSI-X	yes	yes	yes
ihdad	same	same	same	yes	MSI	yes	yes	yes
ac97d	same	same	same	yes	INTx	yes	yes	yes
vboxd	same	same	same	yes	n/a	yes	yes	yes
amd-mp2-i2cd	same	same	same	yes	MSI	yes	yes	yes
intel-thc-hidd	same	same	same	yes	MSI	yes	yes	yes

Crucial invariant: all 17 drivers already fulfil C3–C8, C12, C16, C17 through pcid_interface::PciFunctionHandle::connect_default() followed by PciClient::* calls. driver-manager's role is to deliver a working channel FD into the child's env. No driver rewrite required at any phase.

9.4 TOML schema (canonical end-state at C3)

Match table (/lib/drivers.d/*.toml):

# matches are AND-ed within an entry, OR-ed across entries
[[driver]]
name = "e1000d"
description = "Intel e1000 Gigabit Ethernet"
priority = 50

[driver.command]
argv = ["e1000d"]   # or absolute path

[driver.depends_on]
schemes = ["pci", "firmware"]

[[driver.match]]
vendor = 0x8086
device = 0x100E
class = 0x02       # network controller
subclass = 0x00    # ethernet

[[driver.match]]
vendor = 0x8086
device = 0x10D3
# wildcard rest

[driver.params]
debug = { type = "bool", default = false, writable = true }
priority_arg = { type = "int", default = 0, writable = true }
exclusive_with = { type = "string", default = "", writable = false }

Policy layer (/etc/driver-manager.d/*.toml):

# Blacklist
[[blacklist]]
module = "iTCO_wdt"
reason = "CachyOS precedent; conflicts with iTCO hardware"

# Forced module-options
[amdgpu.params]
si_support = true
cik_support = true
radeon_overlap = "exclusive"   # CachyOS mutual exclusion pattern

# Autoload (cold-boot pre-driver)
[[autoload]]
module = "ntsync"

Initfs manifest (/etc/driver-manager.d/initfs.manifest):

# ordered (CachyOS-style hook ordering)
[ramdisk]
microcode = ["amd-ucode", "intel-ucode"]
policy = "00-driver-conf"
kms_drivers = ["amdgpu", "i915"]
block_drivers = ["ahci", "nvme", "virtio_blk"]
fs_drivers = ["redoxfs", "ext4"]

9.5 Migration effort & ownership

Phase	Effort estimate	Owner role
D-Phase	Effort estimate	Owner role
---	---	---
D1 — Linux capability bridge	6–10 weeks	driver-runtime engineer
D2 — Modern technology surface	8–12 weeks (largest phase; SMP + S/P + PM + IOMMU + AER + MSI-X + NUMA)	driver-runtime + kernel-interface engineer + ACPI engineer
D3 — Hotplug event-driven	4–6 weeks	driver-runtime engineer
D4 — Quirk integration + audit	6–8 weeks (includes the § 0.5 no-stubs audit)	driver-runtime + SRE
D5 — Feature-complete gate	1–2 weeks	driver-runtime engineer + operator ratification
D-phase total	25–38 weeks (~6–9 months)

C-Phase	Effort estimate	Owner role
C0 — Service wiring (dormant)	1 week	driver-runtime engineer
C1 — Dual-mode observation	2–4 weeks (must run alongside pcid-spawner in production)	driver-runtime engineer + build-system engineer
C2 — Initfs switchover	2–3 weeks	driver-runtime + boot-system engineer
C3 — Rootfs switchover	2–4 weeks	driver-runtime engineer
C4 — Operator-ratified production cutover	1–2 weeks + 2-week soak + 3 hardware reboots	operator + driver-runtime engineer
C-phase total	8–14 weeks + soak (~2–4 months)

Grand total: 33–52 weeks (~8–13 months) for full D+C trajectory.

Operator ratification required at the following phase boundaries:

• D5 → C0 — feature-complete gate (the § 0.5 audit clean + hardware matrix passes)
• C1 → C2 — rootfs observation confirmed dual-mode parity
• C2 → C3 — initfs switchover ratified
• C3 → C4 — rootfs switchover ratified
• C4 transition — production cutover ratified

Phase boundaries without explicit operator ratification are not allowed to advance.

9.6 References

Internal (Red Bear OS):

• local/AGENTS.md — policy authority
• local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md — supersedes for desktop path
• local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md — GPU-specific decisions
• local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md — PCI/IRQ quality
• local/docs/USB-IMPLEMENTATION-PLAN.md — USB bus (out of scope here)
• local/docs/WIFI-IMPLEMENTATION-PLAN.md — Wi-Fi bus (out of scope here)
• local/docs/QUIRKS-SYSTEM.md — redox-driver-sys quirks surface
• local/docs/QUIRKS-IMPROVEMENT-PLAN.md — Task 2.1 driver-manager bridge
• local/docs/HARDWARE-VALIDATION-MATRIX.md — status of driver runs
• local/docs/UPSTREAM-SYNC-PROCEDURE.md — historical status note to update
• local/docs/PATCH-GOVERNANCE.md — patch carrier rules
• local/docs/RELEASE-BUMP-WORKFLOW.md — version sync
• local/scripts/TOOLS.md — tool inventory

External cross-reference (not authoritative here, cited for design intent):

• Linux 7.1 reference tree at local/reference/linux-7.1/ (commit ab9de95c9):
  • drivers/pci/pci-driver.c:1021-1742 — pci_driver, pci_bus_type
  • drivers/pci/pci.c:2120, 3916, 4172 — pci_enable_device, pci_request_regions, pci_set_master
  • drivers/pci/msi/api.c:205-264 — pci_alloc_irq_vectors_affinity
  • drivers/pci/hotplug/pciehp_core.c:185-372 — native hotplug
  • drivers/pci/pcie/aer.c:1203-1280 — AER recovery
  • drivers/base/bus.c:732, 818, 612, 869 — driver-core binding
• CachyOS-Settings (master, v1.3.5): https://github.com/CachyOS/CachyOS-Settings
  • usr/lib/udev/rules.d/60-ioschedulers.rules — kernel-event → sysfs-write policy
  • usr/lib/udev/rules.d/71-nvidia.rules — bind/unbind lifecycle symmetry
  • usr/lib/udev/rules.d/20-audio-pm.rules — cross-subsystem reaction
  • usr/lib/udev/rules.d/85-iw-regulatory.rules + cachyos-iw-set-regdomain.{path,service} — udev→systemd delegation
  • usr/lib/modprobe.d/{amdgpu,blacklist,nvidia}.conf — driver-exclusion pattern
• CachyOS/linux-cachyos: scheduler variants, mkinitcpio preset ordering.

---

10. Position statement

This plan supersedes the inline deferred notes that accompany the existing driver-manager recipe:

• config/redbear-mini.toml:31 ("driver-manager requires driver config migration and is not yet ready")
• config/redbear-device-services.toml:9-13 ("driver-manager intentionally not included … its service launched pcid-spawner instead of driver-manager").

These notes remain accurate at the moment of writing (2026-07-20). They will be amended at the relevant phase boundaries as the migration advances. At no point in the migration is pcid-spawner removed from the tree, the recipe, or the live image. The boot path is never single-point-of-failure.

v1.1 additions (this revision): § 0 Strategic Context is added with rationale, success criteria, upstream risk, modern-technology surface, comprehensive-implementation principle, and the parallel-development constraint. § 5 is restructured into D-Phase (parallel development) and C-Phase (cutover & validation). All cross-references in §§ 1, 2, 4, 5, 6, 7, 8, 9 are updated to the new phase nomenclature. The § 0.5 comprehensive principle is the binding code-quality bar; the § 0.6 parallel-development constraint is the binding development model.

Binding constraints derived from § 0:

• Comprehensive implementation — every public trait method on Bus, Driver, and Manager is fully implemented. No unimplemented!(), no todo!(), no empty match arms returning trivial defaults, no #[cfg(...)]-gated no-ops. Honoring local/AGENTS.md § STUB AND WORKAROUND POLICY — ZERO TOLERANCE.
• Modern technology surface — SMP-aware concurrent probe, C/P-state coordination, runtime PM, IOMMU group management, AER error recovery, MSI-X vector allocation, NUMA-aware DMA. None of these are stubs.
• Parallel development model — driver-manager is being built in parallel with the live pcid-spawner system. It is NOT shipped, NOT enabled, NOT included in any boot path until the D5 feature-complete gate ratifies. No exceptions.
• Upstream-first response — if Redox upstream ships an equivalent manager within 6 months of D5, evaluate and consider migrating per Local Fork Supremacy Policy. The migration plan is robust to upstream divergence; it does NOT block on upstream decisions.

Status of § 0.6 (parallel development) at the moment of writing: driver-manager is being built. It is NOT shipped. The boot path is pcid-spawner. The migration plan enters C-phase only after D5 ratifies.

The migration's authority chain is: this document → local/AGENTS.md → AGENTS.md. Every implementation step must be defensible against this chain, the § 0.5 comprehensive principle, and the § 0.6 parallel-development constraint.

Last reviewed: 2026-07-20 (v1.1: strategic-context + D/C phase restructure) Next review: at D5 exit gate, after local/scripts/driver-manager-audit-no-stubs.py reports zero violations AND local/docs/HARDWARE-VALIDATION-MATRIX.md shows driver-manager validated on at least one AMD and one Intel profile across storage, network, and GPU categories.