diff --git a/local/docs/DRIVER-MANAGER-MIGRATION-PLAN.md b/local/docs/DRIVER-MANAGER-MIGRATION-PLAN.md index ce25228dd4..edabcd62de 100644 --- a/local/docs/DRIVER-MANAGER-MIGRATION-PLAN.md +++ b/local/docs/DRIVER-MANAGER-MIGRATION-PLAN.md @@ -1,8 +1,8 @@ # Red Bear OS — `pci-spawner` → `driver-manager` Migration Plan -**Document status:** v4.2 canonical planning authority (supersedes v4.1: v4.2 closes the `acpid pci_fd` item and adds per-vendor firmware recipes. v4.1 in turn superseded 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.) +**Document status:** v4.3 canonical planning authority (supersedes v4.2: v4.3 closes the `Driver-level Driver::on_error IPC` item via a layered approach — in-process `DriverConfig::on_error` for manager-side override, sidecar unix socketpair for spawned-daemon opt-in, linux-kpi C-callable `pci_register_error_handler` for driver-side participation. v4.2 in turn superseded v4.1: v4.2 closes the `acpid pci_fd` item and adds per-vendor firmware recipes. v4.1 in turn superseded 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.2: acpid pci_fd fix + per-vendor firmware split + iommu/numad path corrections + Fatal escalation) +**Last reviewed:** 2026-07-24 (v4.3: Driver::on_error IPC layer) **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) @@ -74,15 +74,46 @@ cache now tracks Cargo `path =` dependency source trees** is closed and verified (`DEBUG: cargo path-dep source hashes changed` → rebuild → cached). -Open items (v4.2): **none** from the v4.0 P3 list — all four closed -across v4.1 and v4.2 (see v4.1 + v4.2 update blocks). Remaining +Open items (v4.3): **none** from the v4.0 P3 list — all closed across +v4.1, v4.2, and v4.3 (see update blocks below). Remaining operational gates (operator-only, not code work): * 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. -* Driver-level `Driver::on_error` IPC (so spawned drivers can return - `RecoveryAction::Handled`/`ResetDevice`/etc. to the manager) — - separate item, requires IPC protocol extension. +* **Driver-level `Driver::on_error` adoption** — the IPC layer is in + place (linux-kpi `pci_register_error_handler` is callable), but no + shipped driver daemon opts in yet. C drivers that want device- + specific recovery decisions register the handler in their probe + path; the IPC layer + protocol + manager-side consultation are + ready to consume their responses. + +**v4.3 update (2026-07-24):** closes the `Driver-level Driver::on_error +IPC` item with a three-layer architecture. + +| Layer | Code | Contract | +|---|---|---| +| Manager-side trait | `DriverConfig::on_error(info, severity) -> Result` | Severity mapping (Correctable→Handled, NonFatal→ResetDevice, Fatal→RescanBus). Drivers may override per-device. | +| Sidecar IPC (manager) | `error_channel::ErrorChannel` + `ErrorChannelRegistry` (process-wide) | Spawn-time: `UnixStream::pair()` → child fd as `REDBEAR_DRIVER_ERROR_FD` env var, parent fd registered by BDF. AER dispatch tries `request_recovery` with 200 ms timeout, falls back to in-process on_error, then to severity default. | +| Sidecar IPC (driver) | linux-kpi `pci_register_error_handler(handler)` + worker thread | Reads length-prefixed `DriverErrorReport`, calls C handler, writes length-prefixed `RecoveryAction` response. Single global handler slot (drivers compose their own chains). | + +Wire protocol (length-prefixed, little-endian): + + manager -> driver: [u32 len][severity:u8][bdf_len:u8][bdf][raw_len:u32][raw] + driver -> manager: [u32 len][action:u8] + +Wire types duplicated between driver-manager (`error_channel::DriverErrorReport`) +and linux-kpi (`error::DriverErrorReport`) so linux-kpi stays +self-contained. A future cleanup could extract a shared `redox-driver-ipc` +crate, but the protocol is small enough that duplication beats the +friction of a new crate. + +C-side API (in c_headers/linux/pci.h): + `uint8_t (*pci_error_handler_fn)(uint8_t severity, const uint8_t *bdf, size_t bdf_len);` + `int pci_register_error_handler(pci_error_handler_fn handler);` + +Discriminants in c_headers/linux/pci.h: + `PCI_ERR_{CORRECTABLE,NONFATAL,FATAL}` = 0/1/2 + `PCI_RECOV_{HANDLED,RESET,RESCAN_BUS,FATAL}` = 0/1/2/3 **v4.2 update (2026-07-24):** closes the `acpid pci_fd` item, splits redbear-firmware into per-vendor recipes, threads `RecoveryAction`