# Red Bear OS USB Plan — v3

> **Status:** Canonical (v3). Supersedes v1 (pre-fork draft) and v2 (archived at `local/docs/archived/USB-IMPLEMENTATION-PLAN-v2-2026-07.md`).
> **Date:** 2026-07-07; last revised 2026-07-18 (P2-A/P2-B completion records, P2-C status, doc consolidation).
> **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 | 6 working (acm 133, ecm 261, audio 308, HID, storage, hub) | 80+ drivers | ~75 missing |
| Hub driver lines | ~700 (usbhubd + port_ops) with Linux state machine | 6,567 (hub.c) | Enumeration core done (P3-A); interrupt EP/LED/TT gaps |
| xHCI quirks | 51 flags + ~85-entry canonical table (redox-driver-sys, P2-A); ~40 check sites in xhcid | 51 quirks | ✅ Done |
| Error recovery | All 36 codes with active recovery (P2-C core ✅); runtime injection tests open | Babble, transaction error, split error, clear-TT | Core done; validation gap |
| Power management | HW LPM substrate + U3 gate + PORTPMSC helpers (P2-B); per-device LPM, U1/U2, autosuspend missing | Runtime PM, U1/U2, LPM, autosuspend | Core 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 ✅ ACHIEVED (2026-07-08)

All 4 host controllers implement `usb_core::UsbHostController`:
- `xhcid` via `XhciAdapter<N>` (trait_adapter.rs)
- `ehcid` via its native scheme
- `uhcid` via `UhciController` (bulk/interrupt transfers implemented 2026-07-08)
- `ohcid` via `OhciController`

**P0 + P1 complete** (2026-07-08): panic reduction done, PortId bounds check, protocol_speeds cap, crossbeam channels bounded, 23 unit tests.

### Critical risks ✅ RESOLVED (2026-07-08)

1. usbscsid `.unwrap()`/.`expect()` fixed — event queue creation and subscribe now use `match` with error logging
2. xhcid panic sites reduced — #![allow(warnings)] removed, EDTLA fixed, PortId Option return
3. 232 test cases remain for TRB (12) + hub (7) + SCSI (4)
3. **Class drivers — all functional** (verified 2026-07-08): `redbear-acmd` (133 lines, CDC ACM serial), `redbear-ecmd` (261 lines, CDC ECM Ethernet), `redbear-usbaudiod` (308 lines, USB Audio). Previously incorrectly listed as 32-line stubs.

## 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 (P2-A, 2026-07-18); ✅ HCCPARAMS2 parsed + gated (P2-B, 2026-07-18); 🚧 error recovery (36 codes defined; active recovery in progress) |
| **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 ✅ RESOLVED | All 6 USB class drivers functional: ACM (133 LOC), ECM (261 LOC), Audio (308 LOC), HID, storage, hub |
| **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 ✅ RESOLVED (2026-07-08)

All 3 class drivers are fully implemented (verified 2026-07-08):
- `redbear-acmd`: 133 lines, CDC ACM serial
- `redbear-ecmd`: 261 lines, CDC ECM Ethernet
- `redbear-usbaudiod`: 308 lines, USB Audio

None are stubs. Original plan incorrectly stated they were 32-line "not yet implemented" stubs.

---

## 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 ✅ COMPLETE (2026-07-18)

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

**Status:** Complete, and converged into the canonical quirks path
(`redox-driver-sys`) per the quirks-system single-source-of-truth policy —
not a per-driver private table as originally scoped.

1. `XhciControllerQuirkFlags` with all 51 Linux 7.1 flags (bit positions
   matching `xhci.h`) lives in `redox-driver-sys/src/quirks/mod.rs`.
2. Canonical controller table `redox-driver-sys/src/quirks/xhci_table.rs`:
   ~85 entries ported from `xhci-pci.c:xhci_pci_quirks()` (lines 251-517),
   `XhciQuirkEntry` with vendor/device/revision matching + WILDCARD,
   38 unit tests.
3. Lookup: `lookup_xhci_controller_quirks_full(vendor, device, revision,
   hci_version, dmi_info)` — revision + hci_version enable the two
   table entries that need them (AMD_0x96_HOST, >= 0x120 spec rule).
4. xhcid consumes via a thin re-export shim (`xhci/quirks.rs`); reads the
   real HCIVERSION from MMIO offset 0x04 (mirrors `xhci_gen_setup()`
   xhci.c:5455).
