Add USB and Bluetooth implementation plans

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
2026-04-14 20:04:30 +01:00
parent 15190543a5
commit 24a8ccfe27
2 changed files with 836 additions and 0 deletions
@@ -0,0 +1,450 @@
 # Red Bear OS Bluetooth Implementation Plan
 ## Purpose
 This document defines the current Bluetooth state in Red Bear OS and lays out a conservative,
 implementation-focused roadmap for adding Bluetooth support.
 The goal is not to imply that Bluetooth already exists in-tree. The goal is to describe what the
 repo currently proves, what it does not prove, and how Red Bear can grow from **no Bluetooth
 support** to a realistic, host-side Bluetooth stack that fits the existing Redox/Red Bear
 architecture.
 ## Validation States
 - **builds** — code exists in-tree and is expected to compile
 - **boots** — image or service path reaches a usable runtime state
 - **validated** — behavior has been exercised with real evidence for the claimed scope
 - **experimental** — available for bring-up, but not support-promised
 - **missing** — no in-tree implementation path is currently present
 This repo should not treat planned scope as equivalent to implemented support.
 ## Current Repo State
 ### Summary
 Bluetooth is currently **missing** in Red Bear OS.
 The repo has no first-class Bluetooth daemon, no controller transport path, no host stack, no
 documented app-facing Bluetooth API, and no profile that can honestly claim Bluetooth support.
 What the repo *does* have is enough adjacent infrastructure to make a Bluetooth port plausible:
 - userspace drivers and schemes as the standard architectural model
 - USB and PCI hardware access patterns
 - runtime diagnostics discipline
 - D-Bus plumbing for later desktop compatibility work
 - an evolving input and hotplug model that could later absorb Bluetooth HID devices
 ### Current Status Matrix
 | Area | State | Notes |
 |---|---|---|
 | Bluetooth controller support | **missing** | No HCI transport daemon in-tree |
 | Bluetooth host stack | **missing** | No L2CAP / ATT / SMP / GATT / RFCOMM stack evidence |
 | Pairing / bond database | **missing** | No Bluetooth-specific persistence path documented |
 | Desktop Bluetooth API | **missing** | D-Bus exists generally, but no Bluetooth API/service exists |
 | Bluetooth HID | **missing** | Could later build on input modernization work |
 | Bluetooth audio | **missing** | Also blocked by broader desktop audio compatibility work |
 | Runtime diagnostics | **partial prerequisite exists** | `redbear-info` model exists, but no Bluetooth integration exists |
 ## Evidence Already In Tree
 ### Direct negative evidence
 - `HARDWARE.md` says Wi-Fi and Bluetooth are not supported yet
 - `local/docs/AMD-FIRST-INTEGRATION.md` marks `Wi-Fi/BT` as missing
 ### Positive architectural prerequisites
 - `docs/01-REDOX-ARCHITECTURE.md` describes the userspace-daemon and scheme model Red Bear must
  follow for any new hardware subsystem
 - `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` sets the repo-wide rule that support claims must be
  profile-scoped and evidence-backed
 - `local/docs/PROFILE-MATRIX.md` defines the validation-language model a future Bluetooth path must
  use
 - `local/docs/INPUT-SCHEME-ENHANCEMENT.md` shows the direction of travel for per-device, hotplug,
  named input sources, which is relevant to later Bluetooth HID support
 - `config/redbear-kde.toml` and related profile wiring already show D-Bus and desktop-session
  plumbing that later Bluetooth desktop integration might rely on
 ## Feasibility Constraints
 ### 1. Bluetooth is not one driver
 Bluetooth in Red Bear cannot be treated as a single device daemon.
 At minimum, Red Bear would need:
 - controller transport handling
 - adapter state management
 - scanning and connection management
 - pairing / bonding persistence
 - higher protocol layers
 - some user-facing control surface
 This makes Bluetooth more like networking than like a single peripheral driver.
 ### 1.1 Minimum Native Subsystem Shape
 The smallest Red Bear-native Bluetooth subsystem should be split into these pieces:
 - one **controller transport daemon** for the first supported controller family
 - one **host daemon** for adapter state, discovery, connection state, and higher protocol work
 - one **user-facing control path** (CLI first, compatibility shim later if needed)
 - one **pairing/bond persistence path** with a documented storage location and lifecycle
 This should be treated as the minimum subsystem shape, not as optional later cleanup.
 ### 2. The correct architectural fit is native userspace daemons
 The repo's existing system model strongly favors:
 - userspace controller daemons
 - explicit runtime services
 - narrow compatibility shims when desktop software expects them
 - profile-scoped support language
 That means Bluetooth should be implemented as a native Red Bear subsystem, not described as a
 wholesale Linux/BlueZ drop-in.
 ### 2.1 Repo Placement Guidance
 Unless upstream Redox grows a first-class Bluetooth path first, the initial Red Bear work should
 live under `local/`:
 - controller transport daemon recipes under `local/recipes/drivers/`
 - host daemon, CLI, and compatibility-surface recipes under `local/recipes/system/`
 - Red Bear-specific profile and service wiring under `config/redbear-*.toml`
 - validation helpers under `local/scripts/`
 - support-language and roadmap updates under `local/docs/`
 That keeps the first implementation pass aligned with Red Bear's overlay model and rebase strategy.
 ### 3. Desktop parity is not the first milestone
 The current repo does not justify claiming a full desktop Bluetooth user experience early.
 The first realistic milestone is much smaller:
 - one controller family
 - one transport path
 - one limited workload
 - experimental support language only
 ### 3.1 First-Milestone Dependency
 If the first supported controller is USB-attached, then Bluetooth Phase B1 depends directly on the
 USB plan's controller and hotplug baseline work.
 In practice that means Bluetooth should not claim a validated first controller path until the USB
 stack can already support that controller family with stable enumeration, attach/detach behavior,
 and honest runtime diagnostics.
 ### 4. Bluetooth scope depends on adjacent subsystems
 Bluetooth HID depends on the modernized input path.
 Bluetooth audio depends on the broader audio compatibility story that the repo already treats as
 unfinished for desktop use.
 That means the Bluetooth roadmap must stay sequenced and should not over-promise audio or broad
 desktop integration early.
 ## Implementation Plan
 ### Repo-fit note
 Some of the implementation targets below refer to upstream-managed trees such as
 `recipes/core/base/source/...`.
 In Red Bear, changes against those paths should be carried through the relevant patch carrier under
 `local/patches/` until intentionally upstreamed. This plan names the technical integration point,
 not a recommendation to edit upstream-managed trees outside Red Bear's normal overlay model.
 ### Phase B0 — Scope Freeze and Support Model
 **Goal**: Decide what the first Bluetooth milestone actually is.
 **What to do**:
 - declare Bluetooth support as absent today
 - define validation labels and support language for future Bluetooth work
 - freeze the first milestone as **host-side, experimental, one controller family, one limited use
  case**
 - keep desktop parity explicitly out of the first support claim
 **Where**:
 - `local/docs/PROFILE-MATRIX.md`
 - `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md`
 - this document
 **Exit criteria**:
 - Bluetooth scope is documented without vague “future wireless” wording
 ---
 ### Phase B1 — Controller Transport Baseline
 **Goal**: Establish one real Bluetooth controller path.
 **Recommended first target**:
 - one USB-attached Bluetooth controller family
 **Why**:
 - Red Bear already has a USB hardware path
 - USB diagnostics and controller visibility already exist
 - it is the narrowest realistic controller baseline before considering broader wireless scope
 **What to do**:
 - implement one controller transport daemon
 - expose adapter presence and basic control through a Red Bear-native runtime surface
 - ensure the daemon fits the userspace service/scheme model
 **Where**:
 - `local/recipes/drivers/` for the first Red Bear Bluetooth transport daemon recipe
 - `config/redbear-*.toml` for profile/package wiring
 - `config/redbear-device-services.toml` or a sibling shared fragment if the daemon becomes a common
  service prerequisite
 - `local/scripts/` for controller bring-up validation helpers
 **Initial launch path**:
 - for a USB-attached first controller, the long-term attach path should be through
  `recipes/core/base/source/drivers/usb/xhcid/drivers.toml` or its eventual Red Bear equivalent
  once a Bluetooth USB class match is ready
 - before that exists, the first milestone may use explicit Red Bear service startup so the transport
  daemon can be validated without pretending that USB class autospawn is already solved
 - if Red Bear adds that xHCI class match before it exists upstream, it should be carried as a Red
  Bear base patch rather than as an unqualified direct tree edit
 **Firmware note**:
 - if the first supported controller family requires firmware upload, reuse the existing
  `firmware-loader` / shared device-service pattern instead of inventing a separate firmware path
 - if that complexity is too high for the first milestone, choose a controller family that can be
  initialized without introducing a second firmware-loading architecture
 **Dependency**:
 - if the first controller is USB-attached, this phase is blocked on the USB plan's U1-U2 baseline
  being sufficiently stable for that controller family
 **Exit criteria**:
 - one supported Bluetooth controller can be detected and initialized repeatedly
 - controller presence can be reported honestly at runtime
 ---
 ### Phase B2 — Minimal Host Daemon
 **Goal**: Create the first Red Bear-native Bluetooth service layer.
 **What to do**:
 - add one host daemon that owns adapter state
 - support scanning and connect/disconnect for one limited workload
 - add persistent pairing/bond storage only once the storage path is explicitly defined
 - keep the control surface small and Red Bear-native
 **Where**:
 - `local/recipes/system/` for the host-daemon recipe
 - `config/redbear-*.toml` and init-service wiring for runtime startup
 - `/var/lib/bluetooth/` as the first Red Bear-owned bond/state directory, created by profile or
  service wiring in the same style used for other runtime-state directories
 **Minimum native surface**:
 - adapter presence/state
 - discovery / scan state
 - connect / disconnect control
 - bond database lifecycle rooted at `/var/lib/bluetooth/`
 - failure reporting suitable for later `redbear-info` integration
 **Exit criteria**:
 - the daemon can rediscover and reconnect to at least one target device class across repeated runs
 ---
 ### Phase B3 — BLE-First User Value
 **Goal**: Deliver the first actually useful Bluetooth capability without overreaching.
 **Recommended first workload**:
 - BLE-first rather than full classic Bluetooth parity
 **What to do**:
 - add scan/connect support for one BLE device type
 - expose minimal read/write/notify behavior if the chosen workload needs it
 - keep support language experimental and hardware-specific
 **Where**:
 - host-daemon implementation under `local/recipes/system/`
 - package-group wiring in one explicitly experimental Red Bear package-group slice named
  `bluetooth-experimental`
 - validation helper in `local/scripts/`
 **Recommended support slice**:
 - start as one explicitly experimental package-group addition named `bluetooth-experimental`
  rather than claiming Bluetooth generically across all Red Bear images
 **Exit criteria**:
 - one real BLE device type works reliably on the chosen controller family
 ---
 ### Phase B4 — Input Integration
 **Goal**: Prepare for Bluetooth HID in a way that matches Red Bear's planned input model.
 **What to do**:
 - build Bluetooth HID integration on top of the named-producer / per-device / hotplug-aware input
  direction already documented for `inputd`
 - avoid introducing a second incompatible input plumbing path
 **Where**:
 - `recipes/core/base/source/drivers/inputd/`
 - `local/docs/INPUT-SCHEME-ENHANCEMENT.md`
 **Exit criteria**:
 - Bluetooth input devices can appear as distinct recoverable input sources rather than as an opaque
  special case
 ---
 ### Phase B5 — Desktop Control Surface
 **Goal**: Add higher-level control only after the native substrate exists.
 **What to do**:
 - start with a small Red Bear-native control path
 - add a compatibility shim only if actual desktop consumers require it
 - keep desktop integration explicitly separate from core Bluetooth correctness
 **Where**:
 - Red Bear-native CLI/tooling under `local/recipes/system/`
 - any compatibility shim under `local/recipes/` with profile-specific wiring in desktop-oriented
  Red Bear configs
 - later runtime reporting hooks in `local/recipes/system/redbear-info/`
 **Why**:
 Red Bear already uses the pattern of adding narrow compatibility surfaces where desktop software
 expects them instead of importing a whole foreign subsystem model blindly.
 **Exit criteria**:
 - one desktop or user-facing consumer can manage the limited supported Bluetooth path without
  changing the underlying native architecture
 ---
 ### Phase B6 — Audio and Broader Class Expansion
 **Goal**: Widen Bluetooth scope only after the substrate and adjacent stacks justify it.
 **What to do**:
 - defer Bluetooth audio until the broader Red Bear desktop-audio compatibility path is stronger
 - defer broad classic Bluetooth parity until controller and host-daemon maturity are no longer the
  main risk
 - decide later whether Bluetooth networking or additional classes are worth supporting
 **Where**:
 - later profile/package-group expansion in `config/redbear-*.toml`
 - later runtime diagnostics and support-language updates in `local/docs/` and `redbear-info`
 **Exit criteria**:
 - later Bluetooth classes are added only after the repo can name real prerequisites and evidence
 ---
 ### Phase B7 — Validation Slice and Support Claims
 **Goal**: Turn Bluetooth from an experimental prototype into a supportable Red Bear feature slice.
 **What to do**:
 - create a Bluetooth-focused validation path tied to a specific profile or package-group slice
 - extend runtime diagnostics conservatively once Bluetooth runtime surfaces actually exist
 - add hardware-target guidance and support labels
 **Recommended first support language**:
 - one explicitly experimental Red Bear package-group slice named `bluetooth-experimental` for the
  first supported controller + workload combination
 **Where**:
 - `local/scripts/`
 - `local/recipes/system/redbear-info/`
 - `local/docs/PROFILE-MATRIX.md`
 - `HARDWARE.md`
 **Exit criteria**:
 - at least one profile can honestly claim validated experimental Bluetooth support for named
  hardware and named workload scope
 ## Support-Language Guidance
 Until B1 through B3 exist, Red Bear should use language such as:
 - “Bluetooth is not supported yet”
 - “Bluetooth remains missing in-tree”
 - “Bluetooth is a future implementation workstream”
 Once B1 through B3 begin to land, prefer:
 - “experimental Bluetooth bring-up exists for one controller family”
 - “Bluetooth support is limited to the documented workload and profile”
 Avoid language such as:
 - “Bluetooth works”
 - “desktop Bluetooth is supported”
 - “wireless support is complete”
 unless the repo has profile-scoped validation evidence to justify those claims.
 ## Summary
 Bluetooth in Red Bear today is not partial support — it is **missing**.
 What makes it feasible is not any existing Bluetooth stack, but the surrounding Red Bear
 architecture: userspace daemons, runtime services, diagnostic discipline, profile-scoped support
 language, and an evolving per-device input model.
 That means the right Bluetooth implementation plan is conservative and staged:
 1. freeze scope and support language
 2. bring up one controller transport path
 3. add one native host daemon
 4. deliver one BLE-first workload
 5. integrate input and desktop control only after the substrate exists
 6. widen class coverage only when adjacent subsystems are ready
 That is the most credible path to Bluetooth in Red Bear without over-claiming support that the repo
 does not yet have.
