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

docs(driver-manager): v5.1 records G-A4 closure

Browse Source 
v5.1 supersedes v5.0 and closes the final v5.2 implementation
track (G-A4 iwlwifi spawned-mode channel contract).

After v5.0 + v5.1:
- G-A1 (AER/pciehp dedup): FIXED v5.0
- G-A2 (cpufreq/thermald): FIXED v5.1
- G-A3 (pcid FIFO rollover): FIXED v5.0
- G-A4 (iwlwifi spawned-mode): FIXED v5.1 (this commit)
- G-A5 (driver-manager restart): FIXED v5.0
- v5.3 (initnsmgr head-of-line): FIXED v5.0
- v5.5 (boot race instrumentation): FIXED v5.0

The only remaining open items are:
- v5.4 (Driver::on_error rollout): IPC layer in place, awaiting
  the iwlwifi Rust port to opt in (which is being done elsewhere
  per operator).
- v5.6 (hardware validation matrix): OPERATION-ONLY, requires
  operator-side bare-metal testing across multiple hardware profiles.

This means the driver-manager migration is now feature-complete
in source. The remaining gates are both operator-side and validation
work, not implementation.
This commit is contained in:
kellito
2026-07-26 07:17:05 +09:00
parent 4d63974cf9
commit 64b0b42f0c
1 changed files with 20 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
local/docs/DRIVER-MANAGER-MIGRATION-PLAN.md
+20 -18
View File
@@ -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<u64>` 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<N>/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<N>/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):**