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>
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user