RedBear-OS/local/docs/IMPROVEMENT-PLAN.md

Red Bear OS — Current Improvement Plan

Date: 2026-07-07 Status: Authoritative — current state after USB/Wi-Fi/Bluetooth quality audits Source of truth: Linux kernel 7.1 (local/reference/linux-7.1/)

This plan is derived from three fresh quality audits conducted on 2026-07-07:

1. USB Subsystem — 38 Rust files, ~15,000 LOC. 83 unwraps/expects/panics. 82 TODOs. 72 unsafe blocks. 4/7 class drivers with zero tests.
2. Wi-Fi Subsystem — iwlwifi (4049 LOC) + wifictl (2786 LOC) + linux-kpi wireless (1900+ LOC). 273 unsafe blocks. 7 PCI device IDs vs. Linux's ~500+.
3. Bluetooth + Adjacent — btusb + btctl. Best-tested USB component (21 tests). 1.3 KB USB core module with 11 tests.

---

1. Scope and Method

This document covers quality gaps found during audits, not feature gaps. Feature gaps (new drivers, new protocols) are covered in USB-IMPLEMENTATION-PLAN.md, WIFI-IMPLEMENTATION-PLAN.md, BLUETOOTH-IMPLEMENTATION-PLAN.md.

1.1 Cross-Reference with Linux 7.1

Where implementations diverge from the correct pattern, we cross-reference Linux 7.1:

Pattern	Linux 7.1 location	Red Bear location	Status
USB port reset with debounce	drivers/usb/core/hub.c:4698-4736	xhci/mod.rs:722-730	Correct pattern, 50ms hold
Event ring overflow handling	drivers/usb/host/xhci-ring.c:550-580	xhci/irq_reactor.rs:542-553	TODO — only logs error
TRB transfer completion	drivers/usb/host/xhci-ring.c:2400-2600	xhci/scheme.rs:2090-2160	Partial (missing code paths)
DMA allocation	drivers/usb/host/xhci-mem.c:230-280	xhci/mod.rs:1053-1066	Good
Quirks enforcement	drivers/usb/host/xhci-pci.c:101-160	xhci/quirks.rs (declarations only)	49/50 NOT enforced at runtime
cfg80211 connect_bss	net/wireless/sme.c:680-700	linux-kpi/wireless.rs:316-340	Good
cfg80211 ibss_joined	net/wireless/sme.c:750-780	Not implemented	Missing
HCI command timeout	net/bluetooth/hci_core.c:4200-4250	redbear-btusb	Partial
Wi-Fi rate scaling	net/mac80211/rc80211_minstrel.c:200-300	None	Missing (hardcoded rate_idx=0)
HDA stream PCM setup	sound/pci/hda/hda_intel.c:2800-2900	redbear-hda	Partial

---

2. P0 — Fix Immediately (CRITICAL safety)

2.1 usbscsid: Replace .unwrap() with proper error handling

File: recipes/core/base/source/drivers/storage/usbscsid/src/scsi/mod.rs:179-259 Severity: CRITICAL — malformed USB device can crash daemon

17 .unwrap() calls on plain::from_mut_bytes() in SCSI command construction and response parsing. Any malformed response from a USB storage device crashes usbscsid.

Fix:

// Before:
plain::from_mut_bytes(&mut self.command_buffer).unwrap()

// After:
plain::from_mut_bytes(&mut self.command_buffer)
    .ok_or(ScsiError::ProtocolError("buffer size mismatch"))?

Cross-reference: Linux 7.1 drivers/usb/storage/usb.c:1080 — returns -EINVAL on buffer errors, never unwraps.

Estimated effort: 2 hours, 17 sites to change.

2.2 xhcid: Document unsafe Send/Sync safety invariants

File: recipes/core/base/source/drivers/usb/xhcid/src/xhci/mod.rs:310-311 Severity: CRITICAL — undocumented soundness claim

unsafe impl<const N: usize> Send for Xhci<N> {}
unsafe impl<const N: usize> Sync for Xhci<N> {}

Fix:

