diff --git a/local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md b/local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md new file mode 100644 index 00000000..bcf86dc9 --- /dev/null +++ b/local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md @@ -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. diff --git a/local/docs/USB-IMPLEMENTATION-PLAN.md b/local/docs/USB-IMPLEMENTATION-PLAN.md new file mode 100644 index 00000000..d97d9da0 --- /dev/null +++ b/local/docs/USB-IMPLEMENTATION-PLAN.md @@ -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.