@@ -0,0 +1,386 @@
 # Red Bear OS USB Implementation Plan
 ## Purpose
 This document defines the current state, completeness, and implementation path for USB in Red Bear
 OS.
 The goal is to describe USB in terms of **what is built**, **what is runtime-wired**, **what is
 actually usable**, and **what still needs to be implemented** before Red Bear can honestly claim a
 modern, future-proof USB stack.
 This document is Red Bear-specific. It uses current repo evidence from code, configs, runtime
 tooling, and status docs instead of assuming inherited upstream documentation is fully current.
 ## Validation States
 - **builds** — code exists in-tree and is expected to compile
 - **enumerates** — runtime surfaces can discover controllers, ports, or descriptors
 - **usable** — a specific controller/class path works in a limited real scenario
 - **validated** — behavior has been exercised with explicit evidence for the claimed scope
 - **experimental** — available for bring-up, but not support-promised
 This repo should not treat **builds** or **enumerates** as equivalent to **validated**.
 ## Current Repo State
 ### Summary
 USB in Red Bear OS is **present but incomplete**.
 The current repo supports a real host-side USB path built around the userspace `xhcid` controller
 daemon, hub and HID class spawning, native USB observability (`lsusb`, `usbctl`, `redbear-info`),
 and a low-level userspace client API through `xhcid_interface`.
 The current limitations are material:
 - xHCI still runs in polling mode because interrupt support is disabled
 - USB support varies by machine, including known `xhcid` panic cases
 - hub/topology handling is partial
 - HID is still wired through the legacy mixed-stream `inputd` path
 - USB mass storage exists in-tree, but default autospawn is disabled because it causes xHCI errors
 - there is no evidence of validated support for broader USB classes or modern USB-C / dual-role
  scope
 ### Current Status Matrix
 | Area | State | Notes |
 |---|---|---|
 | Host mode | **usable / experimental** | Real host-side stack exists, but not broadly validated |
 | xHCI controller | **builds / enumerates / usable on some hardware** | Polling mode, hardware-variable, not fully corrected |
 | Hub handling | **builds / partial usable** | `usbhubd` exists, USB 3 hub limitations remain |
 | HID | **builds / usable in narrow path** | `usbhidd` handles keyboard/mouse/button/scroll via legacy input path |
 | Mass storage | **builds** | `usbscsid` exists, but default autospawn is disabled |
 | Native tooling | **builds / enumerates** | `lsusb`, `usbctl`, `redbear-info` provide partial observability |
 | Low-level userspace API | **builds** | `xhcid_interface` exists, but not a mature general userspace USB story |
 | libusb | **builds / experimental** | WIP, compiled but not tested |
 | usbutils | **broken / experimental** | WIP, compilation error |
 | EHCI/OHCI/UHCI | **absent / undocumented** | No evidence present in-tree |
 | USB networking/audio/video/Bluetooth classes | **absent / undocumented** | No evidence of working support |
 | Device mode / OTG / dual-role / USB-C / PD / alt-modes / USB4 | **absent / undocumented** | No evidence present |
 ## Evidence Already In Tree
 ### Built and wired components
 - `recipes/core/base/recipe.toml` builds `xhcid`, `usbctl`, `usbhidd`, `usbhubd`, and `usbscsid`
 - `recipes/core/base/source/drivers/usb/xhcid/config.toml` autoloads `xhcid` by PCI class match
 - `recipes/core/base/source/drivers/usb/xhcid/drivers.toml` enables hub and HID subdrivers by
  default
 ### Runtime and API surfaces
 - `README.md` documents native `usb.*` schemes and Red Bear's `lsusb`
 - `local/recipes/system/redbear-hwutils/source/src/bin/lsusb.rs` walks `usb.*` schemes, reads port
  topology, parses descriptors, and falls back to reporting port state when full descriptors fail
 - `local/recipes/system/redbear-info/source/src/main.rs` reports USB-controller visibility through
  passive runtime probing
 - `recipes/core/base/source/drivers/usb/xhcid/src/lib.rs` and `driver_interface.rs` define a real
  userspace client interface for the xHCI daemon
 - `recipes/core/base/source/drivers/usb/usbctl/src/main.rs` is a low-level CLI over that client API
 ### Negative and cautionary evidence
 - `HARDWARE.md` says USB support varies by machine and records systems where USB input or USB more
  broadly does not work, plus known `xhcid` panic cases
 - `local/docs/AMD-FIRST-INTEGRATION.md` marks USB as **variable**
 - `recipes/core/base/source/drivers/usb/xhcid/src/main.rs` forces polling mode and leaves
  interrupt setup disabled with `TODO: Fix interrupts.`
 - `recipes/core/base/source/drivers/usb/xhcid/drivers.toml` comments out USB SCSI autospawn with
  `#TODO: causes XHCI errors`
 - `recipes/core/base/source/drivers/COMMUNITY-HW.md` still claims there is no Redox xHCI driver,
  which means inherited USB docs cannot be treated as uniformly current
 ## Current Gaps and Limits
 ### 1. Controller correctness is still incomplete
 `xhcid` is real, but it is not yet mature enough to anchor broad support claims.
 Current repo-visible issues include:
 - polling-mode operation instead of interrupt-driven behavior
 - incorrect or incomplete speed handling for child devices
 - TODOs around configuration choice and alternate settings
 - TODOs around endpoint selection across interfaces
 - incomplete BOS / SuperSpeed / SuperSpeedPlus handling
 This means the current stack is more than a bring-up stub, but still below the bar for a reliable,
 future-proof USB controller foundation.
 ### 2. Topology and hotplug maturity are partial
 The stack can enumerate ports and descendants, but the code still carries explicit TODOs around hub
 behavior and USB 3 hub handling.
 The current repo does not justify a claim that attach, detach, reset, reconfigure, and hub-chained
 topologies are runtime-proven in a broad sense.
 ### 3. HID works through a legacy path
 `usbhidd` exists and is meaningful evidence that USB HID is not hypothetical.
 However, the current HID path is still tied to the older anonymous `inputd` producer model.
 `local/docs/INPUT-SCHEME-ENHANCEMENT.md` already defines the needed next step: named producers,
 per-device streams, and explicit hotplug events.
 ### 4. Storage is present in-tree but not a current support claim
 `usbscsid` is a real driver, but the current xHCI class-driver table disables the SCSI-over-USB
 autospawn path because it causes XHCI errors.
 That means Red Bear should document USB storage as **implemented in-tree but not currently enabled
 as a default working class path**.
 ### 5. The userspace USB story is still low-level
 Red Bear already has:
 - scheme-level access via `usb.*`
 - descriptor/request/configuration APIs through `xhcid_interface`
 - low-level inspection through `usbctl`
 What it does not yet have is a mature, validated general-purpose userspace USB model that desktop
 or application ports can rely on with confidence. The WIP `libusb` and broken `usbutils` recipes
 are the clearest sign of that gap.
 ### 6. Modern USB scope is still undecided / absent
 There is currently no repo evidence for:
 - device mode / gadget mode
 - OTG or dual-role support
 - USB-C policy handling
 - USB Power Delivery
 - alternate modes
 - USB4 / Thunderbolt-class integration
 Those are not small omissions. They are the difference between a partial host USB stack and a
 future-proof USB platform.
 ## Implementation Plan
 ### Repo-fit note
 Some of the implementation targets below live in upstream-managed trees such as
 `recipes/core/base/source/...`.
 In Red Bear, work against those paths should be carried through the appropriate patch carrier under
 `local/patches/` until it is intentionally upstreamed. This plan names the technical target path,
 not a recommendation to bypass Red Bear's overlay/patch discipline.
 ### Phase U0 — Support Model and Scope Freeze
 **Goal**: Make USB claims honest and reproducible before widening implementation scope.
 **What to do**:
 - Define USB support labels per profile: `builds`, `enumerates`, `usable`, `validated`
 - Declare Red Bear's near-term USB scope explicitly as **host-first**
 - Record that device mode / USB-C / PD / alt-modes / USB4 are later decision points, not implied
  current scope
 - Add USB status guidance to the profile/support-language discipline used elsewhere in Red Bear
 **Where**:
 - `local/docs/PROFILE-MATRIX.md`
 - `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md`
 - this document
 **Exit criteria**:
 - USB claims are tied to a named profile or package-group slice
 - no doc implies broad USB support without a matching validation label
 ---
 ### Phase U1 — xHCI Controller Baseline
 **Goal**: Turn `xhcid` from partial bring-up into a dependable baseline on at least one controller
 family.
 **What to do**:
 - Restore interrupt-driven operation or explicitly justify continued polling with measured behavior
 - Eliminate current crash-class regressions and known panic paths
 - Validate one controller family as the first real support target
 - Tighten speed detection and controller-state correctness
 **Where**:
 - `recipes/core/base/source/drivers/usb/xhcid/src/main.rs`
 - `recipes/core/base/source/drivers/usb/xhcid/src/xhci/`
 - `HARDWARE.md`
 **Exit criteria**:
 - one target controller family repeatedly boots without `xhcid` panic
 - controller can enumerate attached devices reliably across repeated boot cycles
 - interrupt strategy is no longer a TODO-level gap
 ---
 ### Phase U2 — Topology, Configuration, and Hotplug Correctness
 **Goal**: Make the USB tree and device configuration path correct enough for real-world devices.
 **What to do**:
 - fix USB 3 hub stall cases and other known hub limitations
 - validate repeated attach/detach/reset behavior
 - support non-default configurations and alternate settings where needed
 - improve composite-device handling and endpoint selection across interfaces
 - separate “enumerates” from “stays correct under topology changes”
 **Where**:
 - `recipes/core/base/source/drivers/usb/usbhubd/`
 - `recipes/core/base/source/drivers/usb/xhcid/src/xhci/mod.rs`
 - `recipes/core/base/source/drivers/usb/xhcid/src/xhci/scheme.rs`
 **Exit criteria**:
 - repeated hub and hotplug scenarios complete without stale topology state
 - at least one composite device configures correctly beyond the simplest path
 - non-default configuration/alternate-setting paths are either implemented or explicitly scoped out
 ---
 ### Phase U3 — HID Modernization
 **Goal**: Move USB HID from legacy mixed-stream input to a modern per-device runtime path.
 **What to do**:
 - migrate `usbhidd` toward named producers and per-device streams
 - expose hotplug add/remove behavior cleanly to downstream consumers
 - keep compatibility with existing consumers while widening capability
 - align USB HID with the `inputd` enhancement design already documented in-tree
 **Where**:
 - `recipes/core/base/source/drivers/input/usbhidd/`
 - `recipes/core/base/source/drivers/inputd/`
 - `local/docs/INPUT-SCHEME-ENHANCEMENT.md`
 **Exit criteria**:
 - two independent USB HID devices appear as separate input sources
 - hot-unplug and replug do not collapse all USB HID into one anonymous stream
 ---
 ### Phase U4 — Storage, Userspace API, and Class Expansion
 **Goal**: Turn USB from a controller/HID substrate into a broader usable host subsystem.
 **What to do**:
 - repair and re-enable USB mass-storage autospawn
 - decide whether BOT-only is sufficient short-term or whether UAS is part of the next step
 - bring `libusb` to a runtime-tested state or explicitly replace it with a Red Bear-native API
  strategy
 - either fix `usbutils` or document native tools as the intended replacement
 - choose the next USB class families explicitly instead of implying broad support
 **Suggested class priority**:
 1. storage baseline
 2. generic userspace API story
 3. USB networking or Bluetooth dongle path
 4. audio/video only after controller and transfer maturity justify it
 **Where**:
 - `recipes/core/base/source/drivers/storage/usbscsid/`
 - `recipes/wip/libs/other/libusb/`
 - `recipes/wip/sys-info/usbutils/`
 - `local/recipes/system/redbear-hwutils/`
 **Exit criteria**:
 - one USB storage path is validated on the target profile
 - one coherent userspace USB API story is documented and works in practice
 - next supported class families are named explicitly in docs and support labels
 ---
 ### Phase U5 — Modern USB Scope Decision Gate
 **Goal**: Decide whether Red Bear remains a host-only USB system or grows toward a modern USB
 platform.
 **What to decide**:
 - host-only versus device mode / gadget support
 - whether OTG / dual-role matters for target hardware
 - whether USB-C / PD / alt-mode policy belongs in Red Bear's target platform story
 - whether USB4 / Thunderbolt-class behavior is in scope or explicitly excluded
 **Why this phase exists**:
 These are architectural choices, not small driver add-ons. A future-proof stack cannot leave them
 implicit forever.
 **Exit criteria**:
 - a written architecture decision exists for included and excluded modern USB scope
 ---
 ### Phase U6 — Validation Slices and Support Claims
 **Goal**: Turn USB from a collection of partial capabilities into an evidence-backed support story.
 **What to do**:
 - create USB-focused validation helpers instead of relying only on other profile scripts that happen
  to include `qemu-xhci`
 - add hardware-matrix coverage for target controllers and class families
 - extend `redbear-info` only where passive probing can be honest
 - tie support claims to a concrete profile or package-group slice
 **Where**:
 - `local/scripts/`
 - `local/recipes/system/redbear-info/`
 - `HARDWARE.md`
 - `local/docs/PROFILE-MATRIX.md`
 **Exit criteria**:
 - at least one profile can honestly claim a validated USB baseline for named controller/class scope
 - USB support language in docs matches real test evidence
 ## Support-Language Guidance
 Until U1 through U3 are substantially complete, Red Bear should avoid broad phrases such as:
 - “USB support works”
 - “USB storage is supported”
 - “USB is complete”
 Prefer language such as:
 - “xHCI host support is present but experimental”
 - “USB enumeration and HID-adjacent host paths exist in-tree”
 - “USB support remains controller-variable”
 - “USB storage support exists in-tree but is not currently enabled as a default working path”
 ## Summary
 USB in Red Bear today is not missing. It is a real userspace host-side subsystem with meaningful
 enumeration, runtime observability, hub/HID infrastructure, and a low-level userspace API.
 It is also not complete. The current gaps are no longer “does Red Bear have any USB code at all?”
 but rather:
 - controller correctness and interrupt maturity
 - topology and configuration correctness
 - HID modernization
 - re-enabling and validating storage
 - defining a coherent userspace USB API strategy
 - deciding how much modern USB scope Red Bear actually wants
 - building a real USB validation surface
 That is the correct framing for a modern, future-proof USB implementation plan in this repo.