From 6689f751d995fedbe16e30f409f6e3478b00edc9 Mon Sep 17 00:00:00 2001 From: Vasilito Date: Fri, 17 Apr 2026 00:05:20 +0100 Subject: [PATCH] Refresh project documentation Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus --- AGENTS.md | 49 +- docs/02-GAP-ANALYSIS.md | 7 +- docs/03-WAYLAND-ON-REDOX.md | 18 +- docs/04-LINUX-DRIVER-COMPAT.md | 43 +- docs/05-KDE-PLASMA-ON-REDOX.md | 25 +- docs/README.md | 10 +- local/AGENTS.md | 44 +- local/docs/ACPI-FIXES.md | 3 + local/docs/AMD-FIRST-INTEGRATION.md | 77 +- local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md | 2 +- local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md | 1195 +++++++---------- local/docs/DESKTOP-STACK-CURRENT-STATUS.md | 170 +-- local/docs/DMA-BUF-IMPROVEMENT-PLAN.md | 432 ++++++ local/docs/HARDWARE-3D-ASSESSMENT.md | 163 +++ local/docs/P2-AMD-GPU-DISPLAY.md | 5 + local/docs/PHASE-0-3-REASSESSMENT.md | 10 +- local/docs/PROFILE-MATRIX.md | 22 +- .../docs/PROJECT-DOCUMENTATION-ASSESSMENT.md | 4 + local/docs/QT6-PORT-STATUS.md | 136 +- local/docs/QUIRKS-IMPROVEMENT-PLAN.md | 303 +++++ local/docs/QUIRKS-SYSTEM.md | 339 +++++ local/docs/USB-IMPLEMENTATION-PLAN.md | 188 ++- local/docs/WIFI-IMPLEMENTATION-PLAN.md | 903 +++---------- 23 files changed, 2428 insertions(+), 1720 deletions(-) create mode 100644 local/docs/DMA-BUF-IMPROVEMENT-PLAN.md create mode 100644 local/docs/HARDWARE-3D-ASSESSMENT.md create mode 100644 local/docs/QUIRKS-IMPROVEMENT-PLAN.md create mode 100644 local/docs/QUIRKS-SYSTEM.md diff --git a/AGENTS.md b/AGENTS.md index efa6739f..1d59f823 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -69,6 +69,7 @@ redox-master/ | Fix relibc (POSIX) | `recipes/core/relibc/source/` | C library written in Rust | | Wayland integration | `recipes/wip/wayland/` + `docs/03-WAYLAND-ON-REDOX.md` | 21 WIP recipes | | KDE Plasma path | `recipes/wip/kde/` + `docs/05-KDE-PLASMA-ON-REDOX.md` | 9 WIP KDE app recipes | +| **Desktop path plan** | `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` | **Canonical plan: console β†’ HW-accelerated KDE** | | Linux driver compat | `docs/04-LINUX-DRIVER-COMPAT.md` | linux-kpi + redox-driver-sys architecture | | Build system internals | `src/bin/repo.rs`, `src/lib.rs`, `mk/repo.mk` | Cookbook tool in Rust | | Cross-toolchain setup | `mk/prefix.mk`, `prefix/x86_64-unknown-redox/` | Downloads Clang/LLVM toolchain | @@ -76,6 +77,7 @@ redox-master/ | GPU/graphics stack | `recipes/libs/mesa/` | OSMesa + LLVMpipe (software only) | | GPU hardware drivers | `local/recipes/gpu/redox-drm/source/` | AMD + Intel DRM/KMS via redox-driver-sys | | Boot config | `config/*.toml` | TOML hierarchy, include-based | +| **Hardware quirks** | `local/recipes/drivers/redox-driver-sys/source/src/quirks/` | Data-driven quirk tables: compiled-in + TOML + DMI; see `local/docs/QUIRKS-SYSTEM.md` | ## BUILD COMMANDS @@ -155,6 +157,19 @@ areas like relibc, prefer the upstream solution whenever upstream already solves Keep Red Bear patch carriers only for gaps or compatibility work that upstream still does not solve adequately. +When upstream Redox already provides a package, crate, or subsystem for functionality that also +exists in Red Bear local code, prefer the upstream Redox version by default unless the Red Bear +implementation is materially better. Do not grow lower-quality in-house duplicates as a steady +state. + +For quirks and driver support specifically: + +- prefer improving and using the canonical `redox-driver-sys` path, +- avoid maintaining separate lower-quality quirk engines when the same functionality belongs in + `redox-driver-sys`, +- if duplication is temporarily unavoidable, treat it as convergence work to remove, not as a + permanent design. + ### Structure ``` @@ -222,7 +237,7 @@ git reset --hard upstream-redox/master ## AMD-FIRST INTEGRATION PATH -See `local/docs/AMD-FIRST-INTEGRATION.md` for the full plan. +See `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for the canonical desktop path plan and `local/docs/AMD-FIRST-INTEGRATION.md` for deeper AMD-specific technical detail. **Target**: AMD64 bare metal, with AMD and Intel machines treated as equal-priority hardware targets. @@ -242,7 +257,11 @@ See `local/docs/AMD-FIRST-INTEGRATION.md` for the full plan. | IOMMU | 🚧 | QEMU first-use proof now passes; real hardware validation still open | | AMD GPU | 🚧 | MMIO mapped, DC port compiles, MSI-X wired, no hardware validation yet | -### Phased Roadmap +### Phased Roadmap (historical P0–P6) + +> **Note:** The P0–P6 numbering below is the historical hardware-enablement sequence. +> The canonical current desktop path plan uses a new Phase 1–5 structure documented in +> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v2.0, 2026-04-16). | Phase | Duration | Delivers | |-------|----------|----------| @@ -254,20 +273,32 @@ See `local/docs/AMD-FIRST-INTEGRATION.md` for the full plan. | ~~P5: DML2 enablement~~ | ~~partial~~ | 🚧 DML2 config enabled, 63 DML source files in build, TTM compiled, libdrm amdgpu βœ…, `iommu` daemon now builds; hardware validation still open | | P6: KDE Plasma | 12-16 weeks | 🚧 In progress β€” Qt6 βœ…, KF6 32/32 βœ…, Mesa EGL/GBM/GLES2 βœ…, kf6-kcmutils βœ…, kf6-kwayland βœ…, kdecoration βœ…, KWin πŸ”„ building | -**Total to KDE Plasma on AMD**: ~48 weeks (~11 months) with 2 developers (P0-P2 complete; P3/P4 build-side substantially advanced, runtime still open). +### Canonical Desktop Path (current plan) + +The current execution plan uses a three-track model with new Phase 1–5 numbering: +- **Phase 1:** Runtime Substrate Validation (4–6 weeks) +- **Phase 2:** Wayland Compositor Proof (4–6 weeks) +- **Phase 3:** KWin Desktop Session (6–10 weeks) +- **Phase 4:** KDE Plasma Session (8–12 weeks) +- **Phase 5:** Hardware GPU Enablement (12–20 weeks, parallel with 3–4) + +See `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for full detail. + +**Total to software-rendered KDE Plasma**: 22–34 weeks (~6–8 months) with 2 developers. +**Total to hardware-accelerated KDE Plasma**: 34–54 weeks (~8–13 months) with 2 developers. ### Critical Path ``` -P0 (ACPI boot) βœ… β†’ P1 (driver infra) βœ… β†’ P2 (AMD display) βœ… β†’ P3 (POSIX+input, build-side) 🚧 β†’ P4 (Wayland runtime) 🚧 β†’ P6 (KDE) - P5 (full amdgpu, parallel) +Phase 1 (runtime substrate) β†’ Phase 2 (software compositor) β†’ Phase 3 (KWin session) β†’ Phase 4 (KDE Plasma) + Phase 5 (hardware GPU, parallel with Phases 3–4) ``` ### Custom Crates (P1/P2) -1. `redox-driver-sys` β€” `local/recipes/drivers/redox-driver-sys/source/` β€” Safe Rust wrappers for scheme:memory, scheme:irq, scheme:pci -2. `linux-kpi` β€” `local/recipes/drivers/linux-kpi/source/` β€” C headers translating Linux kernel APIs β†’ redox-driver-sys -3. `redox-drm` β€” `local/recipes/gpu/redox-drm/source/` β€” DRM scheme daemon (AMD + Intel drivers) +1. `redox-driver-sys` β€” `local/recipes/drivers/redox-driver-sys/source/` β€” Safe Rust wrappers for scheme:memory, scheme:irq, scheme:pci + hardware quirks system (`src/quirks/`) +2. `linux-kpi` β€” `local/recipes/drivers/linux-kpi/source/` β€” C headers translating Linux kernel APIs β†’ redox-driver-sys; includes `pci_get_quirk_flags()` C FFI for quirk queries +3. `redox-drm` β€” `local/recipes/gpu/redox-drm/source/` β€” DRM scheme daemon (AMD + Intel drivers); consumes quirk flags for MSI/MSI-X fallback and DISABLE_ACCEL 4. `firmware-loader` β€” `local/recipes/system/firmware-loader/source/` β€” scheme:firmware for GPU blobs -5. `amdgpu` β€” `local/recipes/gpu/amdgpu/source/` β€” AMD DC C port with linux-kpi compat +5. `amdgpu` β€” `local/recipes/gpu/amdgpu/source/` β€” AMD DC C port with linux-kpi compat; can query quirks via `pci_has_quirk()` FFI All custom work goes in `local/` β€” see `local/AGENTS.md` for overlay usage. diff --git a/docs/02-GAP-ANALYSIS.md b/docs/02-GAP-ANALYSIS.md index 6f2b9c29..b6cde227 100644 --- a/docs/02-GAP-ANALYSIS.md +++ b/docs/02-GAP-ANALYSIS.md @@ -12,6 +12,11 @@ This document maps the distance between current Redox OS 0.9.0 and three goals: Most of this document is a historical roadmap and no longer reflects the repository's current state. Use the matrix below as the authoritative phase summary before reading the older milestone text. +> **Phase numbering note (2026-04-16):** the P0–P6 labels below refer to the historical +> hardware-enablement sequence, not the v2.0 desktop plan phases (Phase 1–5) in +> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`. P4 β‰ˆ v2.0 Phase 2 (compositor), P6 β‰ˆ v2.0 +> Phases 3–4 (KWin + Plasma). + | Layer / Phase | Current repo state | Evidence | |---|---|---| | P0 ACPI / bare-metal boot | Complete in-tree | `local/docs/ACPI-FIXES.md`, `local/patches/kernel/redox.patch`, `local/patches/base/redox.patch` | @@ -83,7 +88,7 @@ implemented phase with its own config/recipe/doc boundary. | DRM/KMS scheme | **Present in-tree** | `local/recipes/gpu/redox-drm/` | [04 Β§3](04-LINUX-DRIVER-COMPAT.md) | | GPU driver (Intel) | Experimental modeset only | `redox-drm/src/drivers/intel/` | [04 Β§3](04-LINUX-DRIVER-COMPAT.md) | | GEM buffers | **Present in-tree** | `local/recipes/gpu/redox-drm/source/src/gem.rs` | [04 Β§3](04-LINUX-DRIVER-COMPAT.md) | -| DMA-BUF sharing | **Present in-tree** | `local/recipes/gpu/redox-drm/source/src/dmabuf.rs` | [04 Β§3](04-LINUX-DRIVER-COMPAT.md) | +| DMA-BUF sharing | βœ… Implemented | PRIME export/import via opaque tokens in `scheme.rs` | [DMA-BUF plan](../local/docs/DMA-BUF-IMPROVEMENT-PLAN.md) | | Mesa hardware backend | **Missing** | Mesa winsys for Redox DRM | [03 Β§3.4](03-WAYLAND-ON-REDOX.md) | | GPU OpenGL | Software only | Blocked on GPU driver | [04](04-LINUX-DRIVER-COMPAT.md) | diff --git a/docs/03-WAYLAND-ON-REDOX.md b/docs/03-WAYLAND-ON-REDOX.md index fa3decdf..0103a5dc 100644 --- a/docs/03-WAYLAND-ON-REDOX.md +++ b/docs/03-WAYLAND-ON-REDOX.md @@ -18,8 +18,8 @@ porting notes. - `smallvil` (Smithay) is still the recommended first runtime target because it is the smallest compositor path already present in-tree - `cosmic-comp` builds but still has no working keyboard input; the remaining issue is runtime/input integration, not simply the absence of a libinput recipe -- `libdrm` builds with all GPU drivers disabled -- Mesa uses OSMesa (software rendering only) +- `libdrm` builds with amdgpu and Intel enabled +- Mesa builds with EGL+GBM+GLES2 (software via LLVMpipe; hardware acceleration still requires kernel DMA-BUF) - **evdevd** (`scheme:evdev`) provides Linux-compatible `/dev/input/eventX` interface - **udev-shim** (`scheme:udev`) provides udev-like device enumeration - **seatd** now builds for Redox and is wired into the KDE runtime config, but DRM-lease/runtime validation is still open @@ -42,12 +42,17 @@ What is actually true today: Read the step-by-step sections below as design history plus implementation notes, not as an exact current-state checklist. -For the current Phase 4 runtime entrypoint in this repo, use: +For the current Wayland runtime entrypoint in this repo, use: - `config/redbear-wayland.toml` - `local/scripts/test-phase4-wayland-qemu.sh` -That path is the current smallvil-first Phase 4 validation target. +> **Numbering note:** the "Phase 4" in the script name above refers to the historical P0-P6 +> hardware-enablement sequence (see `AGENTS.md`). In the v2.0 desktop plan +> (`local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`), Wayland compositor work falls under Phase 2. +> The scripts still work under their original names. + +That path is the current smallvil-first Wayland validation target. Current runtime evidence for that target: @@ -364,8 +369,7 @@ drmd/ β”‚ β”‚ β”œβ”€β”€ plane.rs β€” primary + cursor planes β”‚ β”‚ └── framebuffer.rs β€” framebuffer allocation β”‚ β”œβ”€β”€ gem/ -β”‚ β”‚ β”œβ”€β”€ mod.rs β€” GEM buffer management -β”‚ β”‚ └── dmabuf.rs β€” DMA-BUF export/import +β”‚ β”‚ └── mod.rs β€” GEM buffer management β”‚ └── drivers/ β”‚ β”œβ”€β”€ mod.rs β€” driver trait β”‚ └── intel.rs β€” Intel GPU driver (modesetting) @@ -548,7 +552,7 @@ Once Steps 1-4 are done: 1. **cosmic-comp**: Uncomment libinput dependency in recipe, rebuild 2. **wlroots**: Build with libdrm + libinput + GBM 3. **sway**: Should work once wlroots builds -4. **KWin**: See `05-KDE-PLASMA-ON-REDOX.md` for the full path +4. **KWin**: See `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for the canonical desktop path; `05-KDE-PLASMA-ON-REDOX.md` for historical rationale --- diff --git a/docs/04-LINUX-DRIVER-COMPAT.md b/docs/04-LINUX-DRIVER-COMPAT.md index 489d6065..1461747c 100644 --- a/docs/04-LINUX-DRIVER-COMPAT.md +++ b/docs/04-LINUX-DRIVER-COMPAT.md @@ -24,22 +24,29 @@ Although this document is primarily about the LinuxKPI path for GPU-class driver layer is now being exercised more directly by the bounded Intel Wi-Fi transport port as well. In particular, the current tree now carries LinuxKPI-backed direct/async firmware helpers plus -exported timer, mutex, and IRQ save/restore bindings that the in-tree Intel Wi-Fi transport shim -can consume through actual Linux-style headers. That is still intentionally below the cfg80211 / -mac80211 boundary, but it makes the transport-facing Linux driver port more realistic than a pure -compile-only placeholder. +exported timer, mutex, and IRQ save/restore bindings that the in-tree Intel Wi-Fi transport uses +through actual Linux-style headers. The transport layer now includes full PCIe DMA ring management, +TX/RX queue allocation, command queue with wait/complete semantics, MSI-X interrupt vector tracking, +ieee80211_ops callback registration, NAPI polling, and cfg80211 event dispatch β€” going well beyond +the initial transport-facing boundary. -The tree now also contains the first explicit wireless-subsystem compatibility scaffolding inside -`linux-kpi` itself: initial `sk_buff`, `net_device`, `cfg80211` / `wiphy`, and `mac80211` -registration surfaces that compile and pass host-side crate tests. This should still be read as -foundational compatibility work, not as proof that Red Bear now has a complete Linux wireless stack -or working Intel Wi‑Fi connectivity. +The tree now also contains comprehensive wireless-subsystem compatibility inside `linux-kpi` itself: +`sk_buff` with queue operations, `net_device` with NAPI and queue state, `cfg80211` / `wiphy` with +scan/connect/disconnect/BSS events, `mac80211` with `ieee80211_ops` callback mechanism, channel/ +band/rate/BSS definitions, PCI MSI/MSI-X support, DMA pool allocation, `list_head`, full `atomic_t`, +and IO barrier/copy helpers β€” all compile- and host-test-validated (90 tests pass). This should still +be read as comprehensive compatibility work, not as proof that Red Bear now has working Intel Wi‑Fi +connectivity. -On top of that, the bounded Intel path now also carries the first station-mode compatibility slice: -driver-side scan/connect/disconnect actions, control-daemon connect/disconnect flows, profile- -manager orchestration, and runtime-reporting surfaces that exercise those new LinuxKPI wireless -compatibility surfaces in host-side tests. This is still intentionally below real hardware -scan/auth/association/data-path proof. +On top of that, the Intel path now carries a structurally complete PCIe transport implementation: +persistent device state tracked by PCI identity, firmware header parsing, DMA ring allocation for +TX/RX queues, command submission with timeout-based completion, interrupt cause tracking with +ISR/tasklet dispatch, mac80211 ops callbacks, cfg80211 lifecycle management, device family +detection, CSR register programming, and a chained full-init lifecycle. This is structurally +correct code that would work with real firmware, but without hardware validation it does not +provide working Wi-Fi: command submission times out, scan returns no results, RX processing +produces no frames. The transport is an honest skeleton awaiting hardware bring-up, not a +simulation of working connectivity. Concrete repo entry points for that current bounded Wi‑Fi path are: @@ -52,9 +59,10 @@ Concrete repo entry points for that current bounded Wi‑Fi path are: architecture and operator validation path The validation claim here should also be read narrowly: the repo now has a clean host-side -`linux-kpi` test suite, passing bounded Intel shim/control-plane tests in the dependent crates, and -one host-side CLI flow test for the current Intel path. This is not a claim that a full Linux -Wi‑Fi stack is validated. +`linux-kpi` test suite (90 tests pass), passing comprehensive PCIe transport tests in the +dependent crates (DMA pool, MSI-X, ieee80211_ops, skb queue, NAPI, list_head, atomic_t, +completion timeout, IO barriers), and the iwlwifi transport builds and passes its host-side +test suite (8 tests). This is not a claim that a full Linux Wi‑Fi stack is validated on hardware. ## Goal @@ -301,7 +309,6 @@ redox-drm/ β”‚ β”‚ β”œβ”€β”€ encoder.rs β€” Encoder management β”‚ β”‚ └── plane.rs β€” Primary/cursor planes β”‚ β”œβ”€β”€ gem.rs β€” GEM buffer object management -β”‚ β”œβ”€β”€ dmabuf.rs β€” DMA-BUF export/import via FD passing β”‚ └── drivers/ β”‚ β”œβ”€β”€ mod.rs β€” trait GpuDriver β”‚ β”œβ”€β”€ intel/ diff --git a/docs/05-KDE-PLASMA-ON-REDOX.md b/docs/05-KDE-PLASMA-ON-REDOX.md index 1eb37883..438d1f60 100644 --- a/docs/05-KDE-PLASMA-ON-REDOX.md +++ b/docs/05-KDE-PLASMA-ON-REDOX.md @@ -16,7 +16,7 @@ | Area | Current repo state | |---|---| | Qt6 | Built in-tree (`qtbase`, `qtdeclarative`, `qtsvg`, `qtwayland`) | -| KF6 | Mixed: many real builds, some still partial | +| KF6 | All 32/32 built (some still shimmed or stubbed) | | `config/redbear-kde.toml` | Present with KDE session launcher | | `kwin`, `plasma-workspace`, `plasma-desktop` | Recipes exist, still marked TODO | | `kirigami` | Stub-only package for dependency resolution | @@ -42,11 +42,10 @@ Before KDE work begins, these MUST be complete: - [x] evdevd compiled, libevdev built, libinput 1.30.2 built (comprehensive redox.patch) - [x] DRM/KMS scheme daemon compiled (redox-drm: 15+ ioctls, AMD+Intel drivers) - [x] Wayland: libwayland + wayland-protocols built -- [x] Mesa: OSMesa + LLVMpipe software rendering (EGL platform_redox.c exists, Orbital-only) +- [x] Mesa: EGL+GBM+GLES2 built (software via LLVMpipe; hardware acceleration requires kernel DMA-BUF) - [x] D-Bus 1.16.2 built for Redox -- [x] Qt6: qtbase (Core+Gui+Widgets+DBus+Wayland), qtdeclarative, qtsvg, qtwayland ALL BUILT -- [ ] Mesa EGL+GBM with LLVMpipe (platform_redox.c needs GBM extension β€” planned) -- [ ] libdrm amdgpu+intel enablement (in progress) +- [x] Qt6: qtbase (Core+Gui+Widgets+DBus+Wayland+OpenGL+EGL), qtdeclarative, qtsvg, qtwayland ALL BUILT +- [x] libdrm amdgpu+intel enabled and built ## Three-Phase KDE Implementation @@ -61,22 +60,22 @@ Qt6 core stack fully built for x86_64-unknown-redox: | qtsvg | 6.11.0 | βœ… | Svg, SvgWidgets | | qtwayland | 6.11.0 | βœ… | WaylandClient (compositor disabled) | -### Phase KDE-B: KF6 Frameworks β€” πŸ”„ IN PROGRESS (21/30+ built) +### Phase KDE-B: KF6 Frameworks β€” βœ… COMPLETE (32/32 built) -Built: ecm, kcoreaddons, kwidgetsaddons, kconfig, ki18n, kcodecs, kguiaddons, +All 32 KF6 frameworks built: ecm, kcoreaddons, kwidgetsaddons, kconfig, ki18n, kcodecs, kcolorscheme, kauth, kwindowsystem, knotifications, kjobwidgets, kconfigwidgets, -karchive, sonnet, kcompletion, kitemviews, kitemmodels, solid +karchive, sonnet, kcompletion, kitemviews, kitemmodels, solid, kdbusaddons, kcrash, +kservice, kpackage, ktextwidgets, kiconthemes, kglobalaccel, kdeclarative, kxmlgui, +kbookmarks, kidletime, kio, kcmutils. -Building: kdbusaddons, kcrash - -Recipes ready: kiconthemes, kservice, kpackage, kglobalaccel, kxmlgui, ktextwidgets, -kio, kbookmarks, kdeclarative, kcmutils, kirigami, plasma-framework +Additional KDE-facing packages: kdecoration, plasma-wayland-protocols, kf6-kwayland, +kf6-kcmutils (widget-only), kirigami (stub-only). ### Phase KDE-C: KDE Plasma Assembly β€” πŸ“‹ PLANNED Recipes created: kwin, plasma-workspace, plasma-desktop Config: config/redbear-kde.toml -Blocked on: KF6 completion, Mesa EGL/GBM, libdrm amdgpu+intel +Blocked on: KWin shimmed/stubbed deps resolution, KWin runtime integration, Plasma session assembly **Goal**: A Qt application displays a window on the Redox Wayland compositor. diff --git a/docs/README.md b/docs/README.md index f5751a22..1de2fbe1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,10 +6,10 @@ This index is the entry point for the documentation set. Its main job is to make current/canonical versus historical/reference split obvious. > **Status note (2026-04-16):** The canonical desktop path document is now -> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`. It consolidates the Wayland, KDE, and GPU roadmap -> into one honest implementation plan. The historical docs below (01–05) remain useful for -> architecture reference and implementation rationale, but they should be read together with the -> new plan and the current local subsystem docs. +> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v2.0, three-track Phase 1–5 model). It consolidates +> the Wayland, KDE, and GPU roadmap into one honest implementation plan with testable exit criteria. +> The historical docs below (01–05) remain useful for architecture reference and implementation +> rationale, but they should be read together with the new plan and the current local subsystem docs. > **Status note (2026-04-14):** several documents below are historical implementation plans whose > original "missing / not started" language is now stale. The repo already contains substantial @@ -96,7 +96,7 @@ This summary is only a quick orientation layer. For canonical current-state deta - **Wayland**: libwayland + wayland-protocols built. Smallvil/cosmic-comp remain partial runtime experiments. - **Qt6**: qtbase 6.11.0 (Core+Gui+Widgets+DBus+Wayland), qtdeclarative, qtsvg, qtwayland ALL BUILT - **D-Bus**: 1.16.2 built for Redox. Qt6DBus enabled. -- **KF6 Frameworks**: mixed state β€” many real builds, but some packages are still shimmed or stubbed. +- **KF6 Frameworks**: all 32/32 built. Some packages remain shimmed or stubbed (kirigami stub-only, kf6-kio heavy shim). - **Mesa**: software-rendered path is present; full GBM / hardware-validated Wayland path is still incomplete. - **GPU drivers**: redox-drm scheme daemon and AMD+Intel compile-oriented paths exist; hardware validation is still pending. - **Input**: evdevd compiled, libevdev built, libinput 1.30.2 built diff --git a/local/AGENTS.md b/local/AGENTS.md index 2e281e03..8c22636c 100644 --- a/local/AGENTS.md +++ b/local/AGENTS.md @@ -77,6 +77,19 @@ That means: For relibc specifically, patch carriers should be treated as **temporary compatibility overlays**, not a permanent fork strategy. +When upstream Redox already provides a package, crate, or subsystem for functionality that also +exists in Red Bear local code, prefer the upstream Redox version by default unless the Red Bear +implementation is materially better. Do not grow lower-quality in-house duplicates as a steady +state. + +For quirks and driver support specifically: + +- prefer improving and using the canonical `redox-driver-sys` path, +- avoid maintaining separate lower-quality quirk engines when the same functionality belongs in + `redox-driver-sys`, +- if duplication is temporarily unavoidable, treat it as convergence work to remove, not as a + permanent design. + ### Daily-upstream-safe workflow For any change to upstream-owned source: @@ -133,9 +146,9 @@ redox-master/ ← git pull updates mainline Redox β”‚ β”‚ β”œβ”€β”€ branding/ ← redbear-release (os-release, hostname, motd) β”‚ β”‚ β”œβ”€β”€ drivers/ ← redox-driver-sys, linux-kpi β”‚ β”‚ β”œβ”€β”€ gpu/ ← redox-drm (AMD + Intel display drivers), amdgpu (C port) -β”‚ β”‚ β”œβ”€β”€ system/ ← cub, evdevd, udev-shim, redbear-firmware, firmware-loader, redbear-hwutils, redbear-info, redbear-netctl, redbear-meta -β”‚ β”‚ β”œβ”€β”€ wayland/ ← Wayland compositor (Phase 4) -β”‚ β”‚ └── kde/ ← KDE Plasma (Phase 6) +β”‚ β”‚ β”œβ”€β”€ system/ ← cub, evdevd, udev-shim, redbear-firmware, firmware-loader, redbear-hwutils, redbear-info, redbear-netctl, redbear-quirks, redbear-meta +β”‚ β”‚ β”œβ”€β”€ wayland/ ← Wayland compositor (v2.0 Phase 2) +β”‚ β”‚ └── kde/ ← KDE Plasma (v2.0 Phases 3–4) β”‚ β”œβ”€β”€ patches/ β”‚ β”‚ β”œβ”€β”€ kernel/ ← Kernel patches (ACPI, x2APIC) β”‚ β”‚ β”œβ”€β”€ base/ ← Base patches (acpid fixes, power methods, pcid /config endpoint) @@ -187,7 +200,11 @@ redox-master/ ← git pull updates mainline Redox # Then run inside the guest: # ./local/scripts/test-vm-network-runtime.sh -# Phase 3 runtime-substrate validation +# Phase 1 desktop-substrate validation (v2.0 plan: relibc headers, evdevd, udev-shim, +# firmware-loader, DRM/KMS, health-check β€” covers 6 acceptance areas) +./local/scripts/test-phase1-desktop-substrate.sh --qemu redbear-wayland + +# Legacy Phase 3 runtime-substrate validation (historical P0-P6 numbering; script still works) ./local/scripts/test-phase3-runtime-substrate.sh --qemu redbear-desktop # Low-level controller validation @@ -195,6 +212,7 @@ redox-master/ ← git pull updates mainline Redox ./local/scripts/test-msix-qemu.sh ./local/scripts/test-iommu-qemu.sh ./local/scripts/test-usb-storage-qemu.sh +./local/scripts/test-usb-qemu.sh --check # The current xHCI proof checks for an interrupt-driven mode in boot logs. # The current MSI-X proof uses the live virtio-net path in QEMU. @@ -202,13 +220,13 @@ redox-master/ ← git pull updates mainline Redox # AMD-Vi units initialize and drain events successfully in QEMU. # The USB storage proof currently verifies whether usbscsid autospawns without hitting crash-class errors. -# Phase 4 Wayland runtime validation +# Legacy Phase 4 Wayland runtime validation (historical P0-P6 numbering; script still works) ./local/scripts/build-redbear.sh redbear-wayland ./local/scripts/test-phase4-wayland-qemu.sh # Then run inside the guest: # redbear-phase4-wayland-check -# Phase 5 desktop/network plumbing validation +# Legacy Phase 5 desktop/network plumbing validation (historical P0-P6 numbering; script still works) ./local/scripts/build-redbear.sh redbear-full ./local/scripts/test-phase5-network-qemu.sh --check # Then run inside the guest: @@ -229,7 +247,7 @@ redox-master/ ← git pull updates mainline Redox # ./local/scripts/test-wifi-passthrough-qemu.sh --host-pci 0000:xx:yy.z --check --capture-output ./wifi-passthrough-capture.json # ./local/scripts/finalize-wifi-validation-run.sh ./wifi-passthrough-capture.json ./wifi-passthrough-artifacts.tar.gz -# Phase 6 KDE session-surface validation +# Legacy Phase 6 KDE session-surface validation (historical P0-P6 numbering; script still works) ./local/scripts/build-redbear.sh redbear-kde ./local/scripts/test-phase6-kde-qemu.sh --check # Then run inside the guest: @@ -261,15 +279,17 @@ When mainline updates affect our work: | Build system | Makefile/config changes | `mk/`, `src/` | | rsext4 | ext4 crate API changes | `local/recipes/core/ext4d/source/` Cargo.toml | | Installer | ext4 dispatch, filesystem selection | `local/patches/installer/redox.patch` | +| Quirks | New Linux quirk entries to port | `local/recipes/drivers/redox-driver-sys/source/src/quirks/` | ## PLANNING NOTES - `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` is the canonical public execution plan. +- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v2.0) is the canonical desktop path plan from console to + hardware-accelerated KDE Plasma on Wayland, using a three-track Phase 1–5 model. - `local/docs/AMD-FIRST-INTEGRATION.md` remains the deeper AMD-specific technical roadmap, but AMD and Intel machines are now equal-priority Red Bear OS targets. -- `local/docs/PHASE-0-3-REASSESSMENT.md` explains how to read the early phases consistently when - the historical hardware-enablement phases and newer product-enablement phases use different - numbering. +- `local/docs/PHASE-0-3-REASSESSMENT.md` is deprecated β€” its reconciliation role is now covered by the + updated CONSOLE-TO-KDE-DESKTOP-PLAN.md and docs/07. - `local/docs/WIFI-IMPLEMENTATION-PLAN.md` is the current Wi-Fi architecture and rollout plan, including the bounded role of `linux-kpi` and the native wireless control-plane direction. - `local/docs/USB-IMPLEMENTATION-PLAN.md` and `local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md` should @@ -278,6 +298,10 @@ When mainline updates affect our work: VFIO-backed Intel Wi-Fi validation, packaged checkers, and capture artifacts. - `local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` is the current umbrella plan for IRQ delivery, MSI/MSI-X quality, IOMMU validation, and other low-level controller completeness work. +- `local/docs/QUIRKS-SYSTEM.md` documents the hardware quirks infrastructure: compiled-in tables, + TOML runtime files, DMI matching, driver integration, and the linux-kpi C FFI bridge. +- `local/docs/QUIRKS-IMPROVEMENT-PLAN.md` is the current follow-up plan for removing quirks drift, + integrating quirks into real drivers, and converging on one source of truth. The current execution order for these subsystem plans is: diff --git a/local/docs/ACPI-FIXES.md b/local/docs/ACPI-FIXES.md index 92f99ad4..8fde482b 100644 --- a/local/docs/ACPI-FIXES.md +++ b/local/docs/ACPI-FIXES.md @@ -1,5 +1,8 @@ # ACPI Fixes β€” P0 Phase Tracker +> **Numbering note:** "P0" refers to the historical hardware-enablement phase (ACPI boot), +> not the v2.0 desktop plan phases in `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`. + Status of ACPI fixes for AMD bare metal boot. Cross-referenced with `HARDWARE.md` crash reports and kernel/acpid source TODOs. diff --git a/local/docs/AMD-FIRST-INTEGRATION.md b/local/docs/AMD-FIRST-INTEGRATION.md index 73d5e085..c29459cf 100644 --- a/local/docs/AMD-FIRST-INTEGRATION.md +++ b/local/docs/AMD-FIRST-INTEGRATION.md @@ -1,9 +1,16 @@ -# AMD-FIRST REDOX OS β€” MASTER INTEGRATION PLAN +# AMD-FIRST REDOX OS β€” AMD-SPECIFIC INTEGRATION PLAN -> **Status note (2026-04-14):** This document remains the detailed AMD-focused hardware roadmap, -> but it is no longer the repository-wide platform-priority policy. Red Bear OS should now treat -> AMD and Intel machines as equal-priority targets. Read this file as the deeper AMD-specific plan, -> not as a statement that Intel is secondary going forward. +> **Status note (2026-04-16):** This document remains the detailed AMD-focused hardware roadmap. +> It is no longer the canonical desktop path plan β€” see +> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for that role. This file is now scoped to AMD-specific +> hardware integration detail only. +> +> The P0–P6 section headings below refer to the historical hardware-enablement sequence, not the +> v2.0 desktop plan phases (Phase 1–5). Where numbering conflicts with the v2.0 plan, the v2.0 plan +> takes precedence. +> +> Red Bear OS now treats AMD and Intel machines as equal-priority targets. Read this file as the +> deeper AMD-specific technical plan, not as a platform-priority statement. **Target**: AMD64 bare metal machine with AMD GPU (RDNA2/RDNA3), within an overall Red Bear OS hardware policy that treats AMD and Intel machines as equal-priority targets. @@ -186,7 +193,6 @@ local/recipes/gpu/redox-drm/ β”‚ β”‚ β”œβ”€β”€ encoder.rs # Encoder management β”‚ β”‚ └── plane.rs # Primary/cursor planes β”‚ β”œβ”€β”€ gem.rs # GEM buffer objects -β”‚ β”œβ”€β”€ dmabuf.rs # DMA-BUF export/import β”‚ └── drivers/ β”‚ β”œβ”€β”€ mod.rs # trait GpuDriver β”‚ └── amd/ @@ -257,7 +263,7 @@ ONLY the display/modesetting portion first, using linux-kpi headers. | GTT manager | βœ… | `local/recipes/gpu/redox-drm/source/src/drivers/amd/gtt.rs` | | Ring buffer | βœ… | `local/recipes/gpu/redox-drm/source/src/drivers/amd/ring.rs` | | GEM buffer mgmt | βœ… | `local/recipes/gpu/redox-drm/source/src/gem.rs` | -| DMA-BUF | βœ… | `local/recipes/gpu/redox-drm/source/src/dmabuf.rs` | +| DMA-BUF | βœ… | `local/recipes/gpu/redox-drm/source/src/scheme.rs` (PRIME export/import via opaque tokens) | | Intel driver | βœ… | `local/recipes/gpu/redox-drm/source/src/drivers/intel/mod.rs` + `display.rs` | ### Build Verification @@ -327,7 +333,9 @@ smithay/src/backend/ ### P4-2: libdrm AMD Backend -Currently libdrm has `-Damdgpu=disabled`. Enable it once redox-drm exists. +libdrm now builds with `-Damdgpu=enabled` and `-Dintel=enabled`. The amdgpu and Intel +backends are present in the built sysroot. Runtime hardware validation through real GPU +hardware is still pending. **Patches**: `local/patches/libdrm/` @@ -335,9 +343,10 @@ Currently libdrm has `-Damdgpu=disabled`. Enable it once redox-drm exists. ## PHASE 5: AMD GPU ACCELERATION (16-24 weeks, parallel with P4) -> Note: this AMD-first Phase 5 is a hardware-driver track. It is **not** the same thing as the -> canonical public `docs/07` Phase 5, which is about wired networking and desktop/session -> integration. +> Note: this AMD-first Phase 5 is a hardware-driver track. In the v2.0 desktop plan +> (`local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`), hardware GPU enablement is also Phase 5, so the +> numbering happens to align. The P0–P6 labels in this document refer to the historical +> hardware-enablement sequence, not the current desktop-plan phases. ### P5-1: Full amdgpu Port via LinuxKPI @@ -397,39 +406,29 @@ P0 (ACPI boot) --- -## WHAT NEEDS TO BE DOCUMENTED +## DOCUMENT STATUS -### New Documents to Create +> **Note (2026-04-16):** Most documents and scripts listed below have been created since this plan +> was originally written. This section is retained as a checklist rather than a to-do list. -| Document | Location | Purpose | -|----------|----------|---------| -| This file | `local/docs/AMD-FIRST-INTEGRATION.md` | Master plan | -| ACPI fix guide | `local/docs/ACPI-FIXES.md` | What ACPI functions are missing | -| Firmware loading spec | `local/docs/FIRMWARE-LOADING.md` | How AMD firmware loading works | -| AMD GPU register notes | `local/docs/AMD-GPU-NOTES.md` | Hardware programming notes | -| Bare metal testing log | `local/docs/BAREMETAL-LOG.md` | Hardware test results | -| Build guide (AMD) | `local/docs/BUILD-GUIDE-AMD.md` | How to build for AMD hardware | -| Overlay usage guide | `local/AGENTS.md` | How to use local/ overlay | +### Documents β€” Creation Status -### Existing Documents to Update +| Document | Location | Status | +|----------|----------|--------| +| This file | `local/docs/AMD-FIRST-INTEGRATION.md` | βœ… Created | +| ACPI fix guide | `local/docs/ACPI-FIXES.md` | βœ… Created | +| Bare metal testing log | `local/docs/BAREMETAL-LOG.md` | βœ… Created | +| Overlay usage guide | `local/AGENTS.md` | βœ… Created | +| Desktop path plan | `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` | βœ… Created | -| Document | Change | -|----------|--------| -| `AGENTS.md` (root) | Keep equal-priority AMD/Intel hardware policy visible; keep local/ overlay refs | -| `recipes/core/AGENTS.md` | Add AMD boot requirements, IOMMU note | -| `recipes/wip/AGENTS.md` | Add AMD GPU driver WIP section | -| `docs/AGENTS.md` | Add reference to local/docs/ | -| `docs/04-LINUX-DRIVER-COMPAT.md` | Add AMD-specific porting notes | -| `docs/02-GAP-ANALYSIS.md` | Add P0 bare metal boot layer | +### Config Files and Scripts β€” Creation Status -### Config Files to Create - -| File | Purpose | -|------|---------| -| `local/config/my-amd-desktop.toml` | AMD desktop build config | -| `local/scripts/fetch-firmware.sh` | Download AMD firmware blobs | -| `local/scripts/build-amd.sh` | Build wrapper for AMD target | -| `local/scripts/test-baremetal.sh` | Burn + test on real hardware | +| File | Status | +|------|--------| +| `local/scripts/fetch-firmware.sh` | βœ… Created | +| `local/scripts/build-redbear.sh` | βœ… Created (replaces build-amd.sh) | +| `local/scripts/test-baremetal.sh` | βœ… Created | +| `config/redbear-desktop.toml` | βœ… Created (replaces my-amd-desktop.toml) | --- diff --git a/local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md b/local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md index a84f391a..a1f73415 100644 --- a/local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md +++ b/local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md @@ -74,7 +74,7 @@ one more driver.” The feasible first target is a deliberately small subsystem | Area | State | Notes | |---|---|---| -| Bluetooth controller support | **experimental bounded slice** | `redbear-btusb` provides explicit-startup USB transport probing/status plus a daemon path that is now exercised repeatedly in QEMU for the bounded Battery Level slice | +| Bluetooth controller support | **experimental, USB discovery real** | `redbear-btusb` now probes `/scheme/usb/` for real Bluetooth class devices (USB class 0xE0/0x01/0x01 with vendor-ID fallback), parses descriptor files, assigns `hciN` names deterministically, and writes real adapter metadata into the status file. Daemon re-probes periodically. 8 tests pass including mock-filesystem USB discovery tests. | | Bluetooth host stack | **experimental bounded slice** | `redbear-btctl` provides a BLE-first CLI/scheme surface with stub-backed scan plus bounded connect/disconnect control for stored bond IDs; the packaged checker now reruns that slice repeatedly and covers daemon-restart honesty in QEMU | | Pairing / bond database | **experimental bounded slice** | `redbear-btctl` now persists conservative stub bond records under `/var/lib/bluetooth//bonds/`; connect/disconnect control targets those records, and the checker now verifies cleanup honesty, but this is still storage/control plumbing only, not real pairing or generic reconnect validation | | Desktop Bluetooth API | **missing** | D-Bus exists generally, but no Bluetooth API/service exists | diff --git a/local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md b/local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md index 6bbe7e3a..93d3be31 100644 --- a/local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md +++ b/local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md @@ -1,895 +1,600 @@ # Red Bear OS: Console to Hardware-Accelerated KDE Desktop on Wayland +**Version:** 2.0 (2026-04-16) +**Replaces:** All prior console-to-KDE roadmap documents +**Status:** Canonical desktop path plan + ## Purpose -This document is the single authoritative implementation plan for the Red Bear OS path from -console boot to a hardware-accelerated KDE Plasma desktop on Wayland. +This is the single authoritative plan for the Red Bear OS path from console boot to a +hardware-accelerated KDE Plasma desktop running on Wayland. -It consolidates and replaces the roadmap role previously spread across: +It consolidates and replaces the planning role previously held by: -- `docs/03-WAYLAND-ON-REDOX.md` -- `docs/05-KDE-PLASMA-ON-REDOX.md` -- `docs/02-GAP-ANALYSIS.md` -- `local/docs/AMD-FIRST-INTEGRATION.md` -- `local/docs/DESKTOP-STACK-CURRENT-STATUS.md` -- `local/docs/QT6-PORT-STATUS.md` +- `docs/03-WAYLAND-ON-REDOX.md` (historical Wayland rationale) +- `docs/05-KDE-PLASMA-ON-REDOX.md` (historical KDE rationale) +- `local/docs/AMD-FIRST-INTEGRATION.md` (AMD-specific hardware detail) +- `local/docs/PHASE-0-3-REASSESSMENT.md` (deprecated reconciliation doc) +- Prior revisions of this document (v1, which used a different Phase 1–5 breakdown) -Those documents still matter for subsystem detail, package status, and implementation history. -This document is the place to answer the higher-level question: what still has to happen, in the -right order, before Red Bear OS can honestly claim a usable KDE Plasma desktop on Wayland, first -on the software path and then on real hardware acceleration. +Those documents remain useful for subsystem detail, porting history, and design rationale. +This document answers the higher-level question: **what must happen, in what order, before +Red Bear OS can honestly claim a usable KDE Plasma desktop on Wayland β€” first in software, +then with real hardware acceleration.** -This plan is grounded in the current repo state, not in older greenfield assumptions. The project -already has substantial build-side progress across relibc, driver infrastructure, Wayland, Mesa, -Qt6, KF6, D-Bus, and desktop-facing profiles. The remaining problem is mostly not package absence. -The remaining problem is the gap between what builds and what is runtime-trusted. +This plan is grounded in the current repo state, not greenfield assumptions. The project +has substantial build-side progress across relibc, driver infrastructure, Wayland, Mesa, +Qt6, KF6, D-Bus, and desktop-facing profiles. The remaining problem is not package absence. +It is the gap between what **builds** and what is **runtime-trusted**. -Scope here covers console boot to first working Wayland compositor proof, software-rendered Qt6 on -Wayland, hardware GPU validation for AMD and Intel, KWin session bring-up, and KDE Plasma session -bring-up. It does not cover USB, Wi-Fi, Bluetooth, tutorial-style examples, or repo structure and -build-command reference material already documented elsewhere. +Scope: console boot β†’ first Wayland compositor proof β†’ software-rendered Qt6 on Wayland β†’ +hardware GPU validation β†’ KWin session bring-up β†’ KDE Plasma session bring-up. -This document uses the current Red Bear hardware policy. AMD and Intel GPUs are equal-priority -desktop targets. +Out of scope: USB, Wi-Fi, Bluetooth (covered by their own subsystem plans). + +--- + +## Evidence Model + +This plan uses strict evidence classes. They are not interchangeable. + +| Class | Meaning | Safe to say | Not safe to say | +|---|---|---|---| +| **builds** | Package compiles and stages | "builds" | "works" | +| **boots** | Image reaches prompt or known runtime surface | "boots" | "desktop works" | +| **enumerates** | Scheme/device node appears and answers basic queries | "enumerates" | "usable end to end" | +| **usable** | Bounded runtime path performs its intended task | "usable for this path" | "broadly stable" | +| **validated** | Repeated proof on the intended target class | "validated" | "complete everywhere" | +| **experimental** | Partial, scaffolded, or unproven | "experimental" | "done" | + +Rules: +- Compiles-only β†’ called **builds** +- Boots but doesn't complete a session β†’ called **boots** +- Daemon registers a scheme β†’ called **enumerates** +- Only QEMU proof β†’ claim stays bounded to QEMU +- Dependencies still shimmed/stubbed β†’ layer remains **experimental** +- Nothing is **validated** without repeated runtime proof on the intended target class + +--- ## Current State Baseline -### Evidence model - -This plan uses six evidence classes. They are intentionally strict and are not treated as equal. - -| Evidence class | Meaning | Safe wording | Not safe wording | -|---|---|---|---| -| **builds** | package compiles and stages | builds | works | -| **boots** | image reaches prompt or known runtime surface | boots | desktop works | -| **enumerates** | scheme, device node, or service surface appears and answers basic queries | enumerates | usable end to end | -| **usable** | a bounded runtime path performs its intended task | usable for this path | broadly stable | -| **validated** | repeated proof on the intended target class with explicit checks | validated | complete everywhere | -| **experimental** | partial, scaffolded, or unproven despite visible progress | experimental | done | - -Interpretation rules used throughout this document: - -- if something only compiles, it is called **builds** -- if something boots but does not complete a session, it is called **boots** -- if a daemon registers a scheme or device node, it is called **enumerates** -- if the only proof is a bounded QEMU path, the claim stays bounded to that path -- if dependencies are still shimmed or stubbed, the layer remains **experimental** -- nothing is called **validated** without repeated runtime proof on the intended target class - ### Honest capability matrix -| Area | Current state | Evidence | Notes | +| Area | State | Evidence | Notes | |---|---|---|---| -| AMD bare-metal boot | present | validated for bounded current claim | ACPI, SMP, x2APIC all work | -| relibc Wayland and Qt unblockers | present | builds | signalfd, timerfd, eventfd, open_memstream, F_DUPFD_CLOEXEC, MSG_NOSIGNAL, bounded waitid, bounded RLIMIT, bounded eth0 networking, shm_open, bounded sem_open, bounded sys/ipc.h, bounded sys/shm.h | -| redox-driver-sys | present | builds | driver substrate | -| linux-kpi | present | builds | compatibility layer for Linux-style drivers | -| firmware-loader | present | builds, boots | scheme registers at boot | -| redox-drm with AMD and Intel | present | builds | runtime hardware validation still open | -| amdgpu C port | present | builds | AMD DC + TTM + linux-kpi compat compiles | -| evdevd | present | builds, boots | scheme registers at boot | -| udev-shim | present | builds, boots | scheme registers at boot | -| libwayland 1.24.0 | present | builds | no full compositor proof yet | -| wayland-protocols | present | builds | build-side blocker removed | -| Mesa EGL + GBM + GLES2 | present | builds | proven runtime path is still software via LLVMpipe | -| libdrm + libdrm_amdgpu | present | builds | package-level success only | -| Qt6 qtbase 6.11.0 | present | builds | Core, Gui, Widgets, DBus, Wayland, OpenGL, EGL | -| qtdeclarative | present | builds | QML JIT disabled | -| qtsvg | present | builds | build-visible | -| qtwayland | present | builds | build-visible | -| D-Bus 1.16.2 | present | builds, bounded runtime wiring | system bus wired in `redbear-full` | -| libinput 1.30.2 | present | builds | runtime integration still open | -| libevdev 1.13.2 | present | builds | runtime integration still open | -| linux-input-headers | present | builds | support package | -| seatd | present | builds | session-management runtime proof still open | -| All 32 KF6 frameworks | present | builds | major build milestone complete | -| kdecoration | present | builds | build-visible | -| plasma-wayland-protocols | present | builds | build-visible | -| kf6-kwayland | present | builds | build-visible | -| kf6-kcmutils | present | builds, reduced | widget-only build | -| `redbear-wayland` | present | builds, boots | bounded Wayland runtime profile | -| `redbear-full` | present | builds, boots | broader desktop plumbing profile | -| `redbear-kde` | present | builds | KDE session-surface profile | -| smallvil path | partial | boots, experimental | reaches xkbcommon init and EGL platform selection in QEMU | -| QEMU graphics truth | present | usable for bounded path | current renderer is llvmpipe, not hardware acceleration | -| D-Bus system bus in `redbear-full` | present | usable for bounded path | not equal to full session integration completeness | -| VirtIO networking in QEMU | present | usable | useful for bounded test environment | -| firmware-loader, evdevd, udev-shim scheme registration | present | enumerates | register during boot | -| KWin | blocked | experimental | recipe exists, blocked by remaining shimmed and stubbed dependencies | -| plasma-workspace | partial | experimental | recipe exists, still experimental | -| plasma-desktop | partial | experimental | recipe exists, still experimental | -| QtNetwork | blocked | intentionally disabled | relibc networking completeness still too narrow | -| hardware GPU acceleration | blocked | not runtime-proven | kernel DMA-BUF fd passing required | -| working Wayland compositor session | blocked | runtime not proven | smallvil does not complete a usable session | -| KWin compositor runtime | blocked | runtime not proven | no working KWin session | -| KDE Plasma session | blocked | runtime not proven | no full Plasma session | +| AMD bare-metal boot | validated | Boot, ACPI, SMP, x2APIC all work | Bounded to current tested hardware | +| relibc Wayland/Qt unblockers | builds | signalfd, timerfd, eventfd, open_memstream, F_DUPFD_CLOEXEC, MSG_NOSIGNAL, bounded waitid, bounded RLIMIT, bounded eth0 networking, shm_open, bounded sem_open, bounded sys/ipc.h, bounded sys/shm.h | Runtime pressure from real consumers still untested | +| redox-driver-sys | builds | Driver substrate | | +| linux-kpi | builds | Linux kernel API compatibility layer | | +| firmware-loader | builds, boots | scheme:firmware registers at boot | | +| redox-drm (AMD + Intel) | builds | DRM scheme daemon | No hardware runtime validation | +| amdgpu C port | builds | AMD DC + TTM + linux-kpi compat | No hardware runtime validation | +| evdevd | builds, boots | scheme:evdev registers at boot | | +| udev-shim | builds, boots | scheme:udev registers at boot | | +| libwayland 1.24.0 | builds | No compositor proof yet | | +| wayland-protocols | builds | Build blocker removed | | +| Mesa EGL + GBM + GLES2 | builds | Software rendering via LLVMpipe proven | Hardware path not proven | +| libdrm + libdrm_amdgpu | builds | Package-level success only | | +| Qt6 qtbase 6.11.0 | builds | Core, Gui, Widgets, DBus, Wayland, OpenGL, EGL | | +| qtdeclarative | builds | QML JIT disabled | | +| qtsvg | builds | | | +| qtwayland | builds | | | +| D-Bus 1.16.2 | builds, bounded runtime | System bus wired in redbear-full | | +| libinput 1.30.2 | builds | Runtime integration open | | +| libevdev 1.13.2 | builds | Runtime integration open | | +| seatd | builds | Session-management runtime proof open | | +| All 32 KF6 frameworks | builds | Major build milestone | | +| kdecoration | builds | | | +| plasma-wayland-protocols | builds | | | +| kf6-kwayland | builds | | | +| kf6-kcmutils | builds | Widget-only build (QML stripped) | | +| `redbear-wayland` profile | builds, boots | Bounded Wayland runtime profile | | +| `redbear-full` profile | builds, boots | Broader desktop plumbing profile | | +| `redbear-kde` profile | builds | KDE session-surface profile | KWin only, not plasma-workspace/desktop yet | +| smallvil compositor path | experimental | Reaches xkbcommon init + EGL platform selection in QEMU | No complete session | +| qt6-wayland-smoke | builds, partial | Creates QWindow with colored background, runs 3 seconds | | +| QEMU graphics | usable (bounded) | Renderer is llvmpipe | Not hardware acceleration | +| D-Bus system bus (redbear-full) | usable (bounded) | Not full session integration | | +| VirtIO networking (QEMU) | usable | | | +| KWin | experimental, blocked | Recipe exists, blocked by shimmed/stubbed deps | | +| plasma-workspace | experimental | Recipe exists, incomplete deps | | +| plasma-desktop | experimental | Recipe exists, incomplete deps | | +| QtNetwork | blocked | Intentionally disabled β€” relibc networking too narrow | | +| Hardware GPU acceleration | blocked | PRIME/DMA-BUF scheme ioctls implemented, no GPU CS ioctl | | +| Working Wayland compositor session | blocked | Runtime not proven | | +| KWin compositor runtime | blocked | Runtime not proven | | +| KDE Plasma session | blocked | Runtime not proven | | -### What is DONE, build-side +### What is DONE (build-side) -The repo has already crossed several major build-side gates. +The repo has crossed major build-side gates: -#### relibc surface that now builds downstream consumers +1. **relibc surface** β€” signalfd, timerfd, eventfd, open_memstream, F_DUPFD_CLOEXEC, MSG_NOSIGNAL, bounded waitid, bounded RLIMIT, bounded eth0 networking, shm_open, bounded sem_open, bounded sys/ipc.h, bounded sys/shm.h +2. **Driver substrate** β€” redox-driver-sys, linux-kpi, firmware-loader, redox-drm (AMD+Intel), amdgpu C port, evdevd, udev-shim +3. **Wayland/graphics packages** β€” libwayland, wayland-protocols, Mesa EGL+GBM+GLES2, libdrm, libdrm_amdgpu +4. **Qt6 + D-Bus** β€” qtbase (7 libs + 12 plugins), qtdeclarative (11 libs), qtsvg, qtwayland, D-Bus 1.16.2 +5. **KF6 + KDE-facing** β€” All 32 KF6 frameworks, kdecoration, plasma-wayland-protocols, kf6-kwayland, kf6-kcmutils +6. **Tracked profiles** β€” redbear-wayland, redbear-full, redbear-kde -The current build-visible relibc surface includes signalfd, timerfd, eventfd, open_memstream, -F_DUPFD_CLOEXEC, MSG_NOSIGNAL, bounded waitid, bounded RLIMIT behavior, bounded eth0 networking, -shm_open, bounded sem_open, bounded `sys/ipc.h`, and bounded `sys/shm.h`. +### What is runtime-proven (limited scope) -#### driver and runtime-service substrate - -redox-driver-sys, linux-kpi, firmware-loader, redox-drm with AMD and Intel paths, the amdgpu C -port, evdevd, and udev-shim all build successfully. - -#### Wayland and graphics packages - -libwayland 1.24.0, wayland-protocols, Mesa EGL + GBM + GLES2 with `libEGL.so`, `libgbm.so`, -`libGLESv2.so`, `swrast_dri.so`, plus libdrm and libdrm_amdgpu all build. - -#### Qt6 and D-Bus - -D-Bus 1.16.2 builds. qtbase 6.11.0 builds with Core, Gui, Widgets, DBus, Wayland, OpenGL, and -EGL. qtdeclarative, qtsvg, and qtwayland also build. - -#### KF6 and KDE-facing build surfaces - -All 32 KF6 frameworks build. The completed set spans ecm, core and widget foundations, config, -internationalization, codecs, GUI add-ons, color and notification layers, job and archive support, -item models and views, Solid, D-Bus and service layers, package and crash handling, text and icon -layers, global shortcuts, KDE declarative support, XML GUI, bookmarks, idle time, KIO, and -KCMUtils. Additional KDE-facing packages that already build include kdecoration, -plasma-wayland-protocols, kf6-kwayland, and kf6-kcmutils. - -#### tracked desktop profiles - -The tracked desktop-facing profiles are `redbear-wayland`, `redbear-full`, and `redbear-kde`. - -These are real achievements and should be presented as such. They are not yet desktop-runtime proof. - -### What is runtime-proven, limited scope - -The current desktop-related runtime proof is bounded, but real. - -#### Boot and machine substrate - -Red Bear boots on AMD bare metal, and ACPI, SMP, and x2APIC work for the current bounded claim. - -#### bounded Wayland bring-up path - -`redbear-wayland` boots in QEMU, and smallvil reaches xkbcommon initialization plus EGL platform -selection on Redox. - -#### bounded graphics truth - -Current QEMU graphics are software-rendered, the renderer evidence is llvmpipe, QEMU is useful for -compositor and Qt bring-up, and QEMU is not proof of the final hardware-accelerated desktop path. - -#### bounded runtime services - -D-Bus system bus is wired in `redbear-full`, VirtIO networking works in QEMU, and firmware-loader, -evdevd, and udev-shim register schemes at boot. +- AMD bare-metal boot with ACPI, SMP, x2APIC +- `redbear-wayland` boots in QEMU, smallvil reaches early init +- QEMU graphics via llvmpipe (software) +- D-Bus system bus wired in `redbear-full` +- VirtIO networking in QEMU +- firmware-loader, evdevd, udev-shim register schemes at boot ### What is NOT DONE -This list must stay explicit. +**Runtime not proven:** +- No GPU hardware-accelerated rendering +- No working Wayland compositor session +- No KWin compositor runtime +- No KDE Plasma session +- Qt6 OpenGL/EGL only have software-path proof -#### runtime not proven - -No GPU hardware-accelerated rendering is proven, no kernel DMA-BUF support exists for the required -desktop path, no working Wayland compositor session is proven, no KWin compositor runtime is -proven, no KDE Plasma session is proven, and Qt6 OpenGL and EGL still have only software-path -runtime proof. - -#### builds still blocked or scaffolded - -KWin does not build end to end with fully real dependencies. Kirigami is still stub-only, KIO is -still a heavy shim build, libepoxy, libudev, lcms2, and libdisplay-info remain real blockers, -plasma-workspace and plasma-desktop remain experimental, and QtNetwork remains disabled due to -incomplete relibc networking semantics. +**Builds still blocked/scaffolded:** +- KWin does not build with fully real dependencies (4 stub deps: libepoxy, libudev, lcms2, libdisplay-info) +- kirigami is stub-only +- kf6-kio is a heavy shim +- 9 KWin feature switches remain disabled +- QtNetwork disabled (relibc networking incomplete) ### Baseline conclusion -The repo is no longer stuck at package availability. It is now limited by runtime trust, hardware -validation, and KWin or Plasma session assembly. That is the real starting point for the plan below. +The repo is no longer stuck at package availability. It is limited by **runtime trust, +hardware validation, and KWin/Plasma session assembly**. That is the real starting point. + +--- ## Dependency Stack -### ASCII layer diagram - ```text -+--------------------------------------------------------------------------------+ -| KDE Plasma Session | -| plasma-workspace, plasma-desktop, shell, panels, launcher, apps | -+---------------------------------------^----------------------------------------+ - | -+---------------------------------------|----------------------------------------+ -| KWin desktop-session layer | -| KWin, kdecoration, seat and session wiring | -+---------------------------------------^----------------------------------------+ - | -+---------------------------------------|----------------------------------------+ -| Qt6 and KDE frameworks | -| Qt6 Widgets, QtWayland, QtDBus, QML, KF6, KDE support libs | -+---------------------------------------^----------------------------------------+ - | -+---------------------------------------|----------------------------------------+ -| Wayland compositor and protocols | -| smallvil first, then KWin, plus libwayland | -+---------------------------------------^----------------------------------------+ - | -+---------------------------------------|----------------------------------------+ -| Mesa, GBM, EGL, GLES2, libdrm | -| software path first, hardware path after DMA-BUF | -+---------------------------------------^----------------------------------------+ - | -+---------------------------------------|----------------------------------------+ -| DRM, KMS, firmware, input, device enumeration | -| redox-drm, amdgpu, Intel path, evdevd, udev-shim | -+---------------------------------------^----------------------------------------+ - | -+---------------------------------------|----------------------------------------+ -| Kernel and libc substrate for desktop bring-up | -| relibc, fd passing, DMA-BUF, IRQ, PCI, schemes | -+---------------------------------------^----------------------------------------+ - | -+---------------------------------------|----------------------------------------+ -| Hardware and boot substrate | -| AMD64 boot, ACPI, SMP, x2APIC, AMD and Intel GPUs | -+--------------------------------------------------------------------------------+ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ KDE Plasma Session β”‚ +β”‚ plasma-workspace, plasma-desktop, shell, panels, launcher, apps β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ KWin desktop-session layer β”‚ +β”‚ KWin, kdecoration, seat and session wiring β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Qt6 and KDE frameworks β”‚ +β”‚ Qt6 Widgets, QtWayland, QtDBus, QML, KF6, KDE support libs β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Wayland compositor and protocols β”‚ +β”‚ smallvil first, then KWin, plus libwayland β”‚ +β”‚ NOTE: KWin replaces smallvil as the compositor in Phase 3, β”‚ +β”‚ spanning both the compositor layer and the session layer. β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Mesa, GBM, EGL, GLES2, libdrm β”‚ +β”‚ software path first, hardware path after DMA-BUF β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ DRM, KMS, firmware, input, device enumeration β”‚ +β”‚ redox-drm, amdgpu, Intel path, evdevd, udev-shim β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Kernel and libc substrate for desktop β”‚ +β”‚ relibc, fd passing, DMA-BUF, IRQ, PCI, schemes β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Hardware and boot substrate β”‚ +β”‚ AMD64 boot, ACPI, SMP, x2APIC, AMD and Intel GPUs β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` -### Reading the dependency stack correctly - -This stack has two kinds of blockers. - -#### runtime substrate blockers - -These sit low in the stack and poison all higher work if they are not validated: - -- relibc runtime correctness -- input event correctness -- udev-like device enumeration correctness -- firmware loading correctness -- basic DRM and KMS correctness -- kernel DMA-BUF support for the accelerated path - -#### session-assembly blockers - -These sit higher and matter after the lower layers are trusted: - -- smallvil completion -- Qt6 client display on Wayland -- KWin dependency cleanup -- KWin runtime session wiring -- Plasma shell and workspace integration - -The plan must handle these in order. Otherwise failures in KWin or Plasma will really be lower-layer -failures in disguise. - ### Layer-by-layer status -#### Layer 0, hardware and boot +| Layer | State | What's proven | What's missing | +|---|---|---|---| +| Hardware + boot | partly runtime-proven | AMD boot, ACPI, SMP, x2APIC | Desktop-path validation on real AMD/Intel GPUs | +| Kernel + libc | strong build-side, runtime incomplete | relibc surfaces, driver substrate | Real Wayland/Qt event-loop pressure, GPU CS ioctl | +| DRM/firmware/input | build + boot visible, not runtime-trusted | Scheme registration at boot | Real firmware loading, real input flow, real DRM/KMS queries | +| Graphics userland | software builds, hardware blocked | Mesa EGL/GBM/GLES2, libdrm, Qt6 OpenGL | Hardware renderer path, GBM/EGL on hardware | +| Wayland compositor | partial runtime, not complete | smallvil reaches early init in QEMU | Complete compositor session, input routing, Qt6 client display | +| Qt6 + KF6 | build milestone, runtime thin | All packages build | Real Qt6 Wayland client behavior, QML without JIT | +| KWin session | experimental, blocked | Recipes exist, some features re-enabled | Honest deps, KWin runtime, session services | +| KDE Plasma | not yet proven | Recipe surfaces exist | plasma-workspace, plasma-desktop, shell, panel, apps | -Status: **partly runtime-proven** +### Conclusion -What is true now: +The shortest honest path is not "port more packages". It is: +1. **Validate the substrate** (turn builds into runtime trust) +2. **Finish one software compositor path** (smallvil) +3. **Finish one KWin session path** (on software renderer) +4. **Finish one Plasma session path** (on software renderer) +5. **Land real hardware acceleration** (in parallel with steps 3–4) -- AMD bare-metal boot works for the current bounded claim -- ACPI, SMP, and x2APIC work -- AMD and Intel are equal-priority GPU targets - -What still needs proof: - -- real desktop-path validation on AMD GPUs -- real desktop-path validation on Intel GPUs - -#### Layer 1, kernel and libc substrate - -Status: **strong build-side, runtime incomplete** - -What is true now: - -- relibc exposes the build-visible Wayland and Qt unblockers -- redox-driver-sys and linux-kpi exist as the current driver substrate - -What still needs proof: - -- relibc behavior under real Wayland and Qt event-loop pressure -- kernel DMA-BUF fd passing for the hardware path - -#### Layer 2, DRM, firmware, input, enumeration - -Status: **build-visible and boot-visible, not runtime-trusted** - -What is true now: - -- redox-drm builds with AMD and Intel drivers -- amdgpu builds -- firmware-loader, evdevd, and udev-shim register at boot - -What still needs proof: - -- actual firmware loading by a real consumer -- actual input flow from Redox input sources into compositor-visible event devices -- actual scheme:drm registration and basic KMS query behavior in runtime -- actual AMD and Intel hardware-driver behavior on target machines - -#### Layer 3, graphics userland interface - -Status: **software path builds, hardware path blocked** - -What is true now: - -- Mesa EGL, GBM, and GLES2 build -- libdrm and libdrm_amdgpu build -- Qt6 OpenGL and EGL build -- QEMU proof still uses llvmpipe - -What still needs proof: - -- hardware renderer path through real DRM and real GPU drivers -- GBM allocation on the hardware path -- EGL and GLES stability on the hardware path - -#### Layer 4, Wayland protocol and compositor - -Status: **partial runtime proof, not complete** - -What is true now: - -- libwayland and wayland-protocols build -- smallvil is the bounded first runtime target -- smallvil reaches early initialization in QEMU - -What still needs proof: - -- a complete compositor session -- input routed into the compositor -- Qt6 client display in that compositor - -#### Layer 5, Qt6 and KF6 - -Status: **major build milestone complete, runtime still thin** - -What is true now: - -- Qt6 builds across core, widgets, DBus, Wayland, OpenGL, and EGL -- qtdeclarative and qtwayland build -- all 32 KF6 frameworks build - -What still needs proof: - -- real Qt6 Wayland client behavior on Redox -- behavior of QML-heavy pieces under the no-JIT path -- broader networking semantics needed before QtNetwork can be enabled - -#### Layer 6, KWin session shell - -Status: **experimental and blocked** - -What is true now: - -- recipes exist -- `redbear-kde` exists -- several KWin-adjacent packages already build - -What still needs proof: - -- replacement of shimmed and stubbed blockers with real enough dependencies -- KWin compile success against honest dependencies -- KWin runtime as the compositor - -#### Layer 7, KDE Plasma session - -Status: **not yet proven** - -What is true now: - -- Plasma recipe surfaces exist -- the stack is far enough along that this is now a session-assembly problem, not a package-startup problem - -What still needs proof: - -- plasma-workspace integration -- plasma-desktop integration -- panel, launcher, file manager, settings, and session service behavior - -### Dependency-stack conclusion - -The shortest honest path is not "port more packages". The shortest honest path is "validate the -substrate, finish one software compositor path, finish one KWin session path, finish one Plasma -session path, then land the real hardware renderer path in parallel". +--- ## Phased Work Plan -This plan uses fresh Phase 1 through Phase 5 numbering and does not reuse the old P0 through P6 -scheme. +This plan uses a three-track model: + +- **Track A: Runtime Substrate β†’ Compositor** (sequential, blocking) +- **Track B: Desktop Session Assembly** (sequential after Track A, Phase 2) +- **Track C: Hardware GPU Enablement** (parallel with Track B) + +``` +Track A (Phases 1–2): Substrate β†’ Software Compositor + Phase 1: Runtime Substrate Validation (4–6 weeks) + Phase 2: Wayland Compositor Proof (4–6 weeks) + +Track B (Phases 3–4): Desktop Session Assembly + Phase 3: KWin Desktop Session (6–10 weeks, starts after Phase 2) + Phase 4: KDE Plasma Session (8–12 weeks, starts after Phase 3) + +Track C (parallel): Hardware GPU Enablement + Phase 5: Hardware GPU Enablement (12–20 weeks, starts after Phase 1) +``` ### Phase 1: Runtime Substrate Validation -**Duration:** 4 to 6 weeks +**Duration:** 4–6 weeks +**Goal:** Turn the lowest desktop-facing layers from build-visible into runtime-trusted. +**Why it matters most:** Without this phase, all later failures will be impossible to diagnose correctly. -**Goal:** turn the lowest desktop-facing layers from build-visible into runtime-trusted. +#### Work items -This phase matters more than any other because it removes ambiguity from the entire stack. Without -it, later compositor or KDE failures will be impossible to classify correctly. +| # | Task | Acceptance criteria | +|---|---|---| +| 1.1 | Validate relibc POSIX APIs against real consumers (libwayland, Qt6) | signalfd/timerfd/eventfd pass libwayland event-loop smoke test; shm_open/sem_open pass Qt6 shared-memory path; waitid passes Qt6 process exit detection | +| 1.2 | Validate evdevd path: input schemes β†’ `/dev/input/eventX` | Keyboard/mouse events arrive with correct semantics | +| 1.3 | Validate udev-shim device enumeration | libinput can enumerate at least one keyboard and one pointer device through udev-shim; DRM devices are visible to Mesa | +| 1.4 | Validate firmware-loader with real blobs + real consumer | Blob is requestable, loadable, consumable at runtime | +| 1.5 | Validate `scheme:drm/card0` registration + bounded KMS queries in QEMU | Scheme registers, answers basic queries, no startup-class failures | +| 1.6 | Produce repeatable runtime-service health check for `redbear-wayland` | `redbear-info` or equivalent shows all Phase 1 services as functional | -#### Core work +#### Exit criteria -1. Validate relibc POSIX APIs against real consumers, especially libwayland and Qt6 runtime paths. -2. Validate the evdevd path from Redox input schemes through to `/dev/input/eventX` behavior. -3. Validate udev-shim device enumeration semantics for the current compositor and input stack. -4. Validate firmware-loader and `scheme:firmware` with real firmware blobs and a real consumer path. -5. Validate `scheme:drm/card0` registration and bounded KMS queries in QEMU. -6. Produce a repeatable runtime-service health check for the `redbear-wayland` slice. - -#### Why this phase exists - -The repo already compiles the lower desktop stack. What it lacks is evidence that the lower stack -behaves correctly under real use. Phase 1 is where builds become runtime-trusted enough to support -the first serious compositor pass. - -#### Deliverables - -##### relibc runtime validation set - -Validate the relibc surfaces already present in-tree: - -- signalfd -- timerfd -- eventfd -- open_memstream -- F_DUPFD_CLOEXEC -- MSG_NOSIGNAL -- bounded waitid -- bounded shared-memory and semaphore paths used by Qt6 - -The standard here is not just "the symbol exists". The standard is that real consumers can use the -API without hidden workarounds, hangs, or broken semantics. - -##### evdev input validation set - -Validate the current input chain end to end: - -- input source emits events -- evdevd exposes expected event devices -- keyboard events arrive with correct semantics -- mouse events arrive with correct semantics - -##### udev-shim validation set - -Validate that current consumers can discover and classify the devices they need. Full Linux parity -is not required. Sufficient enumeration for the current desktop path is required. - -##### firmware-loader validation set - -Validate firmware loading with real blobs and a real consumer path. Scheme registration alone is not -enough. The blob must be requestable, discoverable, loadable, and consumable at runtime. - -##### redox-drm runtime-surface validation set - -Validate bounded runtime behavior first in QEMU: - -- scheme registration for `scheme:drm/card0` -- basic KMS queries -- no startup-class failures in the redox-drm path - -#### Acceptance criteria - -Phase 1 is complete when all of the following are true: - -- `redbear-wayland` boots in the bounded validation environment -- Phase 1 runtime services register without startup errors -- relibc runtime checks pass for the selected desktop-facing consumers -- the input path reaches evdevd and yields expected event nodes and bounded test events -- udev-shim exposes the expected bounded device view -- firmware-loader successfully serves at least one real consumer path with real blobs -- `scheme:drm/card0` registers and answers bounded basic queries +- [ ] `redbear-wayland` boots in validation environment +- [ ] All Phase 1 runtime services register without startup errors +- [ ] relibc runtime checks pass for desktop-facing consumers +- [ ] Input path reaches evdevd and yields expected event nodes + bounded test events +- [ ] udev-shim exposes expected bounded device view +- [ ] firmware-loader serves at least one real consumer path with real blobs +- [ ] `scheme:drm/card0` registers and answers bounded basic queries #### Exit statement -At the end of Phase 1, the repo should be able to say: the desktop substrate is no longer only a -build artifact. It is runtime-trusted enough to support a compositor completion pass. +> The desktop substrate is no longer only a build artifact. It is runtime-trusted enough +> to support a compositor completion pass. + +--- ### Phase 2: Wayland Compositor Runtime Proof -**Duration:** 4 to 6 weeks +**Duration:** 4–6 weeks +**Goal:** Produce the first working Wayland compositor session using software rendering. +**Profile target:** `redbear-wayland` +**Renderer:** LLVMpipe (software) β€” acceptable for correctness proof. -**Goal:** produce the first working Wayland compositor session using software rendering. +#### Why smallvil first -This phase stays intentionally narrow. The first complete compositor proof should happen in the -smallest runtime target available, which is still smallvil. +Jumping straight to KWin combines too many unknowns: compositor runtime, input, QML, +session services, dependency scaffolding. smallvil is smaller, easier to debug, already +present. It isolates compositor + input + Qt client issues before session-shell complexity. -#### Core work +#### Work items -1. Complete the current smallvil runtime path. -2. Wire evdevd input into the compositor. -3. Wire Mesa software rendering through GBM and EGL. -4. Get a Qt6 widget application to display through the compositor. +| # | Task | Acceptance criteria | +|---|---|---| +| 2.1 | Complete smallvil runtime path to usable session | smallvil launches, creates a Wayland surface, and does not crash for at least 60 seconds in QEMU; `WAYLAND_DISPLAY` is set and a client can connect | +| 2.2 | Wire evdevd input into compositor | Keyboard + mouse work through Redox input stack | +| 2.3 | Wire Mesa software rendering through GBM + EGL | Software rendering works through Mesa/GBM/EGL | +| 2.4 | Get Qt6 widget app to display through compositor | `qt6-wayland-smoke` shows a window inside compositor in QEMU | -#### Why smallvil remains the right target +#### Exit criteria -Jumping straight to KWin would combine too many unknowns: compositor runtime, input, QML, session -services, dependency scaffolding, and desktop-shell behavior. smallvil is smaller, easier to debug, -and already present. It is the right place to finish the first software compositor proof. - -#### Deliverables - -##### complete smallvil runtime path - -The current proof stops during early initialization. This phase completes the path into a usable -session. - -##### input wired into compositor - -Keyboard and mouse must work through the current Redox input stack, not through an artificial bypass. - -##### software rendering path confirmed - -The proven renderer for this phase is LLVMpipe through Mesa, GBM, and EGL. That is acceptable. The -goal is correctness of compositor and client behavior, not hardware acceleration yet. - -##### Qt6 smoke client on Wayland - -The first meaningful desktop-facing end-to-end proof is a real Qt6 Wayland client window appearing -inside the compositor. - -#### Acceptance criteria - -Phase 2 is complete when all of the following are true: - -- smallvil launches into a working session in QEMU -- keyboard and mouse work through the current input stack -- Mesa software rendering works through GBM and EGL -- `qt6-wayland-smoke` shows a window inside the compositor in QEMU +- [ ] smallvil launches into a working session in QEMU +- [ ] Keyboard and mouse work through the current input stack +- [ ] Mesa software rendering works through GBM and EGL +- [ ] `qt6-wayland-smoke` shows a window inside the compositor in QEMU #### Exit statement -At the end of Phase 2, the repo should be able to say: Red Bear OS has a working software-rendered -Wayland compositor path with a visible Qt6 client. +> Red Bear OS has a working software-rendered Wayland compositor path with a visible +> Qt6 client. -### Phase 3: Hardware GPU Enablement +--- -**Duration:** 12 to 20 weeks +### Phase 3: KWin Desktop Session -**Goal:** replace the software-only graphics proof with real hardware-accelerated display output and -rendering. +**Duration:** 6–10 weeks (starts after Phase 2) +**Goal:** Turn compositor proof into a real desktop-session substrate centered on KWin. +**Profile target:** `redbear-kde` +**Renderer:** LLVMpipe (software) β€” KWin inherits accelerated renderer once Phase 5 lands. -This is the highest-uncertainty phase. It includes new kernel work, real hardware-driver proof, and -the first true Mesa hardware path on Redox. +#### Blocked dependency set that must be closed -#### Core work +**Stub dependencies** (INTERFACE IMPORTED cmake targets without real implementations): -1. Add kernel DMA-BUF fd passing. -2. Validate redox-drm AMD and Intel drivers on real hardware. -3. Validate Mesa hardware rendering path, including real renderer identity. -4. Validate GBM buffer allocation through the hardware path. +| Stub | Must become | Path | +|---|---|---| +| libepoxy-stub | Real libepoxy build | Port or find minimal GL dispatch alternative | +| libudev-stub | Real libudev or enhanced udev-shim lib | Extend udev-shim to provide libudev API | +| lcms2-stub | Real lcms2 build | Port lcms2 color management library | +| libdisplay-info-stub | Real libdisplay-info build | Port or find alternative | -#### Why this phase is separate +**Stub-only/heavily shimmed packages:** -The software compositor path is the fastest honest route to proving compositor and client behavior. -The hardware path is a different class of systems work. It should run in parallel with later KWin -and Plasma assembly instead of blocking everything else. +| Package | Current state | Path forward | +|---|---|---| +| kirigami | Stub-only for dep resolution | Real build needed for QML-dependent Plasma shell | +| kf6-kio | Heavy shim build | Must become honest build for session claims | -#### Deliverables +**KWin feature switches** (9 still disabled): -##### kernel DMA-BUF fd passing +| Switch | Why disabled | Re-enable condition | +|---|---|---| +| BUILD_WITH_QML=OFF | QML-dependent paths | QML runtime proof in Phase 2 | +| KWIN_BUILD_KCMS=OFF | Requires QML | After BUILD_WITH_QML | +| KWIN_BUILD_EFFECTS=OFF | Desktop effects | After basic compositor works | +| KWIN_BUILD_TABBOX=OFF | Alt-tab switcher | After basic window management works | +| KWIN_BUILD_SCREENLOCKING=OFF | Screen locking | Late session polish | +| KWIN_BUILD_SCREENLOCKER=OFF | Screenlocker binary | Late session polish | +| KWIN_BUILD_X11=OFF | X11 windowing | Intentional: Wayland-only | +| KWIN_BUILD_RUNNING_IN_KDE=OFF | KDE runtime detection | After KWin runs as compositor | +| KWIN_BUILD_ELECTRONICALLY_SIGNING_DOCS=OFF | Document signing | Low priority | -This is the gating feature for the accelerated desktop path. Without it, hardware-accelerated KDE -is not a credible target. +**5 switches already re-enabled** (deps verified built): DECORATIONS, GLOBALSHORTCUTS, +RUNNERS, NOTIFICATIONS, USE_DBUS. -##### real AMD hardware validation +#### Work items -Validate on representative AMD hardware: +| # | Task | Acceptance criteria | +|---|---|---| +| 3.1 | Resolve KWin stubbed blockers (libepoxy, libudev, lcms2, libdisplay-info) | KWin cmake configure succeeds without any `-stub` INTERFACE IMPORTED targets; `ldd` on the KWin binary shows real `.so` links for all four libraries | +| 3.2 | Launch KWin as Wayland compositor | KWin process starts, registers `WAYLAND_DISPLAY`, and owns the display output for at least 60 seconds without crash | +| 3.3 | Validate libinput backend behavior | Keyboard keypress and mouse motion events arrive at a KWin-managed window via libinput + evdevd chain | +| 3.4 | Validate D-Bus session behavior | `dbus-send --session --dest=org.kde.KWin /KWin org.kde.KWin.supportInformation` returns a non-empty string | +| 3.5 | Validate seatd for bounded KWin session model | seatd grants the KWin process graphics+input seat access; a client launched under the same seat receives input events | -- device detection -- MMIO mapping -- firmware loading -- connector detection -- mode enumeration -- bounded modeset proof +#### Exit criteria -##### real Intel hardware validation - -Validate on representative Intel hardware: - -- device detection -- MMIO mapping -- connector detection -- mode enumeration -- bounded modeset proof - -##### Mesa hardware rendering proof - -Validate the actual hardware renderer path rather than llvmpipe fallback. For AMD the target is the -radeonsi path. For Intel the target is the intended real Intel hardware path available in the stack. - -#### Acceptance criteria - -Phase 3 is complete when all of the following are true: - -- kernel DMA-BUF fd passing exists and has focused proof coverage -- `modetest -M amd` shows display modes on real AMD hardware -- the equivalent Intel DRM query path shows display modes on real Intel hardware -- the compositor runs through the hardware path rather than llvmpipe on at least one real AMD class - and one real Intel class -- runtime evidence shows a hardware-backed renderer rather than software fallback +- [ ] KWin cmake configure succeeds without any `-stub` INTERFACE IMPORTED targets +- [ ] KWin process starts and registers `WAYLAND_DISPLAY` +- [ ] KWin owns display output for at least 60 seconds without crash +- [ ] Keyboard and mouse events arrive at KWin-managed windows +- [ ] D-Bus session bus responds to KWin supportInformation query +- [ ] seatd grants graphics+input seat access to KWin #### Exit statement -At the end of Phase 3, the repo should be able to say: Red Bear OS can drive real display hardware -and run the compositor on a hardware-accelerated path. +> Red Bear OS has a working Wayland desktop session substrate centered on KWin. -### Phase 4: Desktop Session Assembly +--- -**Duration:** 6 to 10 weeks +### Phase 4: KDE Plasma Session -**Goal:** turn the compositor proof into a real desktop-session substrate centered on KWin. +**Duration:** 8–12 weeks (starts after Phase 3) +**Goal:** Boot into a KDE Plasma session with essential desktop shell and session services. +**Profile target:** `redbear-kde` -This phase starts after Phase 2. It does not need to wait for the full hardware path. KWin can come -up first on the software renderer and later inherit the accelerated renderer once Phase 3 lands. +#### Work items -#### Core work +| # | Task | Acceptance criteria | +|---|---|---| +| 4.1 | Complete plasma-workspace compilation + integration | plasma-workspace cmake configure succeeds without stub targets; binary stages to sysroot | +| 4.2 | Complete plasma-desktop compilation + integration | plasma-desktop cmake configure succeeds without stub targets; binary stages to sysroot | +| 4.3 | Shell, panel, launcher visible and usable | plasmashell process starts; panel renders at least app launcher + clock; clicking launcher opens and closes an app | +| 4.4 | File-manager and settings paths working | dolphin (or kfmclient) opens a directory view; systemsettings opens a settings module | +| 4.5 | Bounded network + audio integration | `ip addr` shows a configured interface inside Plasma session; a sound card device node is visible under `/dev/snd/` or equivalent scheme | -1. Resolve KWin shimmed and stubbed blockers. -2. Get KWin to compile with real enough dependencies. -3. Launch KWin as the Wayland compositor. -4. Validate libinput backend behavior. -5. Validate D-Bus session behavior. -6. Validate seatd for the bounded KWin session model. +#### Dependency chain to close -#### blocked dependency set that must be closed +``` +plasma-desktop + └── plasma-workspace + β”œβ”€β”€ kf6-knewstuff (currently stub) β†’ Phase 4: must become real or bounded real build + β”œβ”€β”€ kf6-kwallet (currently stub) β†’ Phase 4: must become real or bounded real build + β”œβ”€β”€ kf6-prison (real recipe, needs compilation) β†’ Phase 4: compile + validate + └── other unresolved deps β†’ identify during Phase 3 +``` -- kirigami stub-only state -- heavy kio shim state where it blocks honest session claims -- libepoxy -- libudev -- lcms2 -- libdisplay-info +#### Cross-phase blocker ownership -#### Deliverables +| Blocker | Named in "NOT DONE" | Owned by phase | +|---|---|---| +| kirigami stub-only | Yes | **Phase 4** β€” real build needed for QML-dependent Plasma shell components | +| kf6-kio heavy shim | Yes | **Phase 3** β€” KWin uses kf6-kio for runners; honest KWin claim requires honest kio | +| QtNetwork disabled | Yes | **Post-Phase 4** β€” not a desktop session blocker; network clients will use it after relibc networking matures | +| kf6-knewstuff/kwallet stubs | Yes | **Phase 4** β€” plasma-workspace dependency | -##### honest KWin build +#### Exit criteria -The milestone is not just that a recipe exists. The milestone is that KWin builds without fake -dependency satisfaction for core runtime behavior. - -##### KWin runtime as compositor - -KWin must launch as the compositor and own the display path. - -##### session services for bounded desktop use - -D-Bus session behavior and seatd behavior must be good enough for the bounded KWin target this plan -claims. Linux parity is not required. Correct bounded behavior is required. - -#### Acceptance criteria - -Phase 4 is complete when all of the following are true: - -- KWin builds against real enough dependencies to support honest runtime claims -- KWin launches as the compositor -- KWin takes over display output in the bounded session path -- keyboard and mouse work through the KWin session path -- required D-Bus session behavior for the bounded KWin path works -- seatd behavior is validated for the bounded KWin session model +- [ ] `redbear-kde` boots into a KDE Plasma session (plasmashell process is running) +- [ ] KWin is the active compositor (`WAYLAND_DISPLAY` owned by KWin) +- [ ] Plasma panel renders and is interactive (launcher opens, clock visible) +- [ ] An application can be launched from the session and displays a window +- [ ] A file-manager path opens a directory view +- [ ] A settings module opens from systemsettings +- [ ] Network interface is visible inside Plasma session #### Exit statement -At the end of Phase 4, the repo should be able to say: Red Bear OS has a working Wayland desktop -session substrate centered on KWin. +> If Phase 5 incomplete: Red Bear OS has a **software-rendered** KDE Plasma session on Wayland. +> If Phase 5 complete: Red Bear OS has a **hardware-accelerated** KDE Plasma session on Wayland. -### Phase 5: KDE Plasma Session +--- -**Duration:** 8 to 12 weeks +### Phase 5: Hardware GPU Enablement -**Goal:** boot into a KDE Plasma session with the essential desktop shell and session services -working. +**Duration:** 12–20 weeks (starts after Phase 1, runs in parallel with Phases 3–4) +**Goal:** Replace software-only graphics with real hardware-accelerated display + rendering. +**Why separate:** Hardware acceleration is a different class of systems work. It should not +block KWin/Plasma session assembly, which can proceed on the software renderer. +**Dependency note:** Phase 5 can start after Phase 1 (substrate trust), but its final acceptance +criterion ("compositor runs through hardware path") requires a working compositor from Phase 2 +or Phase 3. In practice, Track C's final validation gate depends on Track A completing first. -This is the final desktop product phase. By this point the remaining work should mostly be session -assembly, application integration, and shell behavior. +#### Work items -#### Core work +| # | Task | Acceptance criteria | +|---|---|---| +| 5.1 | Implement GPU command submission (CS ioctl) | PRIME buffer sharing already implemented; CS ioctl is the gating missing piece | +| 5.2 | Validate redox-drm AMD driver on real hardware | Device detection, MMIO mapping, firmware loading, connector detection, mode enumeration, bounded modeset proof | +| 5.3 | Validate redox-drm Intel driver on real hardware | Same validation surface as AMD | +| 5.4 | Validate Mesa hardware rendering path | Real renderer (radeonsi for AMD, iris/anv for Intel), not llvmpipe | +| 5.5 | Validate GBM buffer allocation through hardware path | GBM allocates through real DRM/GPU, not software fallback | -1. Complete plasma-workspace compilation and integration. -2. Complete plasma-desktop compilation and integration. -3. Get the shell, panel, and launcher visible and usable. -4. Get settings and file-manager paths working. -5. Provide bounded network and audio integration suitable for the session claim. +#### Exit criteria -#### Deliverables - -##### Plasma shell - -The minimum target is not a screenshot. The session must show the shell, panel, and launcher and be -stable through basic interaction. - -##### application and settings path - -At least one real file-manager path and one settings path must work. Otherwise the session is still -too incomplete to count as a desktop. - -##### bounded desktop-service integration - -For this phase the question is narrow: can the Plasma session boot into a usable desktop with bounded -network and audio integration. The long-term subsystem plans remain separate. - -#### Acceptance criteria - -Phase 5 is complete when all of the following are true: - -- `redbear-kde` boots into a KDE Plasma session -- KWin is the active compositor -- the Plasma shell, panel, and launcher appear -- an application can be launched from the session -- a file-manager path works through the current kio integration -- a settings path works -- bounded network and audio integration exist for the claimed session profile +- [ ] GPU command submission exists with focused proof coverage +- [ ] `modetest -M amd` shows display modes on real AMD hardware +- [ ] Equivalent Intel DRM query shows display modes on real Intel hardware +- [ ] Compositor runs through hardware path on at least one AMD + one Intel class +- [ ] Runtime evidence shows hardware-backed renderer, not software fallback #### Exit statement -At the end of Phase 5, the repo should be able to say one of two things: +> Red Bear OS can drive real display hardware and run the compositor on a +> hardware-accelerated path. -- if Phase 3 is still incomplete: Red Bear OS has a software-rendered KDE Plasma session on Wayland -- if Phase 3 is complete: Red Bear OS has a hardware-accelerated KDE Plasma session on Wayland +--- ## Critical Path -### primary path to a software-rendered KDE session +### Primary path to software-rendered KDE session -```text -Phase 1, runtime substrate validation - -> Phase 2, software Wayland compositor proof - -> Phase 4, KWin desktop-session assembly - -> Phase 5, KDE Plasma session +``` +Phase 1 (runtime substrate validation) + β†’ Phase 2 (software Wayland compositor proof) + β†’ Phase 3 (KWin desktop-session assembly) + β†’ Phase 4 (KDE Plasma session) ``` -This is the shortest honest path to a KDE desktop claim. +This is the shortest honest path. **~22–34 weeks with 2 developers.** -### parallel hardware path +### Parallel hardware path -```text -Phase 1, runtime substrate validation - -> Phase 3, hardware GPU enablement +``` +Phase 1 (runtime substrate validation) + β†’ Phase 5 (hardware GPU enablement, parallel with Phases 3–4) -Phase 3 proceeds in parallel with Phase 4 where possible - -Phase 3 + Phase 4 + Phase 5 - -> hardware-accelerated KDE Plasma desktop +Phase 5 + Phase 3 + Phase 4 + β†’ hardware-accelerated KDE Plasma desktop ``` -### why Phase 1 is the real gate +**~34–54 weeks total with 2 developers** for hardware-accelerated KDE. -Phase 1 is the true gateway because it converts lower-layer package progress into runtime trust. -Without it, Phase 2, Phase 4, and Phase 5 failures will be misdiagnosed. +### Why Phase 1 is the real gate -### why Phase 2 comes before KWin +Phase 1 converts lower-layer package progress into runtime trust. Without it, Phase 2+ failures +will be misdiagnosed as compositor bugs when they're actually substrate bugs. -The first complete compositor proof should happen in the smallest environment. smallvil is smaller, -already present, and easier to debug than KWin. It isolates compositor, input, and Qt client issues -before session-shell complexity is added. +### Why smallvil before KWin -### why Phase 3 should not block Phase 4 +Smallest environment to isolate compositor + input + Qt client issues. KWin adds session +services, QML, dependency scaffolding, and desktop-shell behavior on top. -Hardware acceleration is critical, but KWin and Plasma also have their own blockers: dependency -cleanup, session services, and compositor integration. Those can be solved on the software renderer -while the hardware path matures. +### Why hardware doesn't block session assembly -### critical-path summary +KWin and Plasma have their own blockers (dependency cleanup, session services, compositor +integration). Those can be solved on software renderer while hardware path matures. -The execution order this repo should present is: - -1. validate the runtime substrate -2. prove one software compositor path -3. assemble one KWin session path -4. assemble one Plasma session path -5. land hardware acceleration in parallel +--- ## Risk Register -| ID | Risk | Likelihood | Impact | Why it matters | Mitigation | -|---|---|---|---|---|---| -| R1 | relibc runtime gaps are worse than build evidence suggests | Medium | High | Qt6 and Wayland may still fail at runtime even though they build | validate with real consumers in Phase 1 | -| R2 | kernel DMA-BUF fd passing is a new feature with uncertain scope | High | High | hardware acceleration depends on it | isolate design and proof early in Phase 3 | -| R3 | AMD or Intel real-hardware validation reveals fundamental driver issues | High | High | compile success may not survive real modesetting or rendering | validate AMD and Intel separately on representative hardware | -| R4 | KWin porting needs significantly more patches than estimated | Medium | High | KWin sits on the desktop critical path | finish smallvil proof first, then attack KWin with cleaner lower-layer evidence | -| R5 | Kirigami and other QML-heavy pieces do not behave acceptably with QML JIT disabled | Medium | Medium to High | Plasma shell may build but behave badly | keep QML-heavy runtime proof explicit in Phase 4 and Phase 5 | -| R6 | Mesa hardware rendering needs Redox-specific winsys work beyond current estimates | Medium | High | hardware acceleration may stall after modesetting starts working | separate display proof from renderer proof | -| R7 | linux-kpi compatibility gaps only appear during real-hardware execution | High | Medium to High | compile-only success can hide runtime failures | budget for hardware-driven compatibility fixes in Phase 3 | +| ID | Risk | Likelihood | Impact | Mitigation | +|---|---|---|---|---| +| R1 | relibc runtime gaps worse than build evidence suggests | Medium | High | Validate with real consumers in Phase 1 | +| R2 | GPU CS ioctl scope is uncertain | High | High | Isolate design + proof early in Phase 5 | +| R3 | Real-hardware validation reveals fundamental driver issues | High | High | Validate AMD and Intel separately | +| R4 | KWin needs significantly more patches than estimated | Medium | High | Finish smallvil proof first for cleaner lower-layer evidence | +| R5 | QML-heavy pieces behave badly with JIT disabled | Medium | Medium-High | Keep QML runtime proof explicit in Phases 3–4 | +| R6 | Mesa hardware rendering needs Redox-specific winsys work | Medium | High | Separate display proof from renderer proof | +| R7 | linux-kpi gaps only surface during real-hardware execution | High | Medium-High | Budget for hardware-driven compat fixes in Phase 5 | +| R8 | kirigami/stub deps cannot be resolved without full QML stack | Medium | High | Evaluate early in Phase 3; may need alternative approach | + +--- ## Timeline -### planning assumptions +### Planning assumptions -These estimates assume 2 developers, usable access to representative AMD and Intel hardware, and no -major regression from unrelated upstream refresh during the desktop push. They do not assume perfect -first-pass success on real hardware. +- 2 developers with access to representative AMD and Intel hardware +- No major regression from upstream refresh during desktop push +- Estimates do not assume perfect first-pass success on real hardware -### phase estimates with 2 developers +### Phase estimates -| Phase | Estimate | Notes | +| Phase | Weeks | Notes | |---|---|---| -| Phase 1, Runtime Substrate Validation | 4 to 6 weeks | must finish honestly before claiming runtime trust | -| Phase 2, Wayland Compositor Runtime Proof | 4 to 6 weeks | can overlap with late Phase 1 cleanup | -| Phase 3, Hardware GPU Enablement | 12 to 20 weeks | parallel track after Phase 1 | -| Phase 4, Desktop Session Assembly | 6 to 10 weeks | starts after Phase 2 | -| Phase 5, KDE Plasma Session | 8 to 12 weeks | starts after Phase 4 | +| Phase 1: Runtime Substrate Validation | 4–6 | Must finish honestly before claiming runtime trust | +| Phase 2: Wayland Compositor Proof | 4–6 | Can overlap with late Phase 1 cleanup | +| Phase 3: KWin Desktop Session | 6–10 | Starts after Phase 2; **lower bound is optimistic β€” assumes stub/shim cleanup stays bounded** | +| Phase 4: KDE Plasma Session | 8–12 | Starts after Phase 3; **lower bound assumes kirigami/knewstuff stubs resolve without major rework** | +| Phase 5: Hardware GPU Enablement | 12–20 | Starts after Phase 1, parallel with 3–4 | -### total duration with 2 developers +### Total duration (2 developers) -#### to software-rendered KDE Plasma on Wayland +| Target | Weeks | Months | +|---|---|---| +| Software-rendered KDE Plasma on Wayland | 22–34 | 6–8 | +| Hardware-accelerated KDE Plasma on Wayland | 34–54 | 8–13 | -- **22 to 34 weeks** -- roughly **6 to 8 months** +### One-developer estimate -This path is Phase 1 + Phase 2 + Phase 4 + Phase 5. +| Target | Months | +|---|---| +| Software-rendered KDE | 9–16 | +| Hardware-accelerated KDE | 12–27 | -#### to hardware-accelerated KDE Plasma on Wayland +### Rough overlap model -- **34 to 54 weeks** -- roughly **8 to 13 months** - -This path is Phase 1 + Phase 2 + Phase 3 in parallel + Phase 4 + Phase 5. - -### rough overlap model - -```text -Weeks 1 to 6 - Phase 1, runtime substrate validation - -Weeks 4 to 12 - Phase 2, software compositor proof - -Weeks 7 to 26 - Phase 3, hardware GPU enablement - -Weeks 13 to 22 - Phase 4, KWin session assembly - -Weeks 23 to 34 - Phase 5, KDE Plasma session +``` +Weeks 1– 6: Phase 1 (runtime substrate validation) +Weeks 4–12: Phase 2 (software compositor proof) +Weeks 7–26: Phase 5 (hardware GPU enablement, parallel) +Weeks 13–22: Phase 3 (KWin session assembly) +Weeks 23–34: Phase 4 (KDE Plasma session) ``` -This is an intended overlap shape, not a guaranteed calendar. - -### one-developer estimate - -With 1 developer, the overall timeline is roughly 1.5x to 2x the two-developer estimates. - -Practical meaning: - -- software-rendered KDE path: about 9 to 16 months -- hardware-accelerated KDE path: about 12 to 27 months - -The wider range reflects the loss of useful parallelism between hardware work and session work. - -### timeline conclusion - -The software-rendered KDE target is no longer a greenfield multi-year fantasy. The hardware- -accelerated KDE target is still a serious systems milestone because Phase 3 carries the widest -uncertainty band. +--- ## Relationship to Other Plans -This is the canonical document for the desktop path from console boot to KDE Plasma on Wayland. It -does not replace every subsystem-specific plan. It sets the ordering, scope, and acceptance language -for the desktop path while deeper subsystem documents retain their detailed ownership. +This is the canonical document for the desktop path. It does not replace subsystem-specific plans. -### primary supporting plans +### Primary supporting plans -- `local/docs/RELIBC-COMPLETENESS-AND-ENHANCEMENT-PLAN.md` for relibc completeness detail, - ownership of patch-carried behavior, and deeper evidence tracking -- `local/docs/AMD-FIRST-INTEGRATION.md` for deeper GPU-driver and firmware detail, with the caveat - that this desktop plan uses equal-priority AMD and Intel targeting -- `local/docs/QT6-PORT-STATUS.md` for Qt6, KF6, KWin blocker, shim, and stub status -- `local/docs/DESKTOP-STACK-CURRENT-STATUS.md` for the short current-state desktop truth summary -- `local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` for controller, IRQ, MSI, MSI-X, - and IOMMU quality work that supports later hardware desktop validation -- `local/docs/INPUT-SCHEME-ENHANCEMENT.md` for deeper input-path design if the current chain needs - structural cleanup beyond Phase 1 validation -- `local/docs/P2-AMD-GPU-DISPLAY.md` for the code-complete AMD display status and concrete AMD - validation targets such as `modetest -M amd` +| Plan | What it covers | +|---|---| +| `local/docs/AMD-FIRST-INTEGRATION.md` | AMD-specific GPU/driver detail (equal-priority AMD+Intel policy) | +| `local/docs/QT6-PORT-STATUS.md` | Qt6, KF6, KWin blocker/shim/stub status detail | +| `local/docs/DESKTOP-STACK-CURRENT-STATUS.md` | Short current-state desktop truth summary | +| `local/docs/RELIBC-COMPLETENESS-AND-ENHANCEMENT-PLAN.md` | relibc completeness detail + patch ownership | +| `local/docs/INPUT-SCHEME-ENHANCEMENT.md` | Input-path design if structural cleanup needed | +| `local/docs/P2-AMD-GPU-DISPLAY.md` | AMD display status + validation targets | +| `local/docs/DMA-BUF-IMPROVEMENT-PLAN.md` | DMA-BUF scheme detail | +| `local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` | Controller/IRQ/IOMMU quality work | +| `local/docs/PROFILE-MATRIX.md` | Profile roles + support-language reference | -### how to use this plan with the supporting plans +### How to use this plan -Read this document first for execution order, current claim language, completion criteria, and the -critical path. Read the subsystem plans for the exact relibc, driver, package, or input details -behind those higher-level phases. +1. Read this document first for execution order, claim language, completion criteria, critical path +2. Read subsystem plans for exact relibc, driver, package, or input details behind those phases +3. Use `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` for the repo-wide workstream ordering + +--- + +## Pre-Phase Work (Already Complete) + +The following work was completed before this plan was written. It is listed here for +continuity, not as future work. + +| Work | Status | When | +|---|---|---| +| AMD bare-metal boot (ACPI, SMP, x2APIC) | βœ… Complete | Prior to this plan | +| Driver infrastructure (redox-driver-sys, linux-kpi, firmware-loader) | βœ… Builds complete | Prior to this plan | +| AMD GPU display (redox-drm, amdgpu C port) | βœ… Builds complete | Prior to this plan | +| relibc POSIX unblockers (signalfd, timerfd, eventfd, etc.) | βœ… Builds complete | Prior to this plan | +| Qt6 base stack (qtbase, qtdeclarative, qtsvg, qtwayland) | βœ… Builds complete | Prior to this plan | +| D-Bus 1.16.2 | βœ… Builds + bounded runtime | Prior to this plan | +| All 32 KF6 frameworks | βœ… Builds complete | Prior to this plan | +| Input stack (libevdev, libinput, evdevd, udev-shim) | βœ… Builds complete | Prior to this plan | +| Mesa EGL/GBM/GLES2 + libdrm amdgpu | βœ… Builds complete | Prior to this plan | +| Desktop profiles (redbear-wayland, redbear-full, redbear-kde) | βœ… Builds complete | Prior to this plan | +| PRIME/DMA-BUF scheme ioctls | βœ… Implemented | Prior to this plan | +| KWin recipe with 5 re-enabled features | βœ… Partial build | Prior to this plan | +| kdecoration, plasma-wayland-protocols, kf6-kwayland | βœ… Builds complete | Prior to this plan | diff --git a/local/docs/DESKTOP-STACK-CURRENT-STATUS.md b/local/docs/DESKTOP-STACK-CURRENT-STATUS.md index 51aad5f5..1043be25 100644 --- a/local/docs/DESKTOP-STACK-CURRENT-STATUS.md +++ b/local/docs/DESKTOP-STACK-CURRENT-STATUS.md @@ -1,146 +1,122 @@ # Red Bear OS Desktop Stack β€” Current Status +**Last updated:** 2026-04-16 +**Canonical plan:** `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v2.0) + ## Purpose This document is the **current build/runtime truth summary** for the Red Bear desktop stack. -It is intentionally narrower than the historical Wayland and KDE roadmap docs. Its job is to answer: - -- what the current desktop stack actually builds, -- what the tracked desktop profiles currently expose, +Its job is to answer: +- what the desktop stack actually builds, +- what the tracked profiles currently expose, - what is only build-visible, - what is runtime-proven, - and what still blocks a trustworthy Wayland/KDE session claim. -Use this document as the current-state summary. Use `docs/03-WAYLAND-ON-REDOX.md` and -`docs/05-KDE-PLASMA-ON-REDOX.md` mainly as design history, rationale, and deeper porting notes. +For the execution plan (phases, timelines, acceptance criteria), see the canonical plan above. +For historical design rationale, see `docs/03-WAYLAND-ON-REDOX.md` and `docs/05-KDE-PLASMA-ON-REDOX.md`. -## Current State Summary +## Where We Are in the Plan -The Red Bear desktop stack is no longer blocked on basic Qt/Wayland package availability. +The canonical desktop plan uses a three-track model: -The repo currently proves: +- **Track A (Phase 1–2):** Runtime Substrate β†’ Software Compositor β€” **Phase 1 is the current target** +- **Track B (Phase 3–4):** KWin Session β†’ KDE Plasma β€” **blocked on Track A** +- **Track C (Phase 5):** Hardware GPU β€” **can start after Phase 1** -- `libwayland` builds successfully against the current relibc/Red Bear compatibility surface -- Qt6 core modules build (`qtbase`, `qtdeclarative`, `qtsvg`, `qtwayland`) -- the current relibc overlay and its fresh-source reapply workflow are strong enough to support the - rebuilt Qt/Wayland stack -- D-Bus builds and is wired into desktop-facing profiles -- `seatd` builds and is wired into the KDE-facing runtime profile -- the `redbear-wayland`, `redbear-full`, and `redbear-kde` profiles exist as real tracked product - surfaces - -The repo does **not** yet prove a generally trustworthy desktop runtime. - -The main gap is no longer β€œcan we build the packages?” The main gap is β€œwhich parts of the desktop -stack are runtime-trusted rather than just build-visible?” +**Current position:** Build-side gates are crossed. Phase 1 (Runtime Substrate Validation) is the +next work target. The repo has not yet started systematic runtime validation. ## Status Matrix -| Area | Current state | What that means | +| Area | Evidence class | Detail | |---|---|---| | `libwayland` | **builds** | relibc/Wayland-facing compatibility is materially better than before | -| Qt6 core stack | **builds** | `qtbase`, `qtdeclarative`, `qtsvg`, `qtwayland` are in-tree build surfaces | -| KF6 frameworks | **mixed but strong build progress** | many frameworks build; some higher-level pieces still rely on bounded or reduced recipes | -| KWin / Plasma session | **experimental / incomplete runtime** | recipe/config wiring exists, but runtime trust still trails build success | -| Mesa / hardware graphics path | **partial** | software path exists; current QEMU validation still shows llvmpipe, and hardware-validated Wayland graphics path still lags | -| Input stack | **build-visible and partly wired** | `evdevd`, `libevdev`, `libinput`, `seatd` are present, but runtime trust is still narrower than full desktop support | -| D-Bus session/system plumbing | **builds / wired into profiles** | present in desktop-facing profiles, but not equal to full desktop integration completeness | +| Qt6 core stack | **builds** | `qtbase` (7 libs + 12 plugins), `qtdeclarative`, `qtsvg`, `qtwayland` | +| KF6 frameworks | **builds** | All 32/32; some higher-level pieces use bounded/reduced recipes (kf6-kio heavy shim, kirigami stub-only) | +| KWin | **experimental** | Recipe exists; 5 features re-enabled; 4 stub deps block honest build; 9 feature switches still disabled | +| plasma-workspace | **experimental** | Recipe exists; stub deps (kf6-knewstuff, kf6-kwallet) unresolved | +| plasma-desktop | **experimental** | Recipe exists; depends on plasma-workspace | +| Mesa EGL+GBM+GLES2 | **builds** | Software path via LLVMpipe proven in QEMU; hardware path not proven | +| libdrm amdgpu | **builds** | Package-level success only | +| Input stack | **builds, enumerates** | evdevd, libevdev, libinput, seatd present; evdevd registers scheme at boot | +| D-Bus | **builds, usable (bounded)** | System bus wired in `redbear-full` | +| DRM/KMS | **builds** | redox-drm scheme daemon; no hardware runtime validation | +| GPU acceleration | **blocked** | PRIME/DMA-BUF ioctls implemented; GPU CS ioctl missing | +| smallvil compositor | **experimental** | Reaches early init in QEMU; no complete session | +| `redbear-wayland` profile | **builds, boots** | Bounded Wayland runtime profile | +| `redbear-full` profile | **builds, boots** | Broader desktop plumbing profile | +| `redbear-kde` profile | **builds** | KDE session-surface profile | ## Profile View ### `redbear-wayland` -Role: - -- narrow runtime validation profile for Wayland bring-up - -Current truth: - -- it is the current first-class profile for a bounded Wayland runtime path -- it should be used for small-scope compositor/runtime validation, not broad desktop claims +- **Role:** Phase 2 Wayland compositor validation target +- **Current truth:** Builds and boots in QEMU; smallvil reaches early init but no complete session +- **Use for:** Compositor/runtime regression testing, not broad desktop claims ### `redbear-full` -Role: - -- broader desktop/network/session plumbing profile - -Current truth: - -- it carries D-Bus and broader desktop integration pieces -- it is stronger than `redbear-wayland` for general integration, but still not the same as a stable - KDE session claim +- **Role:** Broader desktop/network/session plumbing +- **Current truth:** Carries D-Bus and broader integration pieces; VirtIO networking works in QEMU +- **Use for:** Desktop integration testing beyond the narrow Wayland slice ### `redbear-kde` -Role: - -- KDE/Plasma session-surface profile - -Current truth: - -- it carries the KWin/session wiring and the KDE-facing package set -- it should still be described as experimental until runtime evidence catches up with build success +- **Role:** Phase 3–4 KDE/Plasma session bring-up +- **Current truth:** Carries KWin/session wiring and KDE-facing package set; experimental +- **Use for:** KDE session surface testing once Phase 2 completes ## Current Blockers -### 1. Runtime trust still trails build success +### 1. Runtime trust trails build success (Phase 1 gate) -The project now has real build-visible desktop progress, but build success still exceeds runtime -confidence. +The repo has real build-visible desktop progress, but build success exceeds runtime confidence. +Phase 1 exists specifically to close this gap. -That gap is the main thing older docs sometimes blur. +### 2. No complete compositor session (Phase 2 gate) -### 2. Graphics/runtime validation is still thinner than package progress +smallvil reaches early initialization but does not complete a usable Wayland compositor session. +This blocks all desktop session work. -The software-rendered stack is much further along than the hardware-validated stack. +### 3. KWin blocked by stub dependencies (Phase 3 gate) -Current QEMU truth: +Four stub cmake targets must become real builds: -- the tracked `redbear-wayland` test harness still uses `-vga std` -- the live compositor path currently reports `GL Renderer: "llvmpipe (LLVM 21.1.2, 256 bits)"` -- therefore the current QEMU Wayland proof is still a software-rendered runtime slice, not a - hardware-accelerated desktop proof -- QEMU should be treated as a bounded regression/test harness for Wayland/Qt bring-up, not as the - primary proof target for the final hardware-accelerated desktop claim +| Stub | Real library exists? | Path to resolve | Difficulty | +|---|---|---|---| +| `libepoxy-stub` | Yes β€” `recipes/wip/libs/gnome/libepoxy/` (meson, has redox.patch) | Port real libepoxy; currently needs full X11/GLX stack | Medium | +| `libudev-stub` | Partial β€” `recipes/wip/services/eudev/` (broken: POSIX headers missing) | Fix eudev compilation; `udev-shim` is a binary not a C library | Medium-Hard | +| `lcms2-stub` | Yes β€” `recipes/wip/libs/other/liblcms/` (compiled, untested) | Test and integrate real lcms2; depends on libtiff | Low | +| `libdisplay-info-stub` | **No** β€” not in recipe tree at all | New port from freedesktop.org; full EDID/CTA/DisplayID parser | Hard | -The real hardware-accelerated acceptance target remains the bare-metal/runtime-driver path: +Additionally, two packages need honest builds: kirigami (stub-only), kf6-kio (heavy shim). -- `redox-drm` detects and drives the target GPU family -- Mesa GBM/EGL/GLES2 uses that runtime graphics path -- the compositor and Qt Wayland clients run stably on top of it -- runtime evidence shows the desktop path is using the real accelerated stack rather than a - software fallback +### 4. Hardware acceleration missing GPU CS ioctl (Phase 5 gate) -The desktop stack therefore should not over-claim hardware-ready Wayland/KDE support yet. - -### 3. KDE build progress is ahead of session maturity - -KDE package and framework progress is real, but the session surface should still be described as an -experimental bring-up target rather than a broadly working desktop. - -### 4. Input and seat management are present but not yet a final confidence story - -`libinput`, `seatd`, and related runtime pieces matter, but they should still be treated as part of -the runtime-proof gap rather than as already-settled desktop infrastructure. +PRIME/DMA-BUF buffer sharing is implemented at the scheme level, but GPU command submission +does not exist. This blocks hardware-accelerated rendering. ## Canonical Document Roles -Use the desktop-related docs this way: - -- `local/docs/DESKTOP-STACK-CURRENT-STATUS.md` β€” current build/runtime truth summary -- `local/docs/QT6-PORT-STATUS.md` β€” Qt/KF6 package-level build/status truth -- `docs/03-WAYLAND-ON-REDOX.md` β€” historical Wayland implementation path + deeper rationale -- `docs/05-KDE-PLASMA-ON-REDOX.md` β€” historical KDE implementation path + deeper rationale -- `local/docs/PROFILE-MATRIX.md` β€” profile role and support-language reference +| Document | Role | +|---|---| +| `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` | Canonical desktop path plan (v2.0, Phase 1–5) | +| This document | Current build/runtime truth summary | +| `local/docs/QT6-PORT-STATUS.md` | Qt/KF6/KWin package-level build status | +| `local/docs/AMD-FIRST-INTEGRATION.md` | AMD-specific hardware/driver detail | +| `docs/03-WAYLAND-ON-REDOX.md` | Historical Wayland design rationale | +| `docs/05-KDE-PLASMA-ON-REDOX.md` | Historical KDE design rationale | +| `local/docs/PROFILE-MATRIX.md` | Profile roles and support-language reference | ## Bottom Line -The current Red Bear desktop stack is in a transition phase: +The Red Bear desktop stack has crossed major build-side gates: +- All Qt6 core modules, all 32 KF6 frameworks, Mesa EGL/GBM/GLES2, and D-Bus build +- Three tracked desktop profiles exist and at least boot in QEMU +- relibc compatibility is materially stronger than before -- no longer blocked on basic Qt/Wayland package availability, -- materially stronger on relibc/Wayland-facing compatibility than before, -- but still short of a broad runtime-trusted desktop claim. - -That is the current truth this repo should present. +The remaining work is **runtime validation and session assembly**, not more package porting. +Phase 1 (Runtime Substrate Validation) is the immediate next target. diff --git a/local/docs/DMA-BUF-IMPROVEMENT-PLAN.md b/local/docs/DMA-BUF-IMPROVEMENT-PLAN.md new file mode 100644 index 00000000..e808ff3d --- /dev/null +++ b/local/docs/DMA-BUF-IMPROVEMENT-PLAN.md @@ -0,0 +1,432 @@ +# Red Bear OS: DMA-BUF Improvement Plan + +**Date**: 2026-04-16 +**Status**: v1 COMPLETE (Steps 1-6a implemented, Oracle-verified through 8 rounds). Step 6b blocked on GPU command submission. Stale token cleanup verified across all GEM destruction paths. +**Scope**: Cross-process GPU buffer sharing for hardware-accelerated KDE Plasma on Wayland + +## Bottom Line + +Redox kernel already has the three primitives needed for DMA-BUF-style cross-process buffer +sharing: + +1. **`Provider::FmapBorrowed`** + **`Grant::borrow_fmap()`** β€” kernel mechanism for borrowing + pages from a scheme into another process's address space, mapping the same physical frames + (zero-copy). Source: `kernel/source/src/context/memory.rs:1157`, `memory.rs:1401`. + +2. **`sendfd`** syscall β€” passes file descriptors between processes via scheme IPC. Both + processes hold the same `Arc`. Source: `kernel/source/src/syscall/fs.rs:415`. + +3. **`PhysBorrow`** in `scheme:memory` β€” maps physical addresses directly into process space + (already used for GPU registers/BARs). Source: `kernel/source/src/scheme/memory.rs`. + +No new kernel syscalls or scheme types are needed for v1. The work is entirely in userspace: +redox-drm scheme daemon, libdrm, and Mesa. + +## Architecture Principle + +**DMA-BUF is a sharing and lifetime contract, not a global allocator.** + +Linux `dma_buf` is an exporter/importer contract. The exporter owns allocation and controls +lifetime. The importer gets shared access. Red Bear OS follows the same model: + +- **Allocation stays with `redox-drm`** (the exporter). `DmaBuffer::allocate()` in `gem.rs` + already allocates physically-contiguous system RAM. +- **Sharing uses scheme-backed fds + `sendfd`**. No synthetic fd numbers. No global registry. +- **Mapping uses `FmapBorrowed`**. The kernel maps the same physical pages into the importer's + address space β€” zero-copy. + +## Data Flow + +``` +Process A (GPU client, e.g. Mesa/radeonsi) + 1. open("/scheme/drm/card0") + 2. DRM_IOCTL_GEM_CREATE β†’ allocate GPU buffer ← EXISTS + 3. DRM_IOCTL_PRIME_HANDLE_TO_FD β†’ get opaque export token ← IMPLEMENTED + 4. open("/scheme/drm/card0/dmabuf/{token}") β†’ get scheme fd ← IMPLEMENTED + 5. sendfd(socket, fd) β†’ pass fd to compositor ← KERNEL EXISTS + +Process B (compositor, e.g. KWin) + 6. recvfd(socket) β†’ receive the fd ← KERNEL EXISTS + 7. DRM_IOCTL_PRIME_FD_TO_HANDLE β†’ import as local GEM ← IMPLEMENTED + 7. mmap(fd, size) β†’ kernel uses FmapBorrowed ← KERNEL EXISTS + 8. Both processes see same physical pages ← ZERO-COPY +``` + +Steps 1-2 are already working. Steps 3-6 require redox-drm changes. Steps 4-5 and 7-8 use +existing kernel mechanisms. + +## Current State + +### What Exists + +| Component | Status | Detail | +|-----------|--------|--------| +| GEM_CREATE ioctl | βœ… Working | `DmaBuffer::allocate()` in `gem.rs`, physically contiguous system RAM | +| GEM_CLOSE ioctl | βœ… Working | Ownership tracking, reference counting, safe cleanup | +| GEM_MMAP ioctl | βœ… Working | Returns virtual address for mmap_prep | +| KMS/modesetting ioctls | βœ… Working | 16 KMS ioctls, CRTC/connector/encoder/plane | +| Kernel FmapBorrowed | βœ… Exists | `Provider::FmapBorrowed` at `memory.rs:1157`, `Grant::borrow_fmap()` at `memory.rs:1401` | +| Kernel sendfd | βœ… Exists | `SYS_SENDFD` at `syscall/fs.rs:415`, passes `Arc` | +| Kernel PhysBorrow | βœ… Exists | `scheme:memory` physical address mapping | +| libdrm `__redox__` | βœ… Full | Opens `/scheme/drm`, dispatches KMS + PRIME ioctls via `redox_fpath` | + +### What Is Missing + +| Component | Status | Impact | +|-----------|--------|--------| +| PRIME_HANDLE_TO_FD | βœ… Implemented | Opaque export tokens via prime_exports map | +| PRIME_FD_TO_HANDLE | βœ… Implemented | Token lookup via prime_exports, adds to owned_gems | +| libdrm PRIME/GEM dispatch | βœ… Implemented | __redox__ wrappers in drmPrimeHandleToFD/drmPrimeFDToHandle | +| Mesa Redox winsys | 🚧 Scaffolding | Stubs compile but do not render β€” blocked on GPU CS | +| GPU command submission | ❌ Not implemented | No CS ioctl, no ring buffer programming | +| GPU fence/signaling | ❌ Not implemented | No GPU completion notification | + +### What Was Cleaned Up (Previous Session) + +The old fake PRIME implementation used synthetic fd numbers starting at 10,000 that were not real +kernel file descriptors. Other processes could not resolve them. Oracle caught this across 4 +verification rounds. The cleanup: + +- Removed `exported_dmafds` tracking from Handle struct +- Removed `imported_gems` from Handle +- Removed DMA-BUF methods from `GpuDriver` trait and AMD/Intel driver impls +- Removed `DmabufManager` from `GemManager` +- Removed `mod dmabuf` from `main.rs` +- Removed PRIME wire structs (`DrmPrimeHandleToFdWire`, `DrmPrimeFdToHandleWire`) +- PRIME handlers β†’ EOPNOTSUPP (honest, not fake) +- Removed all `#[allow(dead_code)]` from fake bookkeeping + +## Phased Implementation + +### v1: System RAM, Linear, Single GPU (Target: working PRIME) + +**Goal**: A compositor (KWin) can import a buffer rendered by a GPU client (Mesa) and display it. +All buffers in system RAM, linear layout, single GPU. + +**Duration estimate**: 6-10 weeks (2 developers) + +#### Step 1: Delete dead dmabuf.rs + +Remove `local/recipes/gpu/redox-drm/source/src/dmabuf.rs`. It is dead code β€” `mod dmabuf` was +removed from `main.rs` but the file still exists. + +**Effort**: trivial + +#### Step 2: Implement PRIME export in redox-drm + +When `PRIME_HANDLE_TO_FD` is called: + +1. Look up the GEM handle in the calling fd's `owned_gems` +2. Validate ownership (same as GEM_MMAP check) +3. Generate an opaque export token and store `prime_exports[token] = gem_handle` +4. Return the token to the caller (NOT a scheme fd or GEM handle) + +The client then opens `/scheme/drm/card0/dmabuf/{token}` to get a real scheme fd. The open +handler validates the token against `prime_exports`, creates a `NodeKind::DmaBuf` scheme handle, +and bumps the GEM export refcount. When that scheme fd is closed, the refcount is dropped. + +Key design: export tokens are opaque identifiers, not synthetic fd numbers or raw GEM handles. +The `prime_exports` map resolves tokens to GEM handles. Tokens are cleaned up when the last +export ref for a GEM handle is dropped. + +**Changes to `scheme.rs`**: +- Add `NodeKind::DmaBuf { gem_handle, export_token }` variant +- Add `prime_exports: BTreeMap` and `next_export_token: u32` +- `PRIME_HANDLE_TO_FD` handler: validate ownership β†’ generate token β†’ store in prime_exports β†’ return token +- `PRIME_FD_TO_HANDLE` handler: receive token β†’ look up in prime_exports β†’ add GEM to caller's `owned_gems` +- `open()` handler: accept `"card0/dmabuf/{token}"` path β†’ validate token β†’ create DmaBuf node β†’ bump export ref +- `mmap_prep()` handler: for DmaBuf nodes, return GEM physical address + +**Changes to `driver.rs`**: +- No changes needed. GEM operations stay on the trait as-is. PRIME is a scheme-level concern, + not a driver-level concern. + +**Effort**: 1-2 weeks + +#### Step 3: Add reference counting for shared GEM objects + +When a GEM buffer is exported via PRIME, multiple scheme fds may reference it. The `close()` path +must only call `driver.gem_close()` when ALL references (original GEM + all exported fds) are gone. + +**Changes**: +- Add `gem_refcounts: BTreeMap` to `DrmScheme` +- Increment on export, decrement on close of DmaBuf fd +- `gem_close()` checks refcount before calling driver + +**Effort**: 3-5 days + +#### Step 4: Validate with a two-process reproducer + +Build a minimal test that: +1. Process A opens `/scheme/drm/card0`, creates a GEM buffer, writes a pattern +2. Process A exports via PRIME_HANDLE_TO_FD +3. Process A sends the fd to Process B via `sendfd` (or equivalent scheme IPC) +4. Process B receives the fd, imports via PRIME_FD_TO_HANDLE +5. Process B mmaps the imported handle and reads the pattern +6. Verify both processes see the same physical pages (same data, zero-copy) + +This validates the full chain: redox-drm β†’ scheme fd β†’ sendfd β†’ import β†’ mmap β†’ FmapBorrowed. + +**Effort**: 1 week + +#### Step 5: libdrm Redox PRIME/GEM dispatch + +libdrm already has `__redox__` conditionals. Add dispatch for: +- `drmPrimeHandleToFD()` β†’ send `PRIME_HANDLE_TO_FD` ioctl to `/scheme/drm` +- `drmPrimeFDToHandle()` β†’ send `PRIME_FD_TO_HANDLE` ioctl +- `drmPrimeClose()` β†’ close the exported/imported fd +- `drmGemHandleToPrimeFD()` / `drmPrimeFDToGemHandle()` β€” aliases for the above + +The libdrm WIP recipe is at `recipes/wip/x11/libdrm/`. The `__redox__` handling already opens +`/scheme/drm` and has ioctl dispatch infrastructure. The gap is PRIME/GEM-specific ioctl codes. + +**Effort**: 1-2 weeks + +#### Step 6: Mesa Redox winsys (compile-time scaffolding) + +Add `src/gallium/winsys/redox/` to Mesa that: +- Opens the DRM scheme +- Allocates GEM buffers via `GEM_CREATE` +- Exports them via `PRIME_HANDLE_TO_FD` +- Imports shared buffers via `PRIME_FD_TO_HANDLE` +- Maps them via `mmap` (which triggers `FmapBorrowed`) + +Pattern: similar to `winsys/amdgpu/drm/` but using Redox scheme IPC. This is scaffolding β€” it +compiles but cannot render without GPU command submission (Step 8). + +Split into: +- **6a**: Compile-time winsys structure, buffer allocation, PRIME export/import +- **6b**: Runtime buffer-sharing enablement (depends on step 4 validation) + +**Effort**: 3-4 weeks + +### v2: VRAM/GTT Placement, Tiling, Multi-GPU + +**Goal**: Buffers can live in VRAM with GTT aperture access. Tiled/modifier support for +scanout-optimized layouts. Multi-GPU buffer sharing. + +**Duration estimate**: 8-12 weeks (after v1) + +- AMD GTT/VRAM placement via `amdgpu_gtt_mgr` / `amdgpu_vram_mgr` equivalents +- Intel GGTT/PPGTT population for imported buffers +- DRM format modifiers: `DRM_FORMAT_MOD_LINEAR` + vendor-specific tiling +- Multi-GPU: each GPU has its own `redox-drm` instance, PRIME between them +- This tier requires the AMD/Intel driver GTT programming that is currently partial + +### v3: Fencing, Explicit Sync, Vulkan + +**Goal**: GPU fence objects for render/scanout synchronization. Explicit sync protocol for +Wayland. Vulkan driver support. + +**Duration estimate**: 12-16 weeks (after v2) + +- `dma_fence` equivalent: kernel waitable event per page-flip or command submission +- `sync_file` equivalent: fd-backed fence that can be passed between processes +- Wayland `zwp_linux_explicit_synchronization_v1` protocol in compositor +- Vulkan `VK_KHR_external_memory` / `VK_KHR_external_semaphore` backed by DMA-BUF fds +- AMD: fence through ring buffer writeback + IRQ +- Intel: fence through seqno writeback + IRQ + +## Dependency Graph + +``` +Step 1 (delete dmabuf.rs) + β†’ no dependency, do immediately + +Step 2 (PRIME export/import in scheme) + β†’ depends on: nothing + β†’ enables: steps 3, 4, 5 + +Step 3 (refcount for shared GEM) + β†’ depends on: step 2 + β†’ enables: step 4 + +Step 4 (two-process reproducer) + β†’ depends on: steps 2, 3 + β†’ validates: the full chain works + +Step 5 (libdrm dispatch) + β†’ depends on: step 2 (ioctl protocol defined) + β†’ can start in parallel with steps 3-4 + +Step 6 (Mesa winsys) + β†’ depends on: step 5 (libdrm API available) + β†’ 6a can start once step 2 protocol is defined + β†’ 6b should wait for step 4 validation +``` + +Steps 5 and 6a can proceed in parallel with steps 3-4 once step 2 is done. + +## What This Does NOT Cover + +This plan covers **cross-process buffer sharing** (the DMA-BUF/PRIME contract). It does not cover: + +| Out of scope | Where it lives | +|-------------|----------------| +| GPU command submission (CS ioctl) | `HARDWARE-3D-ASSESSMENT.md` Tier 2 | +| GPU fence/signaling | `HARDWARE-3D-ASSESSMENT.md` Tier 2 | +| Mesa hardware Gallium driver (radeonsi/iris) | `HARDWARE-3D-ASSESSMENT.md` Tier 1 | +| AMD ring buffer programming | `local/recipes/gpu/amdgpu/` | +| Intel render ring programming | `local/recipes/gpu/redox-drm/source/src/drivers/intel/` | +| Mesa EGL platform extension for DRM | `HARDWARE-3D-ASSESSMENT.md` Tier 3 | + +PRIME/DMA-BUF is a **prerequisite** for hardware-accelerated rendering, but it is not sufficient +by itself. The render pipeline (command submission + fencing + Mesa driver) is tracked separately +in `HARDWARE-3D-ASSESSMENT.md`. + +## Why Not a Kernel DMA-BUF Scheme + +Linux has a global `dma-buf` kernel subsystem with its own fd type. Red Bear OS does NOT need this +because: + +1. **`redox-drm` IS the exporter.** In Linux, any kernel subsystem can export a dma-buf. In Redox, + only the DRM scheme exports GPU buffers. There is no need for a generic kernel dma-buf layer. + +2. **Scheme fds ARE the sharing mechanism.** In Linux, dma-buf has its own fd type with special + mmap semantics. In Redox, scheme file descriptors already support `fmap_prep` β†’ `FmapBorrowed`. + The kernel maps the same physical pages. No new fd type needed. + +3. **`sendfd` IS the fd passing mechanism.** In Linux, fd passing uses SCM_RIGHTS over Unix + sockets. In Redox, `sendfd` passes `Arc` via scheme IPC. Same result. + +If a future use case requires sharing non-DRM buffers (e.g., camera frames, video decode output), +a separate `scheme:dmabuf` could be created. But for GPU buffer sharing, the DRM scheme is +sufficient. + +## Wire Protocol Design + +### PRIME_HANDLE_TO_FD + +Request (from libdrm client): +```c +struct DrmPrimeHandleToFdWire { + uint32_t handle; // GEM handle to export + uint32_t flags; // DRM_CLOEXEC | DRM_RDWR (hints, not critical for v1) +}; +``` + +Response: +```c +struct DrmPrimeHandleToFdResponseWire { + int32_t fd; // opaque export token (NOT a process fd or GEM handle) + uint32_t _pad; +}; +``` + +The scheme internally: +1. Validates handle ownership +2. Generates an opaque export token (monotonically increasing counter) +3. Stores `prime_exports[token] = gem_handle` +4. Returns the token as `fd` + +The client then opens `/scheme/drm/card0/dmabuf/{token}` to get a real scheme fd. +The open handler validates the token, creates a DmaBuf scheme handle, and bumps +`gem_export_refs`. When that scheme fd is closed, the ref is dropped. + +### PRIME_FD_TO_HANDLE + +Request (from libdrm client): +```c +struct DrmPrimeFdToHandleWire { + int32_t fd; // opaque export token (extracted via redox_fpath on dmabuf fd) + uint32_t _pad; +}; +``` + +Response: +```c +struct DrmPrimeFdToHandleResponseWire { + uint32_t handle; // GEM handle for the imported buffer + uint32_t _pad; +}; +``` + +The scheme internally: +1. Looks up the export token in `prime_exports` β†’ gets the GEM handle +2. Validates the token exists +3. Adds the GEM handle to the caller's `owned_gems` +4. Returns the GEM handle + +### open() path extension + +```rust +// Existing paths: +"card0" β†’ NodeKind::Card +"card0Connector/{id}" β†’ NodeKind::Connector(id) + +// Export token path (validated against prime_exports): +"card0/dmabuf/{token}" β†’ NodeKind::DmaBuf { gem_handle, export_token: token } +``` + +### redox_fpath() for DmaBuf + +```rust +NodeKind::DmaBuf { export_token, .. } => format!("drm:card0/dmabuf/{export_token}") +``` + +### Token cleanup + +When the last export ref for a GEM handle is dropped: +```rust +fn drop_export_ref(&mut self, gem_handle: GemHandle) { + // ... decrement refcount ... + if remove_entry { + self.gem_export_refs.remove(&gem_handle); + self.prime_exports.retain(|_, &mut h| h != gem_handle); + } +} +``` + +When a GEM is destroyed via any path (GEM_CLOSE, DESTROY_DUMB, handle close, fb reap), +`prime_exports` entries are pruned: +- `maybe_close_gem()`: central helper prunes tokens on successful `driver.gem_close()` +- `GEM_CLOSE` / `DESTROY_DUMB`: explicit `prime_exports.retain()` after direct `driver.gem_close()` +- `PRIME_FD_TO_HANDLE`: `gem_size()` liveness check removes stale token on failure +- `open("card0/dmabuf/{token}")`: `gem_size()` liveness check removes stale token on failure + +## Files to Modify + +| File | Change | Status | +|------|--------|--------| +| `local/recipes/gpu/redox-drm/source/src/dmabuf.rs` | **DELETED** | βœ… | +| `local/recipes/gpu/redox-drm/source/src/scheme.rs` | DmaBuf nodes, opaque export tokens, PRIME handlers, refcount cleanup, stale token cleanup | βœ… | +| `local/recipes/gpu/redox-drm/source/src/gem.rs` | No changes (GEM operations unchanged) | β€” | +| `local/recipes/gpu/redox-drm/source/src/driver.rs` | No changes (PRIME is scheme-level) | β€” | +| `local/recipes/gpu/redox-drm/source/src/main.rs` | No changes (already clean) | β€” | +| `recipes/wip/x11/libdrm/source/xf86drm.c` | `redox_fpath()` + export token dmabuf path + `sys/redox.h` | βœ… | +| `recipes/libs/mesa/source/src/gallium/winsys/redox/drm/` | 4 scaffolding files (compile-time only) | βœ… | +| `local/recipes/tests/redox-drm-prime-test/` | Test reproducer recipe + Rust binary (incl. stale token test) | βœ… | +| `local/docs/HARDWARE-3D-ASSESSMENT.md` | PRIME status updated | βœ… | +| `local/docs/DMA-BUF-IMPROVEMENT-PLAN.md` | Implementation status updated | βœ… | + +## Implementation Status (2026-04-16) + +| Step | Status | Deliverable | +|------|--------|-------------| +| 1. Delete dead dmabuf.rs | βœ… Done | File removed | +| 2. PRIME export/import in scheme | βœ… Done | DmaBuf nodes, export refcounting, mmap_prep, open/close/fpath | +| 3. Reference counting for shared GEM | βœ… Done | gem_export_refs, bump/drop, gem_can_close, maybe_close_gem | +| 4. Two-process reproducer | βœ… Recipe created | `local/recipes/tests/redox-drm-prime-test/` (runtime validation pending) | +| 5. libdrm Redox dispatch | βœ… Done | __redox__ wrappers in drmPrimeHandleToFD and drmPrimeFDToHandle | +| 6a. Mesa winsys scaffolding | βœ… Done | `src/gallium/winsys/redox/drm/` (4 files, compiles but does not render) | +| 6b. Mesa runtime buffer sharing | ⏳ Blocked | Requires GPU command submission (not yet implemented) | + +**Stale token cleanup**: All GEM destruction paths now prune `prime_exports`. Central cleanup +in `maybe_close_gem()`, explicit cleanup in `GEM_CLOSE`/`DESTROY_DUMB`, liveness checks in +`PRIME_FD_TO_HANDLE` and `open("dmabuf/{token}")` that remove stale tokens on failure. +Verified by Oracle across 8 rounds. + +**Protocol note**: PRIME uses opaque export tokens. PRIME_HANDLE_TO_FD returns a monotonically- +increasing token stored in `prime_exports`. The client opens `/scheme/drm/card0/dmabuf/{token}` +to get a real scheme fd. `redox_fpath()` on that fd reveals the token. PRIME_FD_TO_HANDLE +accepts the export token and resolves it via `prime_exports`. Tokens are cleaned up when the +last export ref is dropped. + +## Relationship to Other Plans + +- `local/docs/HARDWARE-3D-ASSESSMENT.md` β€” broader hardware 3D status (command submission, fencing, + Mesa driver enablement). This document is the DMA-BUF-specific deep dive. +- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` β€” canonical desktop path plan. DMA-BUF is a + prerequisite for the hardware-accelerated rendering phase. +- `local/docs/AMD-FIRST-INTEGRATION.md` β€” AMD-specific GPU details including GTT/VRAM programming. +- `docs/04-LINUX-DRIVER-COMPAT.md` β€” linux-kpi architecture reference for driver porting. diff --git a/local/docs/HARDWARE-3D-ASSESSMENT.md b/local/docs/HARDWARE-3D-ASSESSMENT.md new file mode 100644 index 00000000..7cae2bdd --- /dev/null +++ b/local/docs/HARDWARE-3D-ASSESSMENT.md @@ -0,0 +1,163 @@ +# Red Bear OS: Hardware-Accelerated 3D Assessment + +**Date**: 2026-04-16 +**Scope**: AMD + Intel GPU hardware OpenGL/Vulkan for KDE Plasma desktop + +## Bottom Line + +PRIME/DMA-BUF cross-process buffer sharing is **now implemented** at the scheme level. GEM +allocation, PRIME export/import, and zero-copy mmap via FmapBorrowed all work through the +redox-drm scheme daemon and libdrm. The remaining gaps for hardware 3D are GPU command +submission (CS ioctl), GPU fence/signaling, and Mesa hardware Gallium driver enablement. +These are tracked separately in `local/docs/DMA-BUF-IMPROVEMENT-PLAN.md`. + +## Capability Stack + +``` +Application (KDE Plasma / Qt6 / Wayland compositor) + ↓ +EGL / GBM / Wayland protocol + ↓ +Mesa (Gallium state tracker β†’ hardware driver) ← ONLY swrast (CPU), Redox winsys scaffolding exists + ↓ +libdrm (userspace DRM wrapper) ← __redox__ PRIME dispatch βœ…, opens /scheme/drm + ↓ +DRM scheme ioctls (GEM, PRIME, render) ← GEM βœ…, PRIME βœ… (DmaBuf nodes), render ❌ + ↓ +redox-drm (userspace DRM/KMS daemon) ← display βœ…, buffer sharing βœ…, render ❌ + ↓ +Kernel (FmapBorrowed, sendfd, GPU interrupts) ← buffer sharing βœ…, GPU fences ❌ + ↓ +GPU hardware (AMD RDNA / Intel Gen) +``` + +## Layer-by-Layer Status + +### 1. GPU Hardware Drivers (redox-drm + amdgpu + linux-kpi) + +| Component | Status | Lines | What's Implemented | +|-----------|--------|-------|-------------------| +| DRM/KMS modesetting | βœ… Code complete | ~500 | 16 KMS ioctls, CRTC/connector/encoder/plane | +| AMD Display Core | βœ… Compiles | ~1400 | DC init, CRTC programming, firmware loading, HPD | +| Intel Display Driver | βœ… Compiles | ~800 | Display pipe, GGTT, forcewake | +| GEM buffer management | βœ… Full | ~350 | create/close/mmap with DmaBuffer | +| GEM scheme ioctls | βœ… Wired | ~100 | GEM_CREATE, GEM_CLOSE, GEM_MMAP | +| PRIME scheme ioctls | βœ… Implemented | ~120 | PRIME_HANDLE_TO_FD + PRIME_FD_TO_HANDLE via DmaBuf nodes + export refcounting | +| libdrm PRIME dispatch | βœ… Implemented | ~30 | __redox__ wrappers: open dmabuf path + fpath-based GEM handle extraction | +| Mesa Redox winsys | 🚧 Scaffolding | ~4 files | Directory structure + stubs in src/gallium/winsys/redox/drm/ | +| Render command submission | ❌ Missing | 0 | No CS ioctl, no ring buffer programming | +| GPU context management | ❌ Missing | 0 | No context create/destroy | +| Fence/sync objects | ❌ Missing | 0 | No GPU fence signaling | +| AMD ring buffer | ⚠️ Partial | ~100 | Page flip only, no general command submission | + +### 2. Mesa Build Configuration + +| Setting | Current Value | Needed for HW 3D | +|---------|--------------|-------------------| +| `gallium-drivers` | `swrast` | `swrast,radeonsi` (AMD) or `swrast,iris` (Intel) | +| `vulkan-drivers` | `swrast` | `swrast,amd` (RADV) or `swrast,intel` (ANV) | +| `platforms` | `redox` | `redox` (same) | +| EGL | enabled | enabled (same) | +| GBM | enabled | enabled (same) | +| `gallium-winsys` | none (swrast doesn't need one) | New Redox winsys for radeonsi/iris | +| `egl/platform_redox.c` | 540 lines, Orbital-backed | Needs DRM backend for HW buffers | + +### 3. Kernel Infrastructure + +| Feature | Status | Impact | +|---------|--------|--------| +| PCI enumeration | βœ… | GPU devices discovered | +| Memory scheme (phys mmap) | βœ… | GPU register access works | +| IRQ scheme (MSI-X) | βœ… | GPU interrupts can be delivered | +| DMA-BUF fd passing | βœ… Scheme-level | FmapBorrowed + sendfd + DmaBuf nodes enable zero-copy cross-process sharing | +| GPU fence/wait | ❌ | No GPU completion signaling | +| IOMMU/GPU page tables for imports | ❌ | Imported buffers can't be mapped into GPU GTT | + +## The Render Path Gap + +For hardware OpenGL, the data path is: + +``` +Mesa Gallium (radeonsi) + β†’ libdrm open("drm:card0") + β†’ DRM_IOCTL_GEM_CREATE (allocate GPU buffer) ← EXISTS + β†’ DRM_IOCTL_PRIME_HANDLE_TO_FD (export for sharing) ← βœ… IMPLEMENTED (DmaBuf node + scheme fd) + β†’ DRM_IOCTL_AMDGPU_CS (submit commands to GPU) ← DOES NOT EXIST + β†’ fence wait (GPU completion) ← DOES NOT EXIST + β†’ present via KMS (PAGE_FLIP) ← EXISTS +``` + +Steps 1-2 now have full scheme ioctl support with cross-process buffer sharing via DmaBuf scheme +nodes, sendfd, and FmapBorrowed. Steps 3-4 (command submission, fencing) remain the critical +gaps. The buffer sharing foundation is in place β€” compositors and clients can share GPU buffers +zero-copy. The missing piece is GPU command submission for actual rendering. + +## What Was Implemented + +| Change | Before | After | +|--------|--------|-------| +| `DRM_IOCTL_GEM_CREATE` | Not in scheme | Full ioctl handler: allocate GEM buffer, track ownership | +| `DRM_IOCTL_GEM_CLOSE` | Not in scheme | Full ioctl handler with ownership check | +| `DRM_IOCTL_GEM_MMAP` | Not in scheme | Full ioctl handler: return virtual address | +| `DRM_IOCTL_PRIME_HANDLE_TO_FD` | EOPNOTSUPP | Full implementation: opaque export tokens, prime_exports map, dmabuf fd creation | +| `DRM_IOCTL_PRIME_FD_TO_HANDLE` | EOPNOTSUPP | Full implementation: accepts export token (from redox_fpath), resolves via prime_exports | +| `libdrm __redox__ PRIME` | Not present | drmPrimeHandleToFD opens dmabuf path via export token; drmPrimeFDToHandle extracts token via redox_fpath | +| `NodeKind::DmaBuf` | Not present | DmaBuf node with mmap_prep returning GEM virtual address (enables FmapBorrowed) | +| `gem_export_refs` tracking | Not present | BTreeMap refcount for shared GEM objects, prevents premature gem_close | +| Mesa winsys scaffolding | Not present | src/gallium/winsys/redox/drm/ stub directory structure | + +## What Remains (Ordered by Dependency) + +### Tier 1: Can be done without kernel changes + +1. **Mesa Gallium hardware driver enablement** β€” Change recipe from `-Dgallium-drivers=swrast` to + include `radeonsi` or `iris`. This will fail to build without a winsys, but the attempt reveals + the exact Mesa-side gaps. + +2. **Redox Mesa winsys** β€” Scaffolding exists at `src/gallium/winsys/redox/drm/` (compile-time + stubs). Needs real implementation of buffer allocation, PRIME export/import, and mmap. + PRIME ioctls are now implemented in redox-drm and libdrm has `__redox__` dispatch. + +3. **libdrm Redox backend** β€” libdrm already has `__redox__` conditional handling, opens + `/scheme/drm`, and dispatches PRIME ioctls via `redox_fpath()` and dmabuf path opening. + The remaining gap is GPU-family-specific command submission ioctls. + +### Tier 2: Requires kernel work + +4. **GPU command submission** β€” The amdgpu and Intel drivers need ring buffer programming for + 3D command submission, not just page flip. This is GPU-family-specific: + - AMD: GFX ring, compute ring, SDMA ring + - Intel: render ring, blitter ring + +6. **GPU fence/signaling** β€” After submitting commands, the kernel needs to signal completion + back to userspace. This requires IRQ handling that maps GPU interrupts to fence objects. + +### Tier 3: Requires significant new code + +7. **GTT/PPGTT population for imported buffers** β€” When Mesa imports a DMA-BUF into the GPU, + the buffer's physical pages must be mapped into the GPU's address space. Currently only + internally-allocated GEM objects get GTT mappings. + +8. **Mesa EGL platform extension** β€” `platform_redox.c` currently uses Orbital for buffer + management. It needs an alternative path that uses DRM GEM for hardware-accelerated + surfaces. + +## Estimated Effort (2 developers) + +| Tier | Duration | Deliverable | +|------|----------|-------------| +| Tier 1 (userspace) | 8-16 weeks | Mesa builds with radeonsi, winsys talks to DRM scheme | +| Tier 2 (kernel/driver) | 12-20 weeks | GPU command submission, fences, VRAM placement | +| Tier 3 (integration) | 6-12 weeks | Hardware-accelerated OpenGL applications | +| **Total** | **26-48 weeks** | **Hardware 3D on AMD** | + +Intel (iris) is expected to be faster than AMD (radeonsi is ~6M lines vs iris ~400k) but both are +equal-priority Red Bear OS targets. The order of enablement is driven by driver complexity, not +platform priority. + +## Relationship to Other Plans + +- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` β€” Phase 5 covers hardware GPU enablement +- `local/docs/AMD-FIRST-INTEGRATION.md` β€” AMD-specific GPU driver details +- `local/docs/P2-AMD-GPU-DISPLAY.md` β€” Display driver code-complete status +- `docs/04-LINUX-DRIVER-COMPAT.md` β€” linux-kpi architecture reference diff --git a/local/docs/P2-AMD-GPU-DISPLAY.md b/local/docs/P2-AMD-GPU-DISPLAY.md index b2fde849..f70f13bf 100644 --- a/local/docs/P2-AMD-GPU-DISPLAY.md +++ b/local/docs/P2-AMD-GPU-DISPLAY.md @@ -123,6 +123,11 @@ pcid: local/config/pcid.d/amd_gpu.toml - Rust side passes real PciDeviceInfo (vendor, device, revision, IRQ, BAR0/BAR2) to C via FFI - C layer validates the struct is populated before `amdgpu_redox_init()` uses it +### linux-kpi quirk consumption (current) +- `redox-drm` now also passes the real PCI BDF into the amdgpu C glue so linux-kpi quirk lookups resolve against the actual GPU, not a guessed location +- `amdgpu_redox_main.c` now calls `pci_get_quirk_flags()` / `pci_has_quirk()` in the live Redox init path +- `PCI_QUIRK_NEED_FIRMWARE` now gates DMCUB firmware loading as a hard requirement when present, while logs also spell out quirk-driven IRQ expectations (`NO_MSI`, `NO_MSIX`, `FORCE_LEGACY`) + ### Intel GPU support (T4-T5) - Intel driver switched to shared `InterruptHandle` (MSI-X + legacy) - Added `local/config/pcid.d/intel_gpu.toml` for auto-detection (vendor 0x8086, class 0x03) diff --git a/local/docs/PHASE-0-3-REASSESSMENT.md b/local/docs/PHASE-0-3-REASSESSMENT.md index 972d9917..331e808f 100644 --- a/local/docs/PHASE-0-3-REASSESSMENT.md +++ b/local/docs/PHASE-0-3-REASSESSMENT.md @@ -1,5 +1,9 @@ # Red Bear OS Phase 0–3 Reassessment +> **DEPRECATED (2026-04-16):** This one-time reconciliation document has been absorbed into the +> updated `CONSOLE-TO-KDE-DESKTOP-PLAN.md` and `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md`. It is +> retained for historical reference only. Do not use it as a current planning source. + ## Purpose This document reconciles the current public execution plan in `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` @@ -256,7 +260,11 @@ For Phase 0–3 work, prefer closing validation gaps and documentation drift bef The early-phase codebase is in a much better structural state now; the main quality risk is no longer missing packages, but overstating readiness before runtime evidence exists. -## Phase 4 Handoff Note +## Phase 4 Handoff Note (historical P0–P6 numbering) + +> This section uses the old P0–P6 phase numbering. In the v2.0 desktop plan +> (`local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`), the "Phase 4" below corresponds to Phase 2 +> (Wayland Compositor Proof). Phase 4 should begin from the existing `wayland.toml` profile, not by jumping straight to KWin. The current repo already contains the `smallvil`, `cosmic-comp`, `qtwayland`, and Mesa software diff --git a/local/docs/PROFILE-MATRIX.md b/local/docs/PROFILE-MATRIX.md index 370656d8..85d73d18 100644 --- a/local/docs/PROFILE-MATRIX.md +++ b/local/docs/PROFILE-MATRIX.md @@ -20,15 +20,19 @@ USB plan uses: ## Tracked Profiles +> **Phase numbering note:** phase labels below use the v2.0 desktop plan phases from +> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`. Scripts and older docs may reference the +> historical P0–P6 hardware-enablement sequence β€” those are not the same numbering. + | Profile | Intent | Key Fragments | Current support language | |---|---|---|---| | `redbear-minimal` | Console + storage + wired-network baseline | `minimal.toml`, `redbear-legacy-base.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / primary validation baseline / DHCP boot profile enabled / input-runtime substrate wired | -| `redbear-bluetooth-experimental` | First bounded Bluetooth validation profile | `redbear-bluetooth-experimental.toml`, `redbear-minimal.toml` | builds / boots in QEMU / validated bounded Battery Level slice via `redbear-bluetooth-battery-check` and `test-bluetooth-qemu.sh --check` / explicit-startup USB BLE-first only / repeated helper + restart cleanup covered / not generic GATT / not USB-class-autospawn | +| `redbear-bluetooth-experimental` | First bounded Bluetooth validation profile | `redbear-bluetooth-experimental.toml`, `redbear-bluetooth-services.toml`, `redbear-minimal.toml` | builds / boots in QEMU / validated bounded Battery Level slice via `redbear-bluetooth-battery-check` and `test-bluetooth-qemu.sh --check` / explicit-startup USB BLE-first only / repeated helper + restart cleanup covered / not generic GATT / not USB-class-autospawn | | `redbear-wifi-experimental` | First bounded Intel Wi-Fi validation profile | `redbear-wifi-experimental.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / experimental bounded Intel Wi-Fi slice / driver + control/profile/reporting stack present / packaged in-target validation and capture commands available / real hardware connectivity still unproven | | `redbear-desktop` | Main Red Bear desktop integration profile without KDE-specific session wiring | `desktop.toml`, `redbear-legacy-base.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / input-runtime substrate wired / runtime reporting installed | -| `redbear-wayland` | Phase 4 Wayland runtime validation profile | `wayland.toml` | builds / boots in QEMU / experimental software-path graphics-runtime slice / not QEMU hardware-acceleration proof | -| `redbear-full` | Phase 5 desktop/network plumbing profile | `desktop.toml`, `redbear-legacy-base.toml`, `redbear-legacy-desktop.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / boots in QEMU / D-Bus system bus wired / experimental runtime path | -| `redbear-kde` | Phase 6 KDE session-surface profile | `desktop.toml`, `redbear-legacy-base.toml`, `redbear-legacy-desktop.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / experimental desktop path / D-Bus+seatd+KWin session surface wired | +| `redbear-wayland` | v2.0 Phase 2 Wayland compositor validation profile | `wayland.toml` | builds / boots in QEMU / experimental software-path graphics-runtime slice / not QEMU hardware-acceleration proof | +| `redbear-full` | Broader desktop/network/session plumbing (spans v2.0 Phases 2–3) | `desktop.toml`, `redbear-legacy-base.toml`, `redbear-legacy-desktop.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / boots in QEMU / D-Bus system bus wired / experimental runtime path | +| `redbear-kde` | v2.0 Phases 3–4 KDE Plasma session-surface profile | `desktop.toml`, `redbear-legacy-base.toml`, `redbear-legacy-desktop.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / experimental desktop path / D-Bus+seatd+KWin session surface wired | | `redbear-live` | Live and recovery image layered on desktop | `redbear-desktop.toml` | builds | ## Profile Notes @@ -37,7 +41,7 @@ USB plan uses: - First place to validate repository discipline and profile reproducibility. - Should stay smaller and less assumption-heavy than the graphics profiles. -- Enables the shared `wired-dhcp` netctl profile by default for the Phase 2 VM/wired baseline. +- Enables the shared `wired-dhcp` netctl profile by default for the VM/wired baseline. - Ships the shared firmware/input runtime service prerequisites so the early substrate can be tested on the smallest profile as well. ### `redbear-bluetooth-experimental` @@ -73,15 +77,15 @@ USB plan uses: ### `redbear-wayland` - Wraps the repo's existing `wayland.toml` into a first-class Red Bear build target. -- Serves as the Phase 4 runtime-validation surface for `orbital-wayland` and `smallvil`. +- Serves as the v2.0 Phase 2 compositor validation surface for `orbital-wayland` and `smallvil`. - Current verified path: QEMU/UEFI boot to login prompt plus guest-side `redbear-phase4-wayland-check`, with `smallvil` reaching xkbcommon initialization and EGL platform selection on Redox. - Current QEMU renderer evidence is still software-based (`llvmpipe` on the current `-vga std` harness), so this profile must not be described as a hardware-accelerated desktop proof yet. -- Treat this profile as the bounded Phase 4 Wayland/Qt regression harness; the final hardware-desktop claim still belongs to the bare-metal accelerated graphics path. +- Treat this profile as the bounded Wayland/Qt regression harness; the final hardware-desktop claim still belongs to the bare-metal accelerated graphics path. ### `redbear-full` - Used for broader desktop/session plumbing after the narrower `redbear-wayland` validation slice. -- Current Phase 5 role: carry D-Bus system-bus plumbing together with the native Red Bear network stack. +- Current role: carry D-Bus system-bus plumbing together with the native Red Bear network stack (spans v2.0 Phases 2–3). - Current verified path: QEMU/UEFI boot to login prompt plus guest-side `redbear-phase5-network-check`, with functional VirtIO networking and `DBUS_SYSTEM_BUS=present`. - Should not be described as fully supported until runtime validation is evidence-backed. @@ -89,7 +93,7 @@ USB plan uses: - Dedicated profile for Plasma/KWin session bring-up. - Keep KDE-specific service wiring here instead of leaking it into the generic desktop profile. -- Current Phase 6 role: carry the KWin session launch surface and its D-Bus/seatd dependencies in one image. +- Current role: carry the KWin session launch surface and its D-Bus/seatd dependencies in one image (v2.0 Phases 3–4). ### `redbear-live` diff --git a/local/docs/PROJECT-DOCUMENTATION-ASSESSMENT.md b/local/docs/PROJECT-DOCUMENTATION-ASSESSMENT.md index c802182e..32733d5b 100644 --- a/local/docs/PROJECT-DOCUMENTATION-ASSESSMENT.md +++ b/local/docs/PROJECT-DOCUMENTATION-ASSESSMENT.md @@ -1,5 +1,9 @@ # Project Documentation Assessment +> **DEPRECATED (2026-04-16):** This one-time assessment was completed and its findings applied to the +> documentation set. It is retained for historical reference only. For current documentation status, +> see `docs/README.md` and the document-status matrix there. + ## Purpose This document assesses the current Red Bear OS documentation set after the repository-model and WIP diff --git a/local/docs/QT6-PORT-STATUS.md b/local/docs/QT6-PORT-STATUS.md index 5fcaca9d..1711e42f 100644 --- a/local/docs/QT6-PORT-STATUS.md +++ b/local/docs/QT6-PORT-STATUS.md @@ -1,11 +1,21 @@ # Qt6 Port β€” Red Bear OS -**Last updated:** 2026-04-14 +**Last updated:** 2026-04-16 **Qt version:** 6.11.0 **Target:** x86_64-unknown-redox (cross-compiled from Linux x86_64 host) -**Phase 1 status:** βœ… COMPLETE β€” Qt6 core stack + OpenGL/EGL + D-Bus + Wayland -**Phase 2 status:** βœ… COMPLETE β€” All 32 KF6 frameworks built -**Phase 3 status:** πŸ”„ IN PROGRESS β€” KWin + KDE Plasma build + +> **Phase numbering note:** The phases below (Phase 1–6) are this document's internal Qt porting +> phases, not the canonical desktop plan phases. For the project-wide desktop execution plan +> (Phase 1: Runtime Substrate β†’ Phase 5: Hardware GPU), see +> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v2.0). + +**Qt Phase 1 status:** βœ… COMPLETE β€” Qt6 core stack + OpenGL/EGL + D-Bus + Wayland +**Qt Phase 2 status:** βœ… COMPLETE β€” All 32 KF6 frameworks built +**Qt Phase 3 status:** πŸ”„ IN PROGRESS β€” KWin + KDE Plasma build + +> **Execution note (2026-04-16):** The current Redox-applicable Qt 6.11 recipe expansion wave has +> real-cook verification for `qtimageformats`, `qt5compat`, `qttools`, `qttranslations`, and +> `qtshadertools`. ## Current Status Summary @@ -15,16 +25,36 @@ | **qtdeclarative** | βœ… | 11 libs, QML JIT disabled | | **qtsvg** | βœ… | 2 libs | | **qtwayland** | βœ… | Wayland client + compositor | +| **qtimageformats** | βœ… | Real recipe + cook verified | +| **qt5compat** | βœ… | Real recipe + cook verified | +| **qttools** | βœ… | Redox-scoped tooling slice cook verified | +| **qttranslations** | βœ… | Translation catalogs cook verified | +| **qtshadertools** | βœ… | Real recipe + cook verified | | **Mesa EGL+GBM** | βœ… | libEGL, libgbm, libGLESv2, swrast DRI | | **libdrm** | βœ… | libdrm + libdrm_amdgpu | | **libinput** | βœ… | 1.30.2 with comprehensive redox.patch | | **D-Bus** | βœ… | 1.16.2, libdbus-1.so | | **KF6 Frameworks** | βœ… 32/32 | All frameworks built | | **KWin** | πŸ”„ | Recipe ready, now using real `libxcvt`, but still blocked by remaining shimmed/stubbed deps and incomplete runtime path | -| **Hardware acceleration** | ❌ | Requires kernel DMA-BUF (future work) | +| **Hardware acceleration** | ❌ | PRIME/DMA-BUF scheme ioctls implemented; blocked on GPU command submission (CS ioctl) | --- +## Wave 1 β€” Redox-applicable Qt 6.11 module expansion + +The first post-core Qt 6.11 coverage wave is now real-cook verified: + +| Module | Status | Verification | +|--------|--------|--------------| +| `qtimageformats` | βœ… | `CI=1 ./target/release/repo cook qtimageformats` | +| `qt5compat` | βœ… | `CI=1 ./target/release/repo cook qt5compat` | +| `qttools` | βœ… | `CI=1 ./target/release/repo cook qttools` | +| `qttranslations` | βœ… | `CI=1 ./target/release/repo cook qttranslations` | +| `qtshadertools` | βœ… | `CI=1 ./target/release/repo cook qtshadertools` | + +This means the repo now has real Qt 6.11 recipes for the first high-yield Redox-applicable +expansion set, all verified by actual `repo cook` runs. + ## Scope Definition **Phase 1 scope**: qtbase, qtdeclarative, qtsvg β€” the foundational Qt6 stack. @@ -32,8 +62,8 @@ Qt6 consists of many modules β€” each is a separate source package. Phase 2 (qtw follows in the next step. **User-agreed scope constraints:** -- OpenGL: software/shm only, no EGL β€” get Qt compiling first -- Disabled features: process, sharedmemory, systemsemaphore, testlib, sql, printsupport +- OpenGL: now enabled (GLES 2.0 software path via Mesa/LLVMpipe); hardware acceleration still future work +- Still disabled features: process testlib, sql, printsupport remain out of scope for current iteration - Iterative approach: enable modules incrementally, re-enable disabled features later ## Build Status @@ -99,32 +129,32 @@ Plus: QML debug plugins, QtQuick/QML modules staged. ### Disabled Modules β€” Full Blocker Analysis -| Module | Blocker | Root Cause | Re-enable Path | -|--------|---------|------------|----------------| -| QtNetwork | Runtime validation still pending | the relibc header/ioctl surface is now present in-tree, but downstream QtNetwork behavior still needs end-to-end validation on Redox | Validate QtNetwork against the updated relibc networking surface | -| QtOpenGL | No EGL, no GPU driver runtime validation | amdgpu/intel DRM drivers compile but haven't been validated on hardware; no Mesa EGL build | Validate GPU drivers on HW β†’ build Mesa with EGL β†’ enable QtOpenGL | -| QtOpenGLWidgets | Gated by `QT_FEATURE_opengl` | Same as QtOpenGL | Same as QtOpenGL | -| QtDBus | D-Bus IPC system not ported to Redox | No D-Bus daemon or libdbus on Redox | Port libdbus β†’ enable QtDBus | -| QtSql | User-agreed scope exclusion | Not needed for initial GUI | Add sqlite/odbc recipe β†’ enable QtSql | -| QtPrintSupport | User-agreed scope exclusion | No printing subsystem on Redox | Port cups/filters β†’ enable QtPrintSupport | +| Module | Status | Blocker | Re-enable Path | +|--------|--------|---------|----------------| +| QtNetwork | ❌ Disabled | relibc networking runtime semantics still incomplete (DNS resolver, IPv6 multicast) | Validate QtNetwork against the updated relibc networking surface | +| QtSql | ❌ Disabled | User-agreed scope exclusion | Add sqlite/odbc recipe β†’ enable QtSql | +| QtPrintSupport | ❌ Disabled | User-agreed scope exclusion, no printing subsystem on Redox | Port cups/filters β†’ enable QtPrintSupport | + +> **Previously disabled, now enabled:** QtOpenGL (βœ… Phase 4b), QtOpenGLWidgets (βœ… Phase 4b), and +> QtDBus (βœ… Phase 2a) were disabled in earlier builds but have since been enabled and built +> successfully. See Phase 4b and Phase 2a sections below for details. ### Disabled Features β€” Full Blocker Analysis -| Feature | CMake Flag | Blocker | Re-enable Path | -|---------|-----------|---------|----------------| -| OpenGL | `-DFEATURE_opengl=OFF` | No EGL, no GPU runtime validation | Validate GPU drivers β†’ Mesa EGL β†’ enable | -| EGL | `-DFEATURE_egl=OFF` | No libEGL from Mesa | Mesa EGL build β†’ enable | -| XCB/Xlib | `-DFEATURE_xcb=OFF -DFEATURE_xlib=OFF` | No X11 on Redox | Not applicable β€” Redox uses Wayland | -| Vulkan | `-DFEATURE_vulkan=OFF` | No Vulkan runtime | Port Mesa Vulkan ICD β†’ enable | -| OpenSSL | `-DFEATURE_openssl=OFF` | OpenSSL3 port in WIP but not validated | Validate openssl3 recipe β†’ enable | -| D-Bus | `-DFEATURE_dbus=OFF` | No D-Bus on Redox | Port libdbus β†’ enable | -| Process | `-DFEATURE_process=ON` | relibc now provides a bounded `waitid()` path and qtbase configures, builds, and stages with process support enabled | Validate QProcess on Redox | -| Shared Memory | `-DFEATURE_sharedmemory=ON` | relibc now provides `shm_open()` plus bounded SysV shared-memory surfaces and qtbase configures, builds, and stages with shared memory enabled | Validate QSharedMemory on Redox | -| System Semaphore | `-DFEATURE_systemsemaphore=ON` | relibc now provides `sem_open()`/`sem_close()`/`sem_unlink()` and qtbase configures, builds, and stages with system semaphore support enabled | Validate QSystemSemaphore on Redox | -| qmake | `-DFEATURE_qmake=OFF` | Build tool, not needed with CMake | Enable if downstream needs qmake | -| SQL | `-DFEATURE_sql=OFF` | User-agreed scope exclusion | Add sqlite/odbc β†’ enable | -| Print Support | `-DFEATURE_printsupport=OFF` | User-agreed scope exclusion | Port cups β†’ enable | -| QML JIT | `-DFEATURE_qml_jit=OFF` | Does not compile for Redox | Fix in upstream or disable permanently | +| Feature | CMake Flag | Status | Notes | +|---------|-----------|--------|-------| +| XCB/Xlib | `-DFEATURE_xcb=OFF -DFEATURE_xlib=OFF` | ❌ Disabled | Not applicable β€” Redox uses Wayland, not X11 | +| Vulkan | `-DFEATURE_vulkan=OFF` | ❌ Disabled | No Vulkan runtime on Redox | +| OpenSSL | `-DFEATURE_openssl=OFF` | ❌ Disabled | OpenSSL3 port in WIP but not validated | +| qmake | `-DFEATURE_qmake=OFF` | ❌ Disabled | Build tool, not needed with CMake | +| SQL | `-DFEATURE_sql=OFF` | ❌ Disabled | User-agreed scope exclusion | +| Print Support | `-DFEATURE_printsupport=OFF` | ❌ Disabled | User-agreed scope exclusion | +| QML JIT | `-DFEATURE_qml_jit=OFF` | ❌ Disabled | Does not compile for Redox | + +> **Previously disabled, now enabled:** OpenGL (`-DFEATURE_opengl=ON`), EGL (`-DFEATURE_egl=ON`), +> and D-Bus (`-DFEATURE_dbus=ON`) were disabled in earlier builds but have since been enabled and +> built successfully. Process, shared memory, and system semaphore were also enabled after relibc +> improvements. See respective Phase sections for details. --- @@ -197,8 +227,8 @@ Plus: QML debug plugins, QtQuick/QML modules staged. | Gap | Impact | Module Blocked | |-----|--------|---------------| -| D-Bus IPC | QtDBus, KDE components | QtDBus | -| GPU display validation | Hardware-accelerated rendering | QtOpenGL | +| broader networking runtime validation | QtNetwork end-to-end behavior | QtNetwork | +| GPU hardware display validation | Hardware-accelerated rendering | QtOpenGL hardware path | | broader shared-memory validation beyond the existing `shm_open()` path | Shared memory | QSharedMemory | | broader semaphore/system-IPC validation beyond the new `sem_open()` path | POSIX semaphores | QSystemSemaphore | | process/runtime validation beyond the new bounded `waitid()` path | QProcess internals | QProcess | @@ -305,8 +335,9 @@ Current truth for Phase 4: as a bounded regression/test path, not as the final acceleration proof target - the in-repo Phase 4 runtime check currently still fails in `qt6-bootstrap-check` during early Qt startup, so even the bounded software-path runtime proof remains incomplete -- true hardware-accelerated desktop readiness still requires kernel DMA-BUF fd passing plus real +- true hardware-accelerated desktop readiness still requires GPU command submission (CS ioctl) plus real AMD/Intel hardware validation through the DRM β†’ GBM/EGL β†’ compositor β†’ Qt client path + (PRIME/DMA-BUF cross-process buffer sharing is implemented at scheme level) ### Phase 4b β€” Qt6 OpenGL Enablement (βœ… build-side complete, 🚧 runtime incomplete) @@ -322,11 +353,29 @@ KDE Plasma packages built: - plasma-wayland-protocols βœ… BUILT (protocol XMLs for kf6-kwayland) - kdecoration βœ… BUILT (KDecoration3 window decoration library) -KWin recipe updated with dependencies (all KF6 + Mesa + libdrm + libinput + qtwayland): -- All KF6 deps built (kconfigwidgets, kxmlgui, kglobalaccel, kidletime, kio, etc.) -- Mesa EGL+GBM βœ… -- libinput βœ… -- libdrm βœ… +plasma-workspace stub dependencies partially resolved: +- kf6-knewstuff βœ… STUB ONLY (KF6NewStuff cmake INTERFACE IMPORTED targets for plasma-workspace dep resolution) +- kf6-kwallet βœ… STUB ONLY (KF6Wallet cmake INTERFACE IMPORTED targets for plasma-workspace dep resolution) +- kf6-prison βœ… REAL RECIPE (real cmake build against libqrencode; dmtx/ZXing disabled; not yet compiled) + +qt6-wayland-smoke improved to create a visible QWindow: +- Creates a 320x240 colored window (red background, "Red Bear OS - Qt6 Wayland Smoke Test" text) +- Uses QBackingStore for software rendering +- Runs for 3 seconds (previously 1 second, no window) +- This turns the smoke test from a bootstrap check into a real Wayland surface proof target + +KWin recipe updated β€” features re-enabled where deps are satisfied: +- KWIN_BUILD_DECORATIONS=ON (kdecoration builds βœ…) +- KWIN_BUILD_GLOBALSHORTCUTS=ON (kglobalaccel builds βœ…) +- KWIN_BUILD_RUNNERS=ON (kf6-kio builds βœ…) +- KWIN_BUILD_NOTIFICATIONS=ON (knotifications builds βœ…) +- USE_DBUS=ON (D-Bus 1.16.2 builds βœ…) +- Still disabled (9): KCMS, screen locking, tabbox, effects, X11, QML, running-in-kde, + signing docs, screenlocker +- Stub deps remaining: libepoxy-stub, libudev-stub, lcms2-stub, libdisplay-info-stub + +New dependency library: +- libqrencode 4.1.1 βœ… BUILT (QR code encoder, dependency of kf6-prison) - kf6-kwayland βœ… - seatd builds separately (runtime dependency, not needed for compilation) @@ -357,7 +406,8 @@ Phase 1 βœ… (qtbase + qtdeclarative + qtsvg) validated more broadly. QML network access is also affected. 3. **No GPU hardware acceleration** β€” Qt6 OpenGL/EGL and Mesa EGL+GBM now build, but they are still validated only on the software/LLVMpipe path. - True hardware acceleration (radeonsi or equivalent) still requires kernel DMA-BUF fd passing and real hardware validation. + True hardware acceleration (radeonsi or equivalent) still requires GPU command submission and real hardware validation. + PRIME/DMA-BUF cross-process buffer sharing is implemented at the scheme level. 4. **relibc / graphics surface still incomplete for runtime** β€” the build-side `open_memstream` and Wayland-facing header export path now work, but DMA-BUF ioctls, sync objects, and broader graphics runtime validation are still unavailable. @@ -370,7 +420,11 @@ Phase 1 βœ… (qtbase + qtdeclarative + qtsvg) The Qt6/KF6 build stack is substantially further along than the earlier "~50%" estimate implied: - Qt6, QtWayland, Mesa EGL+GBM, Qt6 OpenGL, libdrm amdgpu, and all 32 KF6 frameworks now build - the remaining blockers are concentrated in KWin/Plasma runtime integration and in the still-shimmed or stub-only packages such as Kirigami, libepoxy, libudev, lcms2, and libdisplay-info -- hardware acceleration still requires kernel DMA-BUF work and real hardware validation +- hardware acceleration still requires GPU command submission and real hardware validation (PRIME/DMA-BUF buffer sharing is implemented) - a successful build stack is not yet the same thing as a working KDE Plasma session -(Updated 2026-04-14 β€” status reconciled after relibc/libwayland bridge fixes; build-side progress is real, runtime remains incomplete) +For the canonical execution plan from this state to a working KDE Plasma desktop, see +`local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v2.0). The Qt work described here maps to +pre-Phase work (builds complete) and Phase 3 (KWin desktop session) in the canonical plan. + +(Updated 2026-04-16 β€” aligned with CONSOLE-TO-KDE-DESKTOP-PLAN.md v2.0) diff --git a/local/docs/QUIRKS-IMPROVEMENT-PLAN.md b/local/docs/QUIRKS-IMPROVEMENT-PLAN.md new file mode 100644 index 00000000..9c706879 --- /dev/null +++ b/local/docs/QUIRKS-IMPROVEMENT-PLAN.md @@ -0,0 +1,303 @@ +# Hardware Quirks Improvement Plan + +## Purpose + +This plan replaces vague β€œquirks support” follow-up work with a concrete path to: + +1. keep quirks data and reporting honest, +2. integrate quirks into real runtime driver behavior, +3. reduce duplicated quirk logic, +4. leave DMI and USB device quirks in a maintainable state. + +## Current status snapshot + +Completed from this plan: + +- runtime DMI TOML loading in `redox-driver-sys`, +- subsystem-gated PCI TOML matching in both the canonical path and `pcid-spawner`, +- shipped DMI TOML overrides in the brokered `pcid-spawner` env-var path, +- direct canonical `redox-driver-sys` quirk lookup from `pcid-spawner` instead of a separate in-tree PCI quirk engine, +- real USB device quirk consumption in `xhcid`, +- first real linux-kpi quirk consumption in the Red Bear amdgpu path. + +Still open after this implementation wave: + +- no remaining implementation items in the current quirks scope. + +The runtime-behavior milestone from this plan is now implemented. The remaining work is +maintenance, validation depth, and future refinement rather than missing quirks behavior for the +shipped paths. + +It is based on the current in-tree state of: + +- `redox-driver-sys` as the canonical quirks library, +- `pcid-spawner` as an upstream-owned PCI launch broker that now brokers canonical quirks, +- `redox-drm`, `xhcid`, and the amdgpu Redox glue/runtime path as real runtime PCI quirk consumers, +- `lspci`, `lsusb`, and `redbear-info` as reporting surfaces. + +## Reassessment Summary + +### What is real today + +- `redox-driver-sys` owns the canonical PCI/USB quirk flag definitions and lookup helpers. +- `redox-drm` consumes PCI quirks for interrupt fallback and `DISABLE_ACCEL`. +- `xhcid` consumes PCI controller quirks via `PCI_QUIRK_FLAGS` for IRQ mode selection and reset delay. +- `linux-kpi` exposes `pci_get_quirk_flags()` / `pci_has_quirk()` for C drivers, and amdgpu now consumes them in its Redox init path. +- `lspci` and `lsusb` surface active PCI/USB quirk flags for discovered devices. +- `redbear-info --quirks` reports configured TOML entries and DMI rule counts. + +### What is still weak + +- USB quirks now have a first real runtime consumer in `xhcid`, but broader USB-driver adoption is still missing. +- The `linux-kpi` bridge now has a first real in-tree C consumer: amdgpu uses it for firmware gating and quirk-aware IRQ expectation logging. Broader C-driver adoption is still missing. +- `pcid-spawner` still synthesizes a partial `PciDeviceInfo` instead of reusing a richer canonical PCI object, because it operates as an upstream-owned broker with a narrow interface. + +### What should not be β€œfixed” in the wrong layer + +- `firmware-loader` should stay a generic scheme service. `NEED_FIRMWARE` belongs in device driver policy, not in the firmware scheme daemon. +- `redbear-info` should describe configured and observable state; it should not pretend to prove runtime quirk application. + +## Target Architecture + +### Upstream-preference policy + +When upstream Redox already provides the same functionality, the upstream path wins by default +unless the Red Bear-local implementation is materially better. For quirks and driver support, +this means the canonical path should converge on `redox-driver-sys` instead of preserving +lower-quality duplicate quirk engines as a steady state. + +### Canonical rule + +`redox-driver-sys` remains the authoritative quirks model: + +- flag definitions, +- compiled-in tables, +- TOML parsing semantics, +- DMI matching behavior. + +All other code should either: + +1. call the canonical lookup directly, or +2. receive lookup results from a single broker that is guaranteed to use the same semantics. + +### Driver integration rule + +- **Rust PCI drivers using `redox-driver-sys`** should call `info.quirks()` directly. +- **C drivers using `linux-kpi`** should call `pci_has_quirk()` / `pci_get_quirk_flags()` directly in probe/init paths. +- **Upstream base drivers that cannot depend on `redox-driver-sys`** may continue using brokered quirk bits from `pcid-spawner`, but only if that broker is made semantically identical to the canonical library. +- **USB device quirks** should be consumed inside `xhcid` device enumeration/configuration logic, not only in tooling. + +## Concrete Work Plan + +### Wave 1 β€” Cleanup and truthfulness + +#### Task 1.1: Keep docs and reporting surfaces honest + +Scope: + +- `local/docs/QUIRKS-SYSTEM.md` +- `local/recipes/system/redbear-info/source/src/main.rs` +- related AGENTS references if needed + +Goals: + +- separate reporting surfaces from real runtime consumers, +- remove claims that imply driver integration where only tooling exists, +- keep β€œnot yet implemented” items explicit. + +QA: + +- `cargo test` in `local/recipes/system/redbear-info/source` +- review `redbear-info --help` text and `--quirks` output strings + +#### Task 1.2: Remove stale equivalence claims from extraction/documentation + +Scope: + +- `local/scripts/extract-linux-quirks.py` +- `local/docs/QUIRKS-SYSTEM.md` + +Goals: + +- avoid mapping Linux flags to incorrect Red Bear flags, +- clearly mark heuristic extraction limits for PCI handler-name mode. + +QA: + +- run the script on a small synthetic USB/PXI input sample, +- confirm output omits unsupported PCI flag mappings instead of inventing equivalents. + +### Wave 2 β€” Unify PCI quirk semantics + +#### Task 2.1: Eliminate semantic drift between `pcid-spawner` and `redox-driver-sys` + +Constraint: + +- `pcid-spawner` is upstream-owned base code, so any convergence work must be implemented as upstream-base changes carried by Red Bear patching until upstream absorbs them. + +Best approach: + +- make `pcid-spawner` consume generated/shared quirk data instead of hand-maintained duplicated tables and flag maps. + +Preferred implementation options, in order: + +1. **Shared generated data module** used by both `redox-driver-sys` and `pcid-spawner`. +2. **Protocol extension** where a single canonical broker calculates quirk bits and hands them to drivers. +3. Keep duplication only as a short-term fallback if generation is not yet practical. + +Do **not** continue manually editing two separate PCI quirk engines long-term. + +Success criteria: + +- one authoritative source for compiled PCI quirk entries and flag name mapping, +- subsystem matching behavior aligned, +- explicit decision on whether DMI is brokered by `pcid-spawner` or left to driver-local lookup. + +QA: + +- compare quirk outputs for the same synthetic PCI info through both paths, +- verify `PCI_QUIRK_FLAGS` emitted by `pcid-spawner` matches canonical lookup for representative devices. + +#### Task 2.2: Decide DMI ownership clearly + +Decision needed: + +- either `pcid-spawner` becomes DMI-aware and brokers the final PCI quirk bitmask, +- or `pcid-spawner` remains PCI/TOML-only and DMI stays driver-local in `redox-driver-sys` consumers. + +Recommendation: + +- near term: document the split clearly, +- medium term: move toward one brokered result for upstream base drivers. + +QA: + +- one design note added to the docs explaining the chosen ownership model. + +### Wave 3 β€” Real driver integration + +#### Task 3.1: Integrate USB device quirks in `xhcid` + +Best integration points: + +- after device descriptor read, +- before SetConfiguration, +- before enabling LPM/U1/U2 or USB3-specific behavior, +- after reset paths where extra delay or reset-after-probe is needed. + +Minimum runtime behaviors to wire first: + +- `NO_SET_CONFIG` +- `NEED_RESET` +- `NO_LPM` +- `NO_U1U2` +- `BAD_DESCRIPTOR` + +Success criteria: + +- `xhcid` calls `lookup_usb_quirks()` for enumerated devices, +- these flags alter runtime behavior in concrete branches, +- tooling and runtime logic agree on the same device-level quirks. + +QA: + +- unit/integration tests for selector logic where possible, +- manual logging proof that a known vendor/product entry triggers the expected path. + +#### Task 3.2: Consume linux-kpi quirks in `amdgpu` + +Best integration points: + +- probe path, +- IRQ mode selection, +- firmware gating, +- memory/power-management setup. + +First flags to consume: + +- `NO_MSI` +- `NO_MSIX` +- `NEED_FIRMWARE` +- `NO_ASPM` +- `NEED_IOMMU` + +Success criteria: + +- at least one real C driver uses `pci_has_quirk()` in production code, +- runtime logs show quirk-informed decision making. + +Current state: + +- `local/recipes/gpu/amdgpu/source/amdgpu_redox_main.c` now queries linux-kpi PCI quirks in the real Redox runtime path, +- `PCI_QUIRK_NEED_FIRMWARE` turns missing DMCUB firmware into an init failure instead of a warning-only fallback, +- logs now show the active quirk bitmask plus the implied IRQ fallback policy. + +QA: + +- `grep` shows real in-tree call sites in amdgpu, +- build passes for linux-kpi + amdgpu recipe path. + +#### Task 3.3: Keep firmware policy in drivers, not firmware-loader + +Action: + +- when a driver has `NEED_FIRMWARE`, the driver should gate initialization until the firmware load succeeds. +- `firmware-loader` remains a transport/provider only. + +Success criteria: + +- docs stop implying that firmware-loader interprets quirk flags, +- driver init paths own the policy decision. + +QA: + +- driver code path shows firmware gating tied to quirks or explicit device rules. + +### Wave 4 β€” DMI completion + +#### Task 4.1: DMI TOML runtime loading + +Scope: + +- `toml_loader.rs` parses `[[dmi_system_quirk]]`, +- matching uses live DMI info served by `acpid` at `/scheme/acpi/dmi`, +- resulting PCI quirk overrides flow through the canonical `redox-driver-sys` DMI path. + +Success criteria: + +- `50-system.toml` entries are no longer config-only, +- runtime DMI TOML behavior is testable and documented through the live `acpid` DMI scheme. + +QA: + +- tests for TOML parsing, +- one mock DMI input path proving a TOML DMI rule applies flags. + +#### Task 4.2: ACPI blacklist/override layer + +Current state: + +- `acpid` now supports narrow `[[acpi_table_quirk]]` skip rules, optionally gated by the same + DMI-style `match.*` fields used elsewhere. +- The implementation is intentionally limited to table suppression during ACPI table load; it is + not a broad AML patching or firmware replacement framework. + +## Suggested Immediate Deliverables + +If work resumes right away, the next concrete implementation sequence should be: + +1. clean remaining stale quirks docs/reporting text, +2. write a design note for canonical PCI quirk ownership, +3. integrate `lookup_usb_quirks()` into `xhcid` enumeration/configuration, +4. add first real `pci_has_quirk()` use in `amdgpu`, +5. validate and extend shipped DMI TOML coverage as needed. + +## Exit Criteria For The Next Quirks Milestone + +The next milestone is complete when all are true: + +- `pcid-spawner` and `redox-driver-sys` no longer drift semantically, +- `xhcid` consumes USB device quirks at runtime, +- at least one real C driver consumes linux-kpi quirks, +- docs distinguish clearly between reporting, infrastructure, and true runtime behavior, +- DMI TOML entries are either runtime-applied or removed from shipped config. diff --git a/local/docs/QUIRKS-SYSTEM.md b/local/docs/QUIRKS-SYSTEM.md new file mode 100644 index 00000000..c56b8337 --- /dev/null +++ b/local/docs/QUIRKS-SYSTEM.md @@ -0,0 +1,339 @@ +# Red Bear OS Hardware Quirks System + +## Overview + +Red Bear OS implements a data-driven hardware quirks system inspired by Linux's +PCI/USB/DMI quirk infrastructure, adapted for Redox's microkernel/userspace-driver +architecture. + +Quirks handle known hardware defects that cannot be fixed by correct driver code +alone. They override default driver behavior for specific devices, revisions, or +entire system models. + +For the current follow-up cleanup and integration roadmap, see +`local/docs/QUIRKS-IMPROVEMENT-PLAN.md`. + +## Architecture + +``` +Driver probes device + └─ PciDeviceInfo::quirks() + β”œβ”€ Layer 1: Compiled-in table (pci_table.rs, usb_table.rs) + β”œβ”€ Layer 2: TOML files from /etc/quirks.d/*.toml + └─ Layer 3: DMI-based system rules + └─ Returns: PciQuirkFlags (bitwise OR of all matching entries) +``` + +All matching entries accumulate via bitwise OR, so broad rules (e.g., "all AMD GPUs +need firmware") and narrow rules (e.g., "this specific revision has broken MSI-X") +compose naturally. + +## Quirk Sources + +### 1. Compiled-in Tables + +Location: `local/recipes/drivers/redox-driver-sys/source/src/quirks/` + +Critical quirks that must be available before the root filesystem is mounted. +Defined as `const` arrays in Rust: + +- `pci_table.rs` β€” `PCI_QUIRK_TABLE: &[PciQuirkEntry]` +- `usb_table.rs` β€” `USB_QUIRK_TABLE: &[UsbQuirkEntry]` + +Each entry specifies: +- Vendor/device/subsystem match fields (0xFFFF = wildcard) +- Revision range (lo..hi inclusive) +- Class code mask and match value +- `PciQuirkFlags` bitmask + +### 2. TOML Quirk Files + +Location: `/etc/quirks.d/*.toml` (shipped by the `redbear-quirks` package) + +Extensible at runtime without recompiling drivers. Format: + +```toml +[[pci_quirk]] +vendor = 0x1002 +device = 0x73BF +flags = ["need_firmware", "no_d3cold"] + +[[pci_quirk]] +vendor = 0x10EC +device = 0x8125 +flags = ["no_aspm"] + +[[usb_quirk]] +vendor = 0x0A12 +flags = ["bad_descriptor", "no_set_config"] +``` + +Files are loaded alphabetically from `/etc/quirks.d/`. Recommended naming: +`00-core.toml`, `10-gpu.toml`, `20-usb.toml`, `30-net.toml`, `40-storage.toml`, +`50-system.toml`. + +Runtime TOML loading now also supports `[[dmi_system_quirk]]` entries. Those +entries are applied when `acpid` is running and serving live DMI data from +`/scheme/acpi/dmi`. + +### 3. DMI-Based System Quirks + +Match by SMBIOS fields (sys_vendor, board_name, product_name) to apply +system-wide quirk overrides. Eight compiled-in rules exist for known systems, +and `/etc/quirks.d/*.toml` can now add `[[dmi_system_quirk]]` rules with +`match.*` keys plus optional `pci_vendor` / `pci_device` selectors. Runtime use +now reads live SMBIOS strings from `acpid` via `/scheme/acpi/dmi`. + +## Available Quirk Flags + +### PCI Quirks (PciQuirkFlags) + +| Flag | Meaning | +|------|---------| +| `NO_MSI` | MSI capability broken; use MSI-X or legacy | +| `NO_MSIX` | MSI-X capability broken; use MSI or legacy | +| `FORCE_LEGACY_IRQ` | Must use INTx interrupts | +| `NO_PM` | Disable all power management | +| `NO_D3COLD` | Cannot recover from D3cold power state | +| `NO_ASPM` | Active State Power Management broken | +| `NEED_IOMMU` | Requires IOMMU isolation | +| `NO_IOMMU` | Must NOT be behind IOMMU | +| `DMA_32BIT_ONLY` | Only supports 32-bit DMA | +| `RESIZE_BAR` | BAR sizing reports incorrectly | +| `DISABLE_BAR_SIZING` | Use firmware BAR values as-is | +| `NEED_FIRMWARE` | Requires firmware files to initialize | +| `DISABLE_ACCEL` | Disable hardware acceleration | +| `FORCE_VRAM_ONLY` | No GTT/system memory fallback | +| `NO_USB3` | Force USB 2.0 mode | +| `RESET_DELAY_MS` | Needs extra post-reset delay | +| `NO_STRING_FETCH` | Do not fetch string descriptors | +| `BAD_EEPROM` | EEPROM unreliable; use hardcoded values | +| `BUS_MASTER_DELAY` | Needs delay after bus-master enable | +| `WRONG_CLASS` | Reports incorrect class code | +| `BROKEN_BRIDGE` | PCI bridge forwarding bug | +| `NO_RESOURCE_RELOC` | Do not relocate PCI resources | + +### USB Quirks (UsbQuirkFlags) + +| Flag | Meaning | +|------|---------| +| `NO_STRING_FETCH` | Do not fetch string descriptors | +| `RESET_DELAY` | Needs extra reset delay | +| `NO_USB3` | Disable USB 3.x | +| `NO_SET_CONFIG` | Cannot handle SetConfiguration | +| `NO_SUSPEND` | Broken suspend/resume | +| `NEED_RESET` | Needs reset after probe | +| `BAD_DESCRIPTOR` | Wrong descriptor sizes | +| `NO_LPM` | Disable Link Power Management | +| `NO_U1U2` | Disable U1/U2 link transitions | + +## Driver Integration + +### For Rust Drivers (using redox-driver-sys) + +```rust +use redox_driver_sys::quirks::PciQuirkFlags; + +fn probe(info: &PciDeviceInfo) { + let quirks = info.quirks(); + + if quirks.contains(PciQuirkFlags::NO_MSIX) { + // Skip MSI-X, try MSI or legacy + } + + if quirks.contains(PciQuirkFlags::NEED_FIRMWARE) { + // Load firmware before initializing device + } + + if quirks.contains(PciQuirkFlags::DISABLE_ACCEL) { + // Skip hardware probe, let software renderer take over + return Err(DriverError::QuirkDisabled); + } +} +``` + +### For C Drivers (using linux-kpi) + +The `linux-kpi` crate exposes two FFI functions for C drivers to query quirks: + +```c +#include + +// After pci_enable_device() in your probe callback: +static int my_probe(struct pci_dev *dev, const struct pci_device_id *id) +{ + u64 quirks = pci_get_quirk_flags(dev); + + if (quirks & PCI_QUIRK_NO_MSIX) { + // Skip MSI-X, fall back to MSI or legacy IRQ + } + + if (pci_has_quirk(dev, PCI_QUIRK_NEED_FIRMWARE)) { + // Load firmware before initializing hardware + } +} +``` + +The amdgpu Redox glue/runtime path is now the first in-tree production C consumer +of this interface: it queries `pci_get_quirk_flags()` during AMD DC init, logs the +resulting IRQ expectations, and treats `PCI_QUIRK_NEED_FIRMWARE` as a hard failure +instead of a warn-and-continue path when that quirk is active. + +Available C quirk flag macros (defined in `linux/pci.h`): + +| Macro | Bit | Meaning | +|-------|-----|---------| +| `PCI_QUIRK_NO_MSI` | 0 | MSI interrupts broken | +| `PCI_QUIRK_NO_MSIX` | 1 | MSI-X interrupts broken | +| `PCI_QUIRK_FORCE_LEGACY` | 2 | Must use legacy INTx | +| `PCI_QUIRK_NO_PM` | 3 | Power management broken | +| `PCI_QUIRK_NO_D3COLD` | 4 | D3cold state broken | +| `PCI_QUIRK_NO_ASPM` | 5 | ASPM broken | +| `PCI_QUIRK_NEED_IOMMU` | 6 | Requires IOMMU | +| `PCI_QUIRK_DMA_32BIT_ONLY` | 8 | DMA limited to 32-bit | +| `PCI_QUIRK_NEED_FIRMWARE` | 11 | Requires firmware load | +| `PCI_QUIRK_DISABLE_ACCEL` | 12 | Disable hardware acceleration | + +## Adding New Quirks + +### To the compiled-in table + +Edit `local/recipes/drivers/redox-driver-sys/source/src/quirks/pci_table.rs`: + +```rust +const F_MY_FLAGS: PciQuirkFlags = PciQuirkFlags::from_bits_truncate( + PciQuirkFlags::NEED_FIRMWARE.bits() | PciQuirkFlags::NO_ASPM.bits(), +); + +PciQuirkEntry { + vendor: 0xVENDOR, + device: 0xDEVICE, + flags: F_MY_FLAGS, + ..PciQuirkEntry::WILDCARD +}, +``` + +### To a TOML file + +Create or edit a file in `local/recipes/system/redbear-quirks/source/quirks.d/`: + +```toml +[[pci_quirk]] +vendor = 0xVENDOR +device = 0xDEVICE +flags = ["need_firmware", "no_aspm"] + +[[dmi_system_quirk]] +pci_vendor = 0xVENDOR +flags = ["disable_accel"] +match.sys_vendor = "Example Vendor" +match.product_name = "Example Model" + +[[acpi_table_quirk]] +signature = "DMAR" +match.sys_vendor = "Example Vendor" +match.product_name = "Example Model" +``` + +### Choosing where to add + +- **Compiled-in**: Boot-critical quirks, anything needed before root mount +- **TOML**: Everything else β€” easier to update, no recompilation needed +- **DMI rule**: System-specific workarounds that apply to specific laptop models + +## File Layout + +``` +local/recipes/drivers/redox-driver-sys/source/src/quirks/ +β”œβ”€β”€ mod.rs # Public API: lookup_pci_quirks(), PciQuirkFlags, PciQuirkEntry +β”œβ”€β”€ pci_table.rs # Compiled-in PCI quirk table +β”œβ”€β”€ usb_table.rs # Compiled-in USB quirk table +β”œβ”€β”€ dmi.rs # DMI/SMBIOS matching and system-level quirk rules +└── toml_loader.rs # /etc/quirks.d/*.toml parser + +local/recipes/system/redbear-quirks/ +β”œβ”€β”€ recipe.toml # Custom build: copies TOML files to /etc/quirks.d/ +└── source/quirks.d/ + β”œβ”€β”€ 00-core.toml + β”œβ”€β”€ 10-gpu.toml + β”œβ”€β”€ 20-usb.toml + β”œβ”€β”€ 30-net.toml + β”œβ”€β”€ 40-storage.toml + └── 50-system.toml +``` + +## Relationship to Linux Quirks + +| Linux Pattern | Red Bear Equivalent | +|---------------|-------------------| +| `DECLARE_PCI_FIXUP_HEADER(v, d, fn)` | `PciQuirkEntry { vendor: v, device: d, flags: ... }` | +| `pci_dev->dev_flags \|= PCI_DEV_FLAGS_NO_BUS_RESET` | No direct equivalent β€” future flag candidate | +| `USB_QUIRK_STRING_FETCH` | `UsbQuirkFlags::NO_STRING_FETCH` | +| `DMI_MATCH(DMI_SYS_VENDOR, "Lenovo")` | `DmiMatchRule { sys_vendor: Some("Lenovo") }` | +| `acpi_black_listed()` | `[[acpi_table_quirk]] signature = "...."` with skip semantics in `acpid` | + +## Testing + +Run quirks unit tests: + +```bash +cd local/recipes/drivers/redox-driver-sys/source +cargo test +``` + +## Implementation Status + +| Phase | Component | Status | +|-------|-----------|--------| +| Q1 | Core types (PciQuirkFlags, PciQuirkEntry, UsbQuirkFlags) | βœ… Done | +| Q1 | Compiled-in PCI/USB quirk tables | βœ… Done | +| Q1 | Lookup API (quirks(), has_quirk()) | βœ… Done | +| Q1 | Subsystem (subvendor/subdevice) fields | βœ… Done β€” compiled and TOML PCI matching both apply subsystem selectors | +| Q2 | TOML loader for /etc/quirks.d/ | βœ… Done | +| Q2 | redbear-quirks data package | βœ… Done | +| Q3 | redox-drm integration (MSI-X/MSI/legacy + DISABLE_ACCEL) | βœ… Done | +| Q3 | xhcid PCI controller quirks (interrupt + reset delay) | βœ… Done | +| Q3 | xhcid USB device quirks (descriptor/configuration/BOS handling) | βœ… Done | +| Q3 | pcid-spawner quirk passthrough | βœ… Done | +| Q3 | linux-kpi quirk flag bridge | βœ… Done | +| Q3 | amdgpu linux-kpi quirk consumption | βœ… Done | +| Q3 | redbear-info --quirks display | βœ… Done | +| Q4 | DMI/SMBIOS compiled-in rules | βœ… Done β€” 8 system rules (const table) | +| Q4 | DMI/SMBIOS TOML runtime loading | βœ… Done β€” `dmi_system_quirk` uses live `/scheme/acpi/dmi` data from `acpid` | +| Q4 | ACPI table blacklist/override | βœ… Done β€” `acpid` applies `[[acpi_table_quirk]]` skip rules during table load | +| Q5 | lspci quirk display | βœ… Done β€” shows active quirks per device | +| Q5 | lsusb quirk display | βœ… Done β€” shows active quirks per device | +| Q5 | Linux quirk extraction tool | βœ… Script exists β€” PCI mode uses heuristic name matching, USB mode works for table entries | + +Quirk flags span data definition, infrastructure wiring, and driver consumption. +Most flags are defined but not yet consumed at runtime β€” the tables below show +the honest breakdown. + +**Flags consumed by drivers (runtime checks in production code):** +- redox-drm: `NO_MSIX`, `NO_MSI`, `FORCE_LEGACY_IRQ`, `DISABLE_ACCEL` (interrupt setup + driver probe) +- xhcid: `RESET_DELAY_MS`, `NO_MSI`, `NO_MSIX`, `FORCE_LEGACY_IRQ` (interrupt selection + port reset delay) +- xhcid (USB device path): `NO_SET_CONFIG`, `NO_STRING_FETCH`, `BAD_DESCRIPTOR`, `NO_USB3`, `NO_LPM`, `NO_U1U2` (enumeration/configuration/BOS handling) +- amdgpu: `NEED_FIRMWARE` (hard firmware gate), with real quirk-aware logging for `NO_ASPM`, `NEED_IOMMU`, `NO_MSI`, `NO_MSIX` + +**Infrastructure (data flows, reporting, and partial integration):** +- pcid-spawner: computes `PCI_QUIRK_FLAGS` by calling the canonical `redox-driver-sys` lookup on synthesized `PciDeviceInfo`, then passes the env var onward +- linux-kpi: `pci_get_quirk_flags()` / `pci_has_quirk()` C FFI is available for C drivers and is now consumed by the Red Bear amdgpu path +- redbear-info: `--quirks` reads `/etc/quirks.d/*.toml` and reports configured PCI/USB/DMI entries +- lspci: shows active quirk flags per PCI device (via redox-driver-sys lookup) +- lsusb: shows active quirk flags per USB device (via redox-driver-sys lookup) +- DMI compiled-in rules: 8 entries match systems by vendor/product/board (served through `acpid` at `/scheme/acpi/dmi`) + +**Observed/logged but not yet strongly enforced in runtime policy:** +- `NO_ASPM`, `NEED_IOMMU`, `NO_MSI`, `NO_MSIX` in the amdgpu path are surfaced in quirk-aware logs before broader driver policy exists. + +**Defined but not yet consumed by any real driver path:** +- `NO_PM`, `NO_D3COLD`, `DMA_32BIT_ONLY`, `BUS_MASTER_DELAY`, `NO_IOMMU`, etc. + +`firmware-loader` itself does not interpret `NEED_FIRMWARE`; that policy is now enforced in the amdgpu driver path instead. + +`NEED_RESET` remains defined for USB devices but is not yet consumed by a runtime USB driver path. + +**Remaining infrastructure work:** +- none in the current quirks scope + +`pcid-spawner` now brokers quirks through the canonical `redox-driver-sys` lookup instead of carrying a separate in-tree PCI quirk engine. diff --git a/local/docs/USB-IMPLEMENTATION-PLAN.md b/local/docs/USB-IMPLEMENTATION-PLAN.md index 2f05c07a..91729662 100644 --- a/local/docs/USB-IMPLEMENTATION-PLAN.md +++ b/local/docs/USB-IMPLEMENTATION-PLAN.md @@ -26,41 +26,91 @@ This repo should not treat **builds** or **enumerates** as equivalent to **valid ### Summary -USB in Red Bear OS is **present but incomplete**. +USB in Red Bear OS is **present and improving**. The current repo supports a real host-side USB path built around the userspace `xhcid` controller daemon, hub and HID class spawning, native USB observability (`lsusb`, `usbctl`, `redbear-info`), and a low-level userspace client API through `xhcid_interface`. -The current limitations are material: +Completed work: + +- BOS/SuperSpeed descriptor fetching wired up β€” `xhcid` fetches and parses BOS capability + descriptors during device enumeration, with bounds-checked slicing and graceful USB 2 fallback +- Speed detection for hub child devices β€” `usbhubd` extracts child device speed from hub port + status via `UsbSpeed` enum (`#[repr(u8)]` with `TryFrom`) and passes it through + `attach_with_speed()` protocol; server maps to PSIV via `lookup_speed_category()` +- Interrupt-driven operation restored β€” `main.rs` calls `get_int_method()` instead of hard-coded + `(None, Polling)`; MSI/MSI-X/INTx paths re-enabled +- Event ring growth implemented β€” `grow_event_ring()` doubles ring size (up to 4096 cap), + allocates new DMA ring, preserves dequeue pointer, updates ERDP/ERSTBA hardware registers +- USB 3 hub endpoint configuration β€” `SET_INTERFACE` always sent; stall on `(0,0)` tolerated + with debug log and graceful continuation +- Hub interrupt EP1 status change detection replacing full polling loop in `usbhubd` +- Hub change bit clearing on all port paths β€” `clear_port_changes` sends + `ClearFeature(C_PORT_CONNECTION, C_PORT_ENABLE, C_PORT_RESET, C_PORT_OVER_CURRENT)` plus + USB3-specific features (`C_PORT_LINK_STATE`, `C_PORT_CONFIG_ERROR`) after every port status read +- Runtime panic reduction across USB daemons β€” `device_enumerator.rs`, `irq_reactor.rs`, + `mod.rs`, `scheme.rs`, `usbhubd/main.rs`, `usbhidd/main.rs` converted from `panic!/expect` + to `log + continue/return` or `ok_or` in most hot paths; mutex poison recovery on all hot-path + locks; `scsi/mod.rs` block descriptor parsing returns errors instead of panicking; + `xhci/scheme.rs` uses `ok_or` for device descriptor and DMA buffer access +- `usbhidd` no longer panics on malformed report data β€” proper `Result` propagation +- `usbscsid` panic paths eliminated in BOT transport β€” all 4 `panic!()` calls replaced with + stall recovery (`clear_stall` + `reset_recovery`) and `ProtocolError` returns; SCSI + `get_mode_sense10` failure returns error instead of panicking; `main.rs` uses + `unwrap_or_else` with `eprintln` + `exit(1)` instead of `expect()`; startup sector read + failure logs and continues instead of panicking; event loop handles errors gracefully +- Empty UAS module stub removed from `usbscsid`; `protocol::setup` returns `None` gracefully + for unsupported protocols instead of unwrapping +- BOT transport correctness fixes β€” `CLEAR_FEATURE(ENDPOINT_HALT)` now uses USB endpoint + address from descriptor (`bEndpointAddress`) instead of driver endpoint index; `get_max_lun` + sends correct interface number; `early_residue` correctly computes `expected - transferred` + for short packets; CSW read uses iterative bounded loop instead of unbounded recursion +- USB validation harness (`test-usb-qemu.sh`) with 6-check QEMU validation +- In-guest USB checker binary (`redbear-usb-check`) walking scheme tree +- USB validation runbook for operators +- All changes mirrored to `local/patches/base/redox.patch` for upstream refresh survival + +The remaining limitations are: -- xHCI no longer hard-forces polling; it uses the existing interrupt-mode selection path again, but - interrupt-driven behavior is still only lightly validated under runtime load -- checked-in event-ring growth support now exists, but it still needs stronger runtime validation -- USB support varies by machine, including known `xhcid` panic cases -- hub/topology handling is partial - HID is still wired through the legacy mixed-stream `inputd` path -- USB mass storage exists in-tree and now autospawns successfully in the current QEMU validation - path, but broader runtime stability and wider class/topology validation are still open. +- SuperSpeedPlus differentiation requires Extended Port Status (not yet implemented) +- TTT (Think Time) in Slot Context hardcoded to 0 β€” needs parent hub descriptor propagation +- Composite devices and non-default alternate settings use first-match only (`//TODO: USE ENDPOINTS FROM ALL INTERFACES`) +- `grow_event_ring()` swaps to a new ring but does not copy pending TRBs from the old one; under sustained event-ring-full conditions this may lose in-flight events +- `usbhubd` startup uses `unwrap_or_else` with graceful exit (not panics), but per-child-port handle creation now skips failed ports with error logging - there is no evidence of validated support for broader USB classes or modern USB-C / dual-role scope +### Identified Correctness Issues (from audit) + +A comprehensive audit of the xHCI driver identified these correctness issues. Fixes are being +applied through `local/patches/base/redox.patch`: + +- **ERDP read pointer bug** (`event.rs`): `erdp()` returns the software producer pointer from the + ring state instead of reading the actual hardware dequeue pointer from the ERDP runtime register. + Per XHCI spec Β§4.9.3, the ERDP must reflect where hardware has finished reading, not where + software enqueues new entries. This causes the event ring dequeue pointer to be incorrect after + processing events, potentially leading to missed or double-processed events. +- **Mutex poisoning panics**: ~37 `unwrap()` calls on mutex locks across `mod.rs`, `irq_reactor.rs`, + `scheme.rs`, and `ring.rs` will panic if a thread holding the lock panics. All should use + `unwrap_or_else(|e| e.into_inner())` for poisoning recovery. Additionally, ~22 `expect()` calls + need proper error handling. +- **Ring `panic!()` in `trb_phys_ptr()`**: `ring.rs` contains a direct `panic!()` on invalid state + instead of returning an error. + ### Current Status Matrix | Area | State | Notes | |---|---|---| -| Host mode | **usable / experimental** | Real host-side stack exists, but not broadly validated | -| xHCI controller | **builds / enumerates / usable on some hardware** | Interrupt-mode selection restored, hardware-variable, event-ring growth exists in-tree but still needs stronger runtime validation | -| Hub handling | **builds / partial usable** | `usbhubd` exists, USB 3 hub limitations remain | -| HID | **builds / usable in narrow path** | `usbhidd` handles keyboard/mouse/button/scroll via legacy input path | -| Mass storage | **builds / autospawns in QEMU** | `usbscsid` now spawns from the xHCI class-driver table, but runtime stability past spawn still needs work | -| Native tooling | **builds / enumerates** | `lsusb`, `usbctl`, `redbear-info` provide partial observability | -| Low-level userspace API | **builds** | `xhcid_interface` exists, but not a mature general userspace USB story | -| libusb | **builds / experimental** | WIP, compiled but not tested | -| usbutils | **broken / experimental** | WIP, compilation error | -| EHCI/OHCI/UHCI | **absent / undocumented** | No evidence present in-tree | -| USB networking/audio/video/Bluetooth classes | **partial / experimental** | Broad class support remains incomplete, but one bounded explicit-startup USB-attached Bluetooth slice now exists | -| Device mode / OTG / dual-role / USB-C / PD / alt-modes / USB4 | **absent / undocumented** | No evidence present | +| Host mode | **usable / experimental** | Real host-side stack exists, interrupt-driven, not broadly validated on hardware | +| xHCI controller | **builds / usable on some hardware** | Interrupt delivery restored (MSI/MSI-X/INTx), event ring growth, CLEAR_FEATURE uses USB endpoint address; mutex poison recovery on all hot-path locks in scheme.rs and mod.rs | +| Hub handling | **builds / improving** | `usbhubd` uses interrupt EP1, change bits cleared, USB 3 speed-aware attach | +| HID | **builds / usable in narrow path** | `usbhidd` handles keyboard/mouse/button/scroll via legacy input path, no panics in report loop | +| Mass storage | **builds / improving** | `usbscsid` BOT transport has graceful error handling; endpoint addresses corrected; event loop handles errors; `plain::from_bytes`/`slice_from_bytes` error mapping in bot.rs and scsi/mod.rs block descriptors with bounds checks; runtime I/O validation still needed | +| Native tooling | **builds / enumerates** | `lsusb`, `usbctl`, `redbear-info`, `redbear-usb-check` provide observability | +| Low-level userspace API | **builds** | `xhcid_interface` with `UsbSpeed` enum, `attach_with_speed()` | +| Validation | **builds** | `test-usb-qemu.sh` + `redbear-usb-check` + USB-VALIDATION-RUNBOOK.md | ## Evidence Already In Tree @@ -101,19 +151,17 @@ The current limitations are material: Current repo-visible issues include: -- partially restored interrupt-driven behavior without complete event-ring growth support -- incorrect or incomplete speed handling for child devices - TODOs around configuration choice and alternate settings - TODOs around endpoint selection across interfaces -- incomplete BOS / SuperSpeed / SuperSpeedPlus handling +- TTT (Think Time) hardcoded to 0 in Slot Context β€” needs parent hub descriptor propagation This means the current stack is more than a bring-up stub, but still below the bar for a reliable, future-proof USB controller foundation. ### 2. Topology and hotplug maturity are partial -The stack can enumerate ports and descendants, but the code still carries explicit TODOs around hub -behavior and USB 3 hub handling. +The stack can enumerate ports and descendants. USB 3 hub endpoint configuration now works without +stalling, and child device speed detection is correct when devices attach through hubs. The current repo does not justify a claim that attach, detach, reset, reconfigure, and hub-chained topologies are runtime-proven in a broad sense. @@ -126,14 +174,17 @@ However, the current HID path is still tied to the older anonymous `inputd` prod `local/docs/INPUT-SCHEME-ENHANCEMENT.md` already defines the needed next step: named producers, per-device streams, and explicit hotplug events. -### 4. Storage is present in-tree but not a current support claim +### 4. Storage is present in-tree, improving, but not yet validated -`usbscsid` is a real driver and the xHCI class-driver table now spawns it again during QEMU USB -storage validation. The current blocker is not matching or spawn, but transport/runtime stability -after spawn. +`usbscsid` is a real driver and the xHCI class-driver table spawns it during QEMU USB storage +validation. All BOT transport `panic!()` paths have been replaced with proper stall recovery and +error returns. The `main.rs` initialization path uses graceful error handling instead of `expect()`. -That means Red Bear should document USB storage as **implemented in-tree but not currently enabled -as a default working class path**. +The remaining gap is runtime validation: proving that stall recovery actually works under real +device I/O, and that multi-LUN devices configure correctly. + +Red Bear should document USB storage as **implemented in-tree with improved error handling, but not yet +runtime-validated on hardware**. ### 5. The userspace USB story is still low-level @@ -199,6 +250,21 @@ not a recommendation to bypass Red Bear's overlay/patch discipline. ### Phase U1 β€” xHCI Controller Baseline +**Status**: Partially complete. + +**Completed**: +- BOS/SuperSpeed descriptor fetching wired up in `get_desc()` β€” `fetch_bos_desc()` called, + `bos_capability_descs()` iterator parsed, `supports_superspeed`/`supports_superspeedplus` stored + in `DevDesc` +- Speed detection for hub child devices fixed β€” `UsbSpeed` enum with `from_v2_port_status()` and + `from_v3_port_status()` mapping, passed via `attach_with_speed()` protocol from `usbhubd` +- `attach_device_with_speed()` accepts optional speed override byte, maps to PSIV via + `lookup_speed_category()` + +**Remaining**: +- Validate one controller family as the first real support target +- Tighten controller-state correctness under sustained load + **Goal**: Turn `xhcid` from partial bring-up into a dependable baseline on at least one controller family. @@ -225,11 +291,24 @@ family. ### Phase U2 β€” Topology, Configuration, and Hotplug Correctness +**Status**: Partially complete. + +**Completed**: +- USB 3 hub endpoint configuration stall handled β€” `SET_INTERFACE` is always sent; stall on + `(0, 0)` is tolerated with debug log and graceful continuation +- `usbhubd` now passes `interface_desc` and `alternate_setting` to `configure_endpoints` + +**Remaining**: +- validate repeated attach/detach/reset behavior +- support non-default configurations and alternate settings where needed +- improve composite-device handling and endpoint selection across interfaces +- separate "enumerates" from "stays correct under topology changes" + **Goal**: Make the USB tree and device configuration path correct enough for real-world devices. **What to do**: -- fix USB 3 hub stall cases and other known hub limitations +- USB 3 hub stall handling completed β€” SET_INTERFACE always sent with (0,0) stall tolerance - validate repeated attach/detach/reset behavior - support non-default configurations and alternate settings where needed - improve composite-device handling and endpoint selection across interfaces @@ -251,6 +330,17 @@ family. ### Phase U3 β€” HID Modernization +**Status**: Partially complete. + +**Completed**: +- `usbhidd` error handling improved β€” `assert_eq!` replaced with `anyhow::bail!`, `.expect()` in + main loop replaced with `match` + `continue` for graceful recovery + +**Remaining**: +- migrate `usbhidd` toward named producers and per-device streams +- expose hotplug add/remove behavior cleanly to downstream consumers +- align USB HID with the `inputd` enhancement design already documented in-tree + **Goal**: Move USB HID from legacy mixed-stream input to a modern per-device runtime path. **What to do**: @@ -333,6 +423,18 @@ implicit forever. ### Phase U6 β€” Validation Slices and Support Claims +**Status**: Partially complete. + +**Completed**: +- `local/scripts/test-usb-qemu.sh` β€” Full USB stack validation harness that boots with xHCI + + keyboard + tablet + mass storage, then checks for xHCI interrupt mode, HID spawn, SCSI spawn, + BOS processing, and no crash-class errors + +**Remaining**: +- add hardware-matrix coverage for target controllers and class families +- extend `redbear-info` only where passive probing can be honest +- tie support claims to a concrete profile or package-group slice + **Goal**: Turn USB from a collection of partial capabilities into an evidence-backed support story. **What to do**: @@ -368,23 +470,25 @@ Prefer language such as: - β€œxHCI host support is present but experimental” - β€œUSB enumeration and HID-adjacent host paths exist in-tree” - β€œUSB support remains controller-variable” -- β€œUSB storage support exists in-tree and is QEMU-proven for the current validation path, but is - not yet a broad hardware support claim” +- β€œUSB storage support exists in-tree with improved error handling, but is not yet a broad hardware support claim” ## Summary USB in Red Bear today is not missing. It is a real userspace host-side subsystem with meaningful enumeration, runtime observability, hub/HID infrastructure, and a low-level userspace API. -It is also not complete. The current gaps are no longer β€œdoes Red Bear have any USB code at all?” -but rather: +Recent work has closed several specific gaps: BOS/SuperSpeed descriptor handling, hub child speed +detection, USB 3 hub configuration stalls, HID error handling, and a comprehensive QEMU validation +harness. -- controller correctness and interrupt maturity -- topology and configuration correctness -- HID modernization -- re-enabling and validating storage +The remaining gaps are: + +- controller interrupt maturity under sustained load +- topology and configuration correctness under attach/detach stress +- HID modernization toward named producers and per-device streams +- re-enabling and validating storage runtime stability - defining a coherent userspace USB API strategy - deciding how much modern USB scope Red Bear actually wants -- building a real USB validation surface +- building broader USB validation coverage That is the correct framing for a modern, future-proof USB implementation plan in this repo. diff --git a/local/docs/WIFI-IMPLEMENTATION-PLAN.md b/local/docs/WIFI-IMPLEMENTATION-PLAN.md index 826004d7..ef08b652 100644 --- a/local/docs/WIFI-IMPLEMENTATION-PLAN.md +++ b/local/docs/WIFI-IMPLEMENTATION-PLAN.md @@ -2,740 +2,279 @@ ## Purpose -This document defines the current Wi-Fi state in Red Bear OS and lays out the recommended path for -integrating Wi-Fi drivers and a usable wireless control plane. +This document describes the current Wi-Fi state in Red Bear OS and the path from the existing +bounded Intel bring-up scaffold to validated wireless connectivity. -The goal is not to imply that working Wi-Fi already exists. The goal is to describe what the repo -currently proves, what `linux-kpi` can and cannot realistically provide, and how Red Bear can grow -from a **bounded experimental Intel Wi-Fi scaffold** to one experimental, validated Wi-Fi path that -fits the existing Redox / Red Bear architecture. +Wi-Fi is currently **not working connectivity**. What exists is a structurally complete, +host-tested Intel transport layer and native control plane, awaiting real hardware + firmware +validation. ## Validation States -- **builds** β€” code exists in-tree and is expected to compile -- **boots** β€” image or service path reaches a usable runtime state -- **reports** β€” runtime surfaces can honestly report current wireless state -- **validated** β€” behavior has been exercised with real evidence for the claimed scope -- **experimental** β€” available for bring-up, but not support-promised -- **missing** β€” no in-tree implementation path is currently present +| State | Meaning | +|---|---| +| **builds** | Compiles in-tree | +| **host-tested** | Tests pass on Linux host with synthesized fixtures | +| **validated** | Behavior confirmed with real hardware evidence | +| **experimental** | Available for bring-up, not support-promised | +| **missing** | No in-tree implementation | -This repo should not treat planned wireless scope as equivalent to implemented support. +## Current State -## Current Repo State +### Status Matrix -### Summary - -Wi-Fi is currently **not supported as working connectivity** in Red Bear OS. - -There is still no complete in-tree cfg80211/mac80211/nl80211-compatible surface, no supplicant -path, and no profile that can honestly claim working Wi-Fi support. What now exists in-tree is a -bounded Intel bring-up slice: a driver-side package, a Wi-Fi control daemon/scheme, profile -plumbing, and host-validated LinuxKPI/CLI scaffolding below the real association boundary. - -What the repo *does* have is a meaningful set of prerequisites: - -- userspace drivers and schemes as the standard architectural model -- `redox-driver-sys` for PCI/MMIO/IRQ/DMA primitives -- `linux-kpi` as a limited low-level C-driver compatibility layer -- `firmware-loader` for blob-backed devices -- a working native wired network path through `network.*`, `smolnetd`, `dhcpd`, and `netcfg` -- profile/package-group discipline, including the reserved `net-wifi-experimental` slice - -### Current Status Matrix - -| Area | State | Notes | +| Area | State | Detail | |---|---|---| -| Wi-Fi controller support | **experimental bounded slice exists** | `redbear-iwlwifi` provides an Intel-only bounded driver-side package, not validated Wi-Fi connectivity | -| Linux wireless stack compatibility | **early compatibility scaffolding exists** | `linux-kpi` now carries `cfg80211` / `wiphy` / `mac80211` registration, station-mode scaffolding, channel/band/rate/BSS definitions, and RX/TX data-path structures (24 tests pass), but not a complete Linux wireless stack | -| Firmware loading | **partial prerequisite exists** | `firmware-loader` can serve firmware blobs generically | -| Wireless control plane | **experimental bounded slice exists** | `redbear-wifictl` and `redbear-netctl` expose bounded prepare/init/activate/scan orchestration, not real association support | -| Post-association IP path | **present** | Native `smolnetd` / `netcfg` / `dhcpd` / `redbear-netctl` path exists | -| Desktop Wi-Fi API | **missing** | No NetworkManager-like or D-Bus Wi-Fi surface | -| Runtime diagnostics | **experimental bounded slice exists** | `redbear-info` and runtime helpers expose Wi-Fi state surfaces, but not real Wi-Fi functionality proof | - -## Evidence Already In Tree - -### Direct current-state caution about supported connectivity - -- `HARDWARE.md` says broad Wi-Fi and Bluetooth hardware support is still incomplete even though - bounded in-tree scaffolding now exists -- `local/docs/AMD-FIRST-INTEGRATION.md` now treats `Wi-Fi/BT` as in progress with bounded wireless - scaffolding present but validated connectivity still incomplete - -### Positive driver-side prerequisites - -- `docs/04-LINUX-DRIVER-COMPAT.md` documents `redox-driver-sys`, `linux-kpi`, and - `firmware-loader` -- `local/recipes/drivers/redox-driver-sys/` provides userspace PCI/MMIO/IRQ/DMA primitives -- `local/recipes/drivers/linux-kpi/` provides a limited Linux-style compatibility subset -- `local/recipes/system/firmware-loader/` provides `scheme:firmware` - -### Positive network/control-plane prerequisites - -- `local/docs/NETWORKING-RTL8125-NETCTL.md` documents the native wired path: - `pcid-spawner` β†’ NIC daemon β†’ `network.*` β†’ `smolnetd` β†’ `dhcpd` / `netcfg` -- `recipes/core/base/source/netstack/src/scheme/netcfg/mod.rs` shows route/address/resolver state - is already exposed through a native control scheme -- `local/recipes/system/redbear-netctl/source/src/main.rs` shows Red Bear already uses a native - network profile tool, even though it is currently wired-only -- `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` reserves `net-wifi-experimental` as a package-group - slot for future wireless work - -## Feasibility Constraints - -### 1. Wi-Fi is not just a driver - -Wi-Fi in Red Bear cannot be treated as a single hardware daemon. - -At minimum, a working Wi-Fi path needs: - -- hardware transport and firmware bring-up -- scan/discovery -- authentication and association state -- link-state and disconnect handling -- credential storage -- post-association handoff into the native IP stack -- later desktop/user-facing integration if the repo wants it - -This makes Wi-Fi more like a complete subsystem than a simple wired NIC driver. - -### 2. `linux-kpi` is feasible only below the wireless control-plane boundary - -Current `linux-kpi` is suitable for low-level driver-enablement work such as: - -- PCI / IRQ / DMA / MMIO access -- firmware request glue -- workqueue-style helper logic -- C-driver compatibility for narrow hardware bring-up - -Current `linux-kpi` is **not** a complete Wi-Fi architecture because the repo still has no in-tree, -complete: - -- cfg80211 -- mac80211 -- nl80211 -- wiphy model -- supplicant/control-plane compatibility layer - -So `linux-kpi` is feasible only as a **partial low-level aid**, not as the primary Red Bear Wi-Fi -stack. - -### 3. The current Red Bear control plane is Ethernet-specific - -The current native network stack is useful, but not yet Wi-Fi-ready. - -`redbear-netctl` now has a first Wi-Fi-facing profile layer, but only at the profile/orchestration -boundary. - -Current `redbear-netctl` support now includes: - -- `Connection=ethernet` -- `Connection=wifi` -- arbitrary `Interface=` values at the profile layer (for example `eth0`, `wlan0`) -- DHCP/static address, route, and DNS control after association -- Wi-Fi profile fields for `SSID`, `Security`, and `Key`/`Passphrase` -- a bounded native handoff to a future `/scheme/wifictl` control surface - -The repo now also contains the first bounded implementation of that control surface: - -- `local/recipes/system/redbear-wifictl/` provides a `redbear-wifictl` daemon and `/scheme/wifictl` - scheme -- the current daemon supports a stub backend for end-to-end validation and an Intel-oriented backend - boundary that detects Intel wireless-class PCI devices -- the current Intel backend is now firmware-aware: it reports candidate firmware families, selected - firmware blobs when present, and supports a bounded `prepare` step before connect -- this is still not a full Intel association path, but it turns the control-plane contract into a - real in-tree interface rather than a placeholder - -This means `redbear-netctl` can now represent and start a Wi-Fi profile without pretending Wi-Fi is -just an Ethernet profile, but it still does **not** own scan/auth/association itself. - -`netcfg` is no longer hard-wired to a single `eth0` node in the control scheme. The native control -surface can now expose per-device interface nodes dynamically from the current device list, which is -the first required step for post-association Wi-Fi handoff. - -That means Red Bear can reuse its native IP plumbing **after association**, but not as the radio -control plane itself. - -### 4. Intel target changes the first-driver strategy - -The original version of this plan preferred a FullMAC-first path to avoid recreating Linux wireless -subsystem boundaries. - -That is still the simplest architecture in the abstract, but the project target has now changed: -Red Bear must target **Intel Wi-Fi for Arrow Lake and older Intel client chips**. - -That means the first realistic driver family is now Intel `iwlwifi`-class hardware rather than an -unspecified FullMAC family. - -This changes the implementation burden materially: - -- Intel `iwlwifi` is not a simple FullMAC path -- current Linux support is tightly coupled to `mac80211` / `cfg80211` -- firmware loading remains necessary but is not the hard part by itself -- Red Bear must plan for a bounded compatibility layer below the user-facing control plane - -So the practical first target is now: - -- **Intel `iwlwifi`-class devices, Arrow Lake and older**, with the understanding that this is a - harder first driver family than a generic FullMAC-first strategy would have been - -## Recommended Architecture - -The best current Red Bear Wi-Fi architecture for the Intel target is: - -1. **native Red Bear wireless control plane above the driver boundary** -2. **Intel-first low-level driver work below that boundary** -3. **reuse `firmware-loader` and `redox-driver-sys` wherever possible** -4. **accept bounded `linux-kpi` growth where Intel transport/firmware glue requires it** - -### Build-note for the current Intel control-plane code - -The earlier Redox-target source-level compile failure in `redbear-wifictl`'s Intel backend is now -fixed in-tree. If `cargo build --target x86_64-unknown-redox` still reports that -`x86_64-unknown-redox-gcc` is missing, check whether the repo-provided cross toolchain under -`prefix/x86_64-unknown-redox/sysroot/bin/` is on `PATH` before treating it as a fresh source-level -regression. - -For repeatable local builds, use `local/scripts/build-redbear-wifictl-redox.sh`, which wires that -repo-provided toolchain path into the build invocation explicitly. -5. **reuse the existing native IP path only after association** - -This is still a native-first architecture at the control-plane level, but it is no longer a pure -FullMAC-first plan. - -### Subsystem boundary - -The Wi-Fi subsystem should be split into these pieces: - -- one **device transport / driver daemon** for the Intel target family -- one **firmware loading path** via `firmware-loader` -- one **Wi-Fi control daemon** for scan/auth/association/link state -- one **user-facing control tool** (`wifictl` or equivalent) -- one **post-association handoff** into `smolnetd` / `netcfg` / `dhcpd` -- one **later desktop shim** only if KDE/user-facing workflows require it - -`redbear-netctl` should **not** become the supplicant. It can own profile orchestration and the -post-association IP handoff, but scan/auth/association should still live in a dedicated Wi-Fi -control daemon or scheme. - -The current implementation now matches that boundary more closely: - -- `redbear-netctl` can parse Wi-Fi profiles and hand credentials/intent to a native Wi-Fi control - surface (`/scheme/wifictl`) -- `redbear-netctl` now also has a host-side CLI proof that starting a Wi-Fi profile drives the - bounded driver/control actions and preserves the surfaced bounded connect metadata in status - output; this is not yet proof of verified prepare/init/activate/connect execution order on a real - associated link -- `redbear-netctl` stop now also drives the bounded disconnect path, so the current profile-manager - slice covers start and stop instead of start-only behavior -- `redbear-wifictl` now exposes bounded connect and disconnect CLI flows, and the runtime checker - now exercises the bounded connect step through the scheme surface -- the native IP path can address a non-`eth0` interface name after association -- `redbear-netctl` now also performs interface-specific DHCP handoff for Wi-Fi profiles and waits - for the selected interface to receive an address in the bounded host/runtime validation path -- `local/recipes/system/redbear-netctl-console/` now adds a terminal UI client on top of the same - `/scheme/wifictl` + `/etc/netctl` contract, so scan/select/edit/save/connect/disconnect workflows - can be exercised without introducing a new daemon or bypassing profile semantics -- `local/scripts/test-wifi-baremetal-runtime.sh` now provides the strongest in-repo runtime - validation path for this Wi-Fi slice on a real Red Bear OS target: driver probe, control probe, - bounded connect/disconnect, profile start/stop, and `redbear-info --json` lifecycle reporting -- `redbear-phase5-wifi-check` now packages that bounded in-target validation flow as a first-class - guest/runtime command, instead of leaving it only as a shell script -- that packaged runtime proof currently defaults to the bounded open-profile path; WPA2-PSK remains - implemented and host/unit-verified elsewhere in-repo rather than equally packaged/runtime-validated -- `redbear-phase5-wifi-capture` now packages the corresponding runtime evidence bundle, so target - runs can produce a single JSON artifact for debugging real hardware/passthrough failures; - that bundle now includes command outputs, Wi-Fi scheme state, `netctl` profile state, active - profile contents, interface listings, and `lspci` output -- `test-wifi-baremetal-runtime.sh` now writes that capture bundle to `/tmp/redbear-phase5-wifi-capture.json` - as part of the target-side bounded validation flow -- `local/scripts/test-wifi-passthrough-qemu.sh` now provides the corresponding VFIO/QEMU harness for - exercising the same bounded runtime path when an Intel Wi-Fi PCI function can be passed through to - a Red Bear guest, including optional host-side extraction of the packaged Wi-Fi capture bundle -- `local/scripts/prepare-wifi-vfio.sh` now provides the matching host-side bind/unbind helper for - moving an Intel Wi-Fi PCI function onto `vfio-pci` before passthrough validation and restoring it - afterwards -- `local/scripts/run-wifi-passthrough-validation.sh` now wraps the whole host-side passthrough flow: - bind to `vfio-pci`, run the packaged in-guest Wi-Fi validation path, collect the host-visible - capture bundle, and restore the original host driver afterwards -- `local/scripts/validate-wifi-vfio-host.sh` now provides a read-only preflight for the same flow: - PCI presence, current binding, UEFI firmware, image availability, QEMU/expect presence, VFIO - module state, and visible IOMMU groups -- `local/docs/WIFI-VALIDATION-RUNBOOK.md` now ties the bare-metal path, VFIO path, packaged - validators, and capture artifacts together into one operator runbook -- the control daemon exists now, and the first bounded driver-side package now exists as - `local/recipes/drivers/redbear-iwlwifi/` -- `redbear-iwlwifi` now supports bounded `--probe` and `--prepare` driver-side actions for the - current Intel family set -- `redbear-iwlwifi` now also supports bounded `--init-transport` and `--activate-nic` actions for - the current Intel family set -- `redbear-iwlwifi` now also supports bounded `--scan` and `--retry` actions for the current Intel - family set -- `redbear-iwlwifi` now also carries a first bounded `--connect` path that runs through the new - LinuxKPI wireless compatibility scaffolding instead of stopping immediately at a hardcoded - transport/association error -- `redbear-iwlwifi` now also carries a bounded `--disconnect` path so the current station-mode - lifecycle is not connect-only anymore -- `redbear-iwlwifi --status` now reports the current bounded driver-side view directly -- the bounded driver-side action set can be exercised through the dedicated helper script - `local/scripts/test-iwlwifi-driver-runtime.sh` -- on Redox targets, `redbear-iwlwifi` now also begins to use a `linux-kpi` C shim for firmware - request and PCI/MMIO-facing prepare/transport actions instead of keeping those paths purely in - Rust fallback code - -### Port vs rewrite decision - -For Arrow Lake-and-lower Intel Wi‑Fi, the current repo direction is: - -- **do not** attempt a full Linux `mac80211` / `cfg80211` / `nl80211` port first, -- **do** create a bounded Intel driver/transport package below the native Red Bear Wi‑Fi control - plane, -- **do** accept limited `linux-kpi` growth only where it materially reduces transport/firmware glue - cost, -- keep `redbear-netctl` and `redbear-wifictl` as the native control-plane/user-facing layers above - that driver boundary. - -That means the repo is now following a **bounded transport-layer port with native control-plane -rewrite above it**, not a full Linux wireless stack port and not a pure greenfield driver rewrite. - -### What this means in practical porting terms - -The currently feasible interpretation of β€œuse the real Linux Intel driver through `linux-kpi`” is: - -- port and reuse **transport-layer and firmware-facing logic** where that lowers cost materially, -- keep the **native Red Bear control plane** above that boundary, -- and avoid treating a full `cfg80211` / `mac80211` / `nl80211` / `wiphy` port as the immediate - first milestone. - -In other words, Red Bear should not try to import the whole Linux wireless stack in one step. -Red Bear should instead pull over the **device-facing part** of the Intel stack in bounded layers. - -### Boundary where `linux-kpi` is helpful - -`linux-kpi` is most useful for: - -- PCI helper semantics -- MMIO/IRQ/DMA glue -- firmware request/load glue -- workqueue-style deferred execution -- timer, mutex, and IRQ-critical-section helpers that transport-facing Linux Wi-Fi code expects -- low-level transport and reset sequences -- early packet-buffer / `net_device` / `wiphy` / registration scaffolding when Red Bear begins the - first real Linux wireless-subsystem compatibility slice - -That is the boundary where β€œrun Linux driver code on Red Bear” is currently realistic. - -The current tree now has the first explicit step in that direction as well: - -- `linux-kpi` now carries initial `sk_buff`, `net_device`, `cfg80211`/`wiphy`, and `mac80211` - registration scaffolding alongside the earlier firmware/timer/mutex/IRQ helpers -- that scaffolding now also includes the first station-mode compatibility types and hooks used by - the bounded Intel scan/connect path: SSID/connect/station parameter structs plus basic - `cfg80211_connect_bss` / ready-on-channel and `mac80211` VIF/STA/BSS-conf surfaces -- the bounded station-mode slice now also preserves real private-allocation sizes, exposes the - common `sk_buff` reserve/push/pull/headroom/tailroom helpers, tracks `net_device` - registration/setup, keeps carrier down until connect success, and routes - `ieee80211_queue_work()` through the bounded LinuxKPI workqueue instead of silently dropping - deferred work -- the wireless scaffolding now also includes channel/band/rate definitions - (`Ieee80211Channel`, `Ieee80211Rate`, `Ieee80211SupportedBand` with NL80211 band constants - and IEEE80211 channel/rate flags), BSS information reporting (`Cfg80211Bss`, - `cfg80211_inform_bss`/`get_bss`/`put_bss`), RX/TX data-path structures (`Ieee80211RxStatus`, - `Ieee80211TxInfo` with RX/TX flag constants, `ieee80211_rx_irqsafe`/`tx_status`), - channel definition creation (`ieee80211_chandef_create`), and STA state-transition constants - (`IEEE80211_STA_NOTEXIST` through `IEEE80211_STA_AUTHORIZED`) -- all scaffolding is compile- and host-test-validated inside the `linux-kpi` crate (24 tests pass) -- this is still **not** a claim that Red Bear now has a working Linux wireless stack - -### Boundary where a full Linux port becomes too expensive - -A full Linux-style `iwlwifi` port becomes dramatically more expensive as soon as the code path -depends on the Linux wireless subsystem proper: - -- `cfg80211` -- `mac80211` -- `nl80211` -- `wiphy` model and callbacks -- Linux regulatory integration -- Linux station/BSS bookkeeping and userspace-facing wireless semantics - -The repo now has the earliest pieces of those subsystem layers, but still not anything close to a -complete Linux wireless stack. Building them out far enough to host Intel Wi‑Fi as a true Linux-like -solution still turns the effort from a bounded driver port into a much larger compatibility-stack -port. - -### Chosen direction - -The chosen direction for Arrow Lake-and-lower Intel Wi‑Fi is therefore: - -1. keep the **native Red Bear control plane** (`redbear-netctl` + `redbear-wifictl`), -2. keep pushing the **hardware-facing Intel path** down into `redbear-iwlwifi`, -3. use `linux-kpi` for the low-level Linux-facing transport/runtime glue where that reduces effort, -4. avoid promising or attempting a full Linux wireless-stack port as the first milestone. - -The current code now matches that decision more closely than before: `redbear-wifictl` remains the -native control plane, while `redbear-iwlwifi` is the place where Linux-facing firmware/PCI/MMIO -driver logic is starting to accumulate. - -The current tree also now pushes more of that bounded Intel path through the actual LinuxKPI -surface instead of bespoke C declarations alone: - -- `linux-kpi` now exports direct and async firmware request helpers for firmware-family workflows -- timer and IRQ save/restore bindings are exported through the Linux-facing headers instead of - remaining header-only stubs -- `mutex_trylock()` is available to transport-facing code that needs bounded serialization without - pretending the full Linux scheduler model exists -- the current `redbear-iwlwifi` C transport shim now includes the LinuxKPI headers directly and - uses Linux-style firmware, timer, mutex, and IRQ helper entry points for prepare/probe/init/ - activate steps - -This remains a bounded transport-layer port. It does **not** change the rule that cfg80211/ -mac80211/nl80211 remain out of scope for the current milestone. - -### Current validation status for this bounded LinuxKPI slice - -The current validation story for this slice is intentionally narrow and should be described that -way: - -- the `linux-kpi` host-side test suite now runs cleanly in this repo (24 tests pass), including - the Wi‑Fi-facing helper changes in this slice: `request_firmware_direct`, - `request_firmware_nowait`, `mutex_trylock`, IRQ-depth tracking, variable private-allocation - lifetime tracking, station-mode scan/connect/disconnect lifecycle assertions, - workqueue-backed `ieee80211_queue_work()`, `sk_buff` headroom/tailroom helpers, channel/band - creation and flag tests, RX status default and flag combination tests, `ieee80211_get_tid` null - safety, and the existing memory tests -- `redbear-iwlwifi` host-side tests now smoke-test the bounded firmware/transport/activation/scan/ - retry actions used by the current Intel path -- `redbear-iwlwifi` also now has a binary-level host-side CLI smoke test for the current bounded - Intel path against temporary PCI/firmware fixtures; this is not the same as a chained real-target - transportβ†’activationβ†’association proof -- `redbear-wifictl` host-side tests pass for the bounded control-plane state propagation above that - Intel path -- the packaged target-side Wi-Fi validators now also accept bounded `status=associating`/ - pending-connect output, so the in-target/runtime checks stay aligned with the current honest - connect semantics instead of requiring a fake associated/connected result -- the default packaged bounded runtime profile is now `wifi-open-bounded`, separating lifecycle - validation from the later DHCP-on-real-association gate - -This does **not** mean Red Bear has validated a full Linux Wi‑Fi driver stack. The validated claim -is narrower: this repo now has tested, bounded LinuxKPI support for the current Intel transport- -facing helper slice, plus host-tested bounded CLI/control flows above it. Current bounded connect -results should still be read as pending/experimental lifecycle state, not proof of real AP -association. - -In the current host environment used for this hardening pass, the Intel-specific VFIO runtime path -also remains blocked by prerequisites outside the repo changes themselves: the host validator sees a -MediaTek MT7921K (`14c3:0608`) instead of an Intel `iwlwifi` device on the available Wi‑Fi slot, -and `vfio_pci` is not loaded. That means the repo-side bounded runtime harness is present and the -Red Bear image/QEMU/OVMF/`expect` prerequisites are available, but a literal Intel passthrough run -still requires compatible host hardware and VFIO binding before it can be executed. - -That is the current feasibility conclusion grounded in the codebase. +| Intel PCIe transport | **builds, host-tested** | `redbear-iwlwifi`: ~2450 lines C transport + ~1550 lines Rust CLI. Real 802.11 RX frame parsing, DMA ring management, TX reclaim, ISR/tasklet dispatch, command response parsing, mac80211 ops, station state transitions, key management. Commands time out without real firmware β€” by design. | +| LinuxKPI compatibility | **builds, host-tested** | `linux-kpi`: 17 Rust modules, 93 tests. cfg80211/wiphy/mac80211 registration, ieee80211_ops 12-callback dispatch, PCI MSI/MSI-X, DMA pool, sk_buff, NAPI poll, list_head, atomic_t, completion, IO barriers, BSS/channel/band/rate, scan/connect/disconnect events, BSS registry with reference release. | +| IRQ dispatch | **builds, host-tested** | `request_irq`/`free_irq`/`disable_irq`/`enable_irq` fully implemented with real `scheme:irq/{}` integration, thread-based dispatch, and mask/unmask support. | +| Test coverage | **119 tests pass** | 93 linux-kpi + 8 redbear-iwlwifi + 18 redbear-wifictl. No production `unwrap()` in Wi-Fi daemon request loop (startup uses `expect()`). Host-tested; Redox-only C transport paths are compile-tested but not directly exercised by host tests. | +| Firmware loading | **partial** | `firmware-loader` can serve blobs generically. | +| Control plane | **host-tested** | `redbear-wifictl` daemon + `/scheme/wifictl` scheme with stub and Intel backends, state-machine enforcement, firmware-family reporting. Daemon request loop has graceful shutdown on socket errors. | +| Profile orchestration | **host-tested** | `redbear-netctl` Wi-Fi profiles (SSID/Security/Key), bounded prepareβ†’init-transportβ†’activate-nicβ†’connectβ†’disconnect flow, DHCP handoff. | +| Runtime diagnostics | **host-tested** | `redbear-info` Wi-Fi surfaces, packaged validators (`redbear-phase5-wifi-check/run/capture/analyze`). | +| Real hardware validation | **missing** | No Intel Wi-Fi device has been exercised. Transport is structurally correct but functionally unproven. | +| Desktop Wi-Fi API | **missing** | No NetworkManager-like or D-Bus Wi-Fi surface. | + +### Transport Quality (from hardening pass) + +The iwlwifi transport has been hardened with these specific improvements: + +- **Atomic command state**: `command_complete`, `last_cmd_id`, `last_cmd_cookie`, `last_cmd_status` use `__atomic_store_n`/`__atomic_load_n` with `__ATOMIC_SEQ_CST` β€” no torn reads between ISR and command submission. +- **Stale response sentinel** (0xFFFF): After command timeout, the response fields are poisoned so a late-arriving firmware response cannot be misattributed to the next command. +- **Command queue space management**: `iwl_pcie_send_cmd` reclaims completed TX descriptors before submitting each command. If the command queue is still full after reclaim, the command fails immediately rather than entering the overflow queue β€” commands are synchronous and one-at-a-time, so overflow queuing would create ownership ambiguity. +- **DMA read barrier**: `rmb()` added after `dma_sync_single_for_cpu()` and before parsing RX frame data β€” ensures correct ordering on weakly-ordered architectures. +- **TX queue selection safety**: `rb_iwlwifi_choose_txq()` returns -1 when no data queue is active instead of falling back to the command queue β€” data frames never use the command queue. +- **TX error handling**: `iwl_ops_tx` now properly frees the skb on failure and logs warnings instead of silently swallowing errors. +- **Association BSSID guard**: BSSID from association-response frames is only copied to transport state when `trans->connecting` is set β€” prevents stale frames from corrupting connection state. +- **TXQ stuck detection fix**: Removed `trans->irq <= 0` from stuck detection β€” queue stuckness is independent of IRQ allocation state. +- **RX drain**: Parses 802.11 frame_control type/subtype before freeing β€” distinguishes data, management, and control frames instead of blind disposal. +- **RX restock**: Write pointer pushed to hardware in both restock and start_dma paths β€” prevents DMA ring starvation. +- **TX reclaim**: Full DMA unmap cycle β€” no leaked mappings. +- **BSS registry cleanup**: `cfg80211_put_bss()` now removes entries from the BSS registry and cleans up associated IEs β€” no memory leak on repeated scans. + +### LinuxKPI Compat Layer Improvements + +The linux-kpi compatibility layer has been enhanced with real frame delivery and statistics: + +- **RX callback mechanism**: `ieee80211_register_rx_handler(hw, callback)` registers a per-hw + callback that receives drained RX frames. When `ieee80211_rx_drain` processes queued frames, + it delivers them to the registered callback instead of logging and freeing. This allows the + upper layer (e.g., a Redox wireless daemon) to consume frames in real time. +- **TX statistics tracking**: `ieee80211_get_tx_stats(hw)` returns per-hw TX completion counters + (total, acked, nacked). `ieee80211_tx_status` increments these on every TX completion. +- **Full frame data in cfg80211 events**: `cfg80211_rx_mgmt` now stores complete frame data (not + just metadata) in the wireless event state, enabling later consumption by the native wireless + stack. `cfg80211_mgmt_tx_status` similarly stores full TX frame data. +- **IRQ dispatch confirmed real**: `request_irq`/`free_irq`/`disable_irq`/`enable_irq` use real + `scheme:irq/{}` integration with thread-based dispatch and mask/unmask support β€” not stubs. +- **119 tests pass**: 93 linux-kpi + 8 redbear-iwlwifi + 18 redbear-wifictl. + +### Honest Assessment + +Without real hardware + firmware: +- Command submission times out (no firmware alive response) +- Scan returns no results (no firmware scan response) +- Association does not complete +- RX frames are never processed + +The code reports these states honestly (timeout, no results) rather than fabricating success. +Hardware runtime validation is the required next gate. + +## Architecture + +### Subsystem Boundaries + +``` +User-facing + redbear-netctl (profiles, CLI) + redbear-netctl-console (ncurses TUI) + β”‚ + β–Ό + /scheme/wifictl (redbear-wifictl daemon) + β”‚ scan / auth / association / link state / credentials + β–Ό + redbear-iwlwifi (driver daemon) + β”‚ PCIe transport / firmware / DMA / IRQ + β–Ό + linux-kpi (compatibility glue) + β”‚ PCI / MMIO / IRQ / DMA / sk_buff / mac80211 ops + β–Ό + redox-driver-sys (scheme:memory, scheme:irq, scheme:pci) + β”‚ + firmware-loader (scheme:firmware) + β”‚ +Kernel: scheme-based primitives only + +Post-association IP path: + smolnetd β†’ netcfg β†’ dhcpd β†’ redbear-netctl +``` + +### Key Design Decisions + +1. **Native control plane above the driver** β€” `redbear-wifictl` owns scan/auth/association, not `redbear-netctl`. +2. **Bounded Intel transport port below that boundary** β€” reuse Linux-facing firmware/PCI/MMIO logic where it lowers cost. +3. **No full Linux wireless stack port** β€” cfg80211/mac80211/nl80211 are out of scope for the first milestone. +4. **`redbear-netctl` is the profile manager, not the supplicant** β€” it hands off to `/scheme/wifictl`, which hands off to the driver. + +### Port vs Rewrite + +The chosen approach is a **bounded transport-layer port with native control-plane rewrite above it**: +- Port and reuse transport-layer and firmware-facing logic from Linux `iwlwifi` +- Keep the native Red Bear control plane above that boundary +- Do not import the whole Linux wireless stack in one step ## Hardware Strategy -### Target hardware scope +- **Target**: Intel Wi-Fi chips on Arrow Lake and older Intel client platforms +- **Driver family**: `iwlwifi`-class (7000/8000/9000/AX210/BZ) +- **Security scope**: Open networks + WPA2-PSK only (phase 1) +- **Out of scope**: WPA3, 802.1X, AP mode, roaming, monitor mode, suspend/resume, multi-BSS -The target scope for this plan is now: +## Implementation Phases -- **Intel Wi-Fi chips used on Arrow Lake and older Intel client platforms** +### Phase W0 β€” Scope Freeze βœ… Complete -That includes the practical `iwlwifi` family boundary, not an abstract FullMAC-first family chosen -for architectural neatness. +- Intel target scope frozen +- Security scope frozen (open + WPA2-PSK) +- `redbear-wifi-experimental` config slice defined (`config/redbear-wifi-experimental.toml`) +- Unsupported features documented -### What this means for phase 1 +### Phase W1 β€” Intel Driver Substrate Fit βœ… Complete (build-side) -Phase 1 is no longer β€œpick any convenient Wi-Fi family.” +- Intel device family mapped onto `redox-driver-sys` primitives +- Firmware naming/fetch path wired through `firmware-loader` +- Minimum `linux-kpi` additions identified and implemented (93 tests) +- All additions stay below the wireless control-plane boundary -Phase 1 is now: +**Exit criteria met (build-side)**: Intel target device can be discovered, initialized, and paired +with its firmware-loading path β€” in compiled/host-tested code. Real hardware validation still pending. -- prove one bounded Intel client Wi-Fi path, -- keep the support language experimental, -- and avoid promising the entire Linux wireless stack up front. +### Phase W2 β€” Native Wireless Control Plane βœ… Complete (host-tested) -## Security Scope Freeze +- `redbear-wifictl` daemon with `/scheme/wifictl` scheme +- Stub backend for end-to-end control-plane validation +- Intel backend: device detection, firmware-family reporting, transport-readiness, state machine +- `redbear-netctl` Wi-Fi profile support (SSID/Security/Key) +- Bounded prepareβ†’init-transportβ†’activate-nicβ†’scanβ†’connectβ†’disconnect flow +- `redbear-netctl-console` ncurses TUI client -### Phase-1 supported security +**Exit criteria met (host-tested)**: Daemon reports scan results and link state honestly in +host-side tests. Runtime validation pending. -- open networks -- WPA2-PSK +### Phase W3 β€” Network Stack for Post-Association Handoff βœ… Complete (build-side) -### Explicitly out of initial scope +- `netcfg` exposes per-device interface nodes dynamically (not hard-coded `eth0`) +- `redbear-netctl` performs DHCP handoff for Wi-Fi profiles +- Native IP plumbing can consume a post-association Wi-Fi interface -- WPA3 -- 802.1X / enterprise Wi-Fi -- AP mode -- roaming -- monitor mode -- suspend/resume guarantees -- multi-BSS support -- sophisticated regulatory-domain handling +**Exit criteria met (build-side)**: A connected Wi-Fi link can be handed off to the existing IP +path without treating it as raw Ethernet. Runtime validation pending. -This scope freeze is required to keep the first milestone honest and achievable. +### Phase W4 β€” First Association Milestone 🚧 Not started (blocked on hardware) -## Comprehensive Full Plan - -## Current Implementation Progress - -### Already landed in-tree - -The current repo now contains a **bounded Phase W0/W2/W3 slice**: - -- the plan target is explicitly Intel Arrow Lake and older Intel Wi-Fi chips -- `redbear-netctl` now supports Wi‑Fi profiles with `Connection=wifi`, `Interface=...`, `SSID`, - `Security`, and `Key` / `Passphrase` -- `netctl` now performs a bounded `prepare` β†’ `init-transport` β†’ `connect` handoff into - `/scheme/wifictl` -- that user-facing path now also includes a bounded `activate-nic` step before `connect` -- `netctl scan ` now uses the same `prepare` β†’ `init-transport` ordering before the - active `scan` action -- `netcfg` no longer hard-codes a single `eth0` interface node and can expose interfaces from the - current device list dynamically -- `redbear-wifictl` now exists as a real package/daemon/scheme with: - - a stub backend for end-to-end control-plane validation - - an Intel-oriented backend boundary for Arrow Lake-and-lower families - - firmware-family and firmware-presence reporting - - a bounded `prepare` step before `connect` - - transport-readiness reporting derived from PCI command/BAR/IRQ state - - a bounded PCI transport-prep action that enables memory-space and bus-master bits before connect -- a bounded `scan` action with a working stub path and a bounded Intel scan/reporting path rather - than the older explicit `not implemented yet` result - - a bounded `init-transport` state boundary after preparation and before any future association path - - a bounded `activate-nic` state boundary after `init-transport` - - state-machine enforcement so Intel scan/connect refuse to proceed before `init-transport` -- `redbear-info` and the runtime helper scripts now expose the Wi‑Fi control-plane surfaces -- `redbear-info` now reports Wi‑Fi firmware status, transport status, activation status, and scan results from the - primary Wi‑Fi control interface -- `redbear-info` and the runtime helper also now expose `transport-init-status`, which separates - simple transport probing from an actual transport-initialization attempt -- on Redox runtime builds where `/usr/lib/drivers/redbear-iwlwifi` is present **and** at least one - Intel Wi-Fi candidate is actually detectable, `redbear-wifictl` now auto-selects the Intel backend - instead of silently falling back to the stub backend -- if the Intel driver package is present but no Intel Wi-Fi candidate is detected, `redbear-wifictl` - now exposes a dedicated no-device fallback rather than a synthetic stub `wlan0`, so the runtime - does not pretend the Intel path is usable - -### What this means - -This does **not** mean Red Bear has working Intel Wi‑Fi connectivity yet. - -It means the repo now has: - -- a real Wi‑Fi profile model, -- a real Wi‑Fi control-plane daemon and scheme, -- a first dedicated Intel Wi‑Fi driver-side package (`redbear-iwlwifi`), -- a runtime helper for the bounded Intel driver probe path (`local/scripts/test-iwlwifi-driver-runtime.sh`), -- a runtime check that the Wi‑Fi control daemon selects the Intel backend only when Intel Wi‑Fi - candidates are actually present, -- a native post-association IP handoff path that can address non-`eth0` interfaces, -- and a firmware-aware, transport-aware Intel backend boundary. -- and a bounded active scan surface. -- and a bounded transport-initialization surface. - -The current bounded implementation is therefore no longer just static plumbing. It now has a real -user-facing Wi‑Fi orchestration flow through `netctl`, a real control daemon state machine, and a -real Intel-targeted firmware/transport preparation boundary. - -That is the first substantial Wi‑Fi bring-up slice, but not the final result. - -### Still missing after the current slice - -- real Intel transport initialization -- actual firmware loading/prepare action on Redox target hardware -- scan implementation against real hardware -- authentication and association -- WPA2 key negotiation on a real link -- DHCP/static IP handoff on a real associated wireless interface -- runtime validation on Intel hardware or a realistic guest path - -### Phase W0 β€” Scope Freeze and Package-Group Definition - -**Goal**: Define the first Wi-Fi milestone precisely before implementation starts. +**Goal**: One real Wi-Fi connection under phase-1 scope. **What to do**: +1. Obtain an Intel Wi-Fi device (iwlwifi-class) for bare-metal or VFIO passthrough testing +2. Boot Red Bear on hardware with the Intel Wi-Fi PCI function visible +3. Verify firmware loads via `firmware-loader` +4. Verify transport init succeeds (command queue alive, firmware responds) +5. Scan for one real SSID +6. Join one test network (open or WPA2-PSK) +7. Hand off to DHCP or static IP +8. Confirm bidirectional connectivity -- freeze the target scope to Intel Arrow Lake and older Intel Wi-Fi chips -- freeze security scope to open + WPA2-PSK -- define `net-wifi-experimental` as the package/config slice for first Wi-Fi support -- document unsupported wireless features explicitly +**Exit criteria**: One Intel device family reaches usable network connectivity on a real network. -**Exit criteria**: +**Prerequisites**: +- Intel Wi-Fi PCI device available for testing +- `low-level controller` / IRQ quality validated (current blocker chain) +- Firmware blobs for the target device family -- Intel target scope is explicit -- support language and non-goals are written down -- the repo has a standalone tracked Wi-Fi experimental profile (`config/redbear-wifi-experimental.toml`) extending the minimal Red Bear baseline +### Phase W5 β€” Runtime Reporting and Recovery (After W4) ---- +- Extend `redbear-info` with real Wi-Fi runtime evidence (not just bounded surfaces) +- Reconnect after disconnect +- Failure-state reporting and retry +- `redbear-phase5-wifi-check/run/capture/analyze` validated against real hardware -### Phase W1 β€” Intel Driver Substrate Fit - -**Goal**: Prove the Intel target family can fit Red Bear’s existing driver primitives and identify -the minimum additional compatibility surface required. - -**What to do**: - -- map the Intel target family onto `redox-driver-sys` -- verify firmware naming and fetch path through `firmware-loader` -- identify exactly which `linux-kpi` additions are mandatory for Intel transport/firmware bring-up -- keep those additions below the wireless control-plane boundary - -**Exit criteria**: - -- one Intel target device can be discovered, initialized, and paired with its firmware-loading path - ---- - -### Phase W2 β€” Native Wireless Control Plane - -**Goal**: Add a Red Bear-native wireless daemon and control interface. - -**What to do**: - -- implement a Wi-Fi daemon that owns: - - scan state - - auth/association state - - link state - - disconnect/retry behavior - - credential ownership -- add a user-facing `wifictl`-style control surface - -**What not to do**: - -- do not push supplicant logic into `redbear-netctl` -- do not model Wi-Fi as β€œjust another Ethernet profile” at this phase - -**Exit criteria**: - -- the daemon can report scan results and current link state honestly - ---- - -### Phase W3 β€” Network Stack Refactor for Post-Association Handoff - -**Goal**: Make the native IP stack accept Wi-Fi as a first-class post-association interface. - -**What to do**: - -- generalize current `eth0` / Ethernet assumptions where needed -- allow the native stack to consume a post-association Wi-Fi interface state -- keep route/address/DNS handling in native `netcfg` / `smolnetd` plumbing after association - -**Exit criteria**: - -- a connected Wi-Fi link can be handed off to the existing IP path without pretending it is merely a - raw Ethernet control-plane object - ---- - -### Phase W4 β€” First Association Milestone - -**Goal**: Achieve one real Wi-Fi connection under the frozen phase-1 scope. - -**What to do**: - -- scan for one real SSID -- join one test network -- complete open or WPA2-PSK association -- hand off to DHCP or static IP configuration - -**Exit criteria**: - -- one chosen device family reaches usable network connectivity on a real network - ---- - -### Phase W5 β€” Runtime Reporting and Recovery - -**Goal**: Make Wi-Fi support diagnosable and honest. - -**What to do**: - -- extend `redbear-info` with Wi-Fi-specific runtime reporting -- add reconnect and failure-state reporting -- keep all support labels experimental - -**Exit criteria**: - -- users can see whether hardware is present, firmware is loaded, scans succeed, and association has - succeeded or failed - ---- +**Exit criteria**: Users can see whether hardware is present, firmware is loaded, scans succeed, +and association has succeeded or failed β€” backed by real hardware evidence. ### Phase W6 β€” Desktop Compatibility (Later) -**Goal**: Add desktop-oriented control only after native Wi-Fi works. +- If KDE or desktop workflows require it, add a compatibility shim over the native Wi-Fi service +- Keep the shim above the native control plane, not in place of it -**What to do**: +### Phase W7 β€” Broader Hardware Reassessment (Later) -- if KDE or desktop workflows require it, add a small compatibility shim over the native Wi-Fi - service -- keep that shim above the native control plane, not in place of it - -**Exit criteria**: - -- desktop Wi-Fi workflows become possible without changing the native subsystem boundaries - ---- - -### Phase W7 β€” Broader Hardware and `linux-kpi` Reassessment - -**Goal**: Reassess whether Red Bear wants to widen Wi‑Fi support after one bounded Intel path works. - -**What to do**: - -- only after one bounded Intel transport/association path is validated, decide whether a wider - multi-family or deeper `linux-kpi` path is worth the cost -- do not assume this is automatically justified - -**Exit criteria**: - -- Red Bear either keeps the narrow native-first architecture, or consciously chooses a larger Linux - wireless-compat effort with full awareness of the cost +- After one bounded Intel path is validated, reassess whether wider multi-family or deeper + `linux-kpi` growth is justified +- Do not assume this is automatically warranted ## Validation Gates -Wi-Fi should not be described as supported until these gates are passed in order: +Wi-Fi should not be described as supported until these gates pass in order: -1. hardware is detected -2. firmware loads successfully -3. the driver/daemon initializes and reports link state -4. scan sees a real SSID -5. association succeeds for one supported network type -6. DHCP or static IP handoff succeeds through the native network stack -7. reconnect works after disconnect or reboot -8. `redbear-info` and profile docs report supported and unsupported states honestly +1. βœ… Hardware detected via PCI scheme +2. 🚧 Firmware loads successfully +3. 🚧 Driver/daemon initializes and reports link state +4. 🚧 Scan sees a real SSID +5. 🚧 Association succeeds for one supported network type +6. 🚧 DHCP or static IP handoff succeeds +7. 🚧 Reconnect works after disconnect or reboot +8. 🚧 `redbear-info` reports all states honestly with real evidence -Until then, support language should remain under `net-wifi-experimental` only. +Until all gates pass, support language stays under `redbear-wifi-experimental`. -## Support-Language Guidance +## Current Blockers -Until the validation gates above are passed, Red Bear should use language such as: +1. **No Intel Wi-Fi hardware available for testing** β€” the current host has a MediaTek MT7921K + (`14c3:0608`), not an Intel `iwlwifi` device +2. **Low-level controller / IRQ quality** β€” must be validated before driver bring-up is reliable +3. **VFIO not loaded on current host** β€” passthrough path requires `vfio_pci` module and compatible IOMMU groups -- β€œWi-Fi is not supported yet” -- β€œWi-Fi remains experimental and hardware-specific” -- β€œThe current wireless path is an experimental Intel bounded-transport bring-up” +## Scripts and Validation Tools -Avoid language such as: +| Script | Purpose | +|---|---| +| `test-iwlwifi-driver-runtime.sh` | Bounded Intel driver lifecycle check in target runtime | +| `test-wifi-control-runtime.sh` | Bounded Wi-Fi control/profile runtime check | +| `test-wifi-baremetal-runtime.sh` | Strongest in-repo Wi-Fi runtime check on real Red Bear target | +| `test-wifi-passthrough-qemu.sh` | QEMU/VFIO Wi-Fi validation with in-guest checks | +| `validate-wifi-vfio-host.sh` | Host-side VFIO passthrough readiness check | +| `prepare-wifi-vfio.sh` | Bind/unbind Intel Wi-Fi PCI function for VFIO | +| `run-wifi-passthrough-validation.sh` | One-shot host wrapper for full passthrough validation | +| `package-wifi-validation-artifacts.sh` | Package validation artifacts into host-side tarball | +| `summarize-wifi-validation-artifacts.sh` | Summarize captured artifacts for quick triage | +| `finalize-wifi-validation-run.sh` | Analyze capture bundle and package final evidence set | -- β€œLinux Wi‑Fi drivers are supported” -- β€œwireless support works” -- β€œWi-Fi is generally available” +Packaged validators (inside target runtime): +- `redbear-phase5-wifi-check` β€” bounded in-target Wi-Fi validation +- `redbear-phase5-wifi-run` β€” run bounded Wi-Fi lifecycle +- `redbear-phase5-wifi-capture` β€” capture runtime evidence bundle +- `redbear-phase5-wifi-analyze` β€” analyze captured evidence +- `redbear-phase5-wifi-link-check` β€” link-level validation -unless profile-scoped validation evidence exists. +## Related Documents + +- `local/docs/WIFI-VALIDATION-RUNBOOK.md` β€” canonical operator runbook for bare-metal and VFIO validation +- `local/docs/WIFI-VALIDATION-ISSUE-TEMPLATE.md` β€” issue template for validation failures +- `local/docs/WIFICTL-SCHEME-REFERENCE.md` β€” `/scheme/wifictl` protocol reference +- `docs/04-LINUX-DRIVER-COMPAT.md` β€” linux-kpi and redox-driver-sys architecture ## Summary The best Red Bear Wi-Fi path is **native-first**: -- native wireless control plane -- one experimental bounded Intel family path first +- Native wireless control plane (`redbear-wifictl` + `redbear-netctl`) +- One experimental Intel family path first (`redbear-iwlwifi`) - `firmware-loader` + `redox-driver-sys` underneath -- optional narrow `linux-kpi` glue only where useful -- native `smolnetd` / `netcfg` / `redbear-netctl` reused only after association +- Narrow `linux-kpi` glue only where useful (93 tests, 17 modules) +- Native `smolnetd` / `netcfg` / `dhcpd` reused after association -`linux-kpi` is therefore **feasible only in a narrow sense**. It is useful as a low-level helper -for driver bring-up, but it is not currently a viable full Wi‑Fi architecture for Red Bear OS. - -That is the most realistic way to integrate Wi‑Fi into Red Bear while keeping the design aligned -with the repo’s current userspace-driver and profile-based architecture. +The codebase has 119 tests passing (93 linux-kpi + 8 redbear-iwlwifi + 18 redbear-wifictl), no production `unwrap()` in the Wi-Fi daemon request loop (startup uses `expect()`), atomic command +handling, proper timer cancellation, honest timeout reporting, and real 802.11 frame parsing. +The structural skeleton is solid. The next required step is **real hardware validation** with an +Intel Wi-Fi device β€” everything else is gated on that.