391 lines
16 KiB
Markdown
391 lines
16 KiB
Markdown
# 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 no longer hard-forces polling; it uses the existing interrupt-mode selection path again, but
|
|
interrupt-driven behavior is still only lightly validated under runtime load
|
|
- checked-in event-ring growth support now exists, but it still needs stronger runtime validation
|
|
- 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 and now autospawns successfully in the current QEMU validation
|
|
path, but broader runtime stability and wider class/topology validation are still open.
|
|
- 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** | Interrupt-mode selection restored, hardware-variable, event-ring growth exists in-tree but still needs stronger runtime validation |
|
|
| 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 / autospawns in QEMU** | `usbscsid` now spawns from the xHCI class-driver table, but runtime stability past spawn still needs work |
|
|
| 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 | **partial / experimental** | Broad class support remains incomplete, but one bounded explicit-startup USB-attached Bluetooth slice now exists |
|
|
| 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/xhci/irq_reactor.rs` now contains event-ring growth logic, but the restored interrupt path still needs stronger validation under sustained runtime load
|
|
- `recipes/core/base/source/drivers/usb/xhcid/drivers.toml` now re-enables USB SCSI autospawn with
|
|
explicit protocol matching for BOT (`0x50`)
|
|
- `recipes/core/base/source/drivers/COMMUNITY-HW.md` is a historical/community request ledger and
|
|
cannot be treated as a canonical current-state source for xHCI support
|
|
|
|
## 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:
|
|
|
|
- partially restored interrupt-driven behavior without complete event-ring growth support
|
|
- 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 and the xHCI class-driver table now spawns it again during QEMU USB
|
|
storage validation. The current blocker is not matching or spawn, but transport/runtime stability
|
|
after spawn.
|
|
|
|
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**:
|
|
|
|
- stabilize USB mass-storage after autospawn (BOT transport / SCSI runtime path)
|
|
- 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 and is QEMU-proven for the current validation path, but is
|
|
not yet a broad hardware support claim”
|
|
|
|
## 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.
|