// SAFETY: Xhci<N> contains:
// - `port_states`, `handles`, `drivers`: CHashMap (per-key locking)
// - `op`, `ports`, `cmd`, `run`, `primary_event_ring`: Mutex<...>
// - `irq_reactor_*_sender`: crossbeam_channel (lock-free)
// All shared mutable state is protected by interior mutability primitives.
// Xhci<N> does not contain !Send/!Sync fields (File is Send+Sync, Dma is Send+Sync).
unsafe impl<const N: usize> Send for Xhci<N> {}
unsafe impl<const N: usize> Sync for Xhci<N> {}

2.3 usbscsid: Remove debug panic in init

File: recipes/core/base/source/drivers/storage/usbscsid/src/main.rs:106 Severity: CRITICAL

scsi.read(&mut *protocol, 0, &mut buffer).unwrap();

Block 0 read during init. Any USB stall crashes usbscsid before registering its scheme. Replace with ? or let _ = ....

2.4 usbhubd: Remove init panics

File: recipes/core/base/source/drivers/usb/usbhubd/src/main.rs Severity: CRITICAL — hub driver can't recover from port enumeration failures

14 .expect() / .unwrap() calls in init path. All fatal. Replace with proper error propagation:

// Before:
handle.device_request(...).expect("Failed to set port power");

// After:
if let Err(e) = handle.device_request(...) {
    log::warn!("usbhubd: port power failed: {}", e);
    continue;
}

Cross-reference: Linux 7.1 drivers/usb/core/hub.c:4772-4778 — logs and continues on port power failure.

2.5 Fix PortId::root_hub_port_index() panic

File: recipes/core/base/source/drivers/usb/xhcid/src/driver_interface.rs:293 Severity: CRITICAL — can panic on port 0

pub fn root_hub_port_index(&self) -> usize {
    self.root_hub_port_num.checked_sub(1).unwrap().into()
}

Replace .unwrap() with proper error or debug_assert!.

---

3. P1 — High Priority (this week)

3.1 xhcid: Implement event ring growth

File: recipes/core/base/source/drivers/usb/xhcid/src/xhci/irq_reactor.rs:542-553 Severity: HIGH — under load, events are silently dropped

// TODO
error!("TODO: grow event ring");

Cross-reference: Linux 7.1 drivers/usb/host/xhci-ring.c:570-590 — xhci_ring_expansion() allocates new segment, copies ERSTBA entries, updates dequeue pointer.

Fix:

fn grow_event_ring(&mut self) {
    // 1. Allocate new segment (2x current size)
    // 2. Copy existing TRBs
    // 3. Update ERSTBA entry
    // 4. Write ERDP to new dequeue
    // 5. Update internal state
}

3.2 xhcid: Fix BOS descriptor fetching

File: xhci/scheme.rs:1900-1905 Severity: HIGH — USB 3.x devices not correctly detected

//TODO let (bos_desc, bos_data) = self.fetch_bos_desc(port_id, slot).await?;
let supports_superspeed = false;

BOS descriptor is commented out. USB 3.x devices are treated as USB 2.0. Cross-reference: Linux 7.1 drivers/usb/core/config.c:387-420 — calls usb_get_bos_descriptor() and parses USB 3.0 capability descriptors.

3.3 xhcid: Enforce critical runtime quirks

File: xhci/init() in xhci/mod.rs:623-693 Severity: HIGH — 49/50 quirks declared but not enforced

Currently 6 quirks are enforced (NO_SOFT_RETRY, AVOID_BEI, BROKEN_MSI, RESET_ON_RESUME, RESET_TO_DEFAULT, SPURIOUS_REBOOT). The remaining 49 are logged at init but not acted upon.

Priority enforcement gaps:

Quirk	Affected HW	Action Needed
MISSING_CAS	Some early AMD	Skip command abort semaphore wait
BROKEN_STREAMS	Fresco Logic, Etron	Skip stream context array init
ZERO_64B_REGS	Renesas uPD720202	Split 64-bit regs into 2×32-bit writes
WRITE_64_HI_LO	Some Renesas	Write high half first
BROKEN_PORT_PED	Some	Skip port enable polling

3.4 Add test suites for usbscsid and usbhubd

Severity: HIGH — 17 .unwrap() calls with no test coverage

