RedBear-OS/local/docs/USB-IMPLEMENTATION-PLAN.md

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.