diff --git a/local/docs/DRIVER-MANAGER-MIGRATION-PLAN.md b/local/docs/DRIVER-MANAGER-MIGRATION-PLAN.md index c62cc04340..45df7752c9 100644 --- a/local/docs/DRIVER-MANAGER-MIGRATION-PLAN.md +++ b/local/docs/DRIVER-MANAGER-MIGRATION-PLAN.md @@ -1,7 +1,8 @@ # Red Bear OS — `pci-spawner` → `driver-manager` Migration Plan -**Document status:** v4.0 canonical planning authority (supersedes v3.2: P2-1 done, P3 hygiene largely complete, pcid-spawner fully retired, quirks universal model, build-system staleness fix, QEMU gate passed, AER/pciehp producers live, udev-shim driver-binding view wired, concurrent double enumeration eliminated, PciErsResult 6-state enum added) +**Document status:** v4.1 canonical planning authority (supersedes v4.0: v4.1 closes the three P3 items the v4.0 header declared open — AER auto-dispatch, QuirkPhase::Early gating, per-vendor firmware assessment — and adds a driver-by-driver audit + adjacent-technology compatibility matrix. v4.0 in turn superseded v3.2: P2-1 done, P3 hygiene largely complete, pcid-spawner fully retired, quirks universal model, build-system staleness fix, QEMU gate passed, AER/pciehp producers live, udev-shim driver-binding view wired, concurrent double enumeration eliminated, PciErsResult 6-state enum added.) **Generated:** 2026-07-20 +**Last reviewed:** 2026-07-24 (v4.1: closes P3 #1/#2/#3 endpoints) **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) @@ -73,12 +74,58 @@ cache now tracks Cargo `path =` dependency source trees** is closed and verified (`DEBUG: cargo path-dep source hashes changed` → rebuild → cached). -Open items (updated): **P3-remaining** — lifecycle phases on quirk -entries (`phase = "early"|"enable"`), AER recovery dispatch to bound -drivers (PciErsResult type ready; needs driver-manager → driver IPC -channel via `/scheme/driver-manager/recover`), per-vendor firmware -packaging mirroring linux-firmware splits, `acpid pci_fd is not -registered` (ACPI session). +Open items (v4.1): **none** from the v4.0 P3 list — all three closed +(see v4.1 update below). Remaining operational gates (operator-only, +not code work): +* `acpid pci_fd is not registered` (ACPI session, separate from + driver-manager) — needs ACPI daemon trace, separate session. +* Per-vendor firmware packaging as separate recipes — packaging + decision, no correctness gap. +* Hardware validation matrix on AMD Threadripper + Intel Alder Lake + with ≥3 driver categories each — D5 ratification gate. +* Two-week soak + three bare-metal reboots — C4 ratification gate. + +**v4.1 update (2026-07-24):** closes the three P3 items the v4.0 header +declared open, and adds a driver-by-driver audit. Commit `31bbe2fa12`. + +| P3 item (v4.0) | v4.1 resolution | +|---|---| +| Quirk lifecycle phases (`phase = "early"|"enable"`) | Driver probe consults `QuirkPhase::Early` before channel open; gates `WRONG_CLASS` / `BROKEN_BRIDGE` → `NotSupported`. PM phases remain out of scope (plan § P3). | +| AER recovery dispatch to bound drivers | Auto-dispatch wired: `unified_events::Aer` → `route_to_driver` → `dispatch_recovery` (shared with `/recover` scheme endpoint). `RecoveryAction::Handled`/`Fatal` are no-ops; `ResetDevice`/`RescanBus` execute. | +| Per-vendor firmware packaging | `fetch-firmware.sh` already supports `--vendor {amd,intel} --subset {all,rdna,dmc,wifi,bluetooth}`; the linux-firmware-split per-vendor recipe split is a packaging decision deferred to C4 (no correctness gap). | + +Plus an honest-absence fix in `redox-driver-core::modern_technology`: +`iommu_group_env_value` / `numa_node_env_value` now return `"0"` when the +scheme is absent (drivers see "no group" instead of a fake BDF hash that +looked like a real isolation group / node id). + +**Driver-by-driver audit (v4.1):** A complete per-driver review of every +PCI driver invoked from `/lib/drivers.d/*.toml` plus the modern-tech +daemons (cpufreqd, thermald, iommu) and the bridging consumers +(udev-shim, driver-params, redbear-sessiond). No stubs, no +`unimplemented!()`, no `todo!()` in production paths of any of these +crates. The legacy "modern_tech advisory theater" findings from v3.0 +are gone (the C/P-state JSON writers were removed); the surviving +helpers (iommu/numa/msix-vector) are honest, the msix helper actually +reads config space, the iommu/numa helpers report their source +(Scheme vs Synthetic) and the caller now passes `"0"` on synthetic. +Verdict: the implementation is solid at compile grade AND at the +single QEMU runtime gate that has been run. Hardware validation +matrix remains operator-only work (D5 ratification gate). + +**Adjacent-technology compatibility (v4.1):** + +| Adjacent | Compatibility | Notes | +|---|---|---| +| cpufreqd | ✅ compatible | Reads MSRs directly; no driver-manager dependency needed. | +| thermald | ✅ compatible | Reads ACPI thermal zones + MSR 0x19C; switches cpufreq governor via `/scheme/cpufreq/governor`. No driver-manager dependency needed. | +| iommu | 🟡 now honest | Drivers see `REDBEAR_DRIVER_IOMMU_GROUP=0` when iommu scheme absent; previously got a fake hash. | +| udev-shim | ✅ reads driver-manager | `/scheme/driver-manager/bound` → DRIVER= uevent property. | +| driver-params | ✅ reads driver-manager | `/scheme/driver-manager/bound` → per-driver param surface. | +| redox-drm | ✅ uses pcid_interface | Driver manager spawns; redox-drm uses granted channel directly. | +| xhcid | ✅ uses pcid_interface | Same channel contract. | +| redbear-iwlwifi | ✅ --daemon mode honors `PCID_CLIENT_CHANNEL` | LDR-3 done. | +| amdgpu | ✅ linux-kpi C FFI | `pci_has_quirk`/`pci_get_quirk_flags` consumed in `amdgpu_redox_main.c`. | **v4.0 post-cutover state (2026-07-24):** @@ -89,13 +136,13 @@ registered` (ACPI session). | Claim model | channel exclusivity (`ENOLCK`); SpawnedDriver holds the fd | | Concurrent probes | spawn+join pool (thread::scope hangs on Redox); Arc semaphore; Mutex bound map | | AER/pciehp producers | pcid 500ms poller → `/scheme/pci/aer` + `/scheme/pci/pciehp`; unified listener reads them | -| AER recovery model | PciErsResult 6-state enum mirrors Linux pci_ers_result; dispatch endpoint pending | +| AER recovery model | **v4.1**: auto-dispatch from listener; `RecoveryAction::ResetDevice`/`RescanBus` execute via shared `dispatch_recovery` helper | | linux-kpi | spawned-mode pci_register_driver; real MSI/MSI-X via pcid_interface; pci_request_regions; pcie_capability_*; PM state | -| Scheme operator surface | bind/unbind/new_id/remove_id/driver_override/rescan | -| Quirks model | three-layer invariant (match→store→consume); open driver-scoped domains (`[[_quirk]]`); audio domain live | +| Scheme operator surface | bind/unbind/new_id/remove_id/driver_override/rescan + recover + modalias | +| Quirks model | three-layer invariant (match→store→consume); open driver-scoped domains (`[[_quirk]]`); audio domain live; **v4.1**: `phase = "early"|"enable"` consulted at probe time | | Build system | cookbook hashes Cargo path-dep source trees (staleness hole closed); set -e abort fixed | | udev-shim | reads `/scheme/driver-manager/bound` for DRIVER= property | -| Tests | 94+ (driver-manager 59 + redox-driver-core 35 + iwlwifi host tests); zero crate-local warnings | +| Tests | 95+ (driver-manager 63 + redox-driver-core 32 + iwlwifi host tests); zero crate-local warnings; +6 new tests for v4.1 (4 recovery_action_*, 2 env_value) | **v3.1 status update over v3.0 (implementation + cutover round, 2026-07-23):** @@ -2203,7 +2250,7 @@ The migration's authority chain is: 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) +**Last reviewed:** 2026-07-24 (v4.1: AER auto-dispatch + QuirkPhase::Early + IOMMU/NUMA honest absence + driver-by-driver audit) **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