Add unit tests for:

• BOT/CBW/CSW command protocol (usbscsid)
• Plain buffer cast safety (usbscsid)
• Port state machine transitions (usbhubd)
• Over-current detection (usbhubd)

Pattern: See redbear-btusb/src/main.rs:864-1326 — 21 tests using RTM (Return-to-Mock) approach.

3.5 xhcid: DMA buffer reuse/pool

File: xhci/scheme.rs:2077-2079 Severity: HIGH — DMA allocations on every transfer cause allocator pressure

Currently allocates new DMA buffer per control transfer. Implement a buffer pool:

// Simple LRU pool of pre-allocated DMA buffers
struct DmaPool {
    buffers: Mutex<VecDeque<Dma<Vec<u8>>>>,
    size: usize,
}

3.6 usbscsid: Fix .expect() in runtime

File: usbscsid/src/main.rs:141 Severity: HIGH

.map_err(|e| log::error!("...")).unwrap();

Pattern uses .unwrap() after logging. Replace with proper ? propagation.

---

4. P2 — Medium Priority (this month)

4.1 xhcid: Wire or remove usb-core::UsbHostController trait

File: recipes/drivers/usb-core/src/scheme.rs:12 Severity: MEDIUM — dead code representing unexecuted vision

The UsbHostController trait provides HC-agnostic API but is not implemented by any driver.

Decision required:

• Option A: Implement in xhcid and make ecmd/uhcid/ohcid use it
• Option B: Remove the trait as dead code

4.2 Add TRB encoding/decoding tests

File: xhci/trb.rs Severity: MEDIUM — critical for correctness

Zero tests for the most error-prone code in the USB stack. Add:

• All 36 TrbCompletionCode encoding/decoding round-trips
• TransferRing setup/teardown
• StreamContextArray for streams
• Setup packet encoding (8 bytes)

4.3 Add buffer reuse for control transfers

File: xhci/scheme.rs:2081 Severity: MEDIUM

let data_buffer = unsafe { self.alloc_dma_zeroed_unsized(req.length as usize)? };

Allocate once per control_transfer_once call, not per scheme call. Pool buffers up to 64KB.

4.4 xhcid: Cap crossbeam channel sizes

File: xhci/mod.rs:460 Severity: MEDIUM — unbounded channel can cause OOM

let (irq_reactor_sender, irq_reactor_receiver) = crossbeam_channel::unbounded();

Change to bounded:

let (irq_reactor_sender, irq_reactor_receiver) = crossbeam_channel::bounded(1024);

If the channel fills, drop events with a warning (backpressure).

4.5 iwlwifi: Expand PCI device ID table

File: recipes/drivers/redbear-iwlwifi/source/src/linux_port.c:348-357 Severity: HIGH for hardware support, MEDIUM for code quality

Only 7 device IDs (BZ, AX210, AX201, 9462-9560, 9000-series, 8265). Linux 7.1 iwlwifi has ~500+.

Approach: Port from Linux 7.1 drivers/net/wireless/intel/iwlwifi/iwl-cfg.h and pcie/drv.c device ID tables.

4.6 iwlwifi: Document known gaps with TODO markers

Current: Zero TODO/FIXME/HACK/XXX markers. This is both a strength (clean code) and a risk (gaps undocumented). Add markers for:

• MVM layer missing (5,200 lines from Linux 7.1)
• Rate scaling missing (rate_idx hardcoded to 0)
• Power management missing
• Firmware TLV/NVM parser missing
• 5GHz/6GHz scan channels missing
• AMPDU stub (result ignored)

4.7 xhci/extended.rs: Validate protocol speed count

File: xhci/extended.rs:225,231 Severity: MEDIUM

