RedBear-OS/local/docs/WIFI-IMPLEMENTATION-PLAN.md

# 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.