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

# Red Bear OS USB Plan — v3

> **Status:** Canonical. Replaces v1 (archived `archived/USB-IMPLEMENTATION-PLAN-v1-2026-04.md`) and v2 (archived `archived/USB-IMPLEMENTATION-PLAN-v2-2026-07.md`).
> **Date:** 2026-07-07.
> **Goal:** Make USB a first-class citizen in Red Bear OS — mature, reliable, feature-complete host stack matching the user-visible capability of Linux 7.1.

## 0. Scope and method

This plan is the comprehensive roadmap for Red Bear OS USB. It is built from three sources:

1. **Code audit (v2 era, 2026-07-07):** every USB source file enumerated; TODOs, unwraps, and panic sites catalogued; maturity assessed per component.
2. **Linux 7.1 reference deep-dive:** `local/reference/linux-7.1/drivers/usb/` mapped feature-by-feature against Red Bear. Linux is treated as the implementation of excellence — structures, sequences, and edge-case handling are cross-referenced and reimplemented in Rust as needed.
3. **Upstream Redox commit scan:** 33 USB-relevant upstream commits (Jan 2025 – May 2026) tracked; 28 already adopted, 4 needing verification, 1 outstanding.

### Validation labels

- **builds** — code is in tree and compiles.
- **enumerates** — runtime surfaces can discover controllers, ports, descriptors.
- **usable-narrow** — one controller family / one class family works in a bounded scenario.
- **validated-QEMU** — a documented QEMU script passed on the matching recipe, config, and commit.
- **validated-hardware** — a named physical controller + class, with a captured log, on real bare metal.
- **experimental** — present for bring-up but not in any support-promised path.

### Linux 7.1 as the implementation of excellence

Where the v2 plan referenced Redox upstream commits, v3 references **Linux 7.1** as the canonical reference. When implementation detail is in doubt:

1. Check Linux 7.1 first.
2. If Linux has the algorithm, port it to Rust line-by-line (preserving the data structure layouts).
3. If Linux has multiple approaches (e.g., kernel vs. userspace), use the userspace model since Red Bear's USB drivers are all userspace.
4. Cite the Linux source file:line in commit messages.

## 1. Executive summary — gap analysis

| Dimension | Red Bear | Linux 7.1 | Gap |
|---|---|---|---|
| Total USB source lines | ~13,000 | ~280,000+ | ~22× |
| Host controllers with real implementations | 1 (xhcid) | 4 (xHCI, EHCI, UHCI, OHCI) | 3 missing |
| Host controllers building | 3 (ehcid, uhcid, ohcid) | — | — |
| Storage protocols | 1 (BOT) | 5+ (BOT, UAS, SAT, UASP, multi-LUN) | 4 missing |
| HID class features | Boot protocol only | Full report descriptor parsing, multi-touch, quirks | ~80% gap |
| Class drivers | 3 working + 3 empty stubs | 80+ drivers | ~75 missing |
| Hub driver lines | 249 | 6,567 (hub.c) | ~95% gap |
| xHCI quirks | 0 | 51 quirks | **CRITICAL** |
| Error recovery | Stall only | Babble, transaction error, split error, clear-TT | ~90% gap |
| Power management | None | Runtime PM, U1/U2, LPM, autosuspend | All missing |
| Hardware validation matrix | 0 entries | ~200 known-good controllers | All missing |

### P0 — already done (carried from v2)

P0 is complete and committed:

- **P0-A1** xHCI interrupts re-enabled (base fork `cbd40e0d`)
- **P0-A2** Reset fix verified in 0.1.0 baseline
- **P0-A3** CSZ cleanup (removed stale TODO, base fork `7cfed158`)
- **P0-A4** Bounds check on `root_hub_port_index()` (base fork `774a0ac1`)
- **P0-B1** EHCI auto-spawn + xhcid-compat scheme (ehcid + usb-core)
- **P0-B2** UHCI + OHCI real drivers (459 + 280 LoC, compile clean)

### Architectural goal

The single architectural goal of v3: **every host controller implements `usb_core::UsbHostController`** and registers under the same scheme namespace. Currently only `ehcid` implements the trait; `xhcid`, `uhcid`, `ohcid` each have ad-hoc scheme implementations. Unifying these is the prerequisite for every other improvement in v3.

### Critical risks (unconditional stop-ship)

Three risks make Red Bear USB unsupportable today. They MUST be fixed before any further phase:

1. **usbscsid has 12 `panic!()` calls in hot path.** A USB stick disconnect during transfer crashes the entire system. Must convert all to `Result` returns.
2. **xhcid has ~125 panic sites / unwrap() / expect() calls.** Mutex poison panic = full kernel panic. Most are fixable with proper error propagation.
3. **3 class drivers are 32-line stubs** (`redbear-usbaudiod`, `redbear-acmd`, `redbear-ecmd`) that print "not yet implemented" and exit. They are wired in configs but do nothing — dead weight in every image.