5. BROKEN_MSI now skips MSI/MSI-X probing inside `get_int_method()` so
   the interrupt handle and delivery method always agree (previously a
   handle/method mismatch bug).
6. ~40 quirk check sites active across xhcid (reset, run, MSI, streams,
   ring sizing, LPM, suspend).

Bugs fixed vs xhcid's old self-contained table (7): Intel 0x9c31 duplicate,
WildcatPoint→0x9cb1, Panther Point→0x1e31, VIA VL805 flags, Phytium flags,
ASMedia 0x1142 flags, Intel 0x9a13 list placement.

**Commits:** base `9fc1947d`, parent `980fb994ae`.

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

### P2-B: HCCPARAMS2 parsing (xHCI 1.1+ features) ✅ COMPLETE (2026-07-18)

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

**Status:** Parsing was already complete (all 11 HCCPARAMS2 bit constants +
accessors + HCS3 latencies in `capability.rs`). Gating implemented per Linux
7.1 cross-reference:

1. **LEC gate (HCC2_LEC)** — `scheme.rs`: `lec = hci_ver > 0x100 && cap.lec()`
   (Linux xhci-mem.c:1350 exact condition); gates isoch Mult field (existing
   `isoch_mult(lec)`) and zeroes Max ESIT Payload Hi when LEC=0 (spec Table 6-8
   RsvdZ requirement).
2. **U3C gate (HCC2_U3C)** — `suspend_port()` refuses SS U3 entry with ENOSYS
   when `hci_ver >= 0x110 && !hcc2_u3c()` (spec §4.15.1; Linux ignores the bit,
   xhcid is spec-strict). USB2 suspend unaffected (bus-level suspended state).
3. **CMC (HCC2_CMC)** — no active gate (mirrors Linux: error 0x1D
   MaxExitLatencyTooLarge handled unconditionally via P2-C completion codes).
4. **CIC (HCC2_CIC)** — already gated pre-existing: CONFIG.CIE set from
   `cic()` (mod.rs), now with `hci_ver > 0x100` guard; CIE consumed in input
   control context build (scheme.rs).
5. **HW LPM (XHCI_HLC/BLC/L1C)** — new `SupportedProtoCap::{hw_lpm_capable,
   besl_lpm_capable, l1_capable}` accessors (protocol-defined bits, Linux
   xhci-ext-caps.h:62-66); `Xhci::hw_lpm_support` computed per Linux
   xhci-mem.c:2137 (`hci_ver >= 0x100 && !HW_LPM_DISABLE && any USB2 protocol
   cap has HLC`); defensive LPM clear on USB2 ports at attach when unsupported
   (Linux xhci.c:4725 disable path); `Port::enable_lpm/disable_lpm` register
   targets fixed (HLE/HIRD/RWE/L1DS belong in PORTPMSC, not PORTHLPMC —
   spec Tables 5-21/5-23). Per-device L1 enablement (BESL computation, MEL
   Evaluate Context) deferred to P3 hub work.
6. **Bug fix:** removed bogus `CapabilityRegs::hlc()` + `HCC_PARAMS1_HLC_BIT`
   (read xECP pointer bits, not HLC — HLC is in the protocol caps, not
   HCCPARAMS1).
7. **Version guards:** HCC2 log block + `set_cie` gated on `hci_ver > 0x100`
   (HCCPARAMS2 register space is reserved on xHCI 1.0).

**Exit met:** HCCPARAMS2 parsed; 4 features gated (LEC×2, U3C, CIC, HW LPM
substrate). cargo check clean (138 warnings, -2 vs baseline), 43/43 tests pass.

### P2-C: Error recovery ✅ CORE COMPLETE (2026-07-18); runtime injection tests open (P8-C)

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

**Status:** Active recovery is implemented for all 36 completion codes.
`maybe_recover_transfer_error()` (`scheme.rs:559-925`) is the dispatch,
wired into both `execute_control_transfer()` and `execute_transfer()` retry
loops. Linux equivalences verified line-by-line against `xhci-ring.c`.

**Recovery matrix (implemented):**

