diff --git a/local/docs/AMD-FIRST-INTEGRATION.md b/local/docs/AMD-FIRST-INTEGRATION.md index 1177449a..6c0f36c7 100644 --- a/local/docs/AMD-FIRST-INTEGRATION.md +++ b/local/docs/AMD-FIRST-INTEGRATION.md @@ -1,7 +1,12 @@ # AMD-FIRST REDOX OS — MASTER INTEGRATION PLAN -**Target**: Modern AMD64 bare metal machine with AMD GPU (RDNA2/RDNA3) -**Secondary**: Intel GPU machines +> **Status note (2026-04-14):** This document remains the detailed AMD-focused hardware roadmap, +> but it is no longer the repository-wide platform-priority policy. Red Bear OS should now treat +> AMD and Intel machines as equal-priority targets. Read this file as the deeper AMD-specific plan, +> not as a statement that Intel is secondary going forward. + +**Target**: AMD64 bare metal machine with AMD GPU (RDNA2/RDNA3), within an overall Red Bear OS +hardware policy that treats AMD and Intel machines as equal-priority targets. **Date**: 2026-04-11 ## CRITICAL FINDINGS @@ -14,8 +19,9 @@ | i915 (Intel) | ~341,000 | Well-documented, simpler | | nouveau (NVIDIA) | ~400,000 | Community driver | -**Implication**: AMD-first is HARDER but has larger market impact. We MUST use -the LinuxKPI compatibility approach — a clean Rust rewrite would take 5+ years. +**Implication**: The AMD path is HARDER but still important. For AMD-class Linux GPU and related +device enablement, we MUST use the LinuxKPI compatibility approach — a clean Rust rewrite would +take 5+ years. ### AMD Bare Metal Status on Redox @@ -26,7 +32,7 @@ the LinuxKPI compatibility approach — a clean Rust rewrite would 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 | 🚧 Buildable, unvalidated | `iommu` daemon now builds, but no VT-d/AMD-Vi hardware validation yet | +| 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 | | AMD GPU | 🚧 In progress | MMIO mapped, DC port compiles, MSI-X wired, no hardware validation yet | | Wi-Fi/BT | ❌ Missing | No wireless support | | USB | ⚠️ Variable | Some USB controllers work, others don't | @@ -327,6 +333,10 @@ Currently libdrm has `-Damdgpu=disabled`. Enable it once redox-drm exists. ## PHASE 5: AMD GPU ACCELERATION (16-24 weeks, parallel with P4) +> Note: this AMD-first Phase 5 is a hardware-driver track. It is **not** the same thing as the +> canonical public `docs/07` Phase 5, which is about wired networking and desktop/session +> integration. + ### P5-1: Full amdgpu Port via LinuxKPI This is the big one. Port the full amdgpu driver using linux-kpi headers. @@ -403,7 +413,7 @@ P0 (ACPI boot) | Document | Change | |----------|--------| -| `AGENTS.md` (root) | Add AMD-first strategy, local/ overlay refs | +| `AGENTS.md` (root) | Keep equal-priority AMD/Intel hardware policy visible; keep local/ overlay refs | | `recipes/core/AGENTS.md` | Add AMD boot requirements, IOMMU note | | `recipes/wip/AGENTS.md` | Add AMD GPU driver WIP section | | `docs/AGENTS.md` | Add reference to local/docs/ | diff --git a/local/docs/NETWORKING-RTL8125-NETCTL.md b/local/docs/NETWORKING-RTL8125-NETCTL.md index 90ea4841..ed90afeb 100644 --- a/local/docs/NETWORKING-RTL8125-NETCTL.md +++ b/local/docs/NETWORKING-RTL8125-NETCTL.md @@ -80,10 +80,21 @@ base networking services have started. `redbear-minimal`: `pcid-spawner` → `smolnetd` → `dhcpd` → `netctl --boot` → `wired-dhcp`. - `./local/scripts/test-vm-network-qemu.sh` launches a VirtIO-backed QEMU run for the same Phase 2 baseline and prints the in-guest validation commands to run. + On x86_64 hosts it now fails fast unless usable OVMF/edk2 UEFI firmware is installed, because + otherwise the helper can fall through a misleading BIOS/iPXE boot path before Red Bear OS ever + starts. - `./local/scripts/test-vm-network-runtime.sh` is the in-guest check for the same baseline: it verifies `/scheme/pci`, `/scheme/netcfg`, the active netctl profile, visible `network.*` schemes, and the current `eth0` address. +During reassessment, the QEMU/UEFI VM baseline reached a real guest login prompt and +`redbear-info --json` reported: + +- `virtio_net_present: true` +- configured `eth0` address `10.0.2.15/24` +- default route via `10.0.2.2` +- visible `network.pci-0000-00-03.0_virtio_net` scheme + ## Remaining hardware validation This repo change set wires RTL8125 through the native path, but real hardware validation is still diff --git a/local/docs/USB-IMPLEMENTATION-PLAN.md b/local/docs/USB-IMPLEMENTATION-PLAN.md index d97d9da0..056dfe43 100644 --- a/local/docs/USB-IMPLEMENTATION-PLAN.md +++ b/local/docs/USB-IMPLEMENTATION-PLAN.md @@ -34,11 +34,14 @@ and a low-level userspace client API through `xhcid_interface`. The current limitations are material: -- xHCI still runs in polling mode because interrupt support is disabled +- xHCI no longer hard-forces polling; it uses the existing interrupt-mode selection path again, but + interrupt-driven behavior is still only lightly validated under runtime load +- checked-in event-ring growth support now exists, but it still needs stronger runtime validation - USB support varies by machine, including known `xhcid` panic cases - hub/topology handling is partial - HID is still wired through the legacy mixed-stream `inputd` path -- USB mass storage exists in-tree, but default autospawn is disabled because it causes xHCI errors +- 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. - there is no evidence of validated support for broader USB classes or modern USB-C / dual-role scope @@ -47,10 +50,10 @@ The current limitations are material: | Area | State | Notes | |---|---|---| | Host mode | **usable / experimental** | Real host-side stack exists, but not broadly validated | -| xHCI controller | **builds / enumerates / usable on some hardware** | Polling mode, hardware-variable, not fully corrected | +| xHCI controller | **builds / enumerates / usable on some hardware** | Interrupt-mode selection restored, hardware-variable, event-ring growth exists in-tree but still needs stronger runtime validation | | Hub handling | **builds / partial usable** | `usbhubd` exists, USB 3 hub limitations remain | | HID | **builds / usable in narrow path** | `usbhidd` handles keyboard/mouse/button/scroll via legacy input path | -| Mass storage | **builds** | `usbscsid` exists, but default autospawn is disabled | +| Mass storage | **builds / autospawns in QEMU** | `usbscsid` now spawns from the xHCI class-driver table, but runtime stability past spawn still needs work | | Native tooling | **builds / enumerates** | `lsusb`, `usbctl`, `redbear-info` provide partial observability | | Low-level userspace API | **builds** | `xhcid_interface` exists, but not a mature general userspace USB story | | libusb | **builds / experimental** | WIP, compiled but not tested | @@ -84,10 +87,9 @@ The current limitations are material: - `HARDWARE.md` says USB support varies by machine and records systems where USB input or USB more broadly does not work, plus known `xhcid` panic cases - `local/docs/AMD-FIRST-INTEGRATION.md` marks USB as **variable** -- `recipes/core/base/source/drivers/usb/xhcid/src/main.rs` forces polling mode and leaves - interrupt setup disabled with `TODO: Fix interrupts.` -- `recipes/core/base/source/drivers/usb/xhcid/drivers.toml` comments out USB SCSI autospawn with - `#TODO: causes XHCI errors` +- `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 @@ -99,7 +101,7 @@ The current limitations are material: Current repo-visible issues include: -- polling-mode operation instead of interrupt-driven behavior +- partially restored interrupt-driven behavior without complete event-ring growth support - incorrect or incomplete speed handling for child devices - TODOs around configuration choice and alternate settings - TODOs around endpoint selection across interfaces @@ -126,8 +128,9 @@ per-device streams, and explicit hotplug events. ### 4. Storage is present in-tree but not a current support claim -`usbscsid` is a real driver, but the current xHCI class-driver table disables the SCSI-over-USB -autospawn path because it causes XHCI errors. +`usbscsid` is a real driver and the xHCI class-driver table now spawns it again during QEMU USB +storage validation. The current blocker is not matching or spawn, but transport/runtime stability +after spawn. That means Red Bear should document USB storage as **implemented in-tree but not currently enabled as a default working class path**. @@ -276,7 +279,7 @@ family. **What to do**: -- repair and re-enable USB mass-storage autospawn +- stabilize USB mass-storage after autospawn (BOT transport / SCSI runtime path) - decide whether BOT-only is sufficient short-term or whether UAS is part of the next step - bring `libusb` to a runtime-tested state or explicitly replace it with a Red Bear-native API strategy diff --git a/local/docs/WIFI-IMPLEMENTATION-PLAN.md b/local/docs/WIFI-IMPLEMENTATION-PLAN.md new file mode 100644 index 00000000..23136847 --- /dev/null +++ b/local/docs/WIFI-IMPLEMENTATION-PLAN.md @@ -0,0 +1,402 @@ +# Red Bear OS Wi-Fi Implementation Plan + +## Purpose + +This document defines the current Wi-Fi state in Red Bear OS and lays out the recommended path for +integrating Wi-Fi drivers and a usable wireless control plane. + +The goal is not to imply that Wi-Fi already exists in-tree. 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. + +## Validation States + +- **builds** — code exists in-tree and is expected to compile +- **boots** — image or service path reaches a usable runtime state +- **reports** — runtime surfaces can honestly report current wireless state +- **validated** — behavior has been exercised with real evidence for the claimed scope +- **experimental** — available for bring-up, but not support-promised +- **missing** — no in-tree implementation path is currently present + +This repo should not treat planned wireless scope as equivalent to implemented support. + +## Current Repo State + +### Summary + +Wi-Fi is currently **missing** 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. + +What the repo *does* have is a meaningful set of prerequisites: + +- userspace drivers and schemes as the standard architectural model +- `redox-driver-sys` for PCI/MMIO/IRQ/DMA primitives +- `linux-kpi` as a limited low-level C-driver compatibility layer +- `firmware-loader` for blob-backed devices +- a working native wired network path through `network.*`, `smolnetd`, `dhcpd`, and `netcfg` +- profile/package-group discipline, including the reserved `net-wifi-experimental` slice + +### Current Status Matrix + +| Area | State | Notes | +|---|---|---| +| 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` | +| 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 | +| 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 | + +## 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 + +### Positive driver-side prerequisites + +- `docs/04-LINUX-DRIVER-COMPAT.md` documents `redox-driver-sys`, `linux-kpi`, and + `firmware-loader` +- `local/recipes/drivers/redox-driver-sys/` provides userspace PCI/MMIO/IRQ/DMA primitives +- `local/recipes/drivers/linux-kpi/` provides a limited Linux-style compatibility subset +- `local/recipes/system/firmware-loader/` provides `scheme:firmware` + +### Positive network/control-plane prerequisites + +- `local/docs/NETWORKING-RTL8125-NETCTL.md` documents the native wired path: + `pcid-spawner` → NIC daemon → `network.*` → `smolnetd` → `dhcpd` / `netcfg` +- `recipes/core/base/source/netstack/src/scheme/netcfg/mod.rs` shows route/address/resolver state + is already exposed through a native control scheme +- `local/recipes/system/redbear-netctl/source/src/main.rs` shows Red Bear already uses a native + network profile tool, even though it is currently wired-only +- `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` reserves `net-wifi-experimental` as a package-group + slot for future wireless work + +## Feasibility Constraints + +### 1. Wi-Fi is not just a driver + +Wi-Fi in Red Bear cannot be treated as a single hardware daemon. + +At minimum, a working Wi-Fi path needs: + +- hardware transport and firmware bring-up +- scan/discovery +- authentication and association state +- link-state and disconnect handling +- credential storage +- post-association handoff into the native IP stack +- later desktop/user-facing integration if the repo wants it + +This makes Wi-Fi more like a complete subsystem than a simple wired NIC driver. + +### 2. `linux-kpi` is feasible only below the wireless control-plane boundary + +Current `linux-kpi` is suitable for low-level driver-enablement work such as: + +- PCI / IRQ / DMA / MMIO access +- firmware request glue +- workqueue-style helper logic +- C-driver compatibility for narrow hardware bring-up + +Current `linux-kpi` is **not** a complete Wi-Fi architecture because the repo has no in-tree: + +- cfg80211 +- mac80211 +- nl80211 +- wiphy model +- supplicant/control-plane compatibility layer + +So `linux-kpi` is feasible only as a **partial low-level aid**, not as the primary Red Bear Wi-Fi +stack. + +### 3. The current Red Bear control plane is Ethernet-specific + +The current native network stack is useful, but not yet Wi-Fi-ready. + +`redbear-netctl` only supports: + +- `Connection=ethernet` +- `Interface=eth0` +- DHCP/static address, route, and DNS control + +`netcfg` is similarly hard-wired around the current `eth0` interface model. + +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 + +The first Wi-Fi target should minimize the amount of 802.11 MAC and Linux wireless subsystem logic +that Red Bear has to recreate. + +That makes **FullMAC** hardware the best first target class. + +Red Bear should explicitly avoid starting with SoftMAC/mac80211-style Linux drivers such as: + +- Intel `iwlwifi` +- Realtek `rtw88` / `rtw89` +- MediaTek `mt76` +- other drivers that fundamentally assume cfg80211/mac80211 semantics + +## Recommended Architecture + +The best Red Bear Wi-Fi architecture 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** +5. **reuse the existing native IP path only after association** + +This is a hybrid architecture, but it is **native-first**, not Linux-stack-first. + +### Subsystem boundary + +The Wi-Fi subsystem should be split into these pieces: + +- one **device transport / driver daemon** for the chosen chipset 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. + +## Hardware Strategy + +### First decision gate + +Before implementation begins, Red Bear must choose **one** first Wi-Fi family from actual target +machines or bring-up hardware. + +The preferred target order is: + +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 + +### What not to choose for phase 1 + +Do not start with: + +- Intel laptop Wi-Fi via `iwlwifi` +- mac80211/cfg80211-dependent Linux drivers +- any phase-1 scope that requires recreating a Linux wireless stack first + +## Security Scope Freeze + +### Phase-1 supported security + +- open networks +- WPA2-PSK + +### Explicitly out of initial scope + +- WPA3 +- 802.1X / enterprise Wi-Fi +- AP mode +- roaming +- monitor mode +- suspend/resume guarantees +- multi-BSS support +- sophisticated regulatory-domain handling + +This scope freeze is required to keep the first milestone honest and achievable. + +## Comprehensive Full Plan + +### 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 security scope to open + WPA2-PSK +- define `net-wifi-experimental` as the package-group slice for first Wi-Fi support +- document unsupported wireless features explicitly + +**Exit criteria**: + +- one hardware family is selected +- support language and non-goals are written down + +--- + +### Phase W1 — Driver Substrate Fit + +**Goal**: Prove the chosen Wi-Fi family can fit Red Bear’s existing driver primitives. + +**What to do**: + +- map the chosen device 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 + +**Exit criteria**: + +- one chosen device can be discovered, initialized, and paired with its firmware-loading path + +--- + +### Phase W2 — Native Wireless Control Plane + +**Goal**: Add a Red Bear-native wireless daemon and control interface. + +**What to do**: + +- implement a Wi-Fi daemon that owns: + - scan state + - auth/association state + - link state + - disconnect/retry behavior + - credential ownership +- add a user-facing `wifictl`-style control surface + +**What not to do**: + +- do not push supplicant logic into `redbear-netctl` +- do not model Wi-Fi as “just another Ethernet profile” at this phase + +**Exit criteria**: + +- the daemon can report scan results and current link state honestly + +--- + +### Phase W3 — Network Stack Refactor for Post-Association Handoff + +**Goal**: Make the native IP stack accept Wi-Fi as a first-class post-association interface. + +**What to do**: + +- generalize current `eth0` / Ethernet assumptions where needed +- allow the native stack to consume a post-association Wi-Fi interface state +- keep route/address/DNS handling in native `netcfg` / `smolnetd` plumbing after association + +**Exit criteria**: + +- a connected Wi-Fi link can be handed off to the existing IP path without pretending it is merely a + raw Ethernet control-plane object + +--- + +### Phase W4 — First Association Milestone + +**Goal**: Achieve one real Wi-Fi connection under the frozen phase-1 scope. + +**What to do**: + +- scan for one real SSID +- join one test network +- complete open or WPA2-PSK association +- hand off to DHCP or static IP configuration + +**Exit criteria**: + +- one chosen device family reaches usable network connectivity on a real network + +--- + +### Phase W5 — Runtime Reporting and Recovery + +**Goal**: Make Wi-Fi support diagnosable and honest. + +**What to do**: + +- extend `redbear-info` with Wi-Fi-specific runtime reporting +- add reconnect and failure-state reporting +- keep all support labels experimental + +**Exit criteria**: + +- users can see whether hardware is present, firmware is loaded, scans succeed, and association has + succeeded or failed + +--- + +### Phase W6 — Desktop Compatibility (Later) + +**Goal**: Add desktop-oriented control only after native Wi-Fi works. + +**What to do**: + +- if KDE or desktop workflows require it, add a small compatibility shim over the native Wi-Fi + service +- keep that shim above the native control plane, not in place of it + +**Exit criteria**: + +- desktop Wi-Fi workflows become possible without changing the native subsystem boundaries + +--- + +### Phase W7 — Broader Hardware and `linux-kpi` Reassessment + +**Goal**: Reassess whether Red Bear wants to widen Wi‑Fi support after one FullMAC 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 +- do not assume this is automatically justified + +**Exit criteria**: + +- Red Bear either keeps the narrow native-first architecture, or consciously chooses a larger Linux + wireless-compat effort with full awareness of the cost + +## Validation Gates + +Wi-Fi should not be described as supported until these gates are passed in order: + +1. hardware is detected +2. firmware loads successfully +3. the driver/daemon initializes and reports link state +4. scan sees a real SSID +5. association succeeds for one supported network type +6. DHCP or static IP handoff succeeds through the native network stack +7. reconnect works after disconnect or reboot +8. `redbear-info` and profile docs report supported and unsupported states honestly + +Until then, support language should remain under `net-wifi-experimental` only. + +## Support-Language Guidance + +Until the validation gates above are passed, Red Bear should use language such as: + +- “Wi-Fi is not supported yet” +- “Wi-Fi remains experimental and hardware-specific” +- “The current wireless path is an experimental FullMAC-first bring-up” + +Avoid language such as: + +- “Linux Wi‑Fi drivers are supported” +- “wireless support works” +- “Wi-Fi is generally available” + +unless profile-scoped validation evidence exists. + +## Summary + +The best Red Bear Wi-Fi path is **native-first**: + +- native wireless control plane +- one experimental FullMAC family first +- `firmware-loader` + `redox-driver-sys` underneath +- optional narrow `linux-kpi` glue only where useful +- native `smolnetd` / `netcfg` / `redbear-netctl` reused only after association + +`linux-kpi` is therefore **feasible only in a narrow sense**. It is useful as a low-level helper +for driver bring-up, but it is not currently a viable full Wi‑Fi architecture for Red Bear OS. + +That is the most realistic way to integrate Wi‑Fi into Red Bear while keeping the design aligned +with the repo’s current userspace-driver and profile-based architecture.