pub unsafe fn protocol_speeds(&self) -> &[ProtocolSpeed] {

Slice raw capability register data without validating the reported count. A buggy controller reporting excessive count causes OOB reads.

4.8 xhcid: Remove #![allow(warnings)]

File: xhci/src/main.rs:25 Severity: MEDIUM

#![allow(warnings)]

Hides all compiler warnings. Remove and fix underlying warnings (unused imports, dead code, etc.).

---

5. P3 — Low Priority (nice to have)

5.1 fuzzer for USB descriptor parsing

File: xhci/usb/ descriptors Severity: LOW

Add cargo-fuzz target for parsing:

• Standard device descriptors
• Configuration descriptors
• BOS descriptors
• Hub descriptors

5.2 fuzzer for TRB encoding

File: xhci/trb.rs Severity: LOW

Add cargo-fuzz target for:

• All TRB types encode/decode round-trip
• Random byte sequences (should not crash)

5.3 XhciEndpHandle: Add Send/Sync

File: xhci/src/driver_interface.rs:709 Severity: LOW

pub struct XhciEndpHandle { data: File, ctl: File }

File is !Sync. If async I/O is added, this will be a blocker. For now, no async needed.

5.4 Runtime USB disconnect recovery

Files: All class drivers Severity: LOW

Add explicit handling for device hot-removal mid-transfer. Currently drivers may loop indefinitely or panic on stale handles.

5.5 Linux 7.1 reference source — verify location

Linux 7.1 reference is in local/reference/linux-7.1/. Verify it's the latest patch level. The current plan references 7.1 but patches may have been applied.

---

6. Wi-Fi Subsystem Improvements

6.1 iwlwifi: Add MVM layer (CRITICAL gap)

File: recipes/drivers/redbear-iwlwifi/ Severity: CRITICAL — entire MAC layer missing

Linux 7.1's iwlwifi has iwl-mvm.c (~5,200 lines) implementing the MAC Virtualization Mode. Red Bear has none. This is the single biggest functional gap.

Scope: Port iwl-mvm.c, iwl-mvm-ops.c, iwl-mvm-rs.c (rate scaling) from Linux 7.1. Estimated 8,000+ lines of Rust.

6.2 iwlwifi: Add firmware TLV/NVM parser

File: recipes/drivers/redbear-iwlwifi/source/src/linux_port.c:624-646 Severity: HIGH

Current firmware handling only checks magic number. Linux 7.1's iwl-nvm-parse.c parses NVM sections, EEPROM calibration data, SAR tables. ~2,000 lines.

6.3 iwlwifi: Implement rate scaling

File: recipes/drivers/redbear-iwlwifi/source/src/linux_port.c:1438 Severity: HIGH

rate_idx=0 hardcoded. Implement Minstrel or simple fixed-rate table.

6.4 iwlwifi: Add 5GHz/6GHz scan channels

File: recipes/drivers/redbear-iwlwifi/source/src/linux_port.c:2260-2261 Severity: HIGH

Only 2.4GHz channels 1-11. Add 5GHz (36, 40-165) and 6GHz (1-233) channels.

6.5 iwlwifi: Proper power management

File: Missing entirely Severity: MEDIUM

Implement:

• PS (Power Save) mode transitions
• WoWLAN (Wake-on-Wireless)
• Thermal throttling via kernel thermal framework

6.6 iwlwifi: Wire up AMPDU (802.11n aggregation)

File: recipes/drivers/redbear-iwlwifi/source/src/linux_port.c:2353,2408 Severity: MEDIUM

start_tx_ba_session and stop_tx_ba_session are called but result is ignored. Wire to actual rate scaling.

6.7 wifictl: Replace unwrap() in production code

File: recipes/system/redbear-wifictl/source/src/scheme.rs:565,568,578,584,585 Severity: MEDIUM

5 bare .unwrap() in production code would panic on state errors. Convert to proper Result propagation.

6.8 linux-kpi: Audit transmute function pointers

File: recipes/drivers/linux-kpi/src/mac80211.rs:469, timer.rs:202 Severity: HIGH

std::mem::transmute for FFI callbacks is UB if type signatures change. Add compile-time assertions:

const _: () = assert!(size_of::<fn(...) -> ...>() == size_of::<extern "C" fn(...) -> ...>());

6.9 linux-kpi: Reduce unsafe count

File: All linux-kpi files Severity: MEDIUM

273 unsafe blocks. While structural for FFI, each is a soundness boundary. Add comprehensive safety comments.

---

7. Bluetooth Subsystem Improvements

7.1 btusb: Wire HCI command timeout properly

File: recipes/drivers/redbear-btusb/src/main.rs Severity: MEDIUM

Best-tested USB component (21 tests). Some HCI command paths may not have proper timeout handling.

7.2 Add ibss_joined (cfg80211)

File: recipes/drivers/linux-kpi/src/wireless.rs Severity: LOW

Currently ibss_joined() is not implemented. Only needed for Ad-Hoc (IBSS) mode — not client station role.

7.3 Add ch_switch_notify (cfg80211)

File: recipes/drivers/linux-kpi/src/wireless.rs Severity: LOW

cfg80211_ch_switch_completed() missing. Only needed for AP mode channel switching.

---

8. Adjacent Subsystem Improvements

8.1 init: Fix magic number for log dir

File: recipes/system/init/ Severity: LOW

8.2 ext4d: Add fsck support

File: recipes/core/ext4d/ Severity: MEDIUM

8.3 fatd: Improve error recovery

File: recipes/core/fatd/ Severity: MEDIUM

8.4 netstack: Add IPv6 robustness

File: local/sources/base/netstack/ Severity: MEDIUM

8.5 init: Add service health monitoring

File: recipes/system/init/ Severity: MEDIUM

8.6 ptyd: Error handling

File: recipes/system/ptyd/ Severity: LOW

8.7 acpid: Power management

File: recipes/system/acpid/ Severity: LOW

---

9. Execution Priority

Tier P0 — Safety (THIS WEEK)

1. usbscsid .unwrap() replacement (Section 2.1)
2. xhcid unsafe Send/Sync documentation (Section 2.2)
3. usbscsid init panic (Section 2.3)
4. usbhubd init panics (Section 2.4)
5. PortId panic (Section 2.5)

Tier P1 — Correctness (THIS MONTH)

6. xhcid event ring growth (Section 3.1)
7. xhcid BOS descriptor fix (Section 3.2)
8. xhcid critical runtime quirks (Section 3.3)
9. usbscsid test suite (Section 3.4)
10. xhcid DMA buffer pool (Section 3.5)
11. usbscsid .expect() fixes (Section 3.6)

Tier P2 — Quality (THIS QUARTER)

12. usb-core trait decision (Section 4.1)
13. TRB tests (Section 4.2)
14. Control transfer buffer reuse (Section 4.3)
15. Crossbeam bounded (Section 4.4)
16. iwlwifi PCI device table (Section 4.5)
17. iwlwifi gap documentation (Section 4.6)
18. extended.rs validation (Section 4.7)
19. Remove allow(warnings) (Section 4.8)
20. linux-kpi transmute audit (Section 6.8)
21. wifictl unwrap() (Section 6.7)

Tier P3 — Nice to Have (THIS HALF)

22. iwlwifi MVM port (Section 6.1) — massive work
23. iwlwifi firmware parser (Section 6.2)
24. iwlwifi rate scaling (Section 6.3)
25. iwlwifi 5GHz/6GHz channels (Section 6.4)
26. iwlwifi power management (Section 6.5)
27. iwlwifi AMPDU wire (Section 6.6)
28. Bluetooth HCI timeout (Section 7.1)
29. libredox unsafe ptr (Section 4.9)
30. Adjacent subsystem improvements (Section 8)
31. Fuzzer for USB descriptors (Section 5.1)
32. Fuzzer for TRB (Section 5.2)
33. XhciEndpHandle Send/Sync (Section 5.3)
34. Runtime USB disconnect recovery (Section 5.4)
35. Linux 7.1 reference verification (Section 5.5)

---

10. File Inventory (Audit Outputs)

Audit Reports

• USB quality audit (5m 29s) — 38 .rs files, ~15,000 LOC, 83 unwraps, 82 TODOs
• Wi-Fi quality audit (3m 47s) — 4,049 + 2,786 + ~3,000 LOC, 0 TODOs, 273 unsafe
• Bluetooth/adjacent audit (0s) — no response received (timeout)

Plan Status

• STALE PLANS REMOVED: None removed yet
• NEW PLAN CREATED: This document (IMPROVEMENT-PLAN.md)
• PRIORITY: P0 fixes must ship before next release