| Code | xhcid behavior | Linux equivalent |
|---|---|---|
| `UsbTransaction` (0x04) | Soft retry ×3 (`reset_endpoint(tsp=true)` + `restart_endpoint`), then hard reset | `process_bulk_intr_td` ring.c:2529, `MAX_SOFT_RETRY=3` |
| `Resource` (0x07) | Backoff retry ×3 (10 ms×count) + reset, then hard reset | giveback + re-queue |
| `Stall` (0x06) | `reset_endpoint(tsp=false)` + `restart_endpoint` + `CLEAR_FEATURE(ENDPOINT_HALT)`, no retry | `finish_td` → `xhci_handle_halted_endpoint(EP_HARD_RESET)` + `usb_clear_halt` |
| `Babble/DataBuffer/Trb/SplitTransaction` | Hard reset + `clear_tt_buffer_once()` when `behind_highspeed_hub`, no retry | `xhci_handle_halted_endpoint` + `usb_hub_clear_tt_buffer` (hub.c:920) |
| `Stopped*` (0x1A-0x1C) | restart + retry ×3, then hard reset | stop-endpoint completion path |
| `InvalidStreamType/Id` | soft reset + retry ×3 | stream error path |
| `IncompatibleDevice` (0x16) | `disable_slot` — re-enumeration required | ring.c:2757 comment |
| `MissedService/NoPingResponse` | log + surface | `ep->skip` semantics |
| `ContextState/Parameter/IsochBuffer/EventLost/Undefined` | hard reset | fatal class |
| `MaxExitLatencyTooLarge` (0x1D) | log (CMC detection, see P2-B) | xhci.c:2198 |
| Command errors on transfer events | log (xHC state confusion) | — |

**Infrastructure (verified 2026-07-18):**

- `reset_endpoint` / `restart_endpoint` / `set_tr_deque_ptr` command chain
  mirrors Linux's RESET_EP → SET_TR_DEQUEUE → doorbell sequence.
- `restart_endpoint()` fixed this pass: (a) **latent deadlock** — the
  `port_states` write guard was held across `set_tr_deque_ptr()`'s internal
  read-guard acquisition on the same key (std RwLock read-while-write);
  (b) **doorbell ordering** — spec 4.6.8/4.6.10 requires Set TR Dequeue
  *before* doorbell (TR Dequeue Pointer is undefined after Reset Endpoint);
  (c) **NoOp priming** — dequeue now points *at* the priming NoOp so the
  xHC executes it on restart (Linux `xhci_move_dequeue_past_td` semantics).
- `CLEAR_FEATURE(ENDPOINT_HALT)` control transfer
  (`clear_endpoint_halt_no_recovery`) = `usb_clear_halt` device-side half.
- `clear_tt_buffer_once()` for FS/LS devices behind HS hubs = bounded
  `usb_hub_clear_tt_buffer` equivalent (hub.c:920).

**Known simplifications vs Linux (documented, acceptable for current usage):**

- Retry budget is per-transfer-call (matches Linux's per-TD `err_count`;
  Linux resets it on success, so semantics are equivalent within one
  transfer). No cross-transfer cumulative counters yet.
- On stall, pending TRBs *after* the failed TD are abandoned (Linux
  NoOps the stalled TD in place and resumes subsequent TDs). xhcid's
  transfer model is synchronous/single-TD, so this is not observable today.
- `handle_event_trb` maps all non-Success command completions to EIO
  without per-code discrimination.

**Exit met:** 36 completion codes handled with appropriate recovery.
**Remaining:** runtime error-injection proof (P8-C: hot-unplug mid-transfer,
stall injection, 10k random disconnects without panic).

---

## 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 ✅ CORE COMPLETE (2026-07-18)

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

**Status:** usbhubd (now ~700 LoC incl. `port_ops.rs`) implements the full
Linux port state machine with injected-side-effect, unit-tested ops
(14 tests). Enumeration of hub-attached devices remains delegated to
xhcid's `attach_device()` — architecturally correct (xhcid owns slot
allocation/addressing for root and hub ports alike).

**Implemented (Linux hub.c equivalence):**

1. ✅ Hub descriptor read (V2/V3) — pre-existing. **Fixed:** `HubDescriptorV3`
   now reads the full 12-byte SS descriptor including `device_removable: u16`
   (spec Table 10-15; previously under-read by 2 bytes; SS descriptors have
   no PortPwrCtrlMask — stale TODO comment corrected). Non-removable ports
   logged at startup.
2. ✅ Power-on delay `max(bPwrOn2PwrGood * 2ms, 100ms)` — pre-existing,
   verified vs `hub_power_on_good_delay()` (hub.h:165-173).
