From ae0ce66b3bf0344cab42087a46f6e7a7daa401b5 Mon Sep 17 00:00:00 2001 From: Vasilito Date: Fri, 17 Apr 2026 13:34:49 +0100 Subject: [PATCH] Refresh project documentation Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus --- AGENTS.md | 7 +++- docs/04-LINUX-DRIVER-COMPAT.md | 4 +- docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md | 3 ++ docs/README.md | 3 +- local/AGENTS.md | 15 ++++++-- local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md | 1 + local/docs/DESKTOP-STACK-CURRENT-STATUS.md | 13 ++++++- local/docs/PROFILE-MATRIX.md | 27 ++++++++++--- local/docs/QT6-PORT-STATUS.md | 45 +++++++++++++++++++--- local/docs/SCRIPT-BEHAVIOR-MATRIX.md | 10 ++--- local/docs/WIFI-IMPLEMENTATION-PLAN.md | 8 +++- local/docs/WIFI-VALIDATION-RUNBOOK.md | 4 ++ 12 files changed, 110 insertions(+), 30 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1d59f823..2703e169 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -70,12 +70,13 @@ redox-master/ | 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 | +| Linux driver compat | `docs/04-LINUX-DRIVER-COMPAT.md` | linux-kpi + redox-driver-sys architecture (**GPU and Wi-Fi only — not USB**) | | 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 | | Display server | Orbital: `recipes/gui/orbital/` | Userspace scheme-based display server | | 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 | +| D-Bus integration | `local/docs/DBUS-INTEGRATION-PLAN.md` | Architecture, gap analysis, phased implementation for KDE Plasma D-Bus | | 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` | @@ -295,10 +296,12 @@ Phase 1 (runtime substrate) → Phase 2 (software compositor) → Phase 3 (KWin ### 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 + 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 +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. **GPU and Wi-Fi drivers only — linux-kpi does NOT cover USB.** It provides PCI, DMA, IRQ, DRM, networking (ieee80211/nl80211/mac80211), firmware, and related kernel infrastructure headers, but contains zero USB headers, USB device ID tables, or USB driver implementations. 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; can query quirks via `pci_has_quirk()` FFI +6. `redbear-sessiond` — `local/recipes/system/redbear-sessiond/source/` — Rust D-Bus session broker exposing `org.freedesktop.login1` subset for KWin (uses `zbus`) +7. `redbear-dbus-services` — `local/recipes/system/redbear-dbus-services/` — D-Bus activation `.service` files and XML policy files for system and session buses All custom work goes in `local/` — see `local/AGENTS.md` for overlay usage. diff --git a/docs/04-LINUX-DRIVER-COMPAT.md b/docs/04-LINUX-DRIVER-COMPAT.md index 1461747c..8ba646f2 100644 --- a/docs/04-LINUX-DRIVER-COMPAT.md +++ b/docs/04-LINUX-DRIVER-COMPAT.md @@ -34,7 +34,7 @@ The tree now also contains comprehensive wireless-subsystem compatibility inside `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 +and IO barrier/copy helpers — all compile- and host-test-validated (93 tests pass). This should still be read as comprehensive compatibility work, not as proof that Red Bear now has working Intel Wi‑Fi connectivity. @@ -59,7 +59,7 @@ 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 (90 tests pass), passing comprehensive PCIe transport tests in the +`linux-kpi` test suite (93 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. diff --git a/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md b/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md index 6d51c193..d4671543 100644 --- a/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md +++ b/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md @@ -333,6 +333,9 @@ Current state: - packaged in-target Wi-Fi validation/capture commands now exist for the current bounded Intel path (`redbear-phase5-wifi-check`, `redbear-phase5-wifi-link-check`, `redbear-phase5-wifi-capture`, `redbear-phase5-wifi-run`, `redbear-phase5-wifi-analyze`), +- the separate `redbear-phase5-network-check` / `test-phase5-network-qemu.sh` path on `redbear-full` + now proves bounded desktop/network plumbing in QEMU and should not be confused with the Wi-Fi + plan's later real-hardware Phase W5 completion criteria, - real hardware scan/auth/association/data-path proof is still missing, - `linux-kpi` is still not the Wi-Fi architecture by itself. diff --git a/docs/README.md b/docs/README.md index 1de2fbe1..e7aaa99e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -102,10 +102,11 @@ This summary is only a quick orientation layer. For canonical current-state deta - **Input**: evdevd compiled, libevdev built, libinput 1.30.2 built - **Networking**: native wired stack present (`pcid-spawner` → NIC daemon → `smolnetd`/`dhcpd`/`netcfg`), Red Bear ships a native `netctl` command, RTL8125 is wired into the existing Realtek autoload path, and the bounded Intel Wi‑Fi path now has host-tested profile start/stop plus interface-specific DHCP handoff without claiming real wireless connectivity. - **Wi-Fi profile target**: `config/redbear-wifi-experimental.toml` is the first explicit tracked image slice for bounded Intel Wi‑Fi validation, instead of spreading that claim across the generic desktop profiles. -- **Bluetooth**: one bounded in-tree BLE-first experimental slice exists, and the Battery Level read-only workload is now QEMU-validated through a packaged in-guest checker plus a host harness; broad desktop Bluetooth parity is still incomplete +- **Bluetooth**: one bounded in-tree BLE-first experimental slice exists, and the Battery Level read-only workload now has a packaged in-guest checker plus a host QEMU harness; QEMU validation is still in progress, so broad desktop Bluetooth parity is still incomplete - **KDE**: `redbear-kde.toml` exists and the recipe tree is populated, but the runtime stack is still incomplete. - **Linux driver compat**: linux-kpi now includes early wireless-subsystem compatibility scaffolding in addition to the earlier helper layer, redox-driver-sys and firmware-loader compile, and the bounded Intel Wi-Fi path now has host-tested scan/connect/disconnect/profile/reporting flows without claiming real hardware Wi-Fi connectivity. - **Wi-Fi validation tooling**: `redbear-phase5-wifi-check` and `redbear-phase5-wifi-capture` are now packaged in-guest helpers for bounded Intel Wi-Fi runtime validation and evidence capture on bare metal or VFIO-backed guests. +- **Phase 5 naming note**: the bounded `redbear-phase5-network-check` / `test-phase5-network-qemu.sh` path proves desktop/network plumbing on `redbear-full` in QEMU; it does **not** mean the Wi-Fi implementation plan's later Phase W5 real-hardware reporting/recovery milestone is complete. ## Quick Start diff --git a/local/AGENTS.md b/local/AGENTS.md index 8c22636c..a77c2bb1 100644 --- a/local/AGENTS.md +++ b/local/AGENTS.md @@ -144,9 +144,11 @@ redox-master/ ← git pull updates mainline Redox │ ├── recipes/ │ │ ├── core/ ← ext4d (ext4 filesystem scheme daemon + mkfs tool) │ │ ├── branding/ ← redbear-release (os-release, hostname, motd) -│ │ ├── drivers/ ← redox-driver-sys, linux-kpi +│ │ ├── drivers/ ← redox-driver-sys, linux-kpi (GPU/Wi-Fi compat only — NOT USB) │ │ ├── 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-quirks, redbear-meta +│ │ │ ├── redbear-sessiond ← org.freedesktop.login1 D-Bus session broker (zbus-based Rust daemon) +│ │ │ ├── redbear-dbus-services ← D-Bus .service activation files + XML policies │ │ ├── wayland/ ← Wayland compositor (v2.0 Phase 2) │ │ └── kde/ ← KDE Plasma (v2.0 Phases 3–4) │ ├── patches/ @@ -302,6 +304,7 @@ When mainline updates affect our work: 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. +- `local/docs/DBUS-INTEGRATION-PLAN.md` is the canonical D-Bus architecture and implementation plan for KDE Plasma 6 on Wayland. It defines the phased approach to D-Bus service integration, the `redbear-sessiond` login1-compatible session broker, and the gap analysis for desktop-facing D-Bus services. The current execution order for these subsystem plans is: @@ -438,13 +441,17 @@ redbear-live.toml firmware-loader, evdevd, udev-shim, redbear-info, mc, cub NOTE: ext4d is inherited from desktop.toml (mainline package) - NOTE: cub is included via redbear-desktop.toml and depends on the custom - recipe symlink (recipes/system/cub → local/recipes/system/cub) being - created by integrate-redbear.sh or apply-patches.sh before building. + NOTE: cub is treated as an essential Red Bear utility and is included through the tracked + flavor configs; it still depends on the custom recipe symlink + (recipes/system/cub → local/recipes/system/cub) being created by + integrate-redbear.sh or apply-patches.sh before building. NOTE: redbear-netctl provides a Redox-native `netctl` command with profiles in /etc/netctl and a boot-time `netctl --boot` service. NOTE: redbear-info is the canonical runtime integration report. Keep it updated when Red Bear adds new tools, schemes, services, or hardware integration paths. + NOTE: redbear-live inherits cub through redbear-desktop.toml. + NOTE: redbear-meta is explicitly included in redbear-full.toml. Keep any broader inclusion + deliberate because its dependency surface is much heavier than the core utility layer. redbear-full.toml └── desktop.toml (mainline) diff --git a/local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md b/local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md index 93d3be31..622c9c99 100644 --- a/local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md +++ b/local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md @@ -595,6 +595,7 @@ continuity, not as future work. | 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 | +| `local/docs/DBUS-INTEGRATION-PLAN.md` | D-Bus architecture, service dependency map, and phased implementation | | 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 1043be25..d3241f76 100644 --- a/local/docs/DESKTOP-STACK-CURRENT-STATUS.md +++ b/local/docs/DESKTOP-STACK-CURRENT-STATUS.md @@ -41,7 +41,15 @@ next work target. The repo has not yet started systematic runtime validation. | 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` | +| D-Bus | **builds, usable (bounded)** | System bus wired in `redbear-full` and `redbear-kde`; D-Bus plan + sessiond complete (DB-1), Qt 6.11 D-Bus coverage documented (Section 14), DB-2/3/4 service daemons implemented as stubs (notifications, upower, udisks, polkit) | +| redbear-sessiond | ✅ Scaffold | org.freedesktop.login1 D-Bus session broker — Rust daemon (zbus 5), config wired in redbear-kde.toml, acpi_watcher with edge detection | +| redbear-notifications | ✅ Scaffold | org.freedesktop.Notifications — logs to stderr, no display integration yet | +| redbear-upower | ✅ bounded real | org.freedesktop.UPower — enumerates real AC adapters/batteries from `/scheme/acpi/power`; desktop machines with no battery report line power only | +| redbear-udisks | ✅ bounded real | org.freedesktop.UDisks2 — enumerates real `disk.*` schemes and partitions into read-only D-Bus objects; no fabricated mount/serial metadata | +| Phase 5 D-Bus runtime proof | ✅ implemented (bounded QEMU proof) | `redbear-phase5-network-check` + `test-phase5-network-qemu.sh` assert bounded-real UPower/UDisks2 registration and runtime-backed enumeration on `redbear-full`; this is a desktop/network plumbing proof, not a claim that the Wi-Fi plan's later Phase W5 hardware/runtime-reporting exit criteria are complete | +| Phase 6 Solid readiness proof | ✅ implemented, blocked | `redbear-phase6-kde-check` + `test-phase6-kde-qemu.sh` now distinguish real Solid validation from blocked states; `kf6-solid` remains disabled until runtime proof + tooling are present | +| redbear-polkit | ✅ Scaffold | org.freedesktop.PolicyKit1 — always-permit authorization; KAuth still uses FAKE backend because PolkitQt6-1 is not packaged yet | +| redbear-dbus-services | ✅ Created | D-Bus activation files + policies staged | | 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 | @@ -60,8 +68,9 @@ next work target. The repo has not yet started systematic runtime validation. ### `redbear-full` - **Role:** Broader desktop/network/session plumbing -- **Current truth:** Carries D-Bus and broader integration pieces; VirtIO networking works in QEMU +- **Current truth:** Carries D-Bus and broader integration pieces; VirtIO networking works in QEMU, and the bounded Phase 5 network/session checker is evidence-backed there - **Use for:** Desktop integration testing beyond the narrow Wayland slice +- **Do not overclaim:** This profile proves bounded QEMU desktop/network plumbing only. It does not by itself close the Wi-Fi implementation plan's later real-hardware Phase W5 reporting/recovery gate. ### `redbear-kde` diff --git a/local/docs/PROFILE-MATRIX.md b/local/docs/PROFILE-MATRIX.md index 85d73d18..126b5116 100644 --- a/local/docs/PROFILE-MATRIX.md +++ b/local/docs/PROFILE-MATRIX.md @@ -26,13 +26,13 @@ USB plan uses: | 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-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-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 / USB: daemons built via base but not validated or support-scoped for this profile | +| `redbear-bluetooth-experimental` | First bounded Bluetooth validation profile | `redbear-bluetooth-experimental.toml`, `redbear-bluetooth-services.toml`, `redbear-minimal.toml` | builds / boots in QEMU / packaged Battery Level checker + QEMU harness present / QEMU validation still in progress / explicit-startup USB BLE-first only / 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-desktop` | Main Red Bear desktop integration profile without KDE-specific session wiring | `desktop.toml`, `redbear-legacy-base.toml`, `redbear-legacy-desktop.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / input-runtime substrate wired / runtime reporting installed / USB: xHCI host present + HID keyboard/mouse usable + mass storage autospawns in QEMU / QEMU-validated only / no real hardware USB claim | | `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-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+sessiond+KWin session surface wired | | `redbear-live` | Live and recovery image layered on desktop | `redbear-desktop.toml` | builds | ## Profile Notes @@ -50,7 +50,7 @@ USB plan uses: all Red Bear images. - Extends `redbear-minimal` so the baseline runtime tooling is already present, then adds only the bounded Bluetooth pieces on top. -- Current verified path: QEMU/UEFI boot to login prompt plus guest-side `redbear-bluetooth-battery-check`, with repeated in-boot reruns, daemon-restart coverage, and one experimental battery-sensor Battery Level read-only workload. +- Current path under active validation: QEMU/UEFI boot to login prompt plus guest-side `redbear-bluetooth-battery-check`, targeting repeated in-boot reruns, daemon-restart coverage, and one experimental battery-sensor Battery Level read-only workload. - Current support language is intentionally narrow: explicit-startup only, USB-attached transport, BLE-first CLI/scheme surface, one experimental battery-sensor Battery Level read-only workload, and no USB-class autospawn claim yet. @@ -86,8 +86,9 @@ USB plan uses: - Used for broader desktop/session plumbing after the narrower `redbear-wayland` validation slice. - 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`. +- Current verified path: QEMU/UEFI boot to login prompt plus guest-side `redbear-phase5-network-check`, with functional VirtIO networking, `DBUS_SYSTEM_BUS=present`, and bounded UPower/UDisks2 runtime-backed enumeration. - Should not be described as fully supported until runtime validation is evidence-backed. +- This bounded QEMU Phase 5 proof is not the same thing as the Wi-Fi plan's later Phase W5 real-hardware runtime-reporting-and-recovery exit criteria. ### `redbear-kde` @@ -109,3 +110,17 @@ USB plan uses: profile still does not claim generic GATT, write, or notify support. - The current validation claim is QEMU-scoped and packaged-checker-scoped, not a blanket claim about real hardware Bluetooth maturity. + +## USB Note + +- `redbear-desktop` is the primary profile carrying USB stack components (xHCI, HID, mass storage) + and the only profile where USB is validated and support-scoped. +- USB validation is QEMU-only (`test-usb-qemu.sh --check`). No profile makes a real hardware USB + support claim. +- USB error handling and correctness carry significant Red Bear patches over upstream; see + `local/patches/base/redox.patch` and `local/docs/USB-IMPLEMENTATION-PLAN.md` for details. +- `redbear-minimal` inherits the base recipe which builds `xhcid`, `usbhidd`, `usbhubd`, `usbscsid`, + and `usbctl`. These binaries are present in the image but USB is not validated or support-scoped + for this profile. +- `redbear-bluetooth-experimental` uses USB only as a transport for BLE dongles; it does not make a + general USB-class-autospawn claim. diff --git a/local/docs/QT6-PORT-STATUS.md b/local/docs/QT6-PORT-STATUS.md index 1711e42f..5797d4cd 100644 --- a/local/docs/QT6-PORT-STATUS.md +++ b/local/docs/QT6-PORT-STATUS.md @@ -13,9 +13,9 @@ **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`. +> **Execution note (2026-04-17):** The repo now has a large Redox-desktop-relevant Qt 6.11 subset +> cook-verified across Waves 1–2, but this is not yet the same claim as full Redox-applicable Qt +> 6.11 coverage. Additional graphics / input / desktop-adjacent modules remain to be ported. ## Current Status Summary @@ -24,12 +24,17 @@ | **qtbase** | ✅ | 13 libs incl. OpenGL, EGL, DBus, WaylandClient | | **qtdeclarative** | ✅ | 11 libs, QML JIT disabled | | **qtsvg** | ✅ | 2 libs | -| **qtwayland** | ✅ | Wayland client + compositor | +| **qtwayland** | ◐ Partial | Wayland client path verified; compositor slice still intentionally reduced in recipe | | **qtimageformats** | ✅ | Real recipe + cook verified | | **qt5compat** | ✅ | Real recipe + cook verified | -| **qttools** | ✅ | Redox-scoped tooling slice cook verified | +| **qttools** | ◐ Partial | Redox-scoped tooling slice cook verified; designer/assistant/qdoc/qtattributionsscanner intentionally omitted | | **qttranslations** | ✅ | Translation catalogs cook verified | | **qtshadertools** | ✅ | Real recipe + cook verified | +| **qtscxml** | ✅ | Real recipe + cook verified | +| **qtserialport** | ✅ | Real recipe + cook verified; unsupported modem-control ioctls mapped to runtime UnsupportedOperationError on Redox | +| **qtwebchannel** | ✅ | Real recipe + cook verified | +| **qtcharts** | ✅ | Real recipe + cook verified | +| **qtquicktimeline** | ✅ | Real recipe + cook verified after Qt Quick substrate export fixes | | **Mesa EGL+GBM** | ✅ | libEGL, libgbm, libGLESv2, swrast DRI | | **libdrm** | ✅ | libdrm + libdrm_amdgpu | | **libinput** | ✅ | 1.30.2 with comprehensive redox.patch | @@ -55,6 +60,24 @@ The first post-core Qt 6.11 coverage wave is now real-cook verified: 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. +## Wave 2 — Qt Quick / integration expansion + +The second Redox-applicable Qt 6.11 wave is now also real-cook verified: + +| Module | Status | Verification | +|--------|--------|--------------| +| `qtscxml` | ✅ | `CI=1 ./target/release/repo cook qtscxml` | +| `qtserialport` | ✅ | `CI=1 ./target/release/repo cook qtserialport` | +| `qtwebchannel` | ✅ | `CI=1 ./target/release/repo cook qtwebchannel` | +| `qtcharts` | ✅ | `CI=1 ./target/release/repo cook qtcharts` | +| `qtquicktimeline` | ✅ | `CI=1 ./target/release/repo cook qtquicktimeline` | + +Wave 2 also required a real repair of the Qt Quick substrate rather than recipe-only leaf work: + +- `qtbase` host build now uses a clean separate host build dir with `build/qt-host-build` as the install prefix. +- `qtshadertools` now installs a real host `qsb` and `Qt6ShaderToolsTools` package into that prefix. +- `qtdeclarative` now exports usable `Qt6Quick` / `Qt6Qml` CMake metadata to downstream Redox sysroots. + ## Scope Definition **Phase 1 scope**: qtbase, qtdeclarative, qtsvg — the foundational Qt6 stack. @@ -253,10 +276,20 @@ Current downstream build proof in this repo now includes: ### Phase 2a — qtbase D-Bus Enablement (✅ COMPLETE) -- qtbase rebuilt with `-DFEATURE_dbus=ON` in both host and target builds +- qtbase target build: `-DFEATURE_dbus=ON` (Qt6DBus module built and staged) +- qtbase host build: `-DFEATURE_dbus=OFF` (qdbus tools provisioned via /usr/bin symlinks) - libQt6DBus.so + Qt6DBusConfig.cmake + Qt6DBus.pc staged to sysroot - D-Bus 1.16.2 already built (24-line redox.patch for epoll + socketpair) - Unblocks: kf6-kdbusaddons, kf6-kservice, kf6-kpackage, kf6-kglobalaccel +- D-Bus plan: `local/docs/DBUS-INTEGRATION-PLAN.md` — redbear-sessiond login1 broker + D-Bus service infrastructure for KDE Plasma + +**redbear-sessiond:** Implemented. Rust daemon at `local/recipes/system/redbear-sessiond/` using zbus 5, serving `org.freedesktop.login1` Manager/Session/Seat interfaces on the system bus. Maps `TakeDevice(major, minor)` to Redox scheme paths (`/scheme/drm/card0`, `/dev/input/eventN`). Config wired in `config/redbear-kde.toml` with init service at slot 13. + +**qdbuscpp2xml/qdbusxml2cpp provisioning:** Qt host build has `FEATURE_dbus=OFF` with these tools disabled. KDE recipes provision them via symlinks: kf6-kdbusaddons falls back to `/usr/bin/qdbuscpp2xml` and `/usr/bin/qdbusxml2cpp` from the host system. This works for cross-compilation but is not a long-term solution. Future improvement: enable FEATURE_dbus=ON in host build once D-Bus session bus validation passes. + +**KF6 D-Bus re-enablement roadmap:** 15 KF6 components currently build with `-DUSE_DBUS=OFF`. Re-enablement is gated on D-Bus service availability: kf6-knotifications needs `org.freedesktop.Notifications` (DB-2, now enabled against a stub notification daemon), kf6-solid needs runtime-validated `org.freedesktop.UPower` + `org.freedesktop.UDisks2` enumeration (DB-3, both daemons now expose bounded real enumeration). The runtime proof harness is now in place, but `kf6-solid` still keeps `-DUSE_DBUS=OFF`, `-DBUILD_DEVICE_BACKEND_upower=OFF`, and `-DBUILD_DEVICE_BACKEND_udisks2=OFF` until `solid-hardware6`/Phase 6 validation can confirm the consumer path. kf6-kio and 10 others need full desktop services (DB-5). See `local/docs/DBUS-INTEGRATION-PLAN.md` Section 14 for the complete matrix. + +**Key insight:** QtDBus is NOT the gap — Qt6DBus builds and kf6-kdbusaddons provides the KDE convenience layer. The gap is the freedesktop service contracts (login1, Notifications, UPower, UDisks2, PolicyKit) that need Redox-native implementations. NetworkManager is deferred; Red Bear OS uses `redbear-netctl` for now. ### Phase 2b — qtwayland Module (🔄 Building) diff --git a/local/docs/SCRIPT-BEHAVIOR-MATRIX.md b/local/docs/SCRIPT-BEHAVIOR-MATRIX.md index 7f3dcb79..5b520786 100644 --- a/local/docs/SCRIPT-BEHAVIOR-MATRIX.md +++ b/local/docs/SCRIPT-BEHAVIOR-MATRIX.md @@ -22,7 +22,7 @@ The goal is to remove guesswork from the sync/fetch/apply/build workflow. | `local/scripts/test-wifi-baremetal-runtime.sh` | Exercise bounded Intel Wi-Fi runtime lifecycle on a target system | validates driver probe, control probe, bounded connect/disconnect, profile-manager start/stop via the `wifi-open-bounded` profile, Wi-Fi lifecycle reporting, and writes `/tmp/redbear-phase5-wifi-capture.json` on the target | does not prove real AP association, packet flow, DHCP success over Wi-Fi, or end-to-end hardware connectivity | | `local/scripts/test-wifi-passthrough-qemu.sh` | Launch Red Bear with VFIO-passed Intel Wi-Fi hardware | boots a Red Bear guest with a passed-through Intel Wi-Fi PCI function, auto-runs the in-guest bounded Wi-Fi validation command, and can copy the packaged capture bundle back to a host-side file during `--check` | depends on host VFIO setup and still does not by itself guarantee real AP association or end-to-end Wi-Fi connectivity | | `local/scripts/test-bluetooth-runtime.sh` | Compatibility guest entrypoint for the bounded Bluetooth Battery Level slice | runs the packaged `redbear-bluetooth-battery-check` helper inside a Redox guest or target runtime | does not run on the host and does not expand the Bluetooth support claim beyond the packaged checker’s bounded scope | -| `local/scripts/test-bluetooth-qemu.sh` | Launch or validate the bounded Bluetooth Battery Level slice in QEMU | boots `redbear-bluetooth-experimental`, auto-runs the packaged checker during `--check`, reruns it in one boot, and reruns it again after a clean reboot | does not prove real controller bring-up, generic BLE/GATT maturity, write/notify support, or real hardware Bluetooth behavior | +| `local/scripts/test-bluetooth-qemu.sh` | Launch or validate the bounded Bluetooth Battery Level slice in QEMU | boots `redbear-bluetooth-experimental`, auto-runs the packaged checker during `--check`, reruns it in one boot, and reruns it again after a clean reboot | does not by itself guarantee that the current QEMU proof passes; does not prove real controller bring-up, generic BLE/GATT maturity, write/notify support, or real hardware Bluetooth behavior | | `local/scripts/prepare-wifi-vfio.sh` | Prepare or restore an Intel Wi-Fi PCI function for passthrough | binds a chosen PCI function to `vfio-pci` or restores it to a specified host driver | does not verify guest Wi-Fi functionality and must be used carefully on a host with a safe detachable target device | | `local/scripts/validate-wifi-vfio-host.sh` | Check whether a host looks ready for Wi-Fi VFIO testing | validates PCI presence, current driver, UEFI firmware, Red Bear image presence, QEMU/expect availability, VFIO module state, and IOMMU group visibility; exits non-zero when blockers are found | does not bind devices or prove the guest Wi-Fi stack works | | `local/scripts/run-wifi-passthrough-validation.sh` | End-to-end host-side passthrough validation wrapper | prepares VFIO, runs the packaged in-guest Wi-Fi validation path, captures the guest JSON artifact to the host, writes a host-side metadata sidecar, and restores the host driver afterwards | still depends on real VFIO/hardware support and does not itself guarantee end-to-end Wi-Fi connectivity | @@ -33,10 +33,10 @@ The goal is to remove guesswork from the sync/fetch/apply/build workflow. The packaged companion command for those scripts is `redbear-phase5-wifi-check`, which performs the bounded in-target Wi-Fi lifecycle checks from inside the guest/runtime itself. -The packaged Bluetooth companion command is `redbear-bluetooth-battery-check`, which performs the -bounded Bluetooth Battery Level checks from inside the guest/runtime itself, including repeated -helper runs, daemon-restart coverage, failure-path honesty checks, and stale-state cleanup checks -within the current slice boundary. +The packaged Bluetooth companion command is `redbear-bluetooth-battery-check`, which is intended to +perform the bounded Bluetooth Battery Level checks from inside the guest/runtime itself, including +repeated helper runs, daemon-restart coverage, failure-path honesty checks, and stale-state cleanup +checks within the current slice boundary. The packaged evidence companion is `redbear-phase5-wifi-capture`, which collects the bounded driver, control, profile-manager, reporting, interface-listing, and scheme-state surfaces — plus `lspci` diff --git a/local/docs/WIFI-IMPLEMENTATION-PLAN.md b/local/docs/WIFI-IMPLEMENTATION-PLAN.md index ef08b652..496a8da2 100644 --- a/local/docs/WIFI-IMPLEMENTATION-PLAN.md +++ b/local/docs/WIFI-IMPLEMENTATION-PLAN.md @@ -5,7 +5,7 @@ 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. -Wi-Fi is currently **not working connectivity**. What exists is a structurally complete, +Wi-Fi does not provide working connectivity yet. What exists is a structurally complete, host-tested Intel transport layer and native control plane, awaiting real hardware + firmware validation. @@ -41,7 +41,7 @@ validation. 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. +- **Stale response sentinel** (0xFFFF): After command timeout, the response fields are poisoned. Late-arriving firmware responses and id/cookie mismatches are discarded entirely without completing the waiter — prevents stale responses from completing the wrong in-flight 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. @@ -194,6 +194,10 @@ path without treating it as raw Ethernet. Runtime validation pending. ### Phase W5 — Runtime Reporting and Recovery (After W4) +> **Status note:** This Phase **W5** is not the same as the bounded `redbear-phase5-network-check` +> QEMU plumbing proof on `redbear-full`. W5 here remains a later real-hardware reporting/recovery +> milestone. + - Extend `redbear-info` with real Wi-Fi runtime evidence (not just bounded surfaces) - Reconnect after disconnect - Failure-state reporting and retry diff --git a/local/docs/WIFI-VALIDATION-RUNBOOK.md b/local/docs/WIFI-VALIDATION-RUNBOOK.md index 50e0d1d7..2b134b4c 100644 --- a/local/docs/WIFI-VALIDATION-RUNBOOK.md +++ b/local/docs/WIFI-VALIDATION-RUNBOOK.md @@ -170,6 +170,10 @@ The wrapper handles: 5. writing a host-side metadata sidecar for the run 6. restoring the host driver afterwards +`redbear-phase5-network-check` in that flow is the bounded `redbear-full` desktop/network plumbing +proof. It should not be read as closing the Wi‑Fi implementation plan's later Phase W5 +runtime-reporting-and-recovery milestone by itself. + ### Artifact to preserve - `./wifi-passthrough-capture.json`