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

docs: bump driver-manager plan to v4.3; capture Driver::on_error IPC layer

Browse Source 
Updates the canonical planning authority for the driver-manager migration
to v4.3, which closes the last open v4.0 P3 item ('Driver-level
Driver::on_error IPC') via a three-layer architecture:

1. Manager-side trait: DriverConfig::on_error override returns the
   severity mapping by default; consultable from the AER dispatch.
2. Sidecar IPC (manager): UnixStream::pair(), child fd as
   REDBEAR_DRIVER_ERROR_FD env var, parent fd registered by BDF,
   200ms timeout on the IPC roundtrip, fall-back chain (IPC -> in-
   process -> severity default).
3. Sidecar IPC (driver): linux-kpi pci_register_error_handler() +
   worker thread that services the sidecar fd.

Documents the wire protocol, the C-side API contract, the
discriminant mappings, and the explicit decision to keep wire types
duplicated between driver-manager and linux-kpi rather than extract
a shared crate.

Status table: Open items now empty of v4.0 P3 list items. Remaining
operator-only gates (hardware validation matrix, two-week soak) are
noted but are out of scope for code work. Driver-level Driver::on_error
adoption by shipped drivers is now possible (the IPC layer is ready)
but no daemon opts in yet -- that is an integration task for future
driver work.

Last reviewed line updated to 2026-07-24 (v4.3).
This commit is contained in:
vasilito
2026-07-25 06:22:02 +09:00
parent 3425f55c44
commit bba923e075
1 changed files with 38 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
local/docs/DRIVER-MANAGER-MIGRATION-PLAN.md
+38 -7
View File
@@ -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<RecoveryAction, DriverError>` | 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`