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 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 autospawn is now re-enabled for validation, but the current blocker has moved to post-spawn runtime stability rather than driver matching.
• 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	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/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 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:

• 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 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.