From 90fa45c5456679249ce65a8f753617f73a06074c Mon Sep 17 00:00:00 2001 From: Vasilito Date: Thu, 16 Apr 2026 12:46:07 +0100 Subject: [PATCH] Refresh project documentation Red Bear OS Team --- AGENTS.md | 2 +- HARDWARE.md | 16 +- README.md | 11 +- docs/01-REDOX-ARCHITECTURE.md | 9 +- docs/02-GAP-ANALYSIS.md | 4 +- docs/04-LINUX-DRIVER-COMPAT.md | 40 +- docs/06-BUILD-SYSTEM-SETUP.md | 20 + docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md | 25 +- docs/AGENTS.md | 1 + docs/README.md | 23 +- docs/firmware.md | 85 ++++ local/AGENTS.md | 33 +- local/docs/ACPI-FIXES.md | 9 +- local/docs/AMD-FIRST-INTEGRATION.md | 8 +- local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md | 268 +++++++++-- local/docs/BLUETOOTH-VALIDATION-RUNBOOK.md | 96 ++++ local/docs/DESKTOP-STACK-CURRENT-STATUS.md | 19 +- local/docs/EXTERNAL-TOOLCHAIN.md | 83 ++++ ...D-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md | 46 +- local/docs/NETWORKING-RTL8125-NETCTL.md | 75 +++ local/docs/PHASE-0-3-REASSESSMENT.md | 2 +- local/docs/PROFILE-MATRIX.md | 39 +- local/docs/QT6-PORT-STATUS.md | 21 +- local/docs/REDBEAR-INFO-RUNTIME-REPORT.md | 11 +- local/docs/SCRIPT-BEHAVIOR-MATRIX.md | 33 ++ local/docs/USB-IMPLEMENTATION-PLAN.md | 13 +- local/docs/WIFI-IMPLEMENTATION-PLAN.md | 452 +++++++++++++++--- local/docs/WIFI-VALIDATION-ISSUE-TEMPLATE.md | 78 +++ local/docs/WIFI-VALIDATION-RUNBOOK.md | 215 +++++++++ local/docs/WIFICTL-SCHEME-REFERENCE.md | 77 +++ local/docs/WIP-MIGRATION-LEDGER.md | 1 + local/docs/repo-governance.md | 11 + 32 files changed, 1659 insertions(+), 167 deletions(-) create mode 100644 docs/firmware.md create mode 100644 local/docs/BLUETOOTH-VALIDATION-RUNBOOK.md create mode 100644 local/docs/EXTERNAL-TOOLCHAIN.md create mode 100644 local/docs/WIFI-VALIDATION-ISSUE-TEMPLATE.md create mode 100644 local/docs/WIFI-VALIDATION-RUNBOOK.md create mode 100644 local/docs/WIFICTL-SCHEME-REFERENCE.md diff --git a/AGENTS.md b/AGENTS.md index 3c7b15b7..2b6865da 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -239,7 +239,7 @@ See `local/docs/AMD-FIRST-INTEGRATION.md` for the full plan. | ACPI reboot | ✅ | Reset register + keyboard controller fallback | | ACPI power | ✅ | `\_PS0`/`\_PS3`/`\_PPC` AML methods available | | x2APIC/SMP | ✅ | Multi-core works | -| IOMMU | ❌ | No AMD-Vi support | +| 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 diff --git a/HARDWARE.md b/HARDWARE.md index 0110e99e..ea20ad44 100644 --- a/HARDWARE.md +++ b/HARDWARE.md @@ -52,11 +52,19 @@ We also recommend to add your `pciutils` log as a comment on [this](https://gitl This section contain limitations that apply to any status. -- ACPI support is incomplete (some things are hardcoded on the kernel to work) -- Wi-Fi and Bluetooth aren't supported yet -- AMD, NVIDIA, ARM, and PowerVR GPUs aren't supported yet (only BIOS VESA and UEFI GOP) +- ACPI bring-up is materially complete for the current boot baseline, but broader platform coverage + and hardware validation are still uneven across machines +- Wi-Fi broad support is not available yet; bounded Intel Wi-Fi scaffolding and validation paths now + cover probe/status/prepare/init/activate plus bounded scan/connect/disconnect/retry surfaces, but + validated real wireless connectivity support remains incomplete +- Bluetooth broad support is not available yet; one bounded in-tree BLE-first experimental slice + exists, but broad controller or desktop parity remains incomplete +- Broad hardware-validated GPU acceleration is not supported yet; the default proven path remains + BIOS VESA and UEFI GOP, even though Red Bear now carries compile-oriented AMD/Intel DRM work in + the local overlay - I2C devices aren't supported yet (PS/2 or USB devices should be used) -- USB support varies on each device model because some USB devices require specific drivers (use input devices with standardized controls for more compatibility) +- USB support still varies by machine and device class, but Red Bear now has QEMU-proven xHCI + interrupt-mode and USB mass-storage autospawn paths - Automatic operating system discovery is not implemented in the boot loader yet (remember this before installing Red Bear OS) ## Contribute to this document diff --git a/README.md b/README.md index 45d2a51a..5e86a013 100644 --- a/README.md +++ b/README.md @@ -99,7 +99,9 @@ The current subsystem order is not arbitrary. - **Low-level controllers / IRQ quality** are first-class because they block reliable driver/runtime validation. - **USB** is first-class because Bluetooth and wider device support depend on controller and hotplug maturity. - **Wi-Fi** is first-class because Red Bear still lacks any native wireless driver/control plane. -- **Bluetooth** is first-class because it remains fully missing and depends on either USB maturity or another controller path. +- **Bluetooth** is first-class because broad support is still incomplete, depends on USB maturity or + another controller path, and currently exists only as one bounded BLE-first experimental slice + rather than broad desktop parity. The current blocker chain is: @@ -167,9 +169,10 @@ native `usb.*` schemes exposed by `xhcid`, so there is no dependency on the unfi ## Networking Red Bear ships the existing native Redox wired networking path (`pcid-spawner` → NIC daemon → -`smolnetd`/`dhcpd`/`netcfg`) together with a small Redox-native `netctl` compatibility command. -Profiles live under `/etc/netctl`, the shipped examples live under `/etc/netctl/examples`, and the -boot service applies the enabled profile with `netctl --boot`. +`smolnetd`/`dhcpd`/`netcfg`) together with a small Redox-native `netctl` compatibility command and +the `redbear-netctl-console` ncurses client for the bounded Wi‑Fi profile flow. Profiles live under +`/etc/netctl`, the shipped examples live under `/etc/netctl/examples`, live Wi‑Fi actions go +through `/scheme/wifictl`, and the boot service applies the enabled profile with `netctl --boot`. RTL8125 is wired into the existing native Realtek autoload path by matching `10ec:8125` in the `rtl8168d` driver config. This keeps the implementation in the Redox userspace driver model rather diff --git a/docs/01-REDOX-ARCHITECTURE.md b/docs/01-REDOX-ARCHITECTURE.md index 488634aa..a34bf8a0 100644 --- a/docs/01-REDOX-ARCHITECTURE.md +++ b/docs/01-REDOX-ARCHITECTURE.md @@ -132,10 +132,11 @@ driven wired setup. ### GPU Driver Status -- **No hardware-accelerated GPU drivers** -- Only BIOS VESA and UEFI GOP framebuffers -- Experimental Intel modesetting (Kaby Lake, Tiger Lake) — no acceleration -- AMD, NVIDIA, ARM, PowerVR: not supported +- Broad hardware-validated GPU acceleration is not yet available as a general support claim. +- BIOS VESA and UEFI GOP framebuffers remain the default proven display path. +- Experimental Intel modesetting exists. +- Red Bear also carries compile/integration-oriented AMD and Intel DRM work in its local overlay, + but that should not be read as broad hardware-validated acceleration support yet. ## 4. Orbital Display Server diff --git a/docs/02-GAP-ANALYSIS.md b/docs/02-GAP-ANALYSIS.md index 8723d4ac..6f2b9c29 100644 --- a/docs/02-GAP-ANALYSIS.md +++ b/docs/02-GAP-ANALYSIS.md @@ -19,7 +19,7 @@ Use the matrix below as the authoritative phase summary before reading the older | P2 DRM / AMD+Intel display | Complete in-tree, hardware validation pending | `local/docs/P2-AMD-GPU-DISPLAY.md`, `local/recipes/gpu/redox-drm/`, `local/recipes/gpu/amdgpu/` | | P3 POSIX + input | Implemented in-tree; consumer-visible `signalfd`/`timerfd`/`eventfd`/`open_memstream` header-export path fixed in this repo pass; runtime validation still pending | `recipes/core/relibc/source/src/header/`, `recipes/core/relibc/source/include/sys/signalfd.h`, `local/patches/relibc/`, `local/recipes/system/evdevd/`, `local/recipes/system/udev-shim/` | | P4 Wayland stack | Partially complete | `recipes/wip/wayland/`, `recipes/wip/libs/other/libinput/`, `recipes/wip/services/seatd/` | -| P5 AMD acceleration / IOMMU | Partial | `local/recipes/gpu/amdgpu/`, `local/recipes/system/iommu/` (now buildable via surfaced recipe) | +| P5 AMD acceleration / IOMMU | Partial, but no longer blocked on basic QEMU first-use proof | `local/recipes/gpu/amdgpu/`, `local/recipes/system/iommu/` | | P6 KDE Plasma | In progress with mixed real builds and stubs/shims | `config/redbear-kde.toml`, `local/recipes/kde/`, `local/docs/QT6-PORT-STATUS.md` | ### Ordered Remaining Gaps @@ -27,7 +27,7 @@ Use the matrix below as the authoritative phase summary before reading the older 1. **Validate the completed P3→P4 bridge in practice**: `libwayland` now rebuilds with `signalfd`, `timerfd`, `eventfd`, `open_memstream`, `MSG_CMSG_CLOEXEC`, and `MSG_NOSIGNAL` restored, but compositor/runtime validation is still outstanding. 2. **Complete P4 runtime path**: libinput/seatd/GBM/Wayland compositor integration is still incomplete even though the base libraries now build, `seatd` now builds for Redox, and the KDE runtime config now starts a seatd service. 3. **Separate KDE real builds from scaffolding**: parts of the KDE stack are genuine builds, while others are shimmed or stubbed only to satisfy dependency resolution. -4. **Hardware validation remains open** for AMD/Intel DRM and the IOMMU path, even though the IOMMU daemon now builds. +4. **Hardware validation remains open** for AMD/Intel DRM and the IOMMU path, even though the IOMMU daemon now builds and its guest-driven QEMU first-use proof passes. ### P7 Note diff --git a/docs/04-LINUX-DRIVER-COMPAT.md b/docs/04-LINUX-DRIVER-COMPAT.md index ed916061..489d6065 100644 --- a/docs/04-LINUX-DRIVER-COMPAT.md +++ b/docs/04-LINUX-DRIVER-COMPAT.md @@ -16,7 +16,45 @@ | `redox-drm` | Present and compiling in `local/recipes/gpu/redox-drm/` | | Intel path | Compile-oriented, no hardware validation yet | | AMD path | Compile-oriented via `amdgpu` + AMD DC port, no hardware validation yet | -| IOMMU | Partial — daemon now builds, hardware validation still TODO in `local/recipes/system/iommu/` | +| IOMMU | QEMU first-use proof present — daemon builds, AMD-Vi units initialize in QEMU, real hardware validation still open | + +### Wi-Fi-facing note + +Although this document is primarily about the LinuxKPI path for GPU-class drivers, the same compat +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. + +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. + +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. + +Concrete repo entry points for that current bounded Wi‑Fi path are: + +- `local/recipes/drivers/redbear-iwlwifi/` — bounded Intel driver-side package +- `local/recipes/system/redbear-wifictl/` — native Wi‑Fi control daemon and `/scheme/wifictl` +- `local/recipes/system/redbear-netctl/` — profile-manager orchestration and post-association handoff +- `local/recipes/system/redbear-info/` — runtime-reporting surface for Wi‑Fi lifecycle state +- `local/recipes/system/redbear-hwutils/` — packaged Wi‑Fi validation, capture, and analysis tools +- `local/docs/WIFI-IMPLEMENTATION-PLAN.md` and `local/docs/WIFI-VALIDATION-RUNBOOK.md` — current + 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. ## Goal diff --git a/docs/06-BUILD-SYSTEM-SETUP.md b/docs/06-BUILD-SYSTEM-SETUP.md index 3a528d7e..780f9111 100644 --- a/docs/06-BUILD-SYSTEM-SETUP.md +++ b/docs/06-BUILD-SYSTEM-SETUP.md @@ -123,6 +123,26 @@ make all This produces `build/x86_64/desktop/harddrive.img`. +### Export External Toolchain + +After `make prefix`, you can export a relocatable external cross toolchain that provides +`x86_64-unknown-redox-gcc` and the related host-side wrappers in one directory: + +```bash +make export-toolchain TARGET=x86_64-unknown-redox +source build/toolchain-export/x86_64-unknown-redox/activate.sh +x86_64-unknown-redox-gcc --version +``` + +To export somewhere else: + +```bash +make export-toolchain TARGET=x86_64-unknown-redox \ + TOOLCHAIN_EXPORT_DIR=/opt/redbear/toolchains/x86_64-unknown-redox +``` + +For the full layout and rationale, see `local/docs/EXTERNAL-TOOLCHAIN.md`. + ### Build with Specific Config ```bash diff --git a/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md b/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md index 9cb21a09..c42e1084 100644 --- a/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md +++ b/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md @@ -324,10 +324,17 @@ Goal: Current state: -- Wi-Fi is still missing, -- prerequisites exist, -- `linux-kpi` is only a partial low-level aid, not the Wi-Fi architecture itself, -- a native control plane is still required. +- one bounded experimental Intel Wi-Fi path is now in-tree, +- the corresponding tracked validation profile is `redbear-wifi-experimental`, +- `linux-kpi` now carries early wireless-subsystem compatibility scaffolding in addition to the + earlier low-level helper layer, +- the native control-plane/profile/reporting stack now has bounded scan/connect/disconnect flows, + including profile-manager start/stop wiring for the current Wi-Fi path, +- 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`), +- real hardware scan/auth/association/data-path proof is still missing, +- `linux-kpi` is still not the Wi-Fi architecture by itself. Canonical plan: @@ -337,6 +344,8 @@ Acceptance: - one experimental Wi-Fi family is packaged and evidence-backed, - post-association handoff to the existing network stack is real, +- the bounded station-mode lifecycle is visible through driver, control-daemon, profile-manager, + and runtime-reporting surfaces, - desktop-facing Wi-Fi claims remain honest and bounded. ### 6. Bluetooth @@ -347,8 +356,10 @@ Goal: Current state: -- Bluetooth is still missing, +- one bounded in-tree BLE-first experimental slice now exists, - architecture direction is documented, +- the currently credible implementation target is one bounded BLE-first host-side slice rather than + broad desktop Bluetooth parity, - transport dependency on USB maturity remains explicit. Canonical plan: @@ -357,8 +368,8 @@ Canonical plan: Acceptance: -- one controller path, one host path, and one bounded user-facing workflow exist with experimental - support language. +- one controller path, one host path, and one bounded BLE-first user-facing workflow exist with + experimental support language. ### 7. Graphics, Wayland, and desktop/session compatibility diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 645f740a..0de06b3b 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -43,6 +43,7 @@ docs/ | Which docs are current vs historical? | README | Document Status Matrix | | What is the current WIP ownership policy? | local/docs/WIP-MIGRATION-LEDGER.md | Entire document | | What do the main sync/fetch/apply/build scripts actually guarantee? | local/docs/SCRIPT-BEHAVIOR-MATRIX.md | Entire document | +| What is the current Wi-Fi architecture and validation path? | local/docs/WIFI-IMPLEMENTATION-PLAN.md / local/docs/WIFI-VALIDATION-RUNBOOK.md | Entire document | | What is the current desktop-stack truth? | local/docs/DESKTOP-STACK-CURRENT-STATUS.md | Entire document | | What is the current Qt/KF6 status? | local/docs/QT6-PORT-STATUS.md | Entire document | | What's missing for Wayland? | 02 | Status correction + ordered remaining gaps | diff --git a/docs/README.md b/docs/README.md index ccb99ea8..e65c9b63 100644 --- a/docs/README.md +++ b/docs/README.md @@ -49,16 +49,20 @@ current local subsystem plan. | 05 | [KDE Plasma on Redox](05-KDE-PLASMA-ON-REDOX.md) | Historical KDE implementation path plus deeper KDE-specific rationale | | 06 | [Build System Setup](06-BUILD-SYSTEM-SETUP.md) | How to build Redox from this repository | | 07 | [Red Bear OS Implementation Plan](07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md) | Canonical public implementation plan focused on profiles, packaging, validation, and staged hardware enablement | +| 08 | [Firmware in Red Bear OS](firmware.md) | Canonical firmware packaging, licensing, and runtime-loading policy | -## Related Red Bear-local plans +## Related Red Bear-local current-state plans - `../local/docs/USB-IMPLEMENTATION-PLAN.md` — current USB completeness and rollout plan - `../local/docs/WIFI-IMPLEMENTATION-PLAN.md` — current Wi-Fi architecture and rollout plan +- `../local/docs/WIFI-VALIDATION-RUNBOOK.md` — canonical operator path for bare-metal/VFIO Wi-Fi validation and evidence capture +- `../local/docs/WIFICTL-SCHEME-REFERENCE.md` — bounded `/scheme/wifictl` interface reference for the current Wi-Fi control surface +- `../local/recipes/system/redbear-netctl-console/source/` — Redox-native ncurses terminal client for the bounded Wi-Fi profile flow +- `../local/docs/SCRIPT-BEHAVIOR-MATRIX.md` — guarantees and non-guarantees for the main Wi-Fi and Bluetooth validation helpers plus core repo scripts - `../local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md` — current Bluetooth architecture and rollout plan +- `../local/docs/BLUETOOTH-VALIDATION-RUNBOOK.md` — canonical operator path for the bounded Bluetooth Battery Level QEMU validation slice - `../local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` — current low-level controller and IRQ blocker plan - `../local/docs/AMD-FIRST-INTEGRATION.md` — AMD-focused technical roadmap; historical AMD-first sequencing, not current platform-priority policy -- `../local/docs/WIP-MIGRATION-LEDGER.md` — current WIP ownership and upstream-vs-local migration ledger -- `../local/docs/SCRIPT-BEHAVIOR-MATRIX.md` — what the main sync/fetch/apply/build scripts do and do not guarantee - `../local/docs/PROJECT-DOCUMENTATION-ASSESSMENT.md` — current assessment of documentation quality, canon, and remaining cleanup priorities - `../local/docs/DESKTOP-STACK-CURRENT-STATUS.md` — canonical current build/runtime truth summary for the desktop stack @@ -66,6 +70,12 @@ These local Red Bear plans should be treated as first-class subsystem references Bluetooth, and low-level controller work. They carry blocker detail that the public docs summarize at a higher level. +## Related Red Bear-local governance docs + +- `../local/docs/WIP-MIGRATION-LEDGER.md` — current WIP ownership and upstream-vs-local migration ledger +- `../local/docs/SCRIPT-BEHAVIOR-MATRIX.md` — what the main sync/fetch/apply/build scripts do and do not guarantee +- `../local/docs/EXTERNAL-TOOLCHAIN.md` — how to export a relocatable external `x86_64-unknown-redox-gcc` toolchain from the built prefix + ## Current State Summary (as of 2026-04-15) This summary is only a quick orientation layer. For canonical current-state detail, prefer: @@ -83,9 +93,12 @@ This summary is only a quick orientation layer. For canonical current-state deta - **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 -- **Networking**: native wired stack present (`pcid-spawner` → NIC daemon → `smolnetd`/`dhcpd`/`netcfg`), Red Bear ships a native `netctl` command, and RTL8125 is wired into the existing Realtek autoload path +- **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 - **KDE**: `redbear-kde.toml` exists and the recipe tree is populated, but the runtime stack is still incomplete. -- **Linux driver compat**: linux-kpi (31 C headers + 13 Rust FFI), redox-driver-sys, firmware-loader all compile. +- **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. ## Quick Start diff --git a/docs/firmware.md b/docs/firmware.md new file mode 100644 index 00000000..46dce66a --- /dev/null +++ b/docs/firmware.md @@ -0,0 +1,85 @@ +# Firmware in Red Bear OS + +## Purpose + +This document defines the Red Bear firmware policy. + +Firmware is treated as third-party runtime content, not as normal project source code. + +## Basic Rules + +- firmware is third-party +- firmware licenses vary by vendor and artifact +- firmware remains under its own licenses +- firmware is redistributed unmodified +- firmware is loaded at runtime from the filesystem +- firmware should not be embedded into driver binaries + +## Source and Packaging Model + +Red Bear should package firmware separately from the core OS logic. + +Recommended package-group model: + +- `firmware-base` +- `firmware-intel` +- `firmware-amd` +- `firmware-wifi` + +The current Red Bear package path for the broad upstream firmware corpus is: + +- `local/recipes/system/redbear-firmware/` + +That package is intended to stage firmware under: + +- `/lib/firmware/` + +License metadata should remain clearly separated inside the firmware tree, for example under: + +- `/lib/firmware/LICENSES/` + +## Licensing and Redistribution + +The practical downstream model is the same one used by Linux distributions: + +- Linux distributions ship `linux-firmware` as a separate package +- the operating system itself can remain under its own license +- firmware stays under the vendor license documented in `WHENCE` and related license files + +Red Bear should follow the same model. + +Do not claim a single Red Bear repo-wide license applies to the firmware blobs themselves. + +## What Red Bear Must Not Do + +- do not claim firmware is MIT just because Red Bear OS code is MIT-like or permissive +- do not remove vendor license files or `WHENCE` +- do not modify firmware blobs +- do not merge firmware blobs into normal source trees without clear separation +- do not assume every blob is redistributable without checking upstream `WHENCE` / license metadata + +## Runtime Loading Rule + +Drivers and userspace daemons should request firmware from the filesystem at runtime. + +For Red Bear, the canonical runtime path is: + +- `/lib/firmware/...` + +The current helper daemon for that model is: + +- `firmware-loader` providing `scheme:firmware` + +This keeps the architecture cleaner and legally safer than embedding blobs into binaries. + +## Upstream References + +- upstream firmware source: `linux-firmware` +- upstream license and redistribution metadata: `WHENCE` +- vendor-specific license files: `LICENCE.*`, `LICENSE*` + +## Bottom Line + +Red Bear can distribute a Linux-firmware-derived firmware package, but it must do so as separate +firmware content with its own license metadata, installed under `/lib/firmware/`, and loaded at +runtime rather than compiled into project binaries. diff --git a/local/AGENTS.md b/local/AGENTS.md index bbbec151..2e281e03 100644 --- a/local/AGENTS.md +++ b/local/AGENTS.md @@ -133,7 +133,7 @@ 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, firmware-loader, redbear-hwutils, redbear-info, redbear-netctl, redbear-meta +│ │ ├── 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) │ ├── patches/ @@ -152,6 +152,17 @@ redox-master/ ← git pull updates mainline Redox │ │ ├── build-amd.sh ← Legacy AMD-specific build (use build-redbear.sh) │ │ ├── test-amd-gpu.sh ← AMD GPU test script │ │ ├── test-baremetal.sh ← Bare metal test script +│ │ ├── build-redbear-wifictl-redox.sh ← Build redbear-wifictl for the Redox target with the repo toolchain +│ │ ├── test-iwlwifi-driver-runtime.sh ← Bounded Intel driver lifecycle check inside a target runtime +│ │ ├── test-wifi-control-runtime.sh ← Bounded Wi-Fi control/profile runtime check inside a target runtime +│ │ ├── test-wifi-baremetal-runtime.sh ← Strongest in-repo Wi-Fi runtime check on a real Red Bear target +│ │ ├── validate-wifi-vfio-host.sh ← Host-side VFIO passthrough readiness check for Intel Wi-Fi validation +│ │ ├── prepare-wifi-vfio.sh ← Bind/unbind Intel Wi-Fi PCI function for VFIO validation +│ │ ├── test-wifi-passthrough-qemu.sh ← QEMU/VFIO Wi-Fi validation harness with in-guest checks +│ │ ├── run-wifi-passthrough-validation.sh ← One-shot host wrapper for the full Wi-Fi passthrough validation flow +│ │ ├── package-wifi-validation-artifacts.sh ← Package Wi-Fi validation artifacts into one host-side tarball +│ │ ├── summarize-wifi-validation-artifacts.sh ← Summarize captured Wi-Fi validation artifacts for quick triage +│ │ ├── finalize-wifi-validation-run.sh ← Analyze a Wi-Fi capture bundle and package the final evidence set │ │ ├── validate-vm-network-baseline.sh ← Static repo-level VM networking baseline check │ │ ├── test-vm-network-qemu.sh ← QEMU launcher for the VirtIO VM networking baseline │ │ └── test-vm-network-runtime.sh ← In-guest runtime check for the VM networking baseline @@ -187,7 +198,8 @@ redox-master/ ← git pull updates mainline Redox # 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. -# The current IOMMU proof checks for the AMD IOMMU device plus guest boot reachability. +# The current IOMMU proof runs a guest-driven first-use self-test and checks that discovered +# 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 @@ -202,6 +214,21 @@ redox-master/ ← git pull updates mainline Redox # Then run inside the guest: # redbear-phase5-network-check +# Bounded Intel Wi-Fi runtime validation (real target or passthrough guest) +# Host preparation for VFIO-backed guests: +# sudo ./local/scripts/validate-wifi-vfio-host.sh --host-pci 0000:xx:yy.z --expect-driver iwlwifi +# sudo ./local/scripts/prepare-wifi-vfio.sh bind 0000:xx:yy.z +# Guest/target packaged checks: +# redbear-phase5-wifi-check +# redbear-phase5-wifi-link-check +# redbear-phase5-wifi-run wifi-open-bounded wlan0 /tmp/redbear-phase5-wifi-capture.json +# redbear-phase5-wifi-capture wifi-open-bounded wlan0 /tmp/redbear-phase5-wifi-capture.json +# redbear-phase5-wifi-analyze /tmp/redbear-phase5-wifi-capture.json +# Helper scripts: +# ./local/scripts/test-wifi-baremetal-runtime.sh +# ./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 ./local/scripts/build-redbear.sh redbear-kde ./local/scripts/test-phase6-kde-qemu.sh --check @@ -247,6 +274,8 @@ When mainline updates affect our work: 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 also be treated as first-class subsystem plans, not as side notes. +- `local/docs/WIFI-VALIDATION-RUNBOOK.md` is the canonical operator runbook for bare-metal and + 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. diff --git a/local/docs/ACPI-FIXES.md b/local/docs/ACPI-FIXES.md index 5343dc6a..92f99ad4 100644 --- a/local/docs/ACPI-FIXES.md +++ b/local/docs/ACPI-FIXES.md @@ -20,15 +20,16 @@ P0 ACPI work is **complete**. Kernel patch is 574 lines, base/acpid patch is 558 | DSDT (Differentiated System Description Table) | Parsed by `acpi` crate AML interpreter | Working | Platform-specific device config via AML bytecode | | SSDT (Secondary System Description Table) | Parsed by `acpi` crate AML interpreter | Working | Secondary AML tables (hotplug, etc.) | | FACP/FADT | ✅ Full parse in acpid | ✅ Done | PM registers, reset register, sleep states, `\_S5` | -| IVRS (AMD-Vi IOMMU) | Removed (broken stub) | Deferred to P5+ | Needs real AMD IOMMU implementation | +| IVRS (AMD-Vi IOMMU) | Removed from acpid stub path | Handled by `iommu` daemon path | ACPI-side broken stub removed; runtime AMD-Vi handling now lives in the separate daemon | | MCFG (PCI Express config space) | Removed (broken stub) | ✅ Handled by pcid | pcid /config endpoint provides direct PCI config space access | | DBG2 (Debug port) | Not implemented | Low | Serial debug port discovery | | BGRT (Boot graphics) | Not implemented | Low | Boot logo preservation | | FPDT (Firmware perf data) | Not implemented | Low | Boot performance metrics | -IVRS was previously listed as "implemented" but the stub was broken. It has been removed -from acpid. IVRS needs a real AMD IOMMU driver (P5+ scope). MCFG is now handled by -pcid's /config endpoint (P1 complete) which provides direct PCI config space access. +IVRS was previously listed as "implemented" but the acpid stub was broken, so it was removed from +acpid. AMD-Vi runtime handling now lives in the separate `iommu` daemon path rather than in acpid. +MCFG is now handled by pcid's /config endpoint (P1 complete) which provides direct PCI config space +access. ## Implemented ACPI Tables diff --git a/local/docs/AMD-FIRST-INTEGRATION.md b/local/docs/AMD-FIRST-INTEGRATION.md index 6c0f36c7..73d5e085 100644 --- a/local/docs/AMD-FIRST-INTEGRATION.md +++ b/local/docs/AMD-FIRST-INTEGRATION.md @@ -32,9 +32,9 @@ take 5+ years. | ACPI | ✅ Complete | RSDP/SDT checksums, MADT types 0x4/0x5/0x9/0xA, LVT NMI, FADT shutdown/reboot | | x2APIC | ✅ Works | Auto-detected via CPUID, APIC/SMP functional | | HPET | ✅ Works | Timer initialized from ACPI | -| IOMMU | 🚧 In progress | `iommu` daemon now builds, auto-discovers common IVRS table paths, reaches unit detection plus `scheme:iommu` registration in the QEMU/AMD-IOMMU validation path, and now has a guest-driven first-use self-test that reaches MMIO reads; the remaining blocker is a CPU-side completion/DMA-page fault during init, and real hardware validation is still missing | +| IOMMU | 🚧 In progress | `iommu` daemon now builds, auto-discovers common IVRS table paths, reaches unit detection plus `scheme:iommu` registration in the QEMU/AMD-IOMMU validation path, and now has a guest-driven first-use self-test that initializes both discovered units and drains events successfully in QEMU; real hardware validation is still missing | | AMD GPU | 🚧 In progress | MMIO mapped, DC port compiles, MSI-X wired, no hardware validation yet | -| Wi-Fi/BT | ❌ Missing | No wireless support | +| Wi-Fi/BT | 🚧 In progress | Repo now carries bounded wireless scaffolding: one experimental in-tree Bluetooth slice exists, and a bounded Intel Wi-Fi scaffold exists elsewhere, but validated wireless connectivity support is still incomplete | | USB | ⚠️ Variable | Some USB controllers work, others don't | ### Known AMD-Specific Issues @@ -129,7 +129,9 @@ local/recipes/system/firmware-loader/ | SMC | Power management | `smu_*_bin.bin` | | DMCUB | Display controller | `dcn_*_dmcub.bin` | -**Storage**: `local/firmware/amdgpu/` (fetched via `local/scripts/fetch-firmware.sh`) +**Storage**: staged into `/lib/firmware/amdgpu/` for runtime loading. The current local helper +script still fetches AMD blobs from linux-firmware, but the runtime path should now be read as +`/lib/firmware/amdgpu/`, not `/usr/firmware/amdgpu/`. ### P1-3: linux-kpi Compatibility Headers diff --git a/local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md b/local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md index bcf86dc9..a84f391a 100644 --- a/local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md +++ b/local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md @@ -2,13 +2,13 @@ ## Purpose -This document defines the current Bluetooth state in Red Bear OS and lays out a conservative, -implementation-focused roadmap for adding Bluetooth support. +This document defines the current Bluetooth state in Red Bear OS, assesses what the repo now proves +through its bounded first slice, and lays out the conservative roadmap beyond that slice. -The goal is not to imply that Bluetooth already exists in-tree. The goal is to describe what the -repo currently proves, what it does not prove, and how Red Bear can grow from **no Bluetooth -support** to a realistic, host-side Bluetooth stack that fits the existing Redox/Red Bear -architecture. +The goal is to describe what the repo currently proves, what it does not prove, what parts of the +Bluetooth stack are credible versus not credible today, and how Red Bear can grow from **one +bounded experimental Bluetooth slice** toward broader support without overstating current runtime +validation. ## Validation States @@ -24,10 +24,28 @@ This repo should not treat planned scope as equivalent to implemented support. ### Summary -Bluetooth is currently **missing** in Red Bear OS. +Broad Bluetooth support is still **missing** in Red Bear OS, but the repo now carries one bounded +experimental first slice. -The repo has no first-class Bluetooth daemon, no controller transport path, no host stack, no -documented app-facing Bluetooth API, and no profile that can honestly claim Bluetooth support. +That bounded slice is now **QEMU-validated for its claimed scope** through the packaged +`redbear-bluetooth-battery-check` helper and the host-side +`./local/scripts/test-bluetooth-qemu.sh --check` harness. That validation is still narrow and does +not promote the repo to generic Bluetooth maturity. + +That first in-tree slice is deliberately narrow: + +- standalone profile: `config/redbear-bluetooth-experimental.toml` +- transport daemon: `local/recipes/drivers/redbear-btusb/` +- host/control daemon: `local/recipes/system/redbear-btctl/` +- packaged in-guest checker: `redbear-bluetooth-battery-check` +- host QEMU harness: `local/scripts/test-bluetooth-qemu.sh` +- startup model: explicit startup only +- transport model: USB-attached only +- protocol scope: BLE-first only +- autospawn model: **not** wired to USB-class autospawn yet + +This does **not** mean Red Bear has broad Bluetooth support. It means the repo now has one +experimental, profile-scoped bring-up surface instead of zero in-tree Bluetooth components. What the repo *does* have is enough adjacent infrastructure to make a Bluetooth port plausible: @@ -37,24 +55,41 @@ What the repo *does* have is enough adjacent infrastructure to make a Bluetooth - D-Bus plumbing for later desktop compatibility work - an evolving input and hotplug model that could later absorb Bluetooth HID devices +### Feasibility Summary + +Implementing Bluetooth from scratch in Red Bear is **possible**, but only in a narrow, staged +sense. + +The currently credible interpretation is: + +- **feasible**: one experimental USB-attached controller path, one native host daemon, one BLE-first + workload, one CLI/control surface, one hardware-specific validation slice +- **not yet credible**: broad controller coverage, full classic-Bluetooth parity, Bluetooth audio, + or a desktop-equivalent BlueZ replacement in the first pass + +So the answer is not “Bluetooth from scratch is unrealistic,” but it is also not “Bluetooth is just +one more driver.” The feasible first target is a deliberately small subsystem slice. + ### Current Status Matrix | Area | State | Notes | |---|---|---| -| Bluetooth controller support | **missing** | No HCI transport daemon in-tree | -| Bluetooth host stack | **missing** | No L2CAP / ATT / SMP / GATT / RFCOMM stack evidence | -| Pairing / bond database | **missing** | No Bluetooth-specific persistence path documented | +| 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 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 | | Bluetooth HID | **missing** | Could later build on input modernization work | | Bluetooth audio | **missing** | Also blocked by broader desktop audio compatibility work | -| Runtime diagnostics | **partial prerequisite exists** | `redbear-info` model exists, but no Bluetooth integration exists | +| Runtime diagnostics | **partial implemented** | `redbear-info` now reports the bounded Bluetooth transport/control surfaces conservatively | ## Evidence Already In Tree ### Direct negative evidence -- `HARDWARE.md` says Wi-Fi and Bluetooth are not supported yet -- `local/docs/AMD-FIRST-INTEGRATION.md` marks `Wi-Fi/BT` as missing +- `HARDWARE.md` says broad Wi-Fi and Bluetooth support is still incomplete even though bounded + in-tree scaffolding now exists +- `local/docs/AMD-FIRST-INTEGRATION.md` treats `Wi-Fi/BT` as in progress with bounded wireless + scaffolding present but validated connectivity still incomplete ### Positive architectural prerequisites @@ -64,6 +99,8 @@ What the repo *does* have is enough adjacent infrastructure to make a Bluetooth profile-scoped and evidence-backed - `local/docs/PROFILE-MATRIX.md` defines the validation-language model a future Bluetooth path must use +- `local/docs/BLUETOOTH-VALIDATION-RUNBOOK.md` now records the canonical QEMU operator path for the + current bounded Battery Level slice - `local/docs/INPUT-SCHEME-ENHANCEMENT.md` shows the direction of travel for per-device, hotplug, named input sources, which is relevant to later Bluetooth HID support - `config/redbear-kde.toml` and related profile wiring already show D-Bus and desktop-session @@ -86,7 +123,22 @@ At minimum, Red Bear would need: This makes Bluetooth more like networking than like a single peripheral driver. -### 1.1 Minimum Native Subsystem Shape +### 1.1 From-Scratch Scope Reality + +Starting from zero, the minimum Red Bear-native Bluetooth stack is still several layers: + +- controller transport +- HCI command/event handling +- adapter management +- LE scanning and connection lifecycle +- pairing / bonding policy and persistence +- ATT/GATT client work for the first useful BLE workload +- some observable user control/reporting surface + +That means “from scratch” should be read as “new native subsystem assembly from several bounded +components,” not as “write a single daemon and call Bluetooth done.” + +### 1.2 Minimum Native Subsystem Shape The smallest Red Bear-native Bluetooth subsystem should be split into these pieces: @@ -109,7 +161,26 @@ The repo's existing system model strongly favors: That means Bluetooth should be implemented as a native Red Bear subsystem, not described as a wholesale Linux/BlueZ drop-in. -### 2.1 Repo Placement Guidance +### 2.1 BlueZ-equivalent replacement is not the first feasible target + +Red Bear should not frame the initial work as “reimplement BlueZ.” + +That would pull in a much larger surface: + +- broad controller/transport coverage +- full classic + BLE host functionality +- stable D-Bus compatibility shape +- profile breadth beyond the first bounded use case +- much more policy and persistence behavior than the repo currently needs for an initial milestone + +The first feasible target is instead: + +- native Red Bear controller transport daemon +- native Red Bear host daemon +- small native CLI/control path +- later compatibility shim only if real desktop consumers require one + +### 2.2 Repo Placement Guidance Unless upstream Redox grows a first-class Bluetooth path first, the initial Red Bear work should live under `local/`: @@ -133,7 +204,21 @@ The first realistic milestone is much smaller: - one limited workload - experimental support language only -### 3.1 First-Milestone Dependency +### 3.1 BLE-first is materially more feasible than classic-first + +The repo should treat **BLE-first** as the credible from-scratch path. + +Why: + +- it keeps the first useful workload smaller +- it avoids early pressure for classic-audio and broader profile parity +- it matches the repo's current “bounded experimental slice first” discipline +- it reduces the amount of early compatibility behavior that must be correct before any user value + appears + +Classic Bluetooth should therefore be treated as a later expansion, not as the first milestone. + +### 3.2 First-Milestone Dependency If the first supported controller is USB-attached, then Bluetooth Phase B1 depends directly on the USB plan's controller and hotplug baseline work. @@ -142,6 +227,18 @@ In practice that means Bluetooth should not claim a validated first controller p stack can already support that controller family with stable enumeration, attach/detach behavior, and honest runtime diagnostics. +### 3.3 Most credible first controller family + +The most credible first controller family is: + +- one **USB-attached BLE-capable adapter family** with simple host-facing initialization behavior + +The least credible early targets are: + +- UART-attached laptop-integrated controllers that require new board-specific transport bring-up +- broad “internal laptop Bluetooth” claims across mixed Intel/Realtek/MediaTek controller families +- controller families that immediately force a large firmware and vendor-protocol surface + ### 4. Bluetooth scope depends on adjacent subsystems Bluetooth HID depends on the modernized input path. @@ -152,6 +249,60 @@ unfinished for desktop use. That means the Bluetooth roadmap must stay sequenced and should not over-promise audio or broad desktop integration early. +### 4.1 Native host-side Bluetooth is still required even if transport uses compatibility glue + +The Wi-Fi plan already establishes an important repo rule: a compatibility layer can be useful below +the subsystem boundary, but it does not remove the need for a native Red Bear control plane. + +Bluetooth should follow the same rule. + +That means: + +- transport-side glue or borrowed implementation ideas are acceptable +- but adapter management, support language, diagnostics, persistence, and user-visible control + should still be modeled as native Red Bear runtime services + +### 4.2 Bluetooth is gated more by USB maturity than by D-Bus presence + +The repo already has D-Bus packages, but that does **not** make Bluetooth close to done. + +The more important blockers are still: + +- low-level controller/runtime trust +- USB controller correctness and hotplug quality +- a first real transport path +- native host-daemon correctness + +So Bluetooth feasibility should be tied to controller/runtime credibility first, and only later to +desktop compatibility. + +## Recommended From-Scratch Interpretation + +The currently recommended interpretation of “implement Bluetooth from scratch” in this repo is: + +1. do **not** start by chasing broad desktop Bluetooth parity +2. do **not** start by promising internal laptop Bluetooth across all machines +3. do start with one USB-attached adapter family +4. do build one native controller transport daemon plus one native host daemon +5. do target one BLE-first workflow +6. do keep all support language experimental and hardware-specific until real runtime proof exists + +This is the narrowest version of “from scratch” that is still technically meaningful and worth +shipping. + +## Recommended First Deliverable + +The first deliverable Red Bear should actually target is: + +- one standalone `redbear-bluetooth-experimental` profile slice +- one USB Bluetooth transport daemon +- one host/control daemon with bounded scan/status reporting +- one CLI-oriented control path +- one BLE-first workflow boundary +- one validation helper script plus one named runtime surface contract + +That is small enough to be plausible and large enough to count as real Bluetooth work. + ## Implementation Plan ### Repo-fit note @@ -169,7 +320,7 @@ not a recommendation to edit upstream-managed trees outside Red Bear's normal ov **What to do**: -- declare Bluetooth support as absent today +- declare broad Bluetooth support as incomplete today while one bounded experimental slice exists - define validation labels and support language for future Bluetooth work - freeze the first milestone as **host-side, experimental, one controller family, one limited use case** @@ -193,7 +344,7 @@ not a recommendation to edit upstream-managed trees outside Red Bear's normal ov **Recommended first target**: -- one USB-attached Bluetooth controller family +- one USB-attached Bluetooth controller family, BLE-first **Why**: @@ -206,6 +357,8 @@ not a recommendation to edit upstream-managed trees outside Red Bear's normal ov - implement one controller transport daemon - expose adapter presence and basic control through a Red Bear-native runtime surface - ensure the daemon fits the userspace service/scheme model +- keep the first daemon/controller contract narrow enough that the host daemon can be built around + one stable transport instead of a generic multi-transport abstraction from day one **Where**: @@ -222,6 +375,8 @@ not a recommendation to edit upstream-managed trees outside Red Bear's normal ov once a Bluetooth USB class match is ready - before that exists, the first milestone may use explicit Red Bear service startup so the transport daemon can be validated without pretending that USB class autospawn is already solved +- the first in-tree slice now follows exactly that bounded rule: explicit startup only, with no + claim that `xhcid` or another USB class matcher autospawns Bluetooth yet - if Red Bear adds that xHCI class match before it exists upstream, it should be carried as a Red Bear base patch rather than as an unqualified direct tree edit @@ -241,6 +396,8 @@ not a recommendation to edit upstream-managed trees outside Red Bear's normal ov - one supported Bluetooth controller can be detected and initialized repeatedly - controller presence can be reported honestly at runtime +- attach/detach behavior is good enough that controller disappearance does not require reboot to + recover the service path --- @@ -254,6 +411,7 @@ not a recommendation to edit upstream-managed trees outside Red Bear's normal ov - support scanning and connect/disconnect for one limited workload - add persistent pairing/bond storage only once the storage path is explicitly defined - keep the control surface small and Red Bear-native +- keep classic-Bluetooth scope and audio/profile breadth explicitly out of this phase **Where**: @@ -270,9 +428,20 @@ not a recommendation to edit upstream-managed trees outside Red Bear's normal ov - bond database lifecycle rooted at `/var/lib/bluetooth/` - failure reporting suitable for later `redbear-info` integration +**Current in-tree bounded slice**: + +- `redbear-btctl` now ships a minimal file-backed bond store rooted at `/var/lib/bluetooth//bonds/` +- the CLI can add/list/remove **stub** bond records and reload them across process restarts +- the btctl scheme now exposes bounded connect/disconnect control plus read surfaces for connection state and last connect/disconnect results +- the bounded connect path only targets existing stub bond records and keeps connected bond IDs in daemon memory per adapter +- `redbear-info` now reports the bond-store path/count plus bounded connection/result metadata conservatively +- this is explicitly **not** real pairing, link-key exchange, trusted-device policy, validated reconnect behavior, real device traffic, or B3 BLE workload support + **Exit criteria**: - the daemon can rediscover and reconnect to at least one target device class across repeated runs +- the daemon's runtime state is observable enough that future `redbear-info` integration is + straightforward rather than guesswork --- @@ -283,23 +452,39 @@ not a recommendation to edit upstream-managed trees outside Red Bear's normal ov **Recommended first workload**: - BLE-first rather than full classic Bluetooth parity +- specifically, one experimental **battery-sensor Battery Level read** using Battery Service + `0000180f-0000-1000-8000-00805f9b34fb` and Battery Level characteristic + `00002a19-0000-1000-8000-00805f9b34fb` + +**Examples of acceptable first workloads**: + +- one BLE sensor/control workflow +- one bounded BLE peripheral interaction that needs scan/connect/read/write/notify + +**Examples of bad first-workload choices**: + +- generic “all BLE works” +- Bluetooth audio +- broad HID support before the input plan matures **What to do**: - add scan/connect support for one BLE device type -- expose minimal read/write/notify behavior if the chosen workload needs it +- expose only the minimal behavior the chosen workload needs +- for the current B3 slice, that means **read only** for the experimental battery-sensor workload; + this slice does **not** claim write support or notify support - keep support language experimental and hardware-specific **Where**: - host-daemon implementation under `local/recipes/system/` -- package-group wiring in one explicitly experimental Red Bear package-group slice named - `bluetooth-experimental` +- tracked profile wiring in one explicitly experimental Red Bear profile slice named + `redbear-bluetooth-experimental` - validation helper in `local/scripts/` **Recommended support slice**: -- start as one explicitly experimental package-group addition named `bluetooth-experimental` +- start as one explicitly experimental tracked profile named `redbear-bluetooth-experimental` rather than claiming Bluetooth generically across all Red Bear images **Exit criteria**: @@ -393,8 +578,8 @@ expects them instead of importing a whole foreign subsystem model blindly. **Recommended first support language**: -- one explicitly experimental Red Bear package-group slice named `bluetooth-experimental` for the - first supported controller + workload combination +- one explicitly experimental Red Bear profile named `redbear-bluetooth-experimental` for the first + supported controller + workload combination **Where**: @@ -408,13 +593,19 @@ expects them instead of importing a whole foreign subsystem model blindly. - at least one profile can honestly claim validated experimental Bluetooth support for named hardware and named workload scope +**Current in-tree interpretation**: + +- the repo now satisfies the narrower QEMU-scoped version of this exit criterion for one packaged, + stub-backed Battery Level workload on `redbear-bluetooth-experimental` +- it does **not** satisfy a broader real-hardware or generic BLE exit criterion yet + ## Support-Language Guidance Until B1 through B3 exist, Red Bear should use language such as: -- “Bluetooth is not supported yet” -- “Bluetooth remains missing in-tree” -- “Bluetooth is a future implementation workstream” +- “Bluetooth is not broadly supported yet” +- “only the bounded experimental Bluetooth slice exists in-tree” +- “Bluetooth remains a future implementation workstream beyond the documented first slice” Once B1 through B3 begin to land, prefer: @@ -431,11 +622,26 @@ unless the repo has profile-scoped validation evidence to justify those claims. ## Summary -Bluetooth in Red Bear today is not partial support — it is **missing**. +Bluetooth in Red Bear today is still not broad support. + +What now exists is one bounded experimental first slice: explicit-startup, USB-attached, +BLE-first, profile-scoped to `redbear-bluetooth-experimental`, with conservative stub bond-store +persistence rooted at `/var/lib/bluetooth//bonds/` plus bounded connect/disconnect control +that only targets those stored stub bond IDs, plus one experimental battery-sensor Battery Level +read result for the exact Battery Service / Battery Level UUID pair above. That slice can now be +built, booted in QEMU, exercised by the packaged `redbear-bluetooth-battery-check` helper, rerun in +one boot, and rerun after a clean reboot without changing the bounded support claim. What makes it feasible is not any existing Bluetooth stack, but the surrounding Red Bear architecture: userspace daemons, runtime services, diagnostic discipline, profile-scoped support -language, and an evolving per-device input model. +language, firmware/runtime-service patterns, and an evolving per-device input model. + +The practical feasibility judgment is: + +- **yes**, Bluetooth from scratch is possible in Red Bear +- **but only** as a bounded BLE-first, transport-constrained, experimental subsystem slice +- **and no**, the current repo does not justify treating broad Bluetooth or desktop Bluetooth parity + as a near-term from-scratch target That means the right Bluetooth implementation plan is conservative and staged: diff --git a/local/docs/BLUETOOTH-VALIDATION-RUNBOOK.md b/local/docs/BLUETOOTH-VALIDATION-RUNBOOK.md new file mode 100644 index 00000000..6ff4c283 --- /dev/null +++ b/local/docs/BLUETOOTH-VALIDATION-RUNBOOK.md @@ -0,0 +1,96 @@ +# Red Bear OS Bluetooth Validation Runbook + +This runbook is the canonical operator path for exercising the current bounded Bluetooth Battery +Level slice on Red Bear OS. + +It does **not** claim that Bluetooth is broadly solved. Its job is to make the current +profile-scoped, QEMU-validated Battery Level workload reproducible and honest. + +## Goal + +Produce one or both of the following: + +- a successful bounded Bluetooth validation run via `redbear-bluetooth-battery-check` +- a repeatable QEMU/UEFI validation log via `./local/scripts/test-bluetooth-qemu.sh --check` + +## Path A - Host-side QEMU validation + +Use this when the host supports the repo's normal x86_64 QEMU/UEFI flow. + +### On the host + +Build the tracked Bluetooth profile first: + +```bash +./local/scripts/build-redbear.sh redbear-bluetooth-experimental +``` + +Then run the automated QEMU harness: + +```bash +./local/scripts/test-bluetooth-qemu.sh --check +``` + +What that harness does today: + +1. boots `redbear-bluetooth-experimental` in QEMU with `qemu-xhci` +2. logs in automatically on the serial console +3. runs `redbear-bluetooth-battery-check` twice in one boot +4. reboots the guest +5. runs `redbear-bluetooth-battery-check` again after the clean reboot + +### Artifact to preserve + +- the full terminal log from `./local/scripts/test-bluetooth-qemu.sh --check` +- any serial or CI log captured around the run + +## Path B - Interactive guest validation + +Use this when you want to inspect the runtime manually inside the guest. + +### On the host + +```bash +./local/scripts/test-bluetooth-qemu.sh +``` + +### Inside the guest + +Run the packaged checker directly: + +```bash +redbear-bluetooth-battery-check +``` + +The legacy guest helper remains as a compatibility wrapper: + +```bash +test-bluetooth-runtime.sh +``` + +Useful supporting commands inside the guest: + +```bash +redbear-btusb --status +redbear-btctl --status +redbear-info --verbose +``` + +## What success means today + +Current success is still **bounded** success: + +- the explicit-startup `redbear-btusb` and `redbear-btctl` path can be exercised in QEMU +- the packaged checker can be rerun repeatedly in one boot +- the checker covers daemon restart cleanup and disconnect stale-state cleanup within the current + Battery Level slice +- the exact Battery Service / Battery Level UUID pair can be read through the bounded read-only + workload and reported conservatively by `redbear-info` + +This is **not yet** the same as: + +- real controller bring-up proof +- generic BLE or generic GATT maturity +- write support or notify support +- real pairing or broad reconnect semantics +- desktop Bluetooth parity, HID, audio, or passthrough-backed hardware claims diff --git a/local/docs/DESKTOP-STACK-CURRENT-STATUS.md b/local/docs/DESKTOP-STACK-CURRENT-STATUS.md index 9988db6b..51aad5f5 100644 --- a/local/docs/DESKTOP-STACK-CURRENT-STATUS.md +++ b/local/docs/DESKTOP-STACK-CURRENT-STATUS.md @@ -43,7 +43,7 @@ stack are runtime-trusted rather than just build-visible?” | 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; hardware-validated Wayland graphics path still lags | +| 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 | @@ -96,6 +96,23 @@ That gap is the main thing older docs sometimes blur. The software-rendered stack is much further along than the hardware-validated stack. +Current QEMU truth: + +- 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 + +The real hardware-accelerated acceptance target remains the bare-metal/runtime-driver path: + +- `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 + The desktop stack therefore should not over-claim hardware-ready Wayland/KDE support yet. ### 3. KDE build progress is ahead of session maturity diff --git a/local/docs/EXTERNAL-TOOLCHAIN.md b/local/docs/EXTERNAL-TOOLCHAIN.md new file mode 100644 index 00000000..771d66a8 --- /dev/null +++ b/local/docs/EXTERNAL-TOOLCHAIN.md @@ -0,0 +1,83 @@ +# External Redox Toolchain Export + +This repo already builds the Redox cross toolchain into: + +```text +prefix/x86_64-unknown-redox/sysroot +``` + +That works for in-tree builds, but it is awkward for external consumers because: + +- the checkout path leaks into ad hoc scripts and CMake files, +- `pkg-config` and `llvm-config` need host-side wrappers, +- consumers usually want a single directory they can add to `PATH`. + +## Proposed Export Shape + +Export a standalone toolchain directory: + +```text +/ +├── activate.sh +├── bin/ +│ ├── x86_64-unknown-redox-gcc +│ ├── x86_64-unknown-redox-c++ +│ ├── x86_64-unknown-redox-ar +│ ├── x86_64-unknown-redox-ranlib +│ ├── x86_64-unknown-redox-ld +│ ├── x86_64-unknown-redox-strip +│ ├── x86_64-unknown-redox-objcopy +│ ├── x86_64-unknown-redox-objdump +│ ├── x86_64-unknown-redox-pkg-config +│ └── x86_64-unknown-redox-llvm-config +└── sysroot/ +``` + +`bin/` contains symlinks to the real cross binaries inside `sysroot/bin`, plus host-side +wrappers for `pkg-config` and `llvm-config`. + +## Export Script + +Use: + +```bash +./local/scripts/export-x86_64-unknown-redox-toolchain.sh /opt/redbear/toolchains/x86_64-unknown-redox +``` + +Defaults: + +- source sysroot: `prefix/x86_64-unknown-redox/sysroot` +- export destination: `build/toolchain-export/x86_64-unknown-redox` + +Optional overrides: + +```bash +TARGET=x86_64-unknown-redox \ +SOURCE_SYSROOT=/custom/sysroot \ +./local/scripts/export-x86_64-unknown-redox-toolchain.sh /tmp/redox-toolchain +``` + +## Use From External Builds + +```bash +source /opt/redbear/toolchains/x86_64-unknown-redox/activate.sh +x86_64-unknown-redox-gcc --version +``` + +`activate.sh` exports: + +- `PATH=/bin:/sysroot/bin:$PATH` +- `TARGET=x86_64-unknown-redox` +- `REDBEAR_REDOX_SYSROOT=/sysroot` +- `COOKBOOK_HOST_SYSROOT=/sysroot` +- `COOKBOOK_SYSROOT=/sysroot` + +That keeps external CMake, Cargo, Meson, and ad hoc builds aligned with the in-tree cookbook +environment. + +## Why This Shape + +- It is relocatable after export. +- It does not require the original repo checkout at runtime. +- It reuses the already-built canonical sysroot from `mk/prefix.mk`. +- It avoids teaching every external project Red Bear-specific path conventions. diff --git a/local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md b/local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md index cd96ce75..a2c67217 100644 --- a/local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md +++ b/local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md @@ -124,7 +124,7 @@ Current runtime-proof entrypoint now present in-tree: ### 3. IOMMU and interrupt remapping -IOMMU is the most important low-level controller area that is still incomplete in practice. +IOMMU was the most important low-level controller area that was still incomplete in practice. - The implementation direction is correct. - The data structures and register model are already documented deeply. @@ -132,15 +132,17 @@ IOMMU is the most important low-level controller area that is still incomplete i only partially integrated: the daemon now searches common IVRS table locations automatically, but full platform-native discovery and hardware validation are still open. - The current QEMU path now reaches AMD-Vi unit detection and `scheme:iommu` registration without - crashing at daemon startup, but unit initialization is still deferred and real hardware validation - remains open. -- The current guest-driven first-use proof now reaches AMD-Vi MMIO reads in QEMU (`control=0x0`, - `status=0x0`), but still dies during the completion path with a CPU-side page fault while touching - the completion-store region. That narrows the remaining blocker to DMA mapping/page-coverage - behavior rather than to missing discovery, missing scheme wiring, or unreadable MMIO registers. + crashing at daemon startup. +- The current guest-driven first-use proof now completes successfully in QEMU: it reaches readable + and writable AMD-Vi MMIO, initializes both discovered units, and drains the event path without + faulting. +- The critical blockers that previously stopped this path were fixed in the shared mapping layers, + not just in the userspace `iommu` daemon: physically contiguous DMA allocations now preserve + writable mappings, and MMIO mappings now use the explicit `fmap` path with the intended protection + bits. -This makes IOMMU the highest-value long-term controller enhancement area after basic MSI-X runtime -validation. +This leaves IOMMU as a hardware-validation and deeper interrupt-remapping quality area, rather than +as an immediate QEMU runtime blocker. ### 4. Input/controller path @@ -241,7 +243,7 @@ Current runtime-validation surface now present in-tree: ### IOMMU / interrupt remapping -**State**: the biggest completeness gap. +**State**: QEMU runtime proof present; broader hardware validation still open. Concrete checked-in owner: @@ -255,8 +257,6 @@ Open enhancement items: - interrupt remapping validation under device load - explicit distinction between “daemon builds” and “controller works” - replacement of `IOMMU_IVRS_PATH`-only discovery with real system discovery/integration -- diagnosis/fix for the remaining QEMU first-use blocker where completion-store CPU access faults - even after MMIO reads and multiple completion-store placement strategies succeed structurally Current implementation improvement: @@ -265,8 +265,8 @@ Current implementation improvement: - daemon startup now defers AMD-Vi unit initialization until first scheme use, which keeps the QEMU validation path alive long enough to prove detection plus `scheme:iommu` registration - a guest-driven self-test path now exists (`/usr/bin/iommu --self-test-init` via - `redbear-phase-iommu-check` / `test-iommu-qemu.sh`) and proves that the remaining failure is in - runtime completion/DMA-page handling, not in daemon startup or bare MMIO readability + `redbear-phase-iommu-check` / `test-iommu-qemu.sh`) and now proves first-use unit initialization + and event-drain completion in QEMU ### Legacy IRQ ownership and dispatch map @@ -450,25 +450,28 @@ Why fifth: Important, but less immediately blocking than MSI-X and IOMMU. -## Priority 6 — xHCI interrupt restoration +## Priority 6 — xHCI interrupt-path hardening This is Priority 6 **within the low-level controller plan itself**, not within the repository-wide subsystem order. At the repo-wide level, low-level controller quality remains ahead of USB/Wi-Fi/ Bluetooth because these later subsystems depend on the controller/runtime proof work documented here. -Goal: move USB host-controller operation from polling back to real interrupt-driven behavior. +Goal: keep USB host-controller operation on the restored interrupt-driven path and harden the proof +surface beyond the current narrow QEMU validation. Deliverables: -- restore the actual `get_int_method` path in `xhcid` +- keep the actual `get_int_method` path in `xhcid` healthy - validate MSI/MSI-X or INTx behavior for xHCI on real hardware and/or QEMU -- update docs so USB controller quality is not overstated while polling remains active +- update docs so USB controller quality is not overstated while broader runtime and hardware + validation remain open Why sixth: -This is a real completeness gap in an important low-level controller, but it is narrower in scope -than the cross-cutting MSI-X and IOMMU priorities above. +This remains a real completeness gap in an important low-level controller, but it is now narrower in +scope than the cross-cutting MSI-X and IOMMU priorities above because the interrupt path itself is +already restored and QEMU-proven. ## Execution Plan @@ -533,8 +536,7 @@ runtime-evidence surface: - `local/scripts/test-xhci-irq-qemu.sh --check` — xHCI interrupt-mode proof from QEMU boot logs - `local/scripts/test-msix-qemu.sh` — live MSI-X proof via `virtio-net` - `local/scripts/test-iommu-qemu.sh --check` — AMD IOMMU device visibility plus guest boot reachability -- `local/scripts/test-usb-storage-qemu.sh` — USB mass-storage autospawn probe (currently still an - active blocker path) +- `local/scripts/test-usb-storage-qemu.sh` — USB mass-storage autospawn probe ## Bottom Line diff --git a/local/docs/NETWORKING-RTL8125-NETCTL.md b/local/docs/NETWORKING-RTL8125-NETCTL.md index ed90afeb..46e29ed7 100644 --- a/local/docs/NETWORKING-RTL8125-NETCTL.md +++ b/local/docs/NETWORKING-RTL8125-NETCTL.md @@ -46,6 +46,76 @@ Red Bear ships a Redox-native `netctl` compatibility command in `redbear-netctl` - `Gateway='a.b.c.d'` - `DNS=('a.b.c.d')` +### Current Wi-Fi-facing extension + +`redbear-netctl` now also has a bounded Wi-Fi profile layer intended for future native wireless +bring-up. + +Current Wi-Fi-facing fields: + +- `Interface=wlan0` (or another future wireless interface name) +- `Connection=wifi` +- `SSID='...'` +- `Security=open|wpa2-psk` +- `Key='...'` / `Passphrase='...'` + +Current boundary: + +- `redbear-netctl` can parse and start these profiles +- it writes Wi-Fi intent and credentials into the in-tree `/scheme/wifictl` control surface +- it reuses the native `netcfg`/`dhcpd` handoff only after association +- it is **not** the supplicant and does not currently implement scan/auth/association itself + +Current orchestration order for Intel Wi‑Fi profiles: + +- `prepare` +- `init-transport` +- `activate-nic` +- `connect` + +Current orchestration order for `netctl scan` on Intel Wi‑Fi profiles: + +- `prepare` +- `init-transport` +- `activate-nic` +- `scan` + +The current Intel backend will not attempt `scan` or `connect` until transport initialization has +been attempted. + +The current user-facing Wi‑Fi subcommands are: + +- `netctl scan ` +- `netctl status ` with Wi‑Fi status, link state, firmware status, transport status, transport-init status, activation status, and last error + +The current `redbear-wifictl` daemon provides: + +- a bounded stub backend for end-to-end profile/control validation +- an Intel-oriented backend boundary that detects Intel wireless-class PCI devices +- firmware-family and firmware-presence reporting for the Intel target boundary +- a bounded `prepare` step before connect +- transport-readiness reporting for the detected Intel device +- a bounded `scan` action and per-interface `scan-results` +- a bounded PCI transport-prep action before connect +- a bounded `init-transport` state after preparation and before connect +- a bounded `activate-nic` state after transport initialization and before connect/scan +- per-interface Wi-Fi state files under `/scheme/wifictl/ifaces//...` + +Below that control plane, the current repo also contains the first bounded Intel driver-side package: + +- `local/recipes/drivers/redbear-iwlwifi/` + +Current bounded driver-side actions: + +- `redbear-iwlwifi --probe` +- `redbear-iwlwifi --status ` +- `redbear-iwlwifi --prepare ` +- `redbear-iwlwifi --transport-probe ` +- `redbear-iwlwifi --init-transport ` +- `redbear-iwlwifi --activate-nic ` +- `redbear-iwlwifi --scan ` +- `redbear-iwlwifi --retry ` + ### Supported commands - `netctl list` @@ -56,6 +126,7 @@ Red Bear ships a Redox-native `netctl` compatibility command in `redbear-netctl` - `netctl disable [profile]` - `netctl is-enabled [profile]` - `netctl --boot` +- `netctl scan ` Profiles live in `/etc/netctl`. Shipped examples live in `/etc/netctl/examples/`. @@ -74,6 +145,10 @@ base networking services have started. - `redbear-netctl` was type-checked and smoke-tested with a fake runtime root by exercising: `list`, `enable`, `status`, and `start`. +- the Wi-Fi profile flow was also exercised with a fake runtime root by starting a + `Connection=wifi` / `Interface=wlan0` profile and verifying that `SSID`, `Security`, `Key`, and + `connect` were written to the fake `/scheme/wifictl` tree while `status` reported the Wi-Fi + profile correctly - `rtl8168d` type-checks with the RTL8125 autoload configuration in place. - relibc type-checks with the interface and header updates in place. - `./local/scripts/validate-vm-network-baseline.sh` verifies the repo-level VM boot chain for diff --git a/local/docs/PHASE-0-3-REASSESSMENT.md b/local/docs/PHASE-0-3-REASSESSMENT.md index 71c858b4..972d9917 100644 --- a/local/docs/PHASE-0-3-REASSESSMENT.md +++ b/local/docs/PHASE-0-3-REASSESSMENT.md @@ -188,7 +188,7 @@ real gap is **runtime and downstream-consumer validation**: login prompt over the serial console. - `pcid-spawner` successfully spawned `virtio-netd` during the guest boot sequence. - `firmware-loader` registered `scheme:firmware` without crashing, even with an empty - `/usr/firmware/` directory. +`/lib/firmware/` directory. - `evdevd` registered `scheme:evdev` and `udev-shim` registered `scheme:udev` during the same guest boot. - `redbear-info --json` inside the guest reported `virtio_net_present: true`, a configured diff --git a/local/docs/PROFILE-MATRIX.md b/local/docs/PROFILE-MATRIX.md index 94ef9d19..370656d8 100644 --- a/local/docs/PROFILE-MATRIX.md +++ b/local/docs/PROFILE-MATRIX.md @@ -23,8 +23,10 @@ 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-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 graphics-runtime path | +| `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-live` | Live and recovery image layered on desktop | `redbear-desktop.toml` | builds | @@ -38,6 +40,29 @@ USB plan uses: - Enables the shared `wired-dhcp` netctl profile by default for the Phase 2 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` + +- Standalone tracked profile for the first in-tree Bluetooth slice instead of a blanket claim about + 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 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. + +### `redbear-wifi-experimental` + +- Standalone tracked profile for the current bounded Intel Wi-Fi slice instead of implying that the + wider desktop profiles already carry the full driver stack. +- Extends `redbear-minimal` so the baseline firmware/input/reporting/profile-manager surface stays + inherited while the Intel Wi-Fi driver package and bounded validation role remain isolated here. +- Includes the Intel driver package (`redbear-iwlwifi`) in addition to the shared firmware, + control-plane, reporting, and profile-manager pieces. +- Current support language is intentionally narrow: bounded probe/prepare/init/activate/scan/ + connect/disconnect lifecycle, packaged in-target validation and capture commands, and no claim yet + of validated real AP association or end-to-end Wi-Fi connectivity. + ### `redbear-desktop` - Carries the standard Red Bear desktop-facing package additions. @@ -50,6 +75,8 @@ USB plan uses: - 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`. - 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. ### `redbear-full` @@ -68,3 +95,13 @@ USB plan uses: - Intended for install, demo, and recovery workflows. - Should inherit only stable desktop-profile assumptions unless explicitly documented. + +## Bluetooth Note + +- `redbear-bluetooth-experimental` is now the tracked first Bluetooth-specific profile. +- Its support language remains experimental and bounded; it should not be used to imply Bluetooth + support across the wider Red Bear profile set. +- The current bounded BLE workload is one read-only battery-sensor Battery Level interaction; this + 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. diff --git a/local/docs/QT6-PORT-STATUS.md b/local/docs/QT6-PORT-STATUS.md index 6ededf8e..5fcaca9d 100644 --- a/local/docs/QT6-PORT-STATUS.md +++ b/local/docs/QT6-PORT-STATUS.md @@ -275,7 +275,7 @@ Graphics stack (PRIMARY DELIVERABLE): KWin recipe updated with 40 dependencies (all KF6 + Mesa + libdrm + libinput + qtwayland). plasma-workspace, plasma-desktop recipes created. -### Phase 4 — Graphics Stack (✅ COMPLETE) +### Phase 4 — Graphics Stack (✅ build-side complete, 🚧 runtime incomplete) Mesa EGL+GBM+GLES2 built: - libEGL.so (225KB) — platforms: redox, surfaceless, drm @@ -295,12 +295,25 @@ Qt6 OpenGL enabled: - libQt6EglFSDeviceIntegration.so — EGLFS platform integration - EGLFS KMS plugin for direct DRM/KMS rendering -### Phase 4b — Qt6 OpenGL Enablement (✅ COMPLETE) +Current truth for Phase 4: + +- the graphics stack now builds end to end: Mesa EGL+GBM+GLES2, libdrm amdgpu, Qt6 OpenGL/EGL, + and qtwayland all stage successfully +- the current `redbear-wayland` validation profile is still a bounded smallvil-first runtime path, + not proof of a hardware-accelerated desktop session +- the current QEMU validation harness is still software-rendered (`llvmpipe`) and should be treated + 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 + AMD/Intel hardware validation through the DRM → GBM/EGL → compositor → Qt client path + +### Phase 4b — Qt6 OpenGL Enablement (✅ build-side complete, 🚧 runtime incomplete) qtbase rebuilt with `-DFEATURE_opengl=ON -DINPUT_opengl=es2 -DFEATURE_egl=ON` Qt cmake summary: EGL=yes, OpenGL=yes, "OpenGL ES 2.0=yes, EGLFS GBM=yes" -### Phase 5 — KDE Plasma (🔄 IN PROGRESS) +### Phase 5 — KDE Plasma / desktop-session layer (🔄 IN PROGRESS) KDE Plasma packages built: - kf6-kwayland ✅ BUILT @@ -327,7 +340,7 @@ Phase 1 ✅ (qtbase + qtdeclarative + qtsvg) └── Phase 2b ✅ (qtwayland built) └── Phase 2c ✅ (libevdev + libinput built) └── Phase 3 ✅ (KF6 — ALL 32 frameworks built) - └── Phase 4 ✅ (Mesa EGL+GBM+GLES2, Qt6 OpenGL+EGL, libdrm amdgpu) + └── Phase 4 ✅ build-side / 🚧 runtime (Mesa EGL+GBM+GLES2, Qt6 OpenGL+EGL, libdrm amdgpu) └── Phase 5 🔄 (kdecoration ✅, kf6-kwayland ✅, kirigami stub-only, KWin still blocked on shimmed/scaffolded deps) ``` diff --git a/local/docs/REDBEAR-INFO-RUNTIME-REPORT.md b/local/docs/REDBEAR-INFO-RUNTIME-REPORT.md index 9e9cd9d8..cfd9c6d8 100644 --- a/local/docs/REDBEAR-INFO-RUNTIME-REPORT.md +++ b/local/docs/REDBEAR-INFO-RUNTIME-REPORT.md @@ -34,13 +34,15 @@ are hardware-validated at runtime. - **Identity** — OS name, version, hostname - **Networking** — stack state, connected flag, interface, MAC, IP/CIDR, DNS, default route, - active `netctl` profile, visible `network.*` schemes + active `netctl` profile, visible `network.*` schemes, Wi-Fi control/firmware/transport surfaces, + and bounded Bluetooth transport/control visibility - **Hardware** — PCI device count, USB controller count, DRM card count, RTL8125 PCI visibility - **Hardware** — PCI device count, USB controller count, DRM card count, RTL8125 PCI visibility, VirtIO NIC visibility for VM baselines - **Integrations** — tools, daemons, and integration paths such as `lspci`, `lsusb`, `netctl`, - `pcid-spawner`, `smolnetd`, `firmware-loader`, `udev-shim`, `evdevd`, `redox-drm`, and the - native RTL8125 and VirtIO networking paths + `pcid-spawner`, `smolnetd`, `firmware-loader`, `udev-shim`, `evdevd`, `redox-drm`, + `redbear-wifictl`, `redbear-btusb`, `redbear-btctl`, and the native RTL8125 and VirtIO + networking paths For Phase 3 runtime validation, `udev-shim` is expected at `/usr/bin/udev-shim` and `evdevd` is expected at both `/usr/bin/evdevd` and `/usr/lib/drivers/evdevd` so service execution and runtime @@ -66,5 +68,8 @@ That includes new: - hardware integration paths - configuration layers that users rely on to debug a running image +Recent examples include the Wi-Fi control-plane surfaces and the bounded Bluetooth first-slice +surfaces, both of which extend the runtime report without over-claiming hardware validation. + The goal is for `redbear-info` to remain the first command users run when they need to understand the state of a Red Bear system. diff --git a/local/docs/SCRIPT-BEHAVIOR-MATRIX.md b/local/docs/SCRIPT-BEHAVIOR-MATRIX.md index 42c4396a..7f3dcb79 100644 --- a/local/docs/SCRIPT-BEHAVIOR-MATRIX.md +++ b/local/docs/SCRIPT-BEHAVIOR-MATRIX.md @@ -16,6 +16,39 @@ The goal is to remove guesswork from the sync/fetch/apply/build workflow. | `local/scripts/build-redbear.sh` | Build Red Bear profiles from upstream base + local overlay | applies overlays, builds cookbook if needed, validates profile naming, launches the actual image build | does not guarantee every nested upstream source tree is fresh; does not replace explicit subsystem/runtime validation | | `scripts/fetch-all-sources.sh` | Fetch recipe source inputs for builds | downloads recipe sources for upstream and local recipes, reports status/preflight, supports config-scoped fetches | does not mean fetched upstream WIP source is the durable shipping source of truth | | `local/scripts/fetch-sources.sh` | Fetch local overlay source inputs | fetches local overlay recipe sources and keeps the local side ready for build work | does not decide whether upstream should replace the local overlay | +| `local/scripts/build-redbear-wifictl-redox.sh` | Build `redbear-wifictl` for the Redox target with the repo toolchain | prepends `prefix/x86_64-unknown-redox/sysroot/bin` to `PATH` and runs `cargo build --target x86_64-unknown-redox` in the `redbear-wifictl` crate | does not prove runtime Wi-Fi behavior; only closes the target-build environment gap for this crate | +| `local/scripts/test-iwlwifi-driver-runtime.sh` | Exercise the bounded Intel driver lifecycle inside a target runtime | validates bounded probe/prepare/init/activate/scan/connect/disconnect/retry surfaces for `redbear-iwlwifi` on a live target runtime | does not prove real AP association, packet flow, DHCP success over Wi-Fi, or end-to-end connectivity | +| `local/scripts/test-wifi-control-runtime.sh` | Exercise the bounded Wi-Fi control/profile lifecycle inside a target runtime | validates `/scheme/wifictl` control nodes, bounded connect/disconnect behavior, and profile-manager/runtime reporting surfaces on a live target runtime | does not prove real AP association or end-to-end connectivity | +| `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/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 | +| `local/scripts/package-wifi-validation-artifacts.sh` | Bundle Wi-Fi validation evidence into one archive | packages common capture/log artifacts from bare-metal or VFIO validation runs into a single tarball | does not create missing artifacts or validate their contents | +| `local/scripts/summarize-wifi-validation-artifacts.sh` | Summarize Wi-Fi validation evidence quickly | extracts key runtime signals from a capture JSON or packaged tarball for fast triage | does not replace full artifact review or prove runtime correctness | +| `local/scripts/finalize-wifi-validation-run.sh` | One-shot post-run Wi-Fi triage helper | runs the packaged analyzer on a capture JSON and then packages the chosen artifacts into a tarball | still depends on a real target run having produced the capture/artifacts first | + +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 evidence companion is `redbear-phase5-wifi-capture`, which collects the bounded driver, +control, profile-manager, reporting, interface-listing, and scheme-state surfaces — plus `lspci` +and active-profile contents — into a single JSON artifact. + +The packaged link-oriented companion is `redbear-phase5-wifi-link-check`, which focuses on whether +the target runtime is exposing interface/address/default-route signals in addition to the bounded +Wi-Fi lifecycle state. + +For Redox-target Rust builds of Wi-Fi components such as `redbear-wifictl`, a missing +`x86_64-unknown-redox-gcc` on `PATH` should first be treated as a host toolchain/path issue if the +repo already contains `prefix/x86_64-unknown-redox/sysroot/bin/x86_64-unknown-redox-gcc`. ## Policy Mapping diff --git a/local/docs/USB-IMPLEMENTATION-PLAN.md b/local/docs/USB-IMPLEMENTATION-PLAN.md index 056dfe43..2f05c07a 100644 --- a/local/docs/USB-IMPLEMENTATION-PLAN.md +++ b/local/docs/USB-IMPLEMENTATION-PLAN.md @@ -40,8 +40,8 @@ The current limitations are material: - 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 autospawn is now re-enabled for validation, but the current - blocker has moved to post-spawn runtime stability rather than driver matching. +- 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. - there is no evidence of validated support for broader USB classes or modern USB-C / dual-role scope @@ -59,7 +59,7 @@ The current limitations are material: | 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 | **absent / undocumented** | No evidence of working support | +| 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 | ## Evidence Already In Tree @@ -90,8 +90,8 @@ The current limitations are material: - `recipes/core/base/source/drivers/usb/xhcid/src/xhci/irq_reactor.rs` now contains event-ring growth logic, but the restored interrupt path still needs stronger validation under sustained runtime load - `recipes/core/base/source/drivers/usb/xhcid/drivers.toml` now re-enables USB SCSI autospawn with explicit protocol matching for BOT (`0x50`) -- `recipes/core/base/source/drivers/COMMUNITY-HW.md` still claims there is no Redox xHCI driver, - which means inherited USB docs cannot be treated as uniformly current +- `recipes/core/base/source/drivers/COMMUNITY-HW.md` is a historical/community request ledger and + cannot be treated as a canonical current-state source for xHCI support ## Current Gaps and Limits @@ -368,7 +368,8 @@ 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 but is not currently enabled as a default working path” +- “USB storage support exists in-tree and is QEMU-proven for the current validation path, but is + not yet a broad hardware support claim” ## Summary diff --git a/local/docs/WIFI-IMPLEMENTATION-PLAN.md b/local/docs/WIFI-IMPLEMENTATION-PLAN.md index 23136847..539d00c4 100644 --- a/local/docs/WIFI-IMPLEMENTATION-PLAN.md +++ b/local/docs/WIFI-IMPLEMENTATION-PLAN.md @@ -5,10 +5,10 @@ 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. -The goal is not to imply that Wi-Fi already exists in-tree. The goal is to describe what the repo +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 **no Wi-Fi support** to one experimental, validated Wi-Fi path that fits the existing Redox / -Red Bear architecture. +from a **bounded experimental Intel Wi-Fi scaffold** to one experimental, validated Wi-Fi path that +fits the existing Redox / Red Bear architecture. ## Validation States @@ -25,10 +25,12 @@ This repo should not treat planned wireless scope as equivalent to implemented s ### Summary -Wi-Fi is currently **missing** in Red Bear OS. +Wi-Fi is currently **not supported as working connectivity** in Red Bear OS. -There is no in-tree Wi-Fi driver, no wireless daemon, no cfg80211/mac80211/nl80211-compatible -surface, no supplicant path, and no profile that can honestly claim Wi-Fi support. +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: @@ -43,20 +45,22 @@ What the repo *does* have is a meaningful set of prerequisites: | Area | State | Notes | |---|---|---| -| Wi-Fi controller support | **missing** | No PCIe/USB/SDIO Wi-Fi driver recipes in-tree | -| Linux wireless stack compatibility | **missing** | No cfg80211/mac80211/nl80211/wiphy support in `linux-kpi` | +| 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 initial `cfg80211` / `wiphy` / `mac80211` registration and station-mode compatibility scaffolding, but not a complete Linux wireless stack | | Firmware loading | **partial prerequisite exists** | `firmware-loader` can serve firmware blobs generically | -| Wireless control plane | **missing** | No scan/auth/association/link-state daemon or CLI | +| 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 | **partial prerequisite exists** | `redbear-info` model exists, but no Wi-Fi integration exists | +| 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 negative evidence +### Direct current-state caution about supported connectivity -- `HARDWARE.md` says Wi-Fi and Bluetooth are not supported yet -- `local/docs/AMD-FIRST-INTEGRATION.md` marks `Wi-Fi/BT` as missing +- `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 @@ -104,7 +108,8 @@ Current `linux-kpi` is suitable for low-level driver-enablement work such as: - 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 has no in-tree: +Current `linux-kpi` is **not** a complete Wi-Fi architecture because the repo still has no in-tree, +complete: - cfg80211 - mac80211 @@ -119,76 +124,326 @@ stack. The current native network stack is useful, but not yet Wi-Fi-ready. -`redbear-netctl` only supports: +`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` -- `Interface=eth0` -- DHCP/static address, route, and DNS control +- `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 -`netcfg` is similarly hard-wired around the current `eth0` interface model. +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. FullMAC is a better first target than SoftMAC +### 4. Intel target changes the first-driver strategy -The first Wi-Fi target should minimize the amount of 802.11 MAC and Linux wireless subsystem logic -that Red Bear has to recreate. +The original version of this plan preferred a FullMAC-first path to avoid recreating Linux wireless +subsystem boundaries. -That makes **FullMAC** hardware the best first target class. +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**. -Red Bear should explicitly avoid starting with SoftMAC/mac80211-style Linux drivers such as: +That means the first realistic driver family is now Intel `iwlwifi`-class hardware rather than an +unspecified FullMAC family. -- Intel `iwlwifi` -- Realtek `rtw88` / `rtw89` -- MediaTek `mt76` -- other drivers that fundamentally assume cfg80211/mac80211 semantics +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 Red Bear Wi-Fi architecture is: +The best current Red Bear Wi-Fi architecture for the Intel target is: -1. **native Red Bear wireless control plane** -2. **one experimental FullMAC driver family first** -3. **reuse `redox-driver-sys` + `firmware-loader` directly** -4. **use `linux-kpi` only where it reduces low-level glue cost** +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 a hybrid architecture, but it is **native-first**, not Linux-stack-first. +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 chosen chipset family +- 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 remain the post-association IP -profile tool, or be generalized later, but it should not own scan/auth/association itself. +`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 +- this new scaffolding is compile- and host-test-validated inside the `linux-kpi` crate +- 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, 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()`, the new + `sk_buff` headroom/tailroom helpers, 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. ## Hardware Strategy -### First decision gate +### Target hardware scope -Before implementation begins, Red Bear must choose **one** first Wi-Fi family from actual target -machines or bring-up hardware. +The target scope for this plan is now: -The preferred target order is: +- **Intel Wi-Fi chips used on Arrow Lake and older Intel client platforms** -1. **PCIe FullMAC** — if a real Red Bear target machine in the hardware matrix has one -2. **USB FullMAC** — if PCIe FullMAC hardware is not available, use this as the first prototype path +That includes the practical `iwlwifi` family boundary, not an abstract FullMAC-first family chosen +for architectural neatness. -### What not to choose for phase 1 +### What this means for phase 1 -Do not start with: +Phase 1 is no longer “pick any convenient Wi-Fi family.” -- Intel laptop Wi-Fi via `iwlwifi` -- mac80211/cfg80211-dependent Linux drivers -- any phase-1 scope that requires recreating a Linux wireless stack first +Phase 1 is now: + +- prove one bounded Intel client Wi-Fi path, +- keep the support language experimental, +- and avoid promising the entire Linux wireless stack up front. ## Security Scope Freeze @@ -212,38 +467,113 @@ This scope freeze is required to keep the first milestone honest and achievable. ## 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. **What to do**: -- choose one target FullMAC family from actual hardware +- 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-group slice for first Wi-Fi support +- define `net-wifi-experimental` as the package/config slice for first Wi-Fi support - document unsupported wireless features explicitly **Exit criteria**: -- one hardware family is selected +- 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 W1 — Driver Substrate Fit +### Phase W1 — Intel Driver Substrate Fit -**Goal**: Prove the chosen Wi-Fi family can fit Red Bear’s existing driver primitives. +**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 chosen device family onto `redox-driver-sys` +- map the Intel target family onto `redox-driver-sys` - verify firmware naming and fetch path through `firmware-loader` -- decide whether any narrow `linux-kpi` glue is useful for that family -- keep `linux-kpi` below the wireless control-plane boundary +- 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 chosen device can be discovered, initialized, and paired with its firmware-loading path +- one Intel target device can be discovered, initialized, and paired with its firmware-loading path --- @@ -341,12 +671,12 @@ This scope freeze is required to keep the first milestone honest and achievable. ### Phase W7 — Broader Hardware and `linux-kpi` Reassessment -**Goal**: Reassess whether Red Bear wants to widen Wi‑Fi support after one FullMAC path works. +**Goal**: Reassess whether Red Bear wants to widen Wi‑Fi support after one bounded Intel path works. **What to do**: -- only after one FullMAC family is validated, decide whether a wider SoftMAC / deeper `linux-kpi` - path is worth the cost +- 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**: @@ -375,7 +705,7 @@ Until the validation gates above are passed, Red Bear should use language such a - “Wi-Fi is not supported yet” - “Wi-Fi remains experimental and hardware-specific” -- “The current wireless path is an experimental FullMAC-first bring-up” +- “The current wireless path is an experimental Intel bounded-transport bring-up” Avoid language such as: @@ -390,7 +720,7 @@ unless profile-scoped validation evidence exists. The best Red Bear Wi-Fi path is **native-first**: - native wireless control plane -- one experimental FullMAC family first +- one experimental bounded Intel family path first - `firmware-loader` + `redox-driver-sys` underneath - optional narrow `linux-kpi` glue only where useful - native `smolnetd` / `netcfg` / `redbear-netctl` reused only after association diff --git a/local/docs/WIFI-VALIDATION-ISSUE-TEMPLATE.md b/local/docs/WIFI-VALIDATION-ISSUE-TEMPLATE.md new file mode 100644 index 00000000..4bdf040f --- /dev/null +++ b/local/docs/WIFI-VALIDATION-ISSUE-TEMPLATE.md @@ -0,0 +1,78 @@ +# Wi‑Fi Validation Issue Template + +Use this template after the first real bare-metal or VFIO-backed Intel Wi‑Fi validation run. + +## Environment + +- Run type: bare metal / VFIO-backed guest +- Host PCI BDF (if VFIO): +- Expected host driver before VFIO (if applicable): +- Red Bear profile: `wifi-open-bounded` / `wifi-dhcp` / other +- Interface: `wlan0` / other +- Intel device model: + +## Commands Used + +List the exact command(s) you ran, for example: + +```bash +redbear-phase5-wifi-run wifi-open-bounded wlan0 /tmp/redbear-phase5-wifi-capture.json +``` + +or + +```bash +./local/scripts/run-wifi-passthrough-validation.sh --host-pci 0000:xx:yy.z --host-driver iwlwifi --artifact-dir ./wifi-validation-YYYYMMDD-HHMMSS +``` + +## Expected Outcome + +Describe what you expected to happen. + +## Actual Outcome + +Describe what actually happened. + +## Artifact Paths + +- Capture JSON: +- Metadata JSON (if VFIO): +- Packaged tarball (if created): +- Serial log: +- Console log: + +## Analyzer Output + +Paste the output of: + +```bash +redbear-phase5-wifi-analyze +``` + +## Key Signals + +- `driver_probe` result: +- `driver_status` result: +- `wifictl_probe` result: +- `wifictl_status` result: +- `netctl_status` result: +- `wifi_connect_result`: +- `wifi_disconnect_result`: +- `last_error`: + +## Suspected Blocker Class + +One or more of: + +- device-detection +- firmware +- association-control-path +- disconnect-lifecycle +- dhcp-or-addressing +- reporting-surface +- runtime-failure +- bounded-lifecycle-pass-no-real-link-proof + +## Notes + +Anything else that seems relevant for reproducing or narrowing the issue. diff --git a/local/docs/WIFI-VALIDATION-RUNBOOK.md b/local/docs/WIFI-VALIDATION-RUNBOOK.md new file mode 100644 index 00000000..50e0d1d7 --- /dev/null +++ b/local/docs/WIFI-VALIDATION-RUNBOOK.md @@ -0,0 +1,215 @@ +# Red Bear OS Wi‑Fi Validation Runbook + +This runbook is the canonical operator path for exercising the current bounded Intel Wi‑Fi stack on +either a real Red Bear OS target or a VFIO-backed Red Bear guest. + +It does **not** claim that Wi‑Fi is fully solved. Its job is to make the remaining hardware/runtime +validation step reproducible and evidence-oriented. + +## Goal + +Produce one or both of the following from a real target execution: + +- a successful bounded Wi‑Fi lifecycle run (`redbear-phase5-wifi-check`) +- a structured evidence bundle (`redbear-phase5-wifi-capture`) for debugging real failures + +## Path A — Bare Metal Runtime Validation + +Use this when Red Bear OS is booted on a real machine with a supported Intel Wi‑Fi device. + +### In target runtime + +For an interactive operator path before or alongside the packaged checkers, the new console client is: + +```bash +redbear-netctl-console +``` + +It is a Redox-native **ncurses** terminal client, and it uses the same bounded `/scheme/wifictl` +and `/etc/netctl` surfaces as the scripted/operator flows. + +```bash +redbear-phase5-wifi-run wifi-open-bounded wlan0 /tmp/redbear-phase5-wifi-capture.json +test-wifi-baremetal-runtime.sh +``` + +### Artifacts to preserve + +- `/tmp/redbear-phase5-wifi-capture.json` +- terminal output from `redbear-phase5-wifi-check` +- terminal output from `test-wifi-baremetal-runtime.sh` +- any serial console log captured during the run + +Recommended host-side naming after copying artifacts off the target: + +- `wifi-baremetal-capture.json` +- `wifi-baremetal-serial.log` +- `wifi-baremetal-console.log` + +Recommended staging pattern on the host: + +```bash +run_dir=./wifi-baremetal-$(date +%Y%m%d-%H%M%S) +mkdir -p "$run_dir" +# copy the capture/log files into that directory +./local/scripts/package-wifi-validation-artifacts.sh \ + "${run_dir}.tar.gz" \ + "$run_dir" +``` + +Optional packaging step on the host: + +```bash +./local/scripts/package-wifi-validation-artifacts.sh +``` + +The resulting tarball now includes a small manifest file with the packaged paths and file checksums +for regular files when `sha256sum` is available on the host. + +Optional summary step on the host: + +```bash +./local/scripts/summarize-wifi-validation-artifacts.sh ./wifi-baremetal-capture.json +# or +./local/scripts/summarize-wifi-validation-artifacts.sh ./wifi-validation-artifacts.tar.gz +# or use the packaged analyzer directly on the captured JSON +redbear-phase5-wifi-analyze ./wifi-baremetal-capture.json +``` + +Optional one-shot post-run step on the host: + +```bash +./local/scripts/finalize-wifi-validation-run.sh \ + ./wifi-baremetal-capture.json \ + ./wifi-validation-artifacts.tar.gz \ + ./wifi-baremetal-serial.log \ + ./wifi-baremetal-console.log +``` + +## Path B — VFIO/QEMU Validation + +Use this when a host can safely detach an Intel Wi‑Fi PCI function and pass it through to a Red Bear +guest. + +### On the host + +First, validate the host prerequisites: + +```bash +sudo ./local/scripts/validate-wifi-vfio-host.sh \ + --host-pci 0000:xx:yy.z \ + --expect-driver iwlwifi +``` + +This preflight now exits non-zero when blockers are found, so it is safe to use as an automation +gate before attempting VFIO passthrough validation. + +Then run the full passthrough validation wrapper: + +```bash +sudo ./local/scripts/run-wifi-passthrough-validation.sh \ + --host-pci 0000:xx:yy.z \ + --host-driver iwlwifi \ + --artifact-dir ./wifi-validation-$(date +%Y%m%d-%H%M%S) +``` + +Default output artifacts from that wrapper: + +- `./wifi-passthrough-capture.json` +- `./wifi-passthrough-capture.json.meta.json` + +If `--artifact-dir` is provided, those files are written into that directory instead. + +Recommended packaging step afterwards: + +```bash +./local/scripts/package-wifi-validation-artifacts.sh \ + ./wifi-passthrough-artifacts.tar.gz \ + ./wifi-validation-YYYYMMDD-HHMMSS +``` + +That tarball also includes the manifest/checksum file described above. + +Optional summary step afterwards: + +```bash +./local/scripts/summarize-wifi-validation-artifacts.sh ./wifi-passthrough-artifacts.tar.gz +# or +redbear-phase5-wifi-analyze ./wifi-passthrough-capture.json +``` + +Optional one-shot post-run step afterwards: + +```bash +./local/scripts/finalize-wifi-validation-run.sh \ + ./wifi-passthrough-capture.json \ + ./wifi-passthrough-artifacts.tar.gz \ + ./wifi-passthrough-capture.json.meta.json +``` + +For structured follow-up after a failed run, use: + +- `local/docs/WIFI-VALIDATION-ISSUE-TEMPLATE.md` + +You can override those paths explicitly if needed: + +```bash +sudo ./local/scripts/run-wifi-passthrough-validation.sh \ + --host-pci 0000:xx:yy.z \ + --host-driver iwlwifi \ + --capture-output ./wifi-passthrough-capture.json \ + --metadata-output ./wifi-passthrough-capture.meta.json +``` + +The wrapper handles: + +1. binding the selected device to `vfio-pci` +2. launching the Red Bear guest passthrough harness +3. running `redbear-phase5-network-check` and `redbear-phase5-wifi-run` inside the guest +4. collecting the packaged Wi‑Fi capture bundle back to the host +5. writing a host-side metadata sidecar for the run +6. restoring the host driver afterwards + +### Artifact to preserve + +- `./wifi-passthrough-capture.json` +- `./wifi-passthrough-capture.meta.json` +- full terminal log from the wrapper invocation + +Optional packaging step on the host: + +```bash +./local/scripts/package-wifi-validation-artifacts.sh +``` + +## Minimum Evidence for a Real Runtime Attempt + +At minimum, keep all of the following together: + +- the capture JSON bundle +- the console output of the checker/wrapper +- the exact PCI BDF used for the Intel Wi‑Fi device +- whether the run was bare metal or VFIO/QEMU + +## What Success Means Today + +Current success is still **bounded** success: + +- the Intel driver/runtime lifecycle can be exercised on a real target +- the Wi‑Fi control/profile/reporting stack can observe that lifecycle, including honest bounded + pending/associating connect state when real association is not yet proven +- the default bounded validation profile is `wifi-open-bounded`, which intentionally avoids turning + DHCP handoff into a false requirement for lifecycle-only validation +- the packaged runtime checker currently proves that bounded open-profile path by default; WPA2-PSK + is implemented and covered by host/unit-level regressions, but is not yet the default packaged + runtime validation path +- a structured evidence bundle is captured for debugging + +This is **not yet** the same as: + +- real AP scan/association proof +- real packet/data-path proof +- DHCP success over a true wireless link +- validated end-to-end Wi‑Fi connectivity + +Those remain the next debugging targets after the first real target execution. diff --git a/local/docs/WIFICTL-SCHEME-REFERENCE.md b/local/docs/WIFICTL-SCHEME-REFERENCE.md new file mode 100644 index 00000000..f1e8234a --- /dev/null +++ b/local/docs/WIFICTL-SCHEME-REFERENCE.md @@ -0,0 +1,77 @@ +# `wifictl:` Scheme Reference + +This document describes the current bounded `/scheme/wifictl` surface exposed by +`redbear-wifictl`. + +It is a reference for validation and debugging of the current Intel Wi‑Fi slice. It does **not** +imply that Wi‑Fi connectivity is fully supported. + +## Root Layout + +Top-level entries: + +- `wifictl:/ifaces` +- `wifictl:/capabilities` + +## Per-interface entries + +For each interface under `wifictl:/ifaces//`, the scheme currently exposes: + +### Read-only status/state nodes + +- `status` +- `link-state` +- `firmware-status` +- `transport-status` +- `transport-init-status` +- `activation-status` +- `connect-result` +- `disconnect-result` +- `scan-results` +- `last-error` + +### Read/write profile/config nodes + +- `ssid` +- `security` +- `key` + +### Write-triggered control nodes + +- `scan` +- `prepare` +- `transport-probe` +- `init-transport` +- `activate-nic` +- `connect` +- `disconnect` +- `retry` + +## Current bounded lifecycle + +The bounded Intel path currently treats the Wi‑Fi lifecycle as: + +1. `prepare` +2. `transport-probe` +3. `init-transport` +4. `activate-nic` +5. `connect` +6. `disconnect` +7. `retry` + +The scheme records the last reported bounded connect/disconnect metadata in `connect-result` and +`disconnect-result`. + +## Interpretation guidance + +- Presence of the scheme means the control surface exists, not that a real Wi‑Fi link is proven. +- `connect-result` and `disconnect-result` are lifecycle evidence surfaces, not proof of real AP + authentication or real packet flow. +- `scan-results` may reflect bounded or synthetic runtime outcomes unless and until hardware-backed + scan evidence is captured on a real target. + +## Related documents + +- `local/docs/WIFI-IMPLEMENTATION-PLAN.md` +- `local/docs/WIFI-VALIDATION-RUNBOOK.md` +- `local/docs/SCRIPT-BEHAVIOR-MATRIX.md` diff --git a/local/docs/WIP-MIGRATION-LEDGER.md b/local/docs/WIP-MIGRATION-LEDGER.md index 0a301fcf..7a256e42 100644 --- a/local/docs/WIP-MIGRATION-LEDGER.md +++ b/local/docs/WIP-MIGRATION-LEDGER.md @@ -33,6 +33,7 @@ This is a repo-governance document, not a subsystem deep dive. | `seatd` runtime path | **mixed-transition** | recipe-level decision still local | It builds and is integrated into KDE-facing configs, but runtime trust still trails the packaging story. | | `redox-driver-sys` | **local-overlay-owner** | local overlay | Red Bear-owned driver substrate. | | `linux-kpi` | **local-overlay-owner** | local overlay | Red Bear-owned compatibility layer. | +| `redbear-iwlwifi` | **local-overlay-owner** | local overlay | Bounded Intel Wi-Fi driver-side package below the native Red Bear Wi-Fi control plane; current scope is probe, status, firmware prepare, transport probe/init, NIC activation, bounded scan/connect/disconnect lifecycle, and retry. | | `redox-drm` / `amdgpu` | **local-overlay-owner** | local overlay | Red Bear-owned graphics/driver work. | | `firmware-loader` | **local-overlay-owner** | local overlay | Red Bear-owned runtime infrastructure. | | relibc compatibility overlays | **mixed-transition** | upstream + local overlay | Prefer upstream where available; keep only the overlays that still prove necessary after fresh-source reapply and downstream rebuild. | diff --git a/local/docs/repo-governance.md b/local/docs/repo-governance.md index bade9847..a9347259 100644 --- a/local/docs/repo-governance.md +++ b/local/docs/repo-governance.md @@ -19,8 +19,10 @@ reproducible, reviewable, and upstream-friendly. Tracked Red Bear profiles are: - `redbear-minimal` +- `redbear-bluetooth-experimental` - `redbear-desktop` - `redbear-full` +- `redbear-wayland` - `redbear-kde` - `redbear-live` @@ -54,6 +56,11 @@ why it is intentionally excluded. Primary validation baseline: console, storage, package flow, and wired networking. +### `redbear-bluetooth-experimental` + +First bounded Bluetooth validation profile: explicit-startup, USB-attached, BLE-first, and +experimental only. + ### `redbear-desktop` Main integration profile for desktop-oriented Red Bear services without making KDE the default. @@ -62,6 +69,10 @@ Main integration profile for desktop-oriented Red Bear services without making K Expanded desktop/integration target that includes more runtime pieces and graphics-path bring-up. +### `redbear-wayland` + +Dedicated Wayland runtime validation profile layered above the current Red Bear service baseline. + ### `redbear-kde` Dedicated KDE/Plasma bring-up profile.