3. ✅ USB 3.0 polling→U0 wait (`port_ops::wait_for_u0`) — after port
   power-on, poll link state every 36 ms until out of Polling(7), 400 ms
   ceiling (tPollingLFPSTimeout = 360 ms; Linux hub.c:1226 debounce path).
4. ✅ Per-port enumeration:
   - Reset signaling + **completion wait** (`port_ops::wait_for_reset`) —
     Linux `hub_port_wait_reset()` (hub.c:2953-3047): 10 ms polls until
     RESET clears with CONNECTION set, escalate to 200 ms after two short
     waits, 800 ms budget; then 50 ms TRSTRCY recovery (hub.c:3159) and
     C_PORT_RESET clear. **Replaces** the previous bare `sleep(10ms)`.
   - **Debounce** (`port_ops::debounce_until_connected`) — Linux
     `hub_port_debounce_be_connected()` (hub.c:4696-4737): 25 ms polls,
     connection stable for 100 ms, 2 s budget, change bit cleared in-loop.
   - **Change-bit hygiene** — C_PORT_CONNECTION (debounce), C_PORT_RESET
     (reset-wait), C_PORT_ENABLE (post-handling) all cleared per Linux
     `port_event()` semantics; over-current recovery preserved.
   - Address/descriptor/configuration — via xhcid `attach_device()`
     (enable slot → address device → descriptors → driver spawn), the
     same path as root-hub ports.
