vasilito/RedBear-OS
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: bump driver-manager plan to v4.1; capture v4.1 fixes and audit

Browse Source 
Updates the canonical planning authority for the driver-manager migration
to v4.1, which closes the three P3 items v4.0 had declared open.

Adds:
* v4.1 update block with the table mapping each v4.0 P3 item to its
  v4.1 resolution (QuirkPhase::Early gating, AER auto-dispatch,
  per-vendor firmware assessment) and the IOMMU/NUMA honest-absence
  fix in redox-driver-core::modern_technology.
* Driver-by-driver audit summary — every PCI driver invoked from
  /lib/drivers.d/*.toml plus the modern-tech daemons and bridging
  consumers. No stubs, no todo!()/unimplemented!() in production
  paths.
* Adjacent-technology compatibility matrix — cpufreqd/thermald
  verified compatible; iommu now honest; udev-shim/driver-params
  wired correctly; redox-drm/xhcid/iwlwifi/amdgpu use the granted
  channel contract.

Refreshes the v4.0 post-cutover table to reflect the v4.1 AER row
('auto-dispatch from listener; RecoveryAction::ResetDevice/RescanBus
execute via shared dispatch_recovery helper') and the v4.1 quirks
row (phase = early/enable consulted at probe time).

Replaces the now-stale v4.0 'Open items (updated)' line with the v4.1
list — none from v4.0 P3, plus the operator-only gates that remain
(ACPI session, hardware validation matrix, two-week soak).

Updates Last reviewed line to 2026-07-24.
This commit is contained in:
vasilito
2026-07-24 23:31:15 +09:00
parent 31bbe2fa12
commit f61775c946
1 changed files with 59 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
local/docs/DRIVER-MANAGER-MIGRATION-PLAN.md
+59 -12
View File
@@ -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 (`[[<domain>_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 (`[[<domain>_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