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

Refresh project documentation

Browse Source 
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
Vasilito
2026-04-17 00:05:20 +01:00
parent 2c7659fe3a
commit 6689f751d9
23 changed files with 2428 additions and 1720 deletions
Download Patch File Download Diff File Expand all files Collapse all files
local/docs/WIFI-IMPLEMENTATION-PLAN.md
+221 -682
View File
@@ -2,740 +2,279 @@
## Purpose
This document defines the current Wi-Fi state in Red Bear OS and lays out the recommended path for
integrating Wi-Fi drivers and a usable wireless control plane.
This document describes the current Wi-Fi state in Red Bear OS and the path from the existing
bounded Intel bring-up scaffold to validated wireless connectivity.
The goal is not to imply that working Wi-Fi already exists. The goal is to describe what the repo
currently proves, what `linux-kpi` can and cannot realistically provide, and how Red Bear can grow
from a **bounded experimental Intel Wi-Fi scaffold** to one experimental, validated Wi-Fi path that
fits the existing Redox / Red Bear architecture.
Wi-Fi is currently **not working connectivity**. What exists is a structurally complete,
host-tested Intel transport layer and native control plane, awaiting real hardware + firmware
validation.
## Validation States
- **builds** — code exists in-tree and is expected to compile
- **boots** — image or service path reaches a usable runtime state
- **reports** — runtime surfaces can honestly report current wireless state
- **validated** — behavior has been exercised with real evidence for the claimed scope
- **experimental** — available for bring-up, but not support-promised
- **missing** — no in-tree implementation path is currently present
| State | Meaning |
|---|---|
| **builds** | Compiles in-tree |
| **host-tested** | Tests pass on Linux host with synthesized fixtures |
| **validated** | Behavior confirmed with real hardware evidence |
| **experimental** | Available for bring-up, not support-promised |
| **missing** | No in-tree implementation |
This repo should not treat planned wireless scope as equivalent to implemented support.
## Current State
## Current Repo State
### Status Matrix
### Summary
Wi-Fi is currently **not supported as working connectivity** in Red Bear OS.
There is still no complete in-tree cfg80211/mac80211/nl80211-compatible surface, no supplicant
path, and no profile that can honestly claim working Wi-Fi support. What now exists in-tree is a
bounded Intel bring-up slice: a driver-side package, a Wi-Fi control daemon/scheme, profile
plumbing, and host-validated LinuxKPI/CLI scaffolding below the real association boundary.
What the repo *does* have is a meaningful set of prerequisites:
- userspace drivers and schemes as the standard architectural model
- `redox-driver-sys` for PCI/MMIO/IRQ/DMA primitives
- `linux-kpi` as a limited low-level C-driver compatibility layer
- `firmware-loader` for blob-backed devices
- a working native wired network path through `network.*`, `smolnetd`, `dhcpd`, and `netcfg`
- profile/package-group discipline, including the reserved `net-wifi-experimental` slice
### Current Status Matrix
| Area | State | Notes |
| Area | State | Detail |
|---|---|---|
| Wi-Fi controller support | **experimental bounded slice exists** | `redbear-iwlwifi` provides an Intel-only bounded driver-side package, not validated Wi-Fi connectivity |
| Linux wireless stack compatibility | **early compatibility scaffolding exists** | `linux-kpi` now carries `cfg80211` / `wiphy` / `mac80211` registration, station-mode scaffolding, channel/band/rate/BSS definitions, and RX/TX data-path structures (24 tests pass), but not a complete Linux wireless stack |
| Firmware loading | **partial prerequisite exists** | `firmware-loader` can serve firmware blobs generically |
| Wireless control plane | **experimental bounded slice exists** | `redbear-wifictl` and `redbear-netctl` expose bounded prepare/init/activate/scan orchestration, not real association support |
| Post-association IP path | **present** | Native `smolnetd` / `netcfg` / `dhcpd` / `redbear-netctl` path exists |
| Desktop Wi-Fi API | **missing** | No NetworkManager-like or D-Bus Wi-Fi surface |
| Runtime diagnostics | **experimental bounded slice exists** | `redbear-info` and runtime helpers expose Wi-Fi state surfaces, but not real Wi-Fi functionality proof |
## Evidence Already In Tree
### Direct current-state caution about supported connectivity
- `HARDWARE.md` says broad Wi-Fi and Bluetooth hardware support is still incomplete even though
bounded in-tree scaffolding now exists
- `local/docs/AMD-FIRST-INTEGRATION.md` now treats `Wi-Fi/BT` as in progress with bounded wireless
scaffolding present but validated connectivity still incomplete
### Positive driver-side prerequisites
- `docs/04-LINUX-DRIVER-COMPAT.md` documents `redox-driver-sys`, `linux-kpi`, and
`firmware-loader`
- `local/recipes/drivers/redox-driver-sys/` provides userspace PCI/MMIO/IRQ/DMA primitives
- `local/recipes/drivers/linux-kpi/` provides a limited Linux-style compatibility subset
- `local/recipes/system/firmware-loader/` provides `scheme:firmware`
### Positive network/control-plane prerequisites
- `local/docs/NETWORKING-RTL8125-NETCTL.md` documents the native wired path:
`pcid-spawner` → NIC daemon → `network.*` → `smolnetd` → `dhcpd` / `netcfg`
- `recipes/core/base/source/netstack/src/scheme/netcfg/mod.rs` shows route/address/resolver state
is already exposed through a native control scheme
- `local/recipes/system/redbear-netctl/source/src/main.rs` shows Red Bear already uses a native
network profile tool, even though it is currently wired-only
- `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` reserves `net-wifi-experimental` as a package-group
slot for future wireless work
## Feasibility Constraints
### 1. Wi-Fi is not just a driver
Wi-Fi in Red Bear cannot be treated as a single hardware daemon.
At minimum, a working Wi-Fi path needs:
- hardware transport and firmware bring-up
- scan/discovery
- authentication and association state
- link-state and disconnect handling
- credential storage
- post-association handoff into the native IP stack
- later desktop/user-facing integration if the repo wants it
This makes Wi-Fi more like a complete subsystem than a simple wired NIC driver.
### 2. `linux-kpi` is feasible only below the wireless control-plane boundary
Current `linux-kpi` is suitable for low-level driver-enablement work such as:
- PCI / IRQ / DMA / MMIO access
- firmware request glue
- workqueue-style helper logic
- C-driver compatibility for narrow hardware bring-up
Current `linux-kpi` is **not** a complete Wi-Fi architecture because the repo still has no in-tree,
complete:
- cfg80211
- mac80211
- nl80211
- wiphy model
- supplicant/control-plane compatibility layer
So `linux-kpi` is feasible only as a **partial low-level aid**, not as the primary Red Bear Wi-Fi
stack.
### 3. The current Red Bear control plane is Ethernet-specific
The current native network stack is useful, but not yet Wi-Fi-ready.
`redbear-netctl` now has a first Wi-Fi-facing profile layer, but only at the profile/orchestration
boundary.
Current `redbear-netctl` support now includes:
- `Connection=ethernet`
- `Connection=wifi`
- arbitrary `Interface=` values at the profile layer (for example `eth0`, `wlan0`)
- DHCP/static address, route, and DNS control after association
- Wi-Fi profile fields for `SSID`, `Security`, and `Key`/`Passphrase`
- a bounded native handoff to a future `/scheme/wifictl` control surface
The repo now also contains the first bounded implementation of that control surface:
- `local/recipes/system/redbear-wifictl/` provides a `redbear-wifictl` daemon and `/scheme/wifictl`
scheme
- the current daemon supports a stub backend for end-to-end validation and an Intel-oriented backend
boundary that detects Intel wireless-class PCI devices
- the current Intel backend is now firmware-aware: it reports candidate firmware families, selected
firmware blobs when present, and supports a bounded `prepare` step before connect
- this is still not a full Intel association path, but it turns the control-plane contract into a
real in-tree interface rather than a placeholder
This means `redbear-netctl` can now represent and start a Wi-Fi profile without pretending Wi-Fi is
just an Ethernet profile, but it still does **not** own scan/auth/association itself.
`netcfg` is no longer hard-wired to a single `eth0` node in the control scheme. The native control
surface can now expose per-device interface nodes dynamically from the current device list, which is
the first required step for post-association Wi-Fi handoff.
That means Red Bear can reuse its native IP plumbing **after association**, but not as the radio
control plane itself.
### 4. Intel target changes the first-driver strategy
The original version of this plan preferred a FullMAC-first path to avoid recreating Linux wireless
subsystem boundaries.
That is still the simplest architecture in the abstract, but the project target has now changed:
Red Bear must target **Intel Wi-Fi for Arrow Lake and older Intel client chips**.
That means the first realistic driver family is now Intel `iwlwifi`-class hardware rather than an
unspecified FullMAC family.
This changes the implementation burden materially:
- Intel `iwlwifi` is not a simple FullMAC path
- current Linux support is tightly coupled to `mac80211` / `cfg80211`
- firmware loading remains necessary but is not the hard part by itself
- Red Bear must plan for a bounded compatibility layer below the user-facing control plane
So the practical first target is now:
- **Intel `iwlwifi`-class devices, Arrow Lake and older**, with the understanding that this is a
harder first driver family than a generic FullMAC-first strategy would have been
## Recommended Architecture
The best current Red Bear Wi-Fi architecture for the Intel target is:
1. **native Red Bear wireless control plane above the driver boundary**
2. **Intel-first low-level driver work below that boundary**
3. **reuse `firmware-loader` and `redox-driver-sys` wherever possible**
4. **accept bounded `linux-kpi` growth where Intel transport/firmware glue requires it**
### Build-note for the current Intel control-plane code
The earlier Redox-target source-level compile failure in `redbear-wifictl`'s Intel backend is now
fixed in-tree. If `cargo build --target x86_64-unknown-redox` still reports that
`x86_64-unknown-redox-gcc` is missing, check whether the repo-provided cross toolchain under
`prefix/x86_64-unknown-redox/sysroot/bin/` is on `PATH` before treating it as a fresh source-level
regression.
For repeatable local builds, use `local/scripts/build-redbear-wifictl-redox.sh`, which wires that
repo-provided toolchain path into the build invocation explicitly.
5. **reuse the existing native IP path only after association**
This is still a native-first architecture at the control-plane level, but it is no longer a pure
FullMAC-first plan.
### Subsystem boundary
The Wi-Fi subsystem should be split into these pieces:
- one **device transport / driver daemon** for the Intel target family
- one **firmware loading path** via `firmware-loader`
- one **Wi-Fi control daemon** for scan/auth/association/link state
- one **user-facing control tool** (`wifictl` or equivalent)
- one **post-association handoff** into `smolnetd` / `netcfg` / `dhcpd`
- one **later desktop shim** only if KDE/user-facing workflows require it
`redbear-netctl` should **not** become the supplicant. It can own profile orchestration and the
post-association IP handoff, but scan/auth/association should still live in a dedicated Wi-Fi
control daemon or scheme.
The current implementation now matches that boundary more closely:
- `redbear-netctl` can parse Wi-Fi profiles and hand credentials/intent to a native Wi-Fi control
surface (`/scheme/wifictl`)
- `redbear-netctl` now also has a host-side CLI proof that starting a Wi-Fi profile drives the
bounded driver/control actions and preserves the surfaced bounded connect metadata in status
output; this is not yet proof of verified prepare/init/activate/connect execution order on a real
associated link
- `redbear-netctl` stop now also drives the bounded disconnect path, so the current profile-manager
slice covers start and stop instead of start-only behavior
- `redbear-wifictl` now exposes bounded connect and disconnect CLI flows, and the runtime checker
now exercises the bounded connect step through the scheme surface
- the native IP path can address a non-`eth0` interface name after association
- `redbear-netctl` now also performs interface-specific DHCP handoff for Wi-Fi profiles and waits
for the selected interface to receive an address in the bounded host/runtime validation path
- `local/recipes/system/redbear-netctl-console/` now adds a terminal UI client on top of the same
`/scheme/wifictl` + `/etc/netctl` contract, so scan/select/edit/save/connect/disconnect workflows
can be exercised without introducing a new daemon or bypassing profile semantics
- `local/scripts/test-wifi-baremetal-runtime.sh` now provides the strongest in-repo runtime
validation path for this Wi-Fi slice on a real Red Bear OS target: driver probe, control probe,
bounded connect/disconnect, profile start/stop, and `redbear-info --json` lifecycle reporting
- `redbear-phase5-wifi-check` now packages that bounded in-target validation flow as a first-class
guest/runtime command, instead of leaving it only as a shell script
- that packaged runtime proof currently defaults to the bounded open-profile path; WPA2-PSK remains
implemented and host/unit-verified elsewhere in-repo rather than equally packaged/runtime-validated
- `redbear-phase5-wifi-capture` now packages the corresponding runtime evidence bundle, so target
runs can produce a single JSON artifact for debugging real hardware/passthrough failures;
that bundle now includes command outputs, Wi-Fi scheme state, `netctl` profile state, active
profile contents, interface listings, and `lspci` output
- `test-wifi-baremetal-runtime.sh` now writes that capture bundle to `/tmp/redbear-phase5-wifi-capture.json`
as part of the target-side bounded validation flow
- `local/scripts/test-wifi-passthrough-qemu.sh` now provides the corresponding VFIO/QEMU harness for
exercising the same bounded runtime path when an Intel Wi-Fi PCI function can be passed through to
a Red Bear guest, including optional host-side extraction of the packaged Wi-Fi capture bundle
- `local/scripts/prepare-wifi-vfio.sh` now provides the matching host-side bind/unbind helper for
moving an Intel Wi-Fi PCI function onto `vfio-pci` before passthrough validation and restoring it
afterwards
- `local/scripts/run-wifi-passthrough-validation.sh` now wraps the whole host-side passthrough flow:
bind to `vfio-pci`, run the packaged in-guest Wi-Fi validation path, collect the host-visible
capture bundle, and restore the original host driver afterwards
- `local/scripts/validate-wifi-vfio-host.sh` now provides a read-only preflight for the same flow:
PCI presence, current binding, UEFI firmware, image availability, QEMU/expect presence, VFIO
module state, and visible IOMMU groups
- `local/docs/WIFI-VALIDATION-RUNBOOK.md` now ties the bare-metal path, VFIO path, packaged
validators, and capture artifacts together into one operator runbook
- the control daemon exists now, and the first bounded driver-side package now exists as
`local/recipes/drivers/redbear-iwlwifi/`
- `redbear-iwlwifi` now supports bounded `--probe` and `--prepare` driver-side actions for the
current Intel family set
- `redbear-iwlwifi` now also supports bounded `--init-transport` and `--activate-nic` actions for
the current Intel family set
- `redbear-iwlwifi` now also supports bounded `--scan` and `--retry` actions for the current Intel
family set
- `redbear-iwlwifi` now also carries a first bounded `--connect` path that runs through the new
LinuxKPI wireless compatibility scaffolding instead of stopping immediately at a hardcoded
transport/association error
- `redbear-iwlwifi` now also carries a bounded `--disconnect` path so the current station-mode
lifecycle is not connect-only anymore
- `redbear-iwlwifi --status` now reports the current bounded driver-side view directly
- the bounded driver-side action set can be exercised through the dedicated helper script
`local/scripts/test-iwlwifi-driver-runtime.sh`
- on Redox targets, `redbear-iwlwifi` now also begins to use a `linux-kpi` C shim for firmware
request and PCI/MMIO-facing prepare/transport actions instead of keeping those paths purely in
Rust fallback code
### Port vs rewrite decision
For Arrow Lake-and-lower Intel Wi‑Fi, the current repo direction is:
- **do not** attempt a full Linux `mac80211` / `cfg80211` / `nl80211` port first,
- **do** create a bounded Intel driver/transport package below the native Red Bear Wi‑Fi control
plane,
- **do** accept limited `linux-kpi` growth only where it materially reduces transport/firmware glue
cost,
- keep `redbear-netctl` and `redbear-wifictl` as the native control-plane/user-facing layers above
that driver boundary.
That means the repo is now following a **bounded transport-layer port with native control-plane
rewrite above it**, not a full Linux wireless stack port and not a pure greenfield driver rewrite.
### What this means in practical porting terms
The currently feasible interpretation of “use the real Linux Intel driver through `linux-kpi`” is:
- port and reuse **transport-layer and firmware-facing logic** where that lowers cost materially,
- keep the **native Red Bear control plane** above that boundary,
- and avoid treating a full `cfg80211` / `mac80211` / `nl80211` / `wiphy` port as the immediate
first milestone.
In other words, Red Bear should not try to import the whole Linux wireless stack in one step.
Red Bear should instead pull over the **device-facing part** of the Intel stack in bounded layers.
### Boundary where `linux-kpi` is helpful
`linux-kpi` is most useful for:
- PCI helper semantics
- MMIO/IRQ/DMA glue
- firmware request/load glue
- workqueue-style deferred execution
- timer, mutex, and IRQ-critical-section helpers that transport-facing Linux Wi-Fi code expects
- low-level transport and reset sequences
- early packet-buffer / `net_device` / `wiphy` / registration scaffolding when Red Bear begins the
first real Linux wireless-subsystem compatibility slice
That is the boundary where “run Linux driver code on Red Bear” is currently realistic.
The current tree now has the first explicit step in that direction as well:
- `linux-kpi` now carries initial `sk_buff`, `net_device`, `cfg80211`/`wiphy`, and `mac80211`
registration scaffolding alongside the earlier firmware/timer/mutex/IRQ helpers
- that scaffolding now also includes the first station-mode compatibility types and hooks used by
the bounded Intel scan/connect path: SSID/connect/station parameter structs plus basic
`cfg80211_connect_bss` / ready-on-channel and `mac80211` VIF/STA/BSS-conf surfaces
- the bounded station-mode slice now also preserves real private-allocation sizes, exposes the
common `sk_buff` reserve/push/pull/headroom/tailroom helpers, tracks `net_device`
registration/setup, keeps carrier down until connect success, and routes
`ieee80211_queue_work()` through the bounded LinuxKPI workqueue instead of silently dropping
deferred work
- the wireless scaffolding now also includes channel/band/rate definitions
(`Ieee80211Channel`, `Ieee80211Rate`, `Ieee80211SupportedBand` with NL80211 band constants
and IEEE80211 channel/rate flags), BSS information reporting (`Cfg80211Bss`,
`cfg80211_inform_bss`/`get_bss`/`put_bss`), RX/TX data-path structures (`Ieee80211RxStatus`,
`Ieee80211TxInfo` with RX/TX flag constants, `ieee80211_rx_irqsafe`/`tx_status`),
channel definition creation (`ieee80211_chandef_create`), and STA state-transition constants
(`IEEE80211_STA_NOTEXIST` through `IEEE80211_STA_AUTHORIZED`)
- all scaffolding is compile- and host-test-validated inside the `linux-kpi` crate (24 tests pass)
- this is still **not** a claim that Red Bear now has a working Linux wireless stack
### Boundary where a full Linux port becomes too expensive
A full Linux-style `iwlwifi` port becomes dramatically more expensive as soon as the code path
depends on the Linux wireless subsystem proper:
- `cfg80211`
- `mac80211`
- `nl80211`
- `wiphy` model and callbacks
- Linux regulatory integration
- Linux station/BSS bookkeeping and userspace-facing wireless semantics
The repo now has the earliest pieces of those subsystem layers, but still not anything close to a
complete Linux wireless stack. Building them out far enough to host Intel Wi‑Fi as a true Linux-like
solution still turns the effort from a bounded driver port into a much larger compatibility-stack
port.
### Chosen direction
The chosen direction for Arrow Lake-and-lower Intel Wi‑Fi is therefore:
1. keep the **native Red Bear control plane** (`redbear-netctl` + `redbear-wifictl`),
2. keep pushing the **hardware-facing Intel path** down into `redbear-iwlwifi`,
3. use `linux-kpi` for the low-level Linux-facing transport/runtime glue where that reduces effort,
4. avoid promising or attempting a full Linux wireless-stack port as the first milestone.
The current code now matches that decision more closely than before: `redbear-wifictl` remains the
native control plane, while `redbear-iwlwifi` is the place where Linux-facing firmware/PCI/MMIO
driver logic is starting to accumulate.
The current tree also now pushes more of that bounded Intel path through the actual LinuxKPI
surface instead of bespoke C declarations alone:
- `linux-kpi` now exports direct and async firmware request helpers for firmware-family workflows
- timer and IRQ save/restore bindings are exported through the Linux-facing headers instead of
remaining header-only stubs
- `mutex_trylock()` is available to transport-facing code that needs bounded serialization without
pretending the full Linux scheduler model exists
- the current `redbear-iwlwifi` C transport shim now includes the LinuxKPI headers directly and
uses Linux-style firmware, timer, mutex, and IRQ helper entry points for prepare/probe/init/
activate steps
This remains a bounded transport-layer port. It does **not** change the rule that cfg80211/
mac80211/nl80211 remain out of scope for the current milestone.
### Current validation status for this bounded LinuxKPI slice
The current validation story for this slice is intentionally narrow and should be described that
way:
- the `linux-kpi` host-side test suite now runs cleanly in this repo (24 tests pass), including
the Wi‑Fi-facing helper changes in this slice: `request_firmware_direct`,
`request_firmware_nowait`, `mutex_trylock`, IRQ-depth tracking, variable private-allocation
lifetime tracking, station-mode scan/connect/disconnect lifecycle assertions,
workqueue-backed `ieee80211_queue_work()`, `sk_buff` headroom/tailroom helpers, channel/band
creation and flag tests, RX status default and flag combination tests, `ieee80211_get_tid` null
safety, and the existing memory tests
- `redbear-iwlwifi` host-side tests now smoke-test the bounded firmware/transport/activation/scan/
retry actions used by the current Intel path
- `redbear-iwlwifi` also now has a binary-level host-side CLI smoke test for the current bounded
Intel path against temporary PCI/firmware fixtures; this is not the same as a chained real-target
transport→activation→association proof
- `redbear-wifictl` host-side tests pass for the bounded control-plane state propagation above that
Intel path
- the packaged target-side Wi-Fi validators now also accept bounded `status=associating`/
pending-connect output, so the in-target/runtime checks stay aligned with the current honest
connect semantics instead of requiring a fake associated/connected result
- the default packaged bounded runtime profile is now `wifi-open-bounded`, separating lifecycle
validation from the later DHCP-on-real-association gate
This does **not** mean Red Bear has validated a full Linux Wi‑Fi driver stack. The validated claim
is narrower: this repo now has tested, bounded LinuxKPI support for the current Intel transport-
facing helper slice, plus host-tested bounded CLI/control flows above it. Current bounded connect
results should still be read as pending/experimental lifecycle state, not proof of real AP
association.
In the current host environment used for this hardening pass, the Intel-specific VFIO runtime path
also remains blocked by prerequisites outside the repo changes themselves: the host validator sees a
MediaTek MT7921K (`14c3:0608`) instead of an Intel `iwlwifi` device on the available Wi‑Fi slot,
and `vfio_pci` is not loaded. That means the repo-side bounded runtime harness is present and the
Red Bear image/QEMU/OVMF/`expect` prerequisites are available, but a literal Intel passthrough run
still requires compatible host hardware and VFIO binding before it can be executed.
That is the current feasibility conclusion grounded in the codebase.
| Intel PCIe transport | **builds, host-tested** | `redbear-iwlwifi`: ~2450 lines C transport + ~1550 lines Rust CLI. Real 802.11 RX frame parsing, DMA ring management, TX reclaim, ISR/tasklet dispatch, command response parsing, mac80211 ops, station state transitions, key management. Commands time out without real firmware — by design. |
| LinuxKPI compatibility | **builds, host-tested** | `linux-kpi`: 17 Rust modules, 93 tests. cfg80211/wiphy/mac80211 registration, ieee80211_ops 12-callback dispatch, PCI MSI/MSI-X, DMA pool, sk_buff, NAPI poll, list_head, atomic_t, completion, IO barriers, BSS/channel/band/rate, scan/connect/disconnect events, BSS registry with reference release. |
| IRQ dispatch | **builds, host-tested** | `request_irq`/`free_irq`/`disable_irq`/`enable_irq` fully implemented with real `scheme:irq/{}` integration, thread-based dispatch, and mask/unmask support. |
| Test coverage | **119 tests pass** | 93 linux-kpi + 8 redbear-iwlwifi + 18 redbear-wifictl. No production `unwrap()` in Wi-Fi daemon request loop (startup uses `expect()`). Host-tested; Redox-only C transport paths are compile-tested but not directly exercised by host tests. |
| Firmware loading | **partial** | `firmware-loader` can serve blobs generically. |
| Control plane | **host-tested** | `redbear-wifictl` daemon + `/scheme/wifictl` scheme with stub and Intel backends, state-machine enforcement, firmware-family reporting. Daemon request loop has graceful shutdown on socket errors. |
| Profile orchestration | **host-tested** | `redbear-netctl` Wi-Fi profiles (SSID/Security/Key), bounded prepare→init-transport→activate-nic→connect→disconnect flow, DHCP handoff. |
| Runtime diagnostics | **host-tested** | `redbear-info` Wi-Fi surfaces, packaged validators (`redbear-phase5-wifi-check/run/capture/analyze`). |
| Real hardware validation | **missing** | No Intel Wi-Fi device has been exercised. Transport is structurally correct but functionally unproven. |
| Desktop Wi-Fi API | **missing** | No NetworkManager-like or D-Bus Wi-Fi surface. |
### Transport Quality (from hardening pass)
The iwlwifi transport has been hardened with these specific improvements:
- **Atomic command state**: `command_complete`, `last_cmd_id`, `last_cmd_cookie`, `last_cmd_status` use `__atomic_store_n`/`__atomic_load_n` with `__ATOMIC_SEQ_CST` — no torn reads between ISR and command submission.
- **Stale response sentinel** (0xFFFF): After command timeout, the response fields are poisoned so a late-arriving firmware response cannot be misattributed to the next command.
- **Command queue space management**: `iwl_pcie_send_cmd` reclaims completed TX descriptors before submitting each command. If the command queue is still full after reclaim, the command fails immediately rather than entering the overflow queue — commands are synchronous and one-at-a-time, so overflow queuing would create ownership ambiguity.
- **DMA read barrier**: `rmb()` added after `dma_sync_single_for_cpu()` and before parsing RX frame data — ensures correct ordering on weakly-ordered architectures.
- **TX queue selection safety**: `rb_iwlwifi_choose_txq()` returns -1 when no data queue is active instead of falling back to the command queue — data frames never use the command queue.
- **TX error handling**: `iwl_ops_tx` now properly frees the skb on failure and logs warnings instead of silently swallowing errors.
- **Association BSSID guard**: BSSID from association-response frames is only copied to transport state when `trans->connecting` is set — prevents stale frames from corrupting connection state.
- **TXQ stuck detection fix**: Removed `trans->irq <= 0` from stuck detection — queue stuckness is independent of IRQ allocation state.
- **RX drain**: Parses 802.11 frame_control type/subtype before freeing — distinguishes data, management, and control frames instead of blind disposal.
- **RX restock**: Write pointer pushed to hardware in both restock and start_dma paths — prevents DMA ring starvation.
- **TX reclaim**: Full DMA unmap cycle — no leaked mappings.
- **BSS registry cleanup**: `cfg80211_put_bss()` now removes entries from the BSS registry and cleans up associated IEs — no memory leak on repeated scans.
### LinuxKPI Compat Layer Improvements
The linux-kpi compatibility layer has been enhanced with real frame delivery and statistics:
- **RX callback mechanism**: `ieee80211_register_rx_handler(hw, callback)` registers a per-hw
callback that receives drained RX frames. When `ieee80211_rx_drain` processes queued frames,
it delivers them to the registered callback instead of logging and freeing. This allows the
upper layer (e.g., a Redox wireless daemon) to consume frames in real time.
- **TX statistics tracking**: `ieee80211_get_tx_stats(hw)` returns per-hw TX completion counters
(total, acked, nacked). `ieee80211_tx_status` increments these on every TX completion.
- **Full frame data in cfg80211 events**: `cfg80211_rx_mgmt` now stores complete frame data (not
just metadata) in the wireless event state, enabling later consumption by the native wireless
stack. `cfg80211_mgmt_tx_status` similarly stores full TX frame data.
- **IRQ dispatch confirmed real**: `request_irq`/`free_irq`/`disable_irq`/`enable_irq` use real
`scheme:irq/{}` integration with thread-based dispatch and mask/unmask support — not stubs.
- **119 tests pass**: 93 linux-kpi + 8 redbear-iwlwifi + 18 redbear-wifictl.
### Honest Assessment
Without real hardware + firmware:
- Command submission times out (no firmware alive response)
- Scan returns no results (no firmware scan response)
- Association does not complete
- RX frames are never processed
The code reports these states honestly (timeout, no results) rather than fabricating success.
Hardware runtime validation is the required next gate.
## Architecture
### Subsystem Boundaries
```
User-facing
redbear-netctl (profiles, CLI)
redbear-netctl-console (ncurses TUI)
│
▼
/scheme/wifictl (redbear-wifictl daemon)
│ scan / auth / association / link state / credentials
▼
redbear-iwlwifi (driver daemon)
│ PCIe transport / firmware / DMA / IRQ
▼
linux-kpi (compatibility glue)
│ PCI / MMIO / IRQ / DMA / sk_buff / mac80211 ops
▼
redox-driver-sys (scheme:memory, scheme:irq, scheme:pci)
│
firmware-loader (scheme:firmware)
│
Kernel: scheme-based primitives only
Post-association IP path:
smolnetd → netcfg → dhcpd → redbear-netctl
```
### Key Design Decisions
1. **Native control plane above the driver** — `redbear-wifictl` owns scan/auth/association, not `redbear-netctl`.
2. **Bounded Intel transport port below that boundary** — reuse Linux-facing firmware/PCI/MMIO logic where it lowers cost.
3. **No full Linux wireless stack port** — cfg80211/mac80211/nl80211 are out of scope for the first milestone.
4. **`redbear-netctl` is the profile manager, not the supplicant** — it hands off to `/scheme/wifictl`, which hands off to the driver.
### Port vs Rewrite
The chosen approach is a **bounded transport-layer port with native control-plane rewrite above it**:
- Port and reuse transport-layer and firmware-facing logic from Linux `iwlwifi`
- Keep the native Red Bear control plane above that boundary
- Do not import the whole Linux wireless stack in one step
## Hardware Strategy
### Target hardware scope
- **Target**: Intel Wi-Fi chips on Arrow Lake and older Intel client platforms
- **Driver family**: `iwlwifi`-class (7000/8000/9000/AX210/BZ)
- **Security scope**: Open networks + WPA2-PSK only (phase 1)
- **Out of scope**: WPA3, 802.1X, AP mode, roaming, monitor mode, suspend/resume, multi-BSS
The target scope for this plan is now:
## Implementation Phases
- **Intel Wi-Fi chips used on Arrow Lake and older Intel client platforms**
### Phase W0 — Scope Freeze ✅ Complete
That includes the practical `iwlwifi` family boundary, not an abstract FullMAC-first family chosen
for architectural neatness.
- Intel target scope frozen
- Security scope frozen (open + WPA2-PSK)
- `redbear-wifi-experimental` config slice defined (`config/redbear-wifi-experimental.toml`)
- Unsupported features documented
### What this means for phase 1
### Phase W1 — Intel Driver Substrate Fit ✅ Complete (build-side)
Phase 1 is no longer “pick any convenient Wi-Fi family.”
- Intel device family mapped onto `redox-driver-sys` primitives
- Firmware naming/fetch path wired through `firmware-loader`
- Minimum `linux-kpi` additions identified and implemented (93 tests)
- All additions stay below the wireless control-plane boundary
Phase 1 is now:
**Exit criteria met (build-side)**: Intel target device can be discovered, initialized, and paired
with its firmware-loading path — in compiled/host-tested code. Real hardware validation still pending.
- prove one bounded Intel client Wi-Fi path,
- keep the support language experimental,
- and avoid promising the entire Linux wireless stack up front.
### Phase W2 — Native Wireless Control Plane ✅ Complete (host-tested)
## Security Scope Freeze
- `redbear-wifictl` daemon with `/scheme/wifictl` scheme
- Stub backend for end-to-end control-plane validation
- Intel backend: device detection, firmware-family reporting, transport-readiness, state machine
- `redbear-netctl` Wi-Fi profile support (SSID/Security/Key)
- Bounded prepare→init-transport→activate-nic→scan→connect→disconnect flow
- `redbear-netctl-console` ncurses TUI client
### Phase-1 supported security
**Exit criteria met (host-tested)**: Daemon reports scan results and link state honestly in
host-side tests. Runtime validation pending.
- open networks
- WPA2-PSK
### Phase W3 — Network Stack for Post-Association Handoff ✅ Complete (build-side)
### Explicitly out of initial scope
- `netcfg` exposes per-device interface nodes dynamically (not hard-coded `eth0`)
- `redbear-netctl` performs DHCP handoff for Wi-Fi profiles
- Native IP plumbing can consume a post-association Wi-Fi interface
- WPA3
- 802.1X / enterprise Wi-Fi
- AP mode
- roaming
- monitor mode
- suspend/resume guarantees
- multi-BSS support
- sophisticated regulatory-domain handling
**Exit criteria met (build-side)**: A connected Wi-Fi link can be handed off to the existing IP
path without treating it as raw Ethernet. Runtime validation pending.
This scope freeze is required to keep the first milestone honest and achievable.
### Phase W4 — First Association Milestone 🚧 Not started (blocked on hardware)
## Comprehensive Full Plan
## Current Implementation Progress
### Already landed in-tree
The current repo now contains a **bounded Phase W0/W2/W3 slice**:
- the plan target is explicitly Intel Arrow Lake and older Intel Wi-Fi chips
- `redbear-netctl` now supports Wi‑Fi profiles with `Connection=wifi`, `Interface=...`, `SSID`,
`Security`, and `Key` / `Passphrase`
- `netctl` now performs a bounded `prepare` → `init-transport` → `connect` handoff into
`/scheme/wifictl`
- that user-facing path now also includes a bounded `activate-nic` step before `connect`
- `netctl scan <profile|iface>` now uses the same `prepare` → `init-transport` ordering before the
active `scan` action
- `netcfg` no longer hard-codes a single `eth0` interface node and can expose interfaces from the
current device list dynamically
- `redbear-wifictl` now exists as a real package/daemon/scheme with:
- a stub backend for end-to-end control-plane validation
- an Intel-oriented backend boundary for Arrow Lake-and-lower families
- firmware-family and firmware-presence reporting
- a bounded `prepare` step before `connect`
- transport-readiness reporting derived from PCI command/BAR/IRQ state
- a bounded PCI transport-prep action that enables memory-space and bus-master bits before connect
- a bounded `scan` action with a working stub path and a bounded Intel scan/reporting path rather
than the older explicit `not implemented yet` result
- a bounded `init-transport` state boundary after preparation and before any future association path
- a bounded `activate-nic` state boundary after `init-transport`
- state-machine enforcement so Intel scan/connect refuse to proceed before `init-transport`
- `redbear-info` and the runtime helper scripts now expose the Wi‑Fi control-plane surfaces
- `redbear-info` now reports Wi‑Fi firmware status, transport status, activation status, and scan results from the
primary Wi‑Fi control interface
- `redbear-info` and the runtime helper also now expose `transport-init-status`, which separates
simple transport probing from an actual transport-initialization attempt
- on Redox runtime builds where `/usr/lib/drivers/redbear-iwlwifi` is present **and** at least one
Intel Wi-Fi candidate is actually detectable, `redbear-wifictl` now auto-selects the Intel backend
instead of silently falling back to the stub backend
- if the Intel driver package is present but no Intel Wi-Fi candidate is detected, `redbear-wifictl`
now exposes a dedicated no-device fallback rather than a synthetic stub `wlan0`, so the runtime
does not pretend the Intel path is usable
### What this means
This does **not** mean Red Bear has working Intel Wi‑Fi connectivity yet.
It means the repo now has:
- a real Wi‑Fi profile model,
- a real Wi‑Fi control-plane daemon and scheme,
- a first dedicated Intel Wi‑Fi driver-side package (`redbear-iwlwifi`),
- a runtime helper for the bounded Intel driver probe path (`local/scripts/test-iwlwifi-driver-runtime.sh`),
- a runtime check that the Wi‑Fi control daemon selects the Intel backend only when Intel Wi‑Fi
candidates are actually present,
- a native post-association IP handoff path that can address non-`eth0` interfaces,
- and a firmware-aware, transport-aware Intel backend boundary.
- and a bounded active scan surface.
- and a bounded transport-initialization surface.
The current bounded implementation is therefore no longer just static plumbing. It now has a real
user-facing Wi‑Fi orchestration flow through `netctl`, a real control daemon state machine, and a
real Intel-targeted firmware/transport preparation boundary.
That is the first substantial Wi‑Fi bring-up slice, but not the final result.
### Still missing after the current slice
- real Intel transport initialization
- actual firmware loading/prepare action on Redox target hardware
- scan implementation against real hardware
- authentication and association
- WPA2 key negotiation on a real link
- DHCP/static IP handoff on a real associated wireless interface
- runtime validation on Intel hardware or a realistic guest path
### Phase W0 — Scope Freeze and Package-Group Definition
**Goal**: Define the first Wi-Fi milestone precisely before implementation starts.
**Goal**: One real Wi-Fi connection under phase-1 scope.
**What to do**:
1. Obtain an Intel Wi-Fi device (iwlwifi-class) for bare-metal or VFIO passthrough testing
2. Boot Red Bear on hardware with the Intel Wi-Fi PCI function visible
3. Verify firmware loads via `firmware-loader`
4. Verify transport init succeeds (command queue alive, firmware responds)
5. Scan for one real SSID
6. Join one test network (open or WPA2-PSK)
7. Hand off to DHCP or static IP
8. Confirm bidirectional connectivity
- freeze the target scope to Intel Arrow Lake and older Intel Wi-Fi chips
- freeze security scope to open + WPA2-PSK
- define `net-wifi-experimental` as the package/config slice for first Wi-Fi support
- document unsupported wireless features explicitly
**Exit criteria**: One Intel device family reaches usable network connectivity on a real network.
**Exit criteria**:
**Prerequisites**:
- Intel Wi-Fi PCI device available for testing
- `low-level controller` / IRQ quality validated (current blocker chain)
- Firmware blobs for the target device family
- Intel target scope is explicit
- support language and non-goals are written down
- the repo has a standalone tracked Wi-Fi experimental profile (`config/redbear-wifi-experimental.toml`) extending the minimal Red Bear baseline
### Phase W5 — Runtime Reporting and Recovery (After W4)
---
- Extend `redbear-info` with real Wi-Fi runtime evidence (not just bounded surfaces)
- Reconnect after disconnect
- Failure-state reporting and retry
- `redbear-phase5-wifi-check/run/capture/analyze` validated against real hardware
### Phase W1 — Intel Driver Substrate Fit
**Goal**: Prove the Intel target family can fit Red Bear’s existing driver primitives and identify
the minimum additional compatibility surface required.
**What to do**:
- map the Intel target family onto `redox-driver-sys`
- verify firmware naming and fetch path through `firmware-loader`
- identify exactly which `linux-kpi` additions are mandatory for Intel transport/firmware bring-up
- keep those additions below the wireless control-plane boundary
**Exit criteria**:
- one Intel target device can be discovered, initialized, and paired with its firmware-loading path
---
### Phase W2 — Native Wireless Control Plane
**Goal**: Add a Red Bear-native wireless daemon and control interface.
**What to do**:
- implement a Wi-Fi daemon that owns:
- scan state
- auth/association state
- link state
- disconnect/retry behavior
- credential ownership
- add a user-facing `wifictl`-style control surface
**What not to do**:
- do not push supplicant logic into `redbear-netctl`
- do not model Wi-Fi as “just another Ethernet profile” at this phase
**Exit criteria**:
- the daemon can report scan results and current link state honestly
---
### Phase W3 — Network Stack Refactor for Post-Association Handoff
**Goal**: Make the native IP stack accept Wi-Fi as a first-class post-association interface.
**What to do**:
- generalize current `eth0` / Ethernet assumptions where needed
- allow the native stack to consume a post-association Wi-Fi interface state
- keep route/address/DNS handling in native `netcfg` / `smolnetd` plumbing after association
**Exit criteria**:
- a connected Wi-Fi link can be handed off to the existing IP path without pretending it is merely a
raw Ethernet control-plane object
---
### Phase W4 — First Association Milestone
**Goal**: Achieve one real Wi-Fi connection under the frozen phase-1 scope.
**What to do**:
- scan for one real SSID
- join one test network
- complete open or WPA2-PSK association
- hand off to DHCP or static IP configuration
**Exit criteria**:
- one chosen device family reaches usable network connectivity on a real network
---
### Phase W5 — Runtime Reporting and Recovery
**Goal**: Make Wi-Fi support diagnosable and honest.
**What to do**:
- extend `redbear-info` with Wi-Fi-specific runtime reporting
- add reconnect and failure-state reporting
- keep all support labels experimental
**Exit criteria**:
- users can see whether hardware is present, firmware is loaded, scans succeed, and association has
succeeded or failed
---
**Exit criteria**: Users can see whether hardware is present, firmware is loaded, scans succeed,
and association has succeeded or failed — backed by real hardware evidence.
### Phase W6 — Desktop Compatibility (Later)
**Goal**: Add desktop-oriented control only after native Wi-Fi works.
- If KDE or desktop workflows require it, add a compatibility shim over the native Wi-Fi service
- Keep the shim above the native control plane, not in place of it
**What to do**:
### Phase W7 — Broader Hardware Reassessment (Later)
- if KDE or desktop workflows require it, add a small compatibility shim over the native Wi-Fi
service
- keep that shim above the native control plane, not in place of it
**Exit criteria**:
- desktop Wi-Fi workflows become possible without changing the native subsystem boundaries
---
### Phase W7 — Broader Hardware and `linux-kpi` Reassessment
**Goal**: Reassess whether Red Bear wants to widen Wi‑Fi support after one bounded Intel path works.
**What to do**:
- only after one bounded Intel transport/association path is validated, decide whether a wider
multi-family or deeper `linux-kpi` path is worth the cost
- do not assume this is automatically justified
**Exit criteria**:
- Red Bear either keeps the narrow native-first architecture, or consciously chooses a larger Linux
wireless-compat effort with full awareness of the cost
- After one bounded Intel path is validated, reassess whether wider multi-family or deeper
`linux-kpi` growth is justified
- Do not assume this is automatically warranted
## Validation Gates
Wi-Fi should not be described as supported until these gates are passed in order:
Wi-Fi should not be described as supported until these gates pass in order:
1. hardware is detected
2. firmware loads successfully
3. the driver/daemon initializes and reports link state
4. scan sees a real SSID
5. association succeeds for one supported network type
6. DHCP or static IP handoff succeeds through the native network stack
7. reconnect works after disconnect or reboot
8. `redbear-info` and profile docs report supported and unsupported states honestly
1. ✅ Hardware detected via PCI scheme
2. 🚧 Firmware loads successfully
3. 🚧 Driver/daemon initializes and reports link state
4. 🚧 Scan sees a real SSID
5. 🚧 Association succeeds for one supported network type
6. 🚧 DHCP or static IP handoff succeeds
7. 🚧 Reconnect works after disconnect or reboot
8. 🚧 `redbear-info` reports all states honestly with real evidence
Until then, support language should remain under `net-wifi-experimental` only.
Until all gates pass, support language stays under `redbear-wifi-experimental`.
## Support-Language Guidance
## Current Blockers
Until the validation gates above are passed, Red Bear should use language such as:
1. **No Intel Wi-Fi hardware available for testing** — the current host has a MediaTek MT7921K
(`14c3:0608`), not an Intel `iwlwifi` device
2. **Low-level controller / IRQ quality** — must be validated before driver bring-up is reliable
3. **VFIO not loaded on current host** — passthrough path requires `vfio_pci` module and compatible IOMMU groups
- “Wi-Fi is not supported yet”
- “Wi-Fi remains experimental and hardware-specific”
- “The current wireless path is an experimental Intel bounded-transport bring-up”
## Scripts and Validation Tools
Avoid language such as:
| Script | Purpose |
|---|---|
| `test-iwlwifi-driver-runtime.sh` | Bounded Intel driver lifecycle check in target runtime |
| `test-wifi-control-runtime.sh` | Bounded Wi-Fi control/profile runtime check |
| `test-wifi-baremetal-runtime.sh` | Strongest in-repo Wi-Fi runtime check on real Red Bear target |
| `test-wifi-passthrough-qemu.sh` | QEMU/VFIO Wi-Fi validation with in-guest checks |
| `validate-wifi-vfio-host.sh` | Host-side VFIO passthrough readiness check |
| `prepare-wifi-vfio.sh` | Bind/unbind Intel Wi-Fi PCI function for VFIO |
| `run-wifi-passthrough-validation.sh` | One-shot host wrapper for full passthrough validation |
| `package-wifi-validation-artifacts.sh` | Package validation artifacts into host-side tarball |
| `summarize-wifi-validation-artifacts.sh` | Summarize captured artifacts for quick triage |
| `finalize-wifi-validation-run.sh` | Analyze capture bundle and package final evidence set |
- “Linux Wi‑Fi drivers are supported”
- “wireless support works”
- “Wi-Fi is generally available”
Packaged validators (inside target runtime):
- `redbear-phase5-wifi-check` — bounded in-target Wi-Fi validation
- `redbear-phase5-wifi-run` — run bounded Wi-Fi lifecycle
- `redbear-phase5-wifi-capture` — capture runtime evidence bundle
- `redbear-phase5-wifi-analyze` — analyze captured evidence
- `redbear-phase5-wifi-link-check` — link-level validation
unless profile-scoped validation evidence exists.
## Related Documents
- `local/docs/WIFI-VALIDATION-RUNBOOK.md` — canonical operator runbook for bare-metal and VFIO validation
- `local/docs/WIFI-VALIDATION-ISSUE-TEMPLATE.md` — issue template for validation failures
- `local/docs/WIFICTL-SCHEME-REFERENCE.md` — `/scheme/wifictl` protocol reference
- `docs/04-LINUX-DRIVER-COMPAT.md` — linux-kpi and redox-driver-sys architecture
## Summary
The best Red Bear Wi-Fi path is **native-first**:
- native wireless control plane
- one experimental bounded Intel family path first
- Native wireless control plane (`redbear-wifictl` + `redbear-netctl`)
- One experimental Intel family path first (`redbear-iwlwifi`)
- `firmware-loader` + `redox-driver-sys` underneath
- optional narrow `linux-kpi` glue only where useful
- native `smolnetd` / `netcfg` / `redbear-netctl` reused only after association
- Narrow `linux-kpi` glue only where useful (93 tests, 17 modules)
- Native `smolnetd` / `netcfg` / `dhcpd` reused after association
`linux-kpi` is therefore **feasible only in a narrow sense**. It is useful as a low-level helper
for driver bring-up, but it is not currently a viable full Wi‑Fi architecture for Red Bear OS.
That is the most realistic way to integrate Wi‑Fi into Red Bear while keeping the design aligned
with the repo’s current userspace-driver and profile-based architecture.
The codebase has 119 tests passing (93 linux-kpi + 8 redbear-iwlwifi + 18 redbear-wifictl), no production `unwrap()` in the Wi-Fi daemon request loop (startup uses `expect()`), atomic command
handling, proper timer cancellation, honest timeout reporting, and real 802.11 frame parsing.
The structural skeleton is solid. The next required step is **real hardware validation** with an
Intel Wi-Fi device — everything else is gated on that.