5. ✅ `HUB_SET_DEPTH` (0x0C) for USB 3 hubs — pre-existing.
6. ✅ `wHubDelay` chain accumulation — `port_ops::accumulate_hub_delay_ns`
   (Linux hub.c:1507-1519: `wHubDelay + parent->hub_delay + 40ns`, cap
   65535 ns). usbhubd walks the PortId ancestor chain fetching ancestor
   V3 hub descriptors, then delivers the result to each newly attached
   SuperSpeed child via `SET_ISOCH_DELAY` (USB 3.0 §9.4.11; Linux
   message.c:1142-1158 — hubs and non-SS skipped; children inherit the
   hub's accumulated delay verbatim per hub.c:5128-5129).

**Remaining (documented follow-ups):** USB 2.0 `device_removable`/
`PortPwrCtrlMask` variable-length bitmaps unparsed (separate fetch needed);
SS.Inactive warm-reset recovery loop (hub.c:5841-5868); multi-TT switching;
U1/U2 LPM on hub ports (P7); interrupt-EP usage on USB 3 hubs without one
(polling fallback works).

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

**Runtime validation (2026-07-19, `test-usb-hub-qemu.sh` on QEMU
`usb-hub` + `usb-kbd` behind it):** the full chain is proven at runtime,
for the hub AND for a device behind it. Hub: descriptor read (8 ports),
EP1 interrupt-driven change detection, initial full port scan. Hub-child
(usb-kbd): connection debounce → port reset with completion wait → port
enable → attach → xHCI slot/address/descriptor enumeration → HID class
match → `Loading subdriver "USB HID" for port 5.2` (class 3.1 proto 1,
keyboard boot protocol). The proof surfaced and we fixed seven latent
bugs: the xhcid scheme refused port-dir opens for unenumerated hub
children (attach bootstrap deadlock), a status-bitmap off-by-one
(bit N−1 vs spec's bit N), a missing initial scan (daemon could block
on EP1 before ever polling), an unbounded EP1 wait (state changes during
synchronous waits produce no new interrupt), a debounce that could
deadlock on a hung C_PORT_CONNECTION clear (stability now judged on
connection state, change bit cleared post-attach), an unconditional
PORT_INDICATOR SetPortFeature that NAK-hung on indicator-less hubs
(now gated on wHubCharacteristics.HUB_CHAR_PORTIND like Linux
has_indicators), and QEMU's ClearPortFeature stall on change indicators
(handled gracefully by P2-C stall recovery). **"Reactor startup race" —
root cause found (2026-07-19):** the intermittent apparent boot freeze is
**startup latency under load, not a deadlock or an xhcid bug**. The guest
clock runs ~10-15× slower than wall under boot load, so the full
driver-spawn + enumeration sequence occasionally exceeds a short (50-60s)
timeout, producing a "frozen" log while the guest is actually still
running. Evidence: 18 boots with one apparent loss at the short timeout;
a 12s log-quiet "freeze" capture that the guest resumed from normally;
and every ≥180s run reaching full enumeration. No fix required beyond
adequate test timeouts (360s). Hub-child class-driver bring-up is slow
on QEMU's emulated TT path (~13s for the hub-child Evaluate Context) —
characteristic of emulation, not a defect.

### P3-B: Hub interrupt-driven change detection ✅ COMPLETE (verified 2026-07-18)

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

**Status:** Implemented (predates the P3-A pass; verified during it).
~~Current usbhubd polls at 100ms intervals~~ — stale premise; usbhubd is
interrupt-driven today:

1. ✅ EP1 interrupt endpoint discovered and opened (`EndpointTy::Interrupt` + `EndpDirection::In`).
2. ✅ Status-change bitmap read via `transfer_read()`; per-bit port dispatch (Linux `hub_irq()` → `kick_hub_wq` equivalent).
3. ✅ Fallback to full polling (200 ms) only when EP1 is absent or fails — matches the exit criterion for USB 3 hubs without interrupt endpoints.

**Exit met:** interrupt-driven on USB 2 hubs; polling fallback otherwise.

### P3-C: Port LED control ✅ HUB-SIDE COMPLETE (verified 2026-07-18)

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

**Status:** Hub-side done — usbhubd sets `SetPortFeature(PORT_INDICATOR)`
on connected+enabled+!resetting ports in the event loop.

**Remaining (P5-C scope, not P3):** keyboard LED state sync in usbhidd
(Caps/Num/Scroll Lock → HID SET_REPORT output), cross-coupled with the
input stack.

---

## 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. usbhubd, usbhidd, usbscsid are proven; redbear-acmd (186 LoC), redbear-ecmd (314 LoC), redbear-usbaudiod (367 LoC) are real but minimal implementations (verified 2026-07-20, reconciling P1-D): ACM covers line coding + DTR/RTS + scheme registration, but the full P6-A surface below (CTS/DSR flow control, break signaling, multi-port modems) is NOT covered yet. CDC NCM, full USB Audio, and USB-serial chip families are still missing entirely.

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

**Status (2026-07-20):** substantially complete (`f505d18a89`). **Bug-class
fix:** acmd used per-interface endpoint positions while xhcid keys endpoints
by global enumeration index — on two-interface ACM devices it opened the
wrong endpoints entirely. Same latent class fixed in redbear-ecmd and
redbear-usbaudiod (`08097d5a2d`, endpoint-address ≠ enumeration index) and
usbhidd multi-config counting (base `94a99f02`). usbhidd/ecmd/usbaudiod were
correct-by-coincidence on single-interface/sequential-address devices;
acmd was outright broken. Line coding, DTR/RTS, SEND_BREAK, and SERIAL_STATE
monitoring (interrupt-IN thread → scheme `state` file) implemented.

**Remaining:** multi-port modems (IAD interface grouping — structural);
runtime validation needs an ACM device (QEMU has no CDC ACM emulation).

**Endpoint-indexing bug class — audit result (2026-07-20):**

| Driver | Was | Status |
|---|---|---|
| redbear-acmd | per-interface position → wrong endpoints | ✅ fixed `f505d18a89` |
| redbear-ecmd | `ep.address & 0x0F` (coincides when sequential) | ✅ fixed `08097d5a2d` |
| redbear-usbaudiod | `ep.address & 0x0F` | ✅ fixed `08097d5a2d` |
| usbhidd | global but no per-config reset | ✅ fixed base `94a99f02` |
| usbscsid/bot.rs | per-interface `position()+1` (single-interface devices coincide) | **open — assigned to UAS workstream (C1) for bot.rs + uas.rs pipe discovery** |

**Tasks:**

1. ~~Implement a real CDC ACM class driver~~ ✅ (2026-07-08, P1-D)
2. ~~Line coding: baud rate, parity, stop bits, data bits~~ ✅
3. ~~Flow control: RTS/CTS, DTR/DSR via control transfers~~ ✅ (RTS/DTR via SET_CONTROL_LINE_STATE; CTS/DSR via SERIAL_STATE monitor)
4. ~~Break signaling~~ ✅ (SEND_BREAK 0x23)
5. Multi-port modems (data + control + notification interfaces) — **open**
6. ~~Expose `/scheme/tty` for userspace clients~~ ✅ (`/scheme/ttys/usbACM_<N>` + `state` file)

**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`.

**Status (2026-07-20):** xhcid per-device enablement **implemented** (base fork
`2a3b0d4e`): full Linux xhci.c:4650 gate chain at attach
(`hw_lpm_support` && per-port HLC && device `USB_LPM_SUPPORT` in BOS &&
non-hub && root-hub-direct), BESL vs HIRD parameter selection
(`calculate_hird_besl`, Linux xhci.c:4594), MEL Evaluate Context
(`change_max_exit_latency`, Linux xhci.c:4520), and the PORTHLPMC/PORTPMSC
programming sequence. LPM enable failure logs and continues (device works
in U0). Compile-verified; 3 BOS accessor unit tests. **Runtime validation
requires LPM-capable hardware** — QEMU's xHCI does not advertise HLC, so
the L1-entry exit criterion remains hardware-validation debt (P8-A).

**Status (2026-07-18):** Substrate done in P2-B — HLC/BLC/L1C parsed from the
Supported Protocol capability (NOT `HCCPARAMS1`: an earlier plan version and
driver accessor were wrong; HLC lives in the protocol caps port_info DWORD per
xHCI §7.2.2.1.3.2). `Xhci::hw_lpm_support` computed per Linux xhci-mem.c:2137;
`Port::enable_lpm/disable_lpm` implement the Linux two-register sequence;
defensive LPM clear runs on USB2 ports at attach when unsupported.

**Remaining tasks:**

1. ~~Parse HLC~~ ✅ done (P2-B, protocol caps).
2. Implement `usb_set_device_initiated_lpm()` (port hardware LPM control via PORTSC.PORT_L1DEV).
3. ~~xhcid: per-device `PORT_HLE` enablement at attach~~ ✅ done (2026-07-20, `2a3b0d4e`).
4. ~~ehcid: implement via USBCMD.HIRD~~ **RE-SCOPED (2026-07-20):** audit of
   Linux 7.1 shows no generic EHCI USB 2.0 hardware LPM exists upstream —
   `set_usb2_hw_lpm` is xHCI-only; EHCI power management is limited to the
   vendor-specific TDI PHY LPM path (`has_tdi_phy_lpm`, ehci-hub.c). Per the
   upstream-first policy there is no Linux reference to port. The correct
   EHCI power path is legacy L2 port suspend/resume
   (SetPortFeature PORT_SUSPEND), which is host-controller-agnostic — defer
   until a concrete device need arises rather than building speculative,
   unvalidatable hardware programming.
5. Runtime L1-entry validation on LPM-capable hardware (P8-A hardware matrix).

**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()`.

**Scoping audit (2026-07-20):** U1/U2 timeout *register* programming is trivial
(xhci-hub.c:1488-1510, `PORT_U1/U2_TIMEOUT` in PORTPMSC), but the real work is
upstream's timeout *computation*: `xhci_calculate_lpm_timeout` requires
per-endpoint SEL/PEL from SuperSpeed endpoint companion descriptors across the
hub tree, `calculate_max_exit_latency`, `xhci_check_tier_policy`, and only
engages for controllers carrying the `XHCI_LPM_SUPPORT` quirk (vendor
whitelist — "don't enable hub-initiated timeouts unless the vendor has
provided information about their timeout algorithm"). A defaults-only
implementation would be speculative non-upstream behavior that can break
device links on real hardware. P7-B therefore needs a dedicated workstream
covering endpoint-companion parsing + SEL/PEL plumbing first.

**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. Documentation lineage (2026-07-18, consolidated)

Current live documents:

- `local/docs/USB-IMPLEMENTATION-PLAN.md` — **this document (v3)**, the canonical USB plan.
  Updated 2026-07-18 with P2-A and P2-B completion records.
- `local/docs/USB-VALIDATION-RUNBOOK.md` — **live v3** companion runbook
  (validation scripts, QEMU/bare-metal paths, failure triage).

Archived lineage (read for history only):

- `local/docs/archived/USB-IMPLEMENTATION-PLAN-v2-2026-07.md` — v2 plan.
- `local/docs/archived/USB-VALIDATION-RUNBOOK-2026-07.md` — v2 runbook.
- v1 — initial pre-fork draft (superseded).

`archived/README.md` records the v1 → v2 → v3 supersession chain.

All Linux 7.0 references in active docs were migrated to Linux 7.1 earlier in
the v2 era; active cross-references target `local/reference/linux-7.1/`.

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

- `v1` — initial draft (pre-fork era; now superseded by this live plan)
- `local/docs/USB-IMPLEMENTATION-PLAN.md` — v2 lineage and current live roadmap (archived copy restored here)
- `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)