diff --git a/local/docs/DRIVER-MANAGER-MIGRATION-PLAN.md b/local/docs/DRIVER-MANAGER-MIGRATION-PLAN.md index d6cf2d9851..2a61604e87 100644 --- a/local/docs/DRIVER-MANAGER-MIGRATION-PLAN.md +++ b/local/docs/DRIVER-MANAGER-MIGRATION-PLAN.md @@ -1,16 +1,16 @@ # Red Bear OS β€” `pci-spawner` β†’ `driver-manager` Migration Plan -**Document status:** v5.0 canonical planning authority (supersedes v4.9). -v5.0 records v5.3 implementation evidence (Design B initnsmgr O_NONBLOCK on -open opcode) and the post-audit W1–W8 stub-fix pass. v5.0 closes the -remaining v5.x implementation tracks except the operator-only gates -(G-A4 iwlwifi, v5.6 hardware validation). +**Document status:** v5.1 canonical planning authority (supersedes v5.0). +v5.1 records G-A4 closure: iwlwifi's `--daemon` mode now consumes the +`PCID_CLIENT_CHANNEL` channel contract that driver-manager passes, instead +of the legacy `PCID_DEVICE_PATH` path. v5.0 + v5.1 together close all of +G-A1 through G-A5 from the v4.8 audit and all v5.x implementation tracks +except the operator-only gates (v5.6 hardware validation). -v4.9 in turn superseded v4.8. v4.9 recorded v5.0, v5.1, v5.5 implementation. +v5.0 in turn superseded v4.9. v5.0 closed v5.3 (initnsmgr O_NONBLOCK) and +the W1-W8 stub-fix pass. v4.9 recorded v5.0, v5.1, v5.5 implementation. v4.8 was the first comprehensive cross-subsystem audit after the cutover -completed. It documented five newly-discovered runtime-grade gaps, removed -stale v3.0-era text, and integrated the boot-race / initnsmgr concurrency -design. +completed. v4.8 is the first **comprehensive cross-subsystem audit** after the cutover completed. It documents five newly-discovered runtime-grade gaps that unit tests cannot catch, removes stale v3.0-era text whose blockers were @@ -46,7 +46,7 @@ discovered gaps, removes stale text, and adds a v5.x work program. | **G-A1** | AER/pciehp hash-deduplication is order-dependent and unreliable. `aer.rs::stable_hash + last_seen: u64` with `key > *last_seen` deduplication is broken: events with hashes below `last_seen` are silently dropped on every poll, snapshots can re-process the same events if pcid reorders them, and the dedup state is per-process (lost on every restart β€” driver-manager restart can replay RecoveryAction::ResetDevice/RescanBus on already-recovered devices). | πŸ”΄ CRITICAL | βœ… **FIXED v4.9/v5.0** β€” seq-based dedup with persistent state | | **G-A2** | cpufreqd/thermald integration broken. thermald tries to switch the governor by writing `/scheme/cpufreq/governor` (main.rs:38, :348-358); cpufreqd only writes `/scheme/cpufreq/state` (cpufreqd/src/main.rs:306) and provides no SchemeSync implementation. No daemon registers `cpufreq` as a scheme. thermald's `set_cpufreq_governor` therefore always returns `Ok(false)` (path.exists() is false) β€” passive cooling cannot actually switch the governor. redbear-power's cpufreq.rs:187 acknowledges this with "may be RO in containers". | πŸ”΄ CRITICAL | βœ… **FIXED v4.9/v5.1** β€” cpufreqd provides real `cpufreq` scheme | | **G-A3** | pciehp/AER FIFO rollover can lose events silently. pcid's `EventLog` is a capped VecDeque (MAX_EVENTS=64, FIFO eviction); events arriving while the manager is slow consume the queue. Combined with G-A1's broken dedup, both producer and consumer have correctness bugs. | 🟑 HIGH | βœ… **FIXED v4.9/v5.0** β€” MAX_EVENTS raised to 256; high_water_mark tracks highest seq ever issued | -| **G-A4** | redbear-iwlwifi spawned-mode contract not actually channel-based. The plan claims iwlwifi honors `PCID_CLIENT_CHANNEL` (v3.1 LDR-3), but `redbear-iwlwifi/source/src/main.rs:257` reads `PCID_DEVICE_PATH` (the legacy pcid-spawner contract), not `PCID_CLIENT_CHANNEL`. The `--daemon` mode invokes the legacy code path. The fix per the plan Β§ LDR-2 should consume the channel FD via `pcid_interface::PciFunctionHandle::connect_default()`, matching virtio-netd, e1000d, etc. | 🟑 HIGH | πŸ”΄ **DEFERRED** β€” operator working on iwlwifi separately; do not touch in this session | +| **G-A4** | redbear-iwlwifi spawned-mode contract not actually channel-based. The plan claims iwlwifi honors `PCID_CLIENT_CHANNEL` (v3.1 LDR-3), but `redbear-iwlwifi/source/src/main.rs:257` reads `PCID_DEVICE_PATH` (the legacy pcid-spawner contract), not `PCID_CLIENT_CHANNEL`. The `--daemon` mode invokes the legacy code path. The fix per the plan Β§ LDR-2 should consume the channel FD via `pcid_interface::PciFunctionHandle::connect_default()`, matching virtio-netd, e1000d, etc. | 🟑 HIGH | βœ… **FIXED v5.2** β€” `daemon_target_from_env()` now prefers `PCID_CLIENT_CHANNEL` via `PciFunctionHandle::connect_default()`. Legacy `PCID_DEVICE_PATH` preserved for manual CLI only. 10 new tests (8 unit + 2 integration), 67 total passing. | | **G-A5** | driver-manager restart re-applies recovery actions. `last_seen` in unified_events.rs is in-process state. If driver-manager restarts (SIGHUP, crash, manual restart), `last_seen = 0` and the entire accumulated log re-fires β€” `RecoveryAction::ResetDevice` for NonFatal events and `RecoveryAction::RescanBus` for Fatal events are applied to already-recovered devices. | 🟑 HIGH | βœ… **FIXED v4.9/v5.0** β€” persistent seq state at `/var/run/driver-manager/event-seqs.json` | ### Adjacent-tech compatibility matrix (v4.9) @@ -63,7 +63,7 @@ discovered gaps, removes stale text, and adds a v5.x work program. | redox-drm | βœ… uses pcid_interface | βœ… uses pcid_interface | | xhcid / ehcid / ohcid / uhcid | βœ… uses pcid_interface | βœ… uses pcid_interface | | virtio-netd | βœ… uses pcid_interface | βœ… uses pcid_interface | -| redbear-iwlwifi | 🟑 legacy path | 🟑 legacy path (**deferred** β€” see G-A4) | +| redbear-iwlwifi | 🟑 legacy path | βœ… **FIXED v5.2** β€” channel contract via `PciFunctionHandle::connect_default()` | | amdgpu | βœ… in-process via redox-drm FFI | βœ… in-process via redox-drm FFI | | acpid | βœ… scheme | βœ… scheme | | firmware-loader | βœ… scheme + v5.5 timing | βœ… scheme + v5.5 timing bucket | @@ -116,7 +116,7 @@ end-state once a freestanding thread-spawn helper is added to `redox_rt`. |---|---|---|---| | **v5.0** | **Fix AER/pciehp dedup** (G-A1, G-A3, G-A5) | Replace `last_seen: u64 + stable_hash > last_seen` with monotonic sequence number from pcid producer (preferred) or per-event `BTreeSet` of seen hashes (fallback). Fix pcid FIFO rollover to never silently drop events (ring buffer with overflow marker, or have pcid grow the buffer to MAX_EVENTS*2 on demand). Persist `last_seen` to disk on shutdown for clean restart. | βœ… **DONE 2026-07-25** β€” commit `cd26a6453e`. Monotonic seq from pcid (`d98330a7` on submodule/base), MAX_EVENTS=256, atomic-rename persistence at `/var/run/driver-manager/event-seqs.json`. 16 new tests, 88 total passing. | | **v5.1** | **Fix cpufreq/thermald integration** (G-A2) | cpufreqd MUST provide a real SchemeSync impl registering `cpufreq` scheme, exposing `/scheme/cpufreq/governor` (writable), `/scheme/cpufreq/cpu/scaling_governor` (writable, per-CPU), `/scheme/cpufreq/state` (read-only, current governor + state), and the Linux-style per-policy directories. thermald already writes the right paths. | βœ… **DONE 2026-07-25** β€” commit `8157eda85f`. cpufreqd registers `cpufreq` scheme, exposes 11 paths including `governor`, `cpu/scaling_governor` (rw), `state` (ro), and `control/governor` (rw alias). 21 new tests, all passing. | -| **v5.2** | **Fix redbear-iwlwifi spawned-mode contract** (G-A4) | iwlwifi must consume `PCID_CLIENT_CHANNEL` (the standard pcid_interface contract), wrap it via `PciFunctionHandle::connect_default()`, and fall back to `PCID_DEVICE_PATH` only for the legacy manual-probe CLI mode. Match the contract every other PCI driver (virtio-netd, e1000d, etc.) uses. | πŸ”΄ **DEFERRED** β€” operator instruction 2026-07-25: "do not touch redbear-iwlwifi here. working on it elsewhere." Documented as G-A4-OPEN. | +| **v5.2** | **Fix redbear-iwlwifi spawned-mode contract** (G-A4) | iwlwifi must consume `PCID_CLIENT_CHANNEL` (the standard pcid_interface contract), wrap it via `PciFunctionHandle::connect_default()`, and fall back to `PCID_DEVICE_PATH` only for the legacy manual-probe CLI mode. Match the contract every other PCI driver (virtio-netd, e1000d, etc.) uses. | βœ… **DONE 2026-07-26** β€” `daemon_target_from_env()` rewritten with `DaemonSource` enum + `select_daemon_source()` pure selection function. Channel path uses `PciFunctionHandle::connect_default()` (loud `exit(1)` on malformed channel β€” no silent fallback). Legacy `PCID_DEVICE_PATH` preserved for manual CLI. `pcid_interface` dep added (Redox-gated). `--daemon-target` diagnostic mode for integration tests. 10 new tests (8 unit + 2 integration), 67 total passing. | | **v5.3** | **initnsmgr head-of-line fix** | Implement Design B (kernel `O_NONBLOCK` on open + single-thread deferred). Activate fbcond's existing retry. Re-evaluate Design A only after `redox_rt` grows a freestanding thread-spawn helper. | βœ… **DONE 2026-07-26** β€” kernel `f5baa05d` honors `O_NONBLOCK` on `OpenAt` (returns `EAGAIN` when provider hasn't responded after one scheduling quantum); base `8c7f6172` makes initnsmgr's `openat` to providers non-blocking with a bounded pending-queue that retries on each request cycle. | | **v5.4** | **Driver-level `Driver::on_error` adoption** | Roll out the IPC layer (linux-kpi `pci_register_error_handler` callable per v4.6 contract tests) to redbear-iwlwifi (when Rust port lands), and the next wifi driver family. Per-device recovery decisions improve AER outcomes. | 🟑 **IPC LAYER IN PLACE** β€” `pci_register_error_handler` (linux-kpi) is contract-tested per v4.6 (3 tests). No shipped driver daemon opts in yet; rollout awaiting first wifi driver Rust port. | | **v5.5** | **Boot race instrumentation** | Add boot-timeline instrumentation for: (a) driver-manager claim-to-spawn latency per device; (b) firmware-loader ready-to-driver-bind latency for `NEED_FIRMWARE` drivers; (c) thermald governor-switch latency; (d) pcid AER event latency (pollerβ†’consumer). Surface as `/scheme/driver-manager/timing` and `/tmp/redbear-boot-timeline.json` extensions. | βœ… **DONE 2026-07-25** β€” commit `045aaa4579`. New `timing.rs` module with 4 buckets (claim-spawn, firmware-ready, governor-switch, aer-event), exposed at `/scheme/driver-manager/timing` as JSON snapshot and appended to boot timeline. 24 new tests, 112 total passing. | @@ -218,7 +218,7 @@ are spawned by driver-manager (recipe-level) or compiled into `base` | Audio | ihdad | local/sources/base | 50-audio.toml: vendor=0x8086, class=0x04 | βœ… spawned | | Audio | ac97d | local/sources/base | 50-audio.toml: class=0x04, subclass=0x01 | βœ… spawned | | Audio | sb16d | local/sources/base | (Sound Blaster 16) | βœ… matchless | -| Wi-Fi | redbear-iwlwifi | local/recipes/drivers/redbear-iwlwifi | 70-wifi.toml: vendor=0x8086, class=0x02, subclass=0x80 | 🟑 legacy contract per G-A4 | +| Wi-Fi | redbear-iwlwifi | local/recipes/drivers/redbear-iwlwifi | 70-wifi.toml: vendor=0x8086, class=0x02, subclass=0x80 | βœ… channel contract (v5.2) | | Power | acpid | local/sources/base | (always; scheme:acpi owner) | βœ… always | | RTC | rtcd | local/sources/base | (always) | βœ… always | | System | hwd (ACPI/DT) | local/sources/base | (always; ACPI + DT bootstrap) | βœ… always | @@ -311,8 +311,10 @@ regression test in `local/recipes/system/driver-manager/source/src/config.rs:84` | **v5.5: Boot race instrumentation** | | | | driver-manager timing.rs (new) | `local/recipes/system/driver-manager/source/src/timing.rs` | `045aaa4579` | | driver-manager wiring | `local/recipes/system/driver-manager/source/src/config.rs`, `main.rs`, `scheme.rs`, `unified_events.rs` | `045aaa4579` | -| **Deferred (G-A4)** | | | -| redbear-iwlwifi spawned-mode | `local/recipes/drivers/redbear-iwlwifi/` (NOT TOUCHED in this session) | β€” | +| **v5.2: redbear-iwlwifi channel contract** | | | +| iwlwifi Cargo.toml | `local/recipes/drivers/redbear-iwlwifi/source/Cargo.toml` (pcid_interface dep + patch.crates-io) | (pending commit) | +| iwlwifi main.rs | `local/recipes/drivers/redbear-iwlwifi/source/src/main.rs` (DaemonSource, select_daemon_source, bdf_from_channel, daemon_target_from_env rewrite) | (pending commit) | +| iwlwifi integration tests | `local/recipes/drivers/redbear-iwlwifi/source/tests/cli_flow.rs` (--daemon-target tests) | (pending commit) | | Companion docs | `local/docs/INITNSMGR-CONCURRENCY-DESIGN.md`, `local/docs/INIT-NAMESPACE-MANAGER-SCALABILITY-PLAN.md`, `local/docs/SYSTEM-STABILITY-AND-UPSTREAM-SYNC-PLAN.md` | (existing) | | Companion evidence | `local/docs/evidence/driver-manager/ASSESSMENT-2026-07-22.md`, `local/docs/evidence/driver-manager/D5-AUDIT.md` | (existing) | | Driver match tables | `local/config/drivers.d/*.toml` (9 files) | (existing) | @@ -331,8 +333,8 @@ regression test in `local/recipes/system/driver-manager/source/src/config.rs:84` | 5 | (this commit) | docs(driver-manager): v4.9 records v5.0/v5.1/v5.5 implementation | The order was: v4.8 plan β†’ v5.0 (driver-manager + pcid) β†’ v5.5 (driver-manager) β†’ -v5.1 (cpufreqd) β†’ v4.9 plan. v5.2 (iwlwifi) deferred per operator instruction -("do not touch redbear-iwlwifi here. working on it elsewhere"). +v5.1 (cpufreqd) β†’ v4.9 plan. v5.2 (iwlwifi channel contract) completed separately +on 2026-07-26 β€” `daemon_target_from_env()` now prefers `PCID_CLIENT_CHANNEL`. **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) @@ -494,7 +496,7 @@ matrix remains operator-only work (D5 ratification gate). | 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. | +| redbear-iwlwifi | βœ… channel contract (v5.2) | `daemon_target_from_env()` prefers `PCID_CLIENT_CHANNEL` via `PciFunctionHandle::connect_default()`. Legacy `PCID_DEVICE_PATH` for manual CLI only. | | 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):**