## 2. Phase roadmap

| Phase | Goal | Exit criteria |
|---|---|---|
| **P1** | Trait unification + panic hardening | All 4 controllers implement `UsbHostController`; usbscsid 0 panic sites; xhcid <20 unwraps |
| **P2** | xHCI core completeness | Quirk table populated; HCCPARAMS2 parsed; error recovery for babble/transaction/stall/split |
| **P3** | Hub driver maturity | Full enumeration sequence; USB 3.0 SS hub support; port power/reset timing; wHubDelay accumulation |
| **P4** | Storage: UAS + multi-LUN | UAS protocol implementation; multi-LUN dispatch; SYNCHRONIZE_CACHE; WRITE SAME/UNMAP |
| **P5** | HID: report descriptor parser + input mapping | Full HID report descriptor parser; usage→evdev mapping; HID quirks; multi-touch support |
| **P6** | Class driver completeness | CDC ACM; CDC NCM; USB Audio; remove the 3 empty stubs |
| **P7** | Power management | USB 2.0 LPM; USB 3.0 U1/U2/U3; runtime PM autosuspend; xHCI link state management |
| **P8** | Validation: hardware matrix + QEMU harness expansion | Hardware-validation matrix with one row per controller; new QEMU tests for OHCI/UHCI/EHCI; error-injection tests |
| **P9** | Modern USB scope ADR (inherited from v2 §12) | Decided: host-only. Already written. |

---

## 3. P1 — Trait unification and panic hardening

**Why first:** Without a unified trait, every later phase has to write per-controller glue. Panic hardening is unconditional — the system cannot ship with mass-storage and xHCI crashes.

### P1-A: All four controllers implement `usb_core::UsbHostController`

**Reference:** `local/reference/linux-7.1/drivers/usb/core/hcd.c` (Host Controller Driver framework, 3,194 lines) and `drivers/usb/host/` (4 host drivers, all conforming to a shared `struct hc_driver`).

Current state:

| Controller | Trait | Scheme | Status |
|---|---|---|---|
| xhcid | ❌ | own scheme.rs | ad-hoc |
| ehcid | ✅ | redox-scheme::SchemeSync | good template |
| uhcid | ❌ | none | enum-only |
| ohcid | ❌ | none | enum-only |

**Tasks:**

1. **Define unified scheme path:** `usb-core::SCHEME_NAMESPACE = "usb.<pci_name>_<controller_name>"` (xhcid-style). All controllers register under this namespace.
2. **Refactor xhcid's `scheme.rs`** to satisfy `UsbHostController` trait. The trait's `control_transfer` / `bulk_transfer` / `interrupt_transfer` delegate to existing xhcid scheme handlers.
3. **Add scheme registration to uhcid and ohcid** using the same pattern. Their existing in-guest enumeration stays; we add a `SchemeSync` server under the new namespace.
4. **Replace ad-hoc class spawn** in all four controllers with `usb-core::spawn::spawn_class_driver_for_port`. Class daemons open the namespace from the controller's `scheme_name`.

**Files to touch:**
- `local/sources/base/drivers/usb/xhcid/src/xhci/scheme.rs` (refactor)
- `local/recipes/drivers/uhcid/source/src/main.rs` (add scheme)
- `local/recipes/drivers/ohcid/source/src/main.rs` (add scheme)
- `local/recipes/drivers/usb-core/source/src/scheme.rs` (extend trait if needed)

**Linux 7.1 cross-reference:** `drivers/usb/core/hcd.c:1700` `usb_create_hcd()` — uniform scheme-name pattern `bus_name-hcd_name`. Adapt for Redox's scheme namespace.

**Exit:** all four controllers implement the trait; class daemons can connect to all four via the same scheme.

### P1-B: usbscsid panic hardening

**Reference:** `local/reference/linux-7.1/drivers/usb/storage/transport.c` (1,462 lines) and `drivers/usb/core/urb.c` (1,021 lines). Linux USB storage never panics on stall — it returns `-EPIPE`, `-ETIME`, `-EIO`, etc.

**Files to touch:** `local/sources/base/drivers/storage/usbscsid/src/`

**Tasks:**

1. Replace every `panic!()` in `protocol/bot.rs` (12 sites) with `return Err(...)` or `bail!()`.
2. Each panic site maps to a specific failure mode. Audit each one:
   - CBW send failure → `Err(StorageError::CommandBlockError)`
   - Data-phase stall → `Err(StorageError::Stall)` (don't kill the daemon)
   - CSW parse error → `Err(StorageError::InvalidStatusWrapper)`
   - Mass storage reset → call `usbscsid::reset_port()` instead of panicking
3. Replace `mod uas { // TODO }` stub with either a real UAS implementation (see P4) or a clean `unimplemented!()` that returns `Err(UasError::NotSupported)`.
4. Add `#[derive(Debug, thiserror::Error)]` for all error types — no string-based panic messages.

**Exit:** `cargo check` passes; `grep -c panic!()` on the usbscsid tree returns 0.

### P1-C: xhcid panic reduction

**Reference:** `local/reference/linux-7.1/drivers/usb/host/xhci.c` — uses `dev_err()`, `dev_warn()`, and explicit `return -EINVAL` for every error path. Linux xhci never panics in normal operation.

**Files to touch:** `local/sources/base/drivers/usb/xhcid/src/xhci/`

**Tasks:**

1. Replace each `.unwrap()` on Mutex locks with `.lock().unwrap_or_else(|e| e.into_inner())` — already done in some sites; complete across the tree.
2. Replace each `.expect()` with explicit error logging + fallible helper functions.
3. Remove the 5 explicit `panic!()` calls in hot paths:
   - `irq_reactor.rs:31` — `Failed to received an enumeration request!` → log error + return
   - `irq_reactor.rs:71` — `No XHCI controllers found` → log error + abort init cleanly
   - `irq_reactor.rs:620` — `Polling finished EventTrbFuture again` → log warning + skip
   - `irq_reactor.rs:672/703/731` — `Invalid TRB type` → log error + corrupt-ring recovery
   - `scheme.rs:2011` — `unreachable` HandleKind → log error + return EBADF
4. Convert `mod.rs:694` `TODO handle the second unwrap` and similar known-fragile sites.

**Target:** ≤20 unwrap/expect total in xhcid (down from ~125).

**Exit:** `grep -c 'panic!\|\\.unwrap()\|\\.expect(' local/sources/base/drivers/usb/xhcid/src/xhci/*.rs` ≤20.

### P1-D: Remove the 3 empty stubs

**Files:**
- `local/recipes/system/redbear-usbaudiod/` (32 LoC stub)
- `local/recipes/system/redbear-acmd/` (32 LoC stub)
- `local/recipes/system/redbear-ecmd/` (32 LoC stub)

**Task:** Either implement them properly (see P6 for class driver work) or remove them from the configs. Stub classes inflate image size and mislead operators about USB capability.

---

## 4. P2 — xHCI core completeness

**Why this matters:** The 51-entry xHCI quirk table in Linux is the difference between "works on QEMU" and "works on real hardware." Without quirks, xhcid will silently misbehave on Intel, AMD, NEC, ASMedia, Etron, Cadence, and Fresco Logic controllers.

### P2-A: xHCI quirk table

**Reference:** `local/reference/linux-7.1/drivers/usb/host/xhci.h:1587-1649` (51 quirk flags).

**Tasks:**

1. Define a `XhciQuirks` bitflags struct in `xhcid/src/xhci/mod.rs` matching the Linux 51-entry enum.
2. Implement a per-controller quirk probe: read `PCI_VENDOR_ID` + `PCI_DEVICE_ID`, look up in a quirk table keyed by `{vendor, device}`.
3. Implement the behavior change for each quirk. Reference: `drivers/usb/host/xhci-pci.c:600+` `xhci_pci_quirks()`.
4. Start with the highest-priority quirks:
   - `XHCI_RESET_TO_DEFAULT` — all xhci drivers should program MaxSlotsEn = 1 on reset
   - `XHCI_LPM_SUPPORT` — Intel Panther Point and later
   - `XHCI_BROKEN_STREAMS` — disable streams on affected controllers
   - `XHCI_WRITE_64_HI_LO` — write 64-bit registers high-then-low on AMD
   - `XHCI_ZERO_64B_REGS` — read 32-bit only on old hardware
   - `XHCI_DEFAULT_PM_RUNTIME_ALLOW` — enable runtime PM by default on Intel
5. Wire quirk flags into all relevant code paths: reset, run, MSI-X allocation, streams, ring sizing, error recovery.

**Linux cross-reference:** `xhci-pci.c:617-900` lists the per-controller quirk table. Translate to a Rust match expression.

**Files:** `xhcid/src/xhci/quirks.rs` (new), `xhcid/src/xhci/mod.rs`, `xhcid/src/xhci/pci_quirks.rs` (new).

**Exit:** per-controller quirk probe running at init; quirk-aware behavior in 5+ paths.

### P2-B: HCCPARAMS2 parsing (xHCI 1.1+ features)

**Reference:** `local/reference/linux-7.1/drivers/usb/host/xhci-caps.h:94-119`

13 HCCPARAMS2 bits enable U3 entry, extended TBC, eUSB2, etc. Current xhcid reads only HCCPARAMS1.

**Tasks:**

1. Read and cache `HCSPARAMS2` and `HCCPARAMS2` in `capability.rs`.
2. Define bitflags for each of the 13 capabilities.
3. Gate xHCI 1.1+ features on these bits:
   - `HCC2_U3C` — U3 Entry Capability
   - `HCC2_CMC` — Configure Endpoint Max Exit Latency Too Large
   - `HCC2_LEC` — Large ESIT Payload (>48KB)
   - `HCC2_CIC` — Configuration Information Capability (used for Set Latency Tolerance)
4. Extended port capabilities from `xhci-ext-caps.h:62-66`: `XHCI_L1C`, `XHCI_HLC`, `XHCI_BLC` for LPM.

**Exit:** HCCPARAMS2 parsed; 3+ features gated on it.

### P2-C: Error recovery

**Reference:** `local/reference/linux-7.1/drivers/usb/host/xhci-ring.c` (4,472 lines), specifically `handle_tx_event()` for the 36 completion codes.

**Tasks:**

1. Extend `TrbCompletionCode` handling from 3 codes (Success, ShortPacket, Stall) to all 36.
2. For each error code, implement recovery:
   - `COMP_STALL_ERROR` → endpoint halt + clear-stall control transfer + retry
   - `COMP_DATA_BUFFER_ERROR` → re-queue transfer with new DMA mapping
   - `COMP_BABBLE_DETECTED_ERROR` → reset endpoint + check port disable
   - `COMP_USB_TRANSACTION_ERROR` → retry up to 3 (per `MAX_SOFT_RETRY`)
   - `COMP_TRB_ERROR` → log + fatal to upper layer
   - `COMP_RESOURCE_ERROR` → re-queue later
   - `COMP_SPLIT_TRANSACTION_ERROR` → call Clear-TT-Buffer on parent hub
3. Track retry counts in `Urb` struct. Reference: `xhci-ring.c:1700+` `xhci_urb_request()`.

**Linux cross-reference:** `xhci-ring.c:1700-1900` `xhci_handle_completion()` — the canonical error-handling function.

**Exit:** 36 completion codes handled with appropriate recovery.

---

## 5. P3 — Hub driver maturity

**Why this matters:** The current usbhubd is 249 LoC doing basic port-change detection. Linux hub.c is 6,567 lines doing full enumeration. The gap is 95%.

### P3-A: Full enumeration sequence

**Reference:** `local/reference/linux-7.1/drivers/usb/core/hub.c:1449` `hub_configure()` and `hub_port_connect()`.

**Tasks:**

1. Read hub descriptor (already done — `HubDescriptorV2` / `HubDescriptorV3`).
2. Power-on delay: `bPwrOn2PwrGood * 2ms` (USB 2.0 spec §7.1.6.1).
3. USB 3.0 hub initial state: wait for polling → U0 (tPollingLFPSTimeout = 360ms, polled 10×36ms).
4. Per-port enumeration:
   - Reset signaling (USB 2 ≥10ms, USB 3 warm reset with PORT_WR)
   - Wait for reset completion
   - Read device descriptor (8 bytes → full 18 bytes)
   - Set address
   - Read configuration descriptors
   - Configure endpoints
5. Hub-specific class requests for USB 3 hubs:
   - `HUB_SET_DEPTH` (request 0x0C) — set hub tier depth
6. `wHubDelay` accumulation through the TT path (for split-transaction scheduling).

**Linux cross-reference:** `hub.c:1497-1521` for wHubDelay; `hub.c:3000-3300` for the full port-connect path.

**Files:** `local/sources/base/drivers/usb/usbhubd/src/main.rs`

**Exit:** complete hub enumeration including power timing, USB 3 hub handling, and TT accumulation.

### P3-B: Hub interrupt-driven change detection

**Reference:** `linux-7.1/drivers/usb/core/hub.c:1000+` `hub_irq()`.

Current usbhubd polls at 100ms intervals. Linux uses hub interrupt endpoints (`USB_ENDPOINT_DIR_IN` + `USB_USAGE_TYPE_INTERRUPT`) for immediate change notification.

**Tasks:**

1. Add interrupt endpoint configuration to usbhubd (USB hub interrupt endpoint is always EP1).
2. Subscribe to interrupt IN transfers for status change bitmap.
3. Fall back to polling only when interrupt endpoint is unavailable.

**Exit:** interrupt-driven on USB 2 hubs; polling fallback on USB 3 hubs (which lack interrupt endpoints).

### P3-C: Port LED control

**Reference:** `linux-7.1/drivers/usb/host/xhci-port.h:64-67` (PORT_LED_OFF/AMBER/GREEN).

**Tasks:**

1. Expose hub port LED control via `SET_HUB_FEATURE(PORT_INDICATOR)`.
2. Implement in usbhidd keyboard LED sync (cross-couple with P5-C).

**Exit:** port LEDs controllable via scheme.

---

## 6. P4 — Storage: UAS + multi-LUN + SAT

**Why this matters:** BOT alone limits USB 3.0 storage to ~30-40 MB/s. UAS unlocks 350+ MB/s. Multi-LUN is needed for card readers. SYNCHRONIZE_CACHE / UNMAP are needed for SSD correctness and TRIM.

### P4-A: UAS protocol

**Reference:** `local/reference/linux-7.1/drivers/usb/storage/uas.c` (1,304 lines).

UAS uses 4 endpoints (cmd BULK OUT, status BULK IN, data-in BULK IN, data-out BULK OUT) and Information Units (Command IU, Sense IU, Response IU).

**Tasks:**

1. Detect UAS interface (interface class 0x08, subclass 0x04, protocol 0x62 for UAS; 0x50 for BOT).
2. Implement the 4-endpoint setup in usbscsid.
3. Implement Command IU submission (32-byte structured).
4. Implement Sense IU / Response IU parsing.
5. Wire to xHCI streams (P2 prerequisite): UAS needs streams for true concurrent commands.

**Files:** `local/sources/base/drivers/storage/usbscsid/src/protocol/uas.rs` (new).

**Linux cross-reference:** `uas.c:35-74` struct definitions; `uas.c:600-900` command submission.

**Exit:** UAS path functional, fallback to BOT for non-UAS devices.

### P4-B: Multi-LUN dispatch

**Reference:** `linux-7.1/drivers/usb/storage/usb.c:1258` (`usb_stor_scan_thread()`).

**Tasks:**

1. Extend SCSI dispatch to iterate LUN 0..max_lun.
2. REPORT_LUNS opcode handling — list of LUNs available.
3. Per-LUN device state — each LUN gets its own BlockDevice.

**Files:** `local/sources/base/drivers/storage/usbscsid/src/scsi/cmds.rs`, `scsi/mod.rs`.

**Exit:** 4-slot card reader enumerates as 4 separate block devices.

### P4-C: SYNCHRONIZE_CACHE / WRITE SAME / UNMAP

**Reference:** `linux-7.1/drivers/scsi/sd.c` (sd driver issues these).

**Tasks:**

1. Add `SYNCHRONIZE_CACHE(10)` and `SYNCHRONIZE_CACHE(16)` opcodes to `scsi/opcodes.rs`.
2. Add `WRITE_SAME(10/16)` and `UNMAP` opcodes.
3. Dispatch them in `scsi/cmds.rs` to the BOT transport.

**Exit:** SSD TRIM works, data integrity on disconnect improves.

### P4-D: Mass-storage quirks integration

**Reference:** `linux-7.1/drivers/usb/storage/unusual_devs.h` (2,513 lines, 323 entries).

**Current state:** Red Bear has 214 mass-storage quirks extracted from `unusual_devs.h`. Verify they're loaded at runtime and applied during enumeration.

**Tasks:**

1. Verify `usb-core::spawn::class_driver_for_usb_class()` for mass storage (0x08).
2. Add runtime quirk lookup: when usbscsid enumerates a device, look up its VID:PID in the quirk table, apply `IGNORE_RESIDUE`, `FIX_CAPACITY`, `SINGLE_LUN`, `MAX_SECTORS_64`, etc.
3. Implement the runtime application in `usbscsid/src/main.rs` at the `read_capacity()` and `read_write()` paths.

**Exit:** quirks applied at enumeration; redbear-usb-storage-check verifies a quirk-affected device behaves correctly.

---

## 7. P5 — HID: report descriptor parser + input mapping

**Why this matters:** usbhidd at 566 LoC only handles boot-protocol keyboard/mouse. Linux's `hid-core.c` (3,228 LoC) + `hid-input.c` (2,454 LoC) together handle every HID device class. The gap blocks touchscreens, gamepads (partially), consumer keys, and every non-trivial mouse/keyboard.

### P5-A: HID report descriptor parser

**Reference:** `local/reference/linux-7.1/drivers/hid/hid-core.c:1273` `hid_open_report()`.

**Tasks:**

1. Implement a full HID Report Descriptor parser in a new crate `local/recipes/drivers/redbear-hid-core/source/src/lib.rs`:
   - `ReportDescriptor` struct: tree of `UsagePage`, `Usage`, `Collection` (Application/Physical/Logical), `Field` (Input/Output/Feature with bit fields), `Report` (with report IDs and sizes).
2. Parse the main item types: `Usage Page`, `Usage`, `Logical Minimum/Maximum`, `Report Size`, `Report Count`, `Report ID`, `Push/Pop`, `Collection/End Collection`.
3. Output a tree that other HID drivers can walk.

**Files:** new crate `local/recipes/drivers/redbear-hid-core/`.

**Exit:** parses a Logitech mouse descriptor correctly into a structured tree.

### P5-B: HID input mapping (usages → evdev)

**Reference:** `local/reference/linux-7.1/drivers/hid/hid-input.c:1244` `hidinput_configure_usage()`.

**Tasks:**

1. Implement usage → input event mapping table:
   - Generic Desktop 0x01: X/Y/Wheel → ABS_X/ABS_Y/REL_WHEEL
   - Keyboard 0x07: a/A/Enter/etc → KEY_A/KEY_A/KEY_ENTER
   - Button 0x09: mouse buttons → BTN_MOUSE/BTN_LEFT
   - LED 0x08: keyboard LEDs
   - Consumer 0x0C: Mute/Volume → KEY_MUTE/KEY_VOLUMEUP
   - Digitizer 0x0D: Touch/Position → BTN_TOUCH/ABS_MT_POSITION_X
2. Wire to `redbear-inputd` via evdev events (or whatever input daemon we use).
3. Switch from Orbital KeyEvent protocol to evdev for unified input.

**Linux cross-reference:** `hid-input.c:140-200` (the usage→keycode mapping table).

**Exit:** media keys, gamepad buttons, and touchpad gestures work via USB HID.

### P5-C: LED sync

**Reference:** `local/reference/linux-7.1/drivers/hid/hid-input.c:317` `hidinput_output_event()` (Caps Lock → LED report).

**Tasks:**

1. usbhidd: after boot completion, send `SET_REPORT` to set Caps Lock / Num Lock / Scroll Lock LED state.
2. Wire to `redbear-inputd` LED state events.
3. For both USB HID boot protocol and report protocol.

**Exit:** Caps Lock LED on a USB keyboard actually lights up when toggled.

### P5-D: HID quirks

**Reference:** `local/reference/linux-7.1/drivers/hid/hid-quirks.c` (1,397 lines, ~200 device quirks).

**Tasks:**

1. Add HID quirks table in `redbear-hid-core`.
2. Per-device VID:PID overrides: `HID_QUIRK_NOTOUCH`, `HID_QUIRK_NO_INIT_REPORTS`, `HID_QUIRK_NOGET`, `HID_QUIRK_MULTI_INPUT`, etc.
3. Apply at `usbhidd` enumeration time.

**Exit:** Logitech Unifying receivers, Apple Magic Mouse, and Surface keyboards all work.

### P5-E: Multi-touch

**Reference:** `local/reference/linux-7.1/drivers/hid/hid-multitouch.c` (2,756 lines).

**Tasks:**

1. Detect multi-touch class (Usage Page 0x0D).
2. Implement slot-based protocol (Type B) and report-based protocol (Type A).
3. Forward ABS_MT_POSITION_X, ABS_MT_POSITION_Y, ABS_MT_SLOT, BTN_TOUCH to `inputd`.

**Exit:** a USB touchscreen or touchpad produces touch events.

---

## 8. P6 — Class driver completeness

**Why this matters:** Red Bear has 6 class drivers, of which only 3 work (usbhubd, usbhidd, usbscsid). The other 3 are 32-line stubs. Plus we're missing CDC NCM (ethernet), USB Audio, USB-serial, and others.

### P6-A: CDC ACM (remove the stub)

**Reference:** `local/reference/linux-7.1/drivers/usb/class/cdc-acm.c` (2,186 lines).

**Files:** `local/recipes/system/redbear-acmd/` (currently stub).

**Tasks:**

1. Implement a real CDC ACM class driver (`redbear-cdc-acmd` or just keep the name and add code).
2. Line coding: baud rate, parity, stop bits, data bits.
3. Flow control: RTS/CTS, DTR/DSR via control transfers.
4. Break signaling.
5. Multi-port modems (data + control + notification interfaces).
6. Expose `/scheme/tty` for userspace clients (replacing the stub `redbear-acmd` admin CLI).

**Exit:** an FTDI USB-serial adapter or Arduino appears as a TTY device.

### P6-B: CDC NCM (Ethernet over USB)

**Reference:** `linux-7.1/drivers/net/usb/cdc_ncm.c` (in `drivers/net/usb/`).

**Tasks:**

1. Detect CDC NCM interface (subclass 0x0D).
2. NTB (Network Transfer Block) framing.
3. Aggregate frames into NTBs for efficiency.
4. Wire to the netstack as a new interface.

**Exit:** a USB-Ethernet adapter (e.g., a phone-tethered device) works.

### P6-C: USB Audio

**Reference:** `local/reference/linux-7.1/sound/usb/` (USB audio class driver, ~5,000 lines).

`redbear-usbaudiod/` is currently a 32-line stub. Replace with a real USB Audio Class 1.0 driver:

**Tasks:**

1. Detect AudioControl interface + AudioStreaming interface.
2. Parse Audio Control descriptors (unit IDs, terminals, mixer units).
3. Configure audio streaming endpoint (alternate settings, packet size, format).
4. Isochronous transfer ring setup (xHCI isoch — new code path).
5. PCM playback/capture path to `redbear-audiod`.

**Exit:** USB headphones / headset produce audio.

### P6-D: USB-serial (top 5 drivers)

**Reference:** `linux-7.1/drivers/usb/serial/` (56 .c files).

For v3, implement only the top 5 most common USB-serial chip families:

1. **FTDI** (`ftdi_sio.c`, 3,176 lines) — FT232, FT2232, FT4232
2. **CP210x** (`cp210x.c`, 753 lines) — Silicon Labs CP2102/CP2104
3. **PL2303** (`pl2303.c`, 615 lines) — Prolific PL2303
4. **CH341** (`ch341.c`, 583 lines) — QinHeng CH341
5. **CDC-ACM subset** (covered by P6-A)

**Exit:** common USB-serial adapters work.

### P6-E: USB compliance test driver

**Reference:** `linux-7.1/drivers/usb/misc/usbtest.c` (3,079 lines).

A `redbear-usbtest` tool that exercises:
- Bulk IN/OUT loopback with pattern verification
- Control endpoint round-trip
- Interrupt endpoint reception
- Isochronous endpoint loopback
- Halt/reset recovery

**Exit:** USB protocol compliance can be validated in-tree.

---

## 9. P7 — Power management

**Why this matters:** Without PM, USB devices draw full power forever, draining laptop batteries and overheating peripherals. Linux's PM framework handles U1/U2/U3/LPM/autosuspend.

### P7-A: USB 2.0 LPM

**Reference:** `linux-7.1/drivers/usb/host/xhci-port.h:135-173`, `xhci-hub.c`.

**Tasks:**

1. Parse `HCCPARAMS1.HLC` (Hardware LPM Capability).
2. Implement `usb_set_device_initiated_lpm()` (port hardware LPM control via PORTSC.PORT_L1DEV).
3. xhcid: implement `PORT_HLE` enabling per port.
4. ehcid: implement via USBCMD.HIRD (Host Initiated Resume Duration).

**Exit:** USB 2.0 devices on HWA LPM-capable hubs enter L1 state when idle.

### P7-B: USB 3.0 U1/U2/U3

**Reference:** `linux-7.1/drivers/usb/host/xhci-port.h:17-30`, `xhci.c:2800+` `xhci_stop_device()`.

**Tasks:**

1. Implement U1/U2 entry per port via `PORT_U1_TIMEOUT` / `PORT_U2_TIMEOUT` registers.
2. U3 (suspend) via `Port Link State Write` command TRB.
3. U3 → Resume (U0) detection on PORTSC.PLC.
4. xHC-initiated suspend/resume (device responds to `SetPortFeature(PORT_SUSPEND)`).

**Exit:** USB 3.0 devices enter U1/U2/U3 when idle, resume on traffic.

### P7-C: Runtime PM autosuspend

**Reference:** `linux-7.1/drivers/usb/core/driver.c:2081` `usb_autosuspend()`.

**Tasks:**

1. Add per-device idle timer (default 2s).
2. Suspend device (U1/U2/U3) when timer expires.
3. Resume on URBs being submitted (auto-resume).
4. Disable autosuspend for devices that explicitly opt out.

**Exit:** USB mice, keyboards, storage automatically suspend after idle, resume instantly on activity.

---

## 10. P8 — Validation: hardware matrix + QEMU harness expansion

**Why this matters:** All USB work so far is QEMU-only. We need to validate on real hardware. This phase builds the harness for that.

### P8-A: Hardware validation matrix

**Reference:** `local/docs/HARDWARE-VALIDATION-MATRIX.md` (existing, currently tiny).

**Tasks:**

1. Expand the matrix: one row per (controller, class, board) tuple.
2. Required test points per row:
   - Controller PCI ID → driver recognizes
   - Device enumeration succeeds
   - Specific class test (HID keypress, storage read+write, audio playback)
   - Hot-plug works (USB 3.x + USB 2.0)
   - Suspend/resume works (if device supports)
3. Minimum viable matrix entries (10+):
   - xhcid on AMD Ryzen (USB 3.2, multiple hubs)
   - xhcid on Intel Tiger Lake (USB 4 / Thunderbolt 3 compatible)
   - xhcid on Intel C620 server chipset
   - ehcid on a USB 2.0-only motherboard
   - uhcid on a Via-based legacy system
   - ohcid on an Nvidia nForce board
   - USB HID: Logitech MX Master, Apple Magic Mouse, Cherry keyboard
   - USB Storage: Samsung T7 SSD (UAS-capable), SanDisk Ultra (BOT-only)
   - USB Hub: Anker 7-port powered hub, USB 3.0 hub chain

**Exit:** matrix has ≥10 rows; each row's last-tested date <6 months.

### P8-B: New QEMU tests

The v3 plan calls for QEMU test scripts that don't exist yet:

**Tasks:**

1. `test-uhci-runtime-qemu.sh --check` — boot with `-device piix3-usb-uhci`, verify enumeration.
2. `test-ohci-runtime-qemu.sh --check` — boot with `-device nec-usb-xhci` emulating OHCI compat, verify enumeration.
3. `test-ehci-class-autospawn-qemu.sh --check` — boot with USB keyboard on EHCI route, verify usbhidd spawns and keypress reaches inputd.
4. `test-usb-hub-qemu.sh --check` — boot with a USB hub attached, verify the hub enumerates and devices behind it enumerate.
5. `test-usb-error-recovery-qemu.sh --check` — hot-unplug during transfer, verify graceful error (not panic).
6. `test-usb-uas-qemu.sh --check` — boot with USB 3.0 storage device supporting UAS, verify UAS path active.

**Exit:** all 6 scripts pass.

### P8-C: Error injection tests

**Reference:** Linux's `usbtest.c` includes error injection patterns.

**Tasks:**

1. Build a `redbear-usb-fuzz` tool that performs:
   - Random disconnects mid-transfer
   - Stall injection on specific endpoints
   - Babble simulation
   - CRC error injection (in conjunction with `usbtest` if available)
2. Verify usbscsid / usbhidd / usbaudiod handle errors without panic.

**Exit:** no panics under 10,000 random disconnect events.

---

## 11. Build-and-verify workflow (per-session)

```bash
# After any P-phase change:
cd local/sources/base && git checkout <phase-branch>
cargo check -p xhcid --offline

cd local/recipes/drivers/uhcid/source && cargo check --offline
cd local/recipes/drivers/ohcid/source && cargo check --offline
cd local/recipes/drivers/ehcid/source && cargo check --offline
cd local/recipes/drivers/usb-core/source && cargo check --offline

# Full build:
./local/scripts/build-redbear.sh --upstream redbear-mini

# QEMU tests:
./local/scripts/test-xhci-irq-qemu.sh --check
./local/scripts/test-xhci-device-lifecycle-qemu.sh --check
./local/scripts/test-usb-storage-qemu.sh
./local/scripts/test-usb-qemu.sh
./local/scripts/test-usb-maturity-qemu.sh

# After P1 completes:
./local/scripts/test-uhci-runtime-qemu.sh --check    # new
./local/scripts/test-ohci-runtime-qemu.sh --check    # new
./local/scripts/test-ehci-class-autospawn-qemu.sh --check  # new
./local/scripts/test-usb-hub-qemu.sh --check        # new
./local/scripts/test-usb-error-recovery-qemu.sh --check  # new
```

## 12. Stale documentation cleared

This v3 supersedes:

- `local/docs/USB-IMPLEMENTATION-PLAN.md` (v2 active) → archived as `local/docs/archived/USB-IMPLEMENTATION-PLAN-v2-2026-07.md`
- `local/docs/USB-VALIDATION-RUNBOOK.md` (v2 active) → archived as `local/docs/archived/USB-VALIDATION-RUNBOOK-2026-07.md`

`archived/README.md` updated to record the v1 → v2 → v3 supersession chain.

All Linux 7.0 references in active docs migrated to Linux 7.1 (this happened earlier in the v2 era).

## 13. Cross-reference summary

For every feature in v3, the cross-reference is to Linux 7.1 at `local/reference/linux-7.1/`:

| Feature | Linux 7.1 file | Lines | Implementation strategy |
|---|---|---|---|
| xHCI quirk table | `drivers/usb/host/xhci.h:1587-1649` | 63 | Reimplement as bitflags struct + per-controller lookup table |
| xHCI error recovery | `drivers/usb/host/xhci-ring.c:1700-1900` | 200+ | Port 36-code dispatch table; line-by-line Rust translation |
| USB 2.0 LPM | `drivers/usb/host/xhci-port.h:135-173` | 39 | Reimplement port-link-state transitions |
| Full hub enumeration | `drivers/usb/core/hub.c:1449-1521,3000-3300` | 300+ | Sequential port-and-hub init with timing-aware power-on |
| UAS protocol | `drivers/usb/storage/uas.c` | 1304 | Port full protocol, port 4-endpoint + IU framing |
| HID report descriptor parser | `drivers/hid/hid-core.c:1273` | 200+ | Token-based parser → tree of usage/collection/field |
| HID input mapping | `drivers/hid/hid-input.c:1244+` | 200+ | Usage page → keycode/rel/abs table |
| CDC ACM | `drivers/usb/class/cdc-acm.c` | 2186 | Line discipline + tty interface |
| Multi-touch HID | `drivers/hid/hid-multitouch.c` | 2756 | Slot-based protocol parser |

For all of these: when implementation detail is unclear, **port line-by-line from Linux 7.1**, preserving the data structure layouts and edge-case handling.

## 14. See also

- `local/docs/archived/USB-IMPLEMENTATION-PLAN-v1-2026-04.md` — v1 (P0 host work)
- `local/docs/archived/USB-IMPLEMENTATION-PLAN-v2-2026-07.md` — v2 (P0 + P5 host-only ADR)
- `local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` — IRQ/MSI-X quality surface that P2-A depends on
- `local/docs/WIFI-IMPLEMENTATION-PLAN.md` — Wi-Fi subsystem plan; sibling first-class-citizen effort
- `local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md` — Bluetooth plan; uses `redbear-btusb` (USB Bluetooth transport)
- `local/reference/linux-7.1/drivers/usb/` — Linux 7.1 reference (the implementation of excellence)