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. It distinguishes between the upstream source (unpatched) and the Red Bear state (after applying local/patches/base/redox.patch).

The goal is to describe USB in terms of what is built, what is patched, 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.

Source Model

USB driver code lives in recipes/core/base/source/drivers/usb/, which is an upstream-managed git working copy. Red Bear carries all USB modifications through local/patches/base/redox.patch (currently ~17000 lines across ~100 diff sections).

Upstream state — the unpatched source snapshot that make fetch produces — has significant error handling gaps and several correctness bugs. Red Bear's patch layer fixes these, but the fixes are only visible after patch application. This document describes the Red Bear state unless explicitly noted.

Current Repo State

Summary

USB in Red Bear OS is present and improving.

The Red Bear USB stack consists of:

• a host-side xHCI controller daemon (xhcid) with Red Bear patches for error handling, correctness, and robustness
• hub and HID class daemons with Red Bear patches
• a mass-storage BOT daemon with Red Bear patches
• native USB observability (lsusb, usbctl, redbear-info)
• a low-level userspace client API through xhcid_interface
• a hardware quirks system that applies USB device-specific workarounds at runtime
• four QEMU validation harnesses covering interrupt delivery, bounded device lifecycle hotplug, full stack, and storage autospawn
• an in-guest scheme-tree checker (redbear-usb-check)

Boot-input reality

For bare-metal boot resilience, the current USB stack is still incomplete.

External USB keyboard input is reliably available only when the keyboard is reached through the xHCI -> usbhubd/usbhidd -> inputd path. This is an important distinction because modern bare metal does not guarantee that an attached keyboard will land on the xHCI runtime path.

If a keyboard instead lands on:

• an EHCI-owned path
• a UHCI/OHCI companion path
• a firmware routing topology where low/full-speed devices do not reach the xHCI runtime path

then Red Bear may still detect controller ownership and connected ports, but it does not yet have a complete runtime host path that reaches the existing HID class daemons.

This means Red Bear cannot yet honestly claim that an external USB keyboard is a reliable universal boot fallback on bare metal.

Red Bear xHCI Patch Layer

The Red Bear patch at local/patches/base/redox.patch carries these changes over the upstream source:

Error handling (88 fixes):

• unwrap() on mutex locks replaced with unwrap_or_else(|e| e.into_inner()) across scheme.rs, mod.rs, irq_reactor.rs, and ring.rs — mutex poisoning no longer panics any hot-path lock
• expect() calls replaced with proper Result propagation, logged errors, or fallible helpers
• trb_phys_ptr() returns Result<u64> instead of panicking on invalid TRB pointers
• panic!() in irq_reactor.rs replaced with error returns where possible
• device_enumerator.rs panics replaced with error logging and graceful handling

Correctness fixes:

• ERDP split: upstream has a single erdp() method that conflates the software dequeue pointer with the hardware register read. Red Bear splits this into dequeue_ptr() (software ring position) and erdp(&RuntimeRegs) (actual hardware register read, per XHCI spec §4.9.3)
• endp_direction off-by-one: upstream uses endp_num as usize to index into the endpoints Vec, but USB endpoints are 1-indexed. Red Bear uses endp_num.checked_sub(1) for correct 0-based indexing
• cfg_idx ordering: upstream sets port_state.cfg_idx before validating the config descriptor. Red Bear moves the assignment after validation succeeds
• CLEAR_FEATURE endpoint address: upstream uses the driver-internal endpoint index for CLEAR_FEATURE(ENDPOINT_HALT). Red Bear uses the USB endpoint address from the descriptor (bEndpointAddress)
• usbhubd status_change_buf: upstream has off-by-one bitmap sizing and bit-position parsing. Red Bear sizes the buffer correctly and computes port bit positions explicitly

Functional additions:

• Event ring growth: upstream has a stub grow_event_ring() that logs "TODO". Red Bear implements real ring doubling (up to 4096 cap), new DMA allocation, dequeue pointer preservation, ERDP/ERSTBA register updates, and DCS bit handling
• BOS/SuperSpeed descriptor fetching: fetch_bos_desc() called during device enumeration with bounds-checked slicing and graceful USB 2 fallback
• Speed detection for hub child devices: UsbSpeed enum with from_v2_port_status() / from_v3_port_status() mapping, passed via attach_with_speed() from usbhubd
• Interrupt-driven operation restored: get_int_method() replaces hardwired polling; MSI/MSI-X/ INTx paths re-enabled
• Hub interrupt EP1: usbhubd reads status change via interrupt endpoint instead of polling
• USB 3 hub endpoint configuration: SET_INTERFACE always sent; stall on (0,0) tolerated
• Hub change bit clearing: clear_port_changes sends all relevant ClearFeature requests including USB3-specific features after every port status read
• HID error handling: usbhidd uses anyhow::Result with context, no panics in report loop
• BOT transport robustness: usbscsid replaces all panic!() with stall recovery and error returns; iterative bounded CSW read loop instead of unbounded recursion; correct early_residue computation

Remaining Limitations

Even with the Red Bear patch applied:

• HID is now wired through named producers (ps2-keyboard, ps2-mouse, usb-{port}-if{n}); named producers always fan out to both per-device consumers and the legacy VT consumer path; the InputProducer wrapper falls back to an anonymous legacy ProducerHandle if the named path is unavailable (e.g., older inputd build)
• external USB keyboard fallback is not guaranteed on bare metal unless the keyboard reaches the xHCI runtime path
• EHCI/UHCI/OHCI are not yet full runtime host-controller implementations
• Any remaining USB composite/device-model issues now sit above the bounded helper fixes already landed for active alternates, endpoint direction, real interface/alternate hub configuration, and SSP-aware endpoint-context calculations.
• ~57 TODO/FIXME comments remain across xHCI driver files
• usbhubd: interrupt-driven change detection implemented; 1-second polling retained as fallback
• usbscsid: ReadCapacity16 now implemented with automatic fallback from ReadCapacity10
• usbhidd keyboard LED sync is only a bounded per-device best-effort path, not a system-global lock-state authority
• No real hardware USB validation — all testing is QEMU-only
• No hot-plug stress testing
• No USB storage data I/O validation (autospawn checked, but no read/write tested)
• USB quirk table expanded from 8 to 146 entries mined from Linux 7.0
• USB quirk flags expanded from 9 to 22 (13 new flags from Linux 7.0 including NO_BOS, HUB_SLOW_RESET)
• Terminus hub (0x1A40:0x0101) corrected from no_lpm to hub_slow_reset per Linux semantics

Current Status Matrix

Area	State	Notes
Host mode	builds / QEMU-validated	Real host-side stack, interrupt-driven, QEMU-validated only
xHCI controller	builds / QEMU-validated	Red Bear patch: 88 error handling fixes, ERDP split, endp_direction fix, cfg_idx fix, real grow_event_ring, mutex poison recovery on all hot-path locks; no real hardware validation yet
EHCI/UHCI/OHCI	builds / enumerates	Ownership, port handling, and logging exist, but they are not yet full runtime enumeration paths
Hub handling	builds / good quality	usbhubd: all expect() eliminated, interrupt-driven change detection with polling fallback, graceful per-port error handling
HID	builds / QEMU-validated in narrow path	usbhidd handles keyboard/mouse/button/scroll via named producer path (usb-{port}-if{n}) with legacy fallback, no panics in report loop; keyboard LED sync exists as a bounded per-device best-effort path
Mass storage	builds / good quality	usbscsid: typed ScsiError, fallible parsing, ReadCapacity16 for >2TB, stall recovery, resilient event loop
Native tooling	builds / enumerates	lsusb, usbctl, redbear-info, redbear-usb-check provide observability
Low-level userspace API	builds	xhcid_interface with UsbSpeed enum, attach_with_speed()
Validation	builds / QEMU-only	4 harness scripts + in-guest checker; no real hardware validation scripts
Hardware quirks	builds	redox-driver-sys quirk tables with 146 compiled-in USB quirk entries (mined from Linux 7.0) + 22 USB quirk flags; runtime TOML loading for /etc/quirks.d/

Code Quality by Daemon

xHCI driver (xhcid/src/xhci/)

Upstream state — 91 unwrap(), 25 expect(), 7 panic!(), ~57 TODO/FIXME across ~6000 lines of Rust.

Red Bear state — mutex poisoning eliminated on all hot-path locks; trb_phys_ptr() returns Result; critical correctness bugs fixed; ~57 TODOs remain as design notes.

Key files and their sizes:

File	Lines (approx)	Upstream Issues	Red Bear Fix Status
scheme.rs	~2800	36 unwrap, 14 expect, 2 panic	All unwrap/expect on hot paths fixed; endp_direction, cfg_idx, CLEAR_FEATURE fixed
mod.rs	~1500	38 unwrap, 5 expect	All mutex-related unwrap fixed
irq_reactor.rs	~750	17 unwrap, 6 expect, 4 panic	All fixed; grow_event_ring fully implemented
ring.rs	~200	1 panic (trb_phys_ptr)	Returns Result instead of panicking
event.rs	~60	1 TODO	ERDP split into dequeue_ptr() + erdp(&RuntimeRegs)

Class drivers

Daemon	Lines	Error Handling Quality	Remaining unwrap/expect	Key Gaps
usbhubd	~430	Good — Result<(), Box<dyn Error>>, all expect() eliminated, interrupt-driven change detection	0	1-second polling fallback if interrupt EP unavailable
usbhidd	576	Good — anyhow::Result with context, no panics in report loop; expect() remains in arg parsing and descriptor setup (pre-existing)	7 expect() + 1 assert_eq! (pre-existing, arg parsing/descriptor setup)	Hardcoded 1ms poll rate; mouse ×2 multiplier workaround; X scroll missing
usbscsid	~1800	Good — ScsiError typed errors, fallible parse_bytes/parse_mut_bytes helpers, resilient event loop, ReadCapacity16	0	—

Validation Infrastructure

Host-side QEMU harnesses

Script	What it tests	Limitations
test-xhci-device-lifecycle-qemu.sh --check	Bounded xHCI hotplug lifecycle proof: runtime attach → configure → driver spawn → detach for HID and storage devices	QEMU-only; monitor-driven hotplug; not a broad hardware stress test
test-usb-qemu.sh --check	Full stack: xHCI interrupt mode, HID spawn, SCSI spawn, bounded sector-0 readback, BOS processing, crash errors	QEMU-only; log-grep based; no guest-side write proof
test-usb-storage-qemu.sh	USB mass storage autospawn + sector-0 readback + crash patterns	No guest-side write proof yet; no multi-LUN; no UAS
test-xhci-irq-qemu.sh --check	xHCI interrupt delivery mode (MSI/MSI-X/INTx)	No devices attached during check; single log grep

In-guest tooling

Tool	What it does	Installation
lsusb	Walks /scheme/usb.*, reads descriptors, shows vendor:product + quirks	Installed via redbear-hwutils recipe
redbear-usb-check	Scheme tree walk with pass/fail exit code	Installed via redbear-hwutils recipe
redbear-info --verbose	Reports USB controller count and integration status	Installed via redbear-info recipe

Runbook

local/docs/USB-VALIDATION-RUNBOOK.md documents two operator paths:

• Path A: Host-side QEMU validation via test-usb-qemu.sh --check
• Path B: Interactive guest validation via redbear-usb-check

What is NOT validated

• Real hardware USB controllers (QEMU qemu-xhci only)
• Hub topology (direct-attached devices only)
• USB 3 SuperSpeed data paths
• Isochronous or streaming transfers
• Hot-plug stress testing
• USB storage data I/O (read/write to block device)
• USB device mode / OTG / USB-C

Implementation Plan

Repo-fit note

Some implementation targets live in upstream-managed trees such as recipes/core/base/source/.... In Red Bear, work against those paths is carried through the appropriate patch carrier under local/patches/ until 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

Status: Substantially complete in the Red Bear patch layer. Runtime validation still QEMU-only.

Completed (Red Bear patch):

• BOS/SuperSpeed descriptor fetching wired up
• Speed detection for hub child devices with UsbSpeed enum
• Interrupt-driven operation restored (MSI/MSI-X/INTx)
• Event ring growth fully implemented (ring doubling, DMA, ERDP/ERSTBA, DCS)
• 88 error handling fixes across scheme.rs, mod.rs, irq_reactor.rs, ring.rs
• ERDP split into dequeue_ptr() + erdp(&RuntimeRegs)
• trb_phys_ptr() returns Result<u64>
• Mutex poisoning recovery on all hot-path locks

Remaining:

• Validate one controller family on real hardware (requires hardware)
• Tighten controller-state correctness under sustained load (requires hardware)
• Address remaining ~57 TODO/FIXME design notes (ongoing, not blocking)
• SuperSpeedPlus differentiation via Extended Port Status (xHCI spec extension)
• TTT (Think Time) propagation from parent hub descriptor into Slot Context
• Event ring growth: copy pending TRBs from old ring to avoid losing in-flight events under sustained load

Where: recipes/core/base/source/drivers/usb/xhcid/ (via local/patches/base/redox.patch)

Exit criteria: one target controller family repeatedly boots without xhcid panic on real hardware; controller enumerates attached devices reliably across repeated boot cycles.

---

Phase U2 — Topology, Configuration, and Hotplug Correctness

Status: Partially complete.

Completed (Red Bear patch):

• USB 3 hub endpoint configuration stall handled
• endp_direction off-by-one fixed (checked_sub(1))
• cfg_idx assigned after validation
• xHCI lifecycle gating prevents new I/O from entering while a port is detaching
• attach_device() no longer leaves a published partially-enumerated PortState on attach failure
• detach_device() now waits for in-flight lifecycle operations before removing the port state
• configure_endpoints_once() is transactional: endpoint state is staged locally, input-context mutations are snapshotted, and rollback is attempted if CONFIGURE_ENDPOINT or SET_CONFIGURATION fails
• CLEAR_FEATURE uses correct USB endpoint address from descriptor
• usbhubd status_change_buf sizing and bitmap parsing fixed
• Hub interrupt EP1 status change detection replacing polling
• usbhubd error handling improved — all ~22 expect() eliminated, Result return type, graceful per-port failure handling
• usbhubd interrupt-driven change detection — reads hub interrupt IN endpoint for status change bitmap; falls back to 1-second polling if endpoint unavailable; initial full scan preserved at startup

Remaining:

• Validate repeated attach/detach/reset behavior under stress (requires real hardware)

Completed (Red Bear patch, this session):

• configure_endpoints_once() now filters endpoints by specific interface+alternate when req.interface_desc is set, enabling composite-device drivers to claim individual interfaces without programming endpoints from other interfaces
• When interface_desc is None (initial device setup), endpoints are collected from all default-alternate (alt 0) interfaces, preserving backward compatibility
• PortState.active_ifaces: BTreeMap<u8, u8> tracks which interface numbers are active and which alternate setting each is using
• set_interface() now updates active_ifaces after a successful SET_INTERFACE control request
• spawn_drivers() logs non-default alternates at debug level instead of warning, documenting that non-default alternates are selected by drivers via SET_INTERFACE rather than auto-spawn
• Initial configuration populates active_ifaces with all default-alternate interfaces

Where: recipes/core/base/source/drivers/usb/usbhubd/, 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.

---

Phase U3 — HID Modernization

Status: Partially complete.

Completed (Red Bear patch):

• usbhidd error handling improved — anyhow::Result with context, no panics in report loop; expect()/assert_eq! remain in arg parsing and descriptor setup (pre-existing)
• Display write failures logged as warnings instead of panicking
• inputd scheme enhancement: named producers (/scheme/input/producer/{name}), per-device consumer streams (/scheme/input/{device_name}), hotplug event stream (/scheme/input/events), root directory enumeration (static entries + dynamic device names)
• Named producer events fan out to both matching DeviceConsumers and the legacy VT consumer path
• Hotplug binary format: 16-byte header (kind, device_id, name_len, reserved) + UTF-8 name
• Device IDs allocated monotonically, never reused
• Public API: NamedProducerHandle, DeviceConsumerHandle, HotplugHandle, InputDeviceLister, InputProducer (named-first, legacy-fallback convenience wrapper)
• All legacy paths, event payloads, VT behavior, and display/control behavior preserved unchanged
• ps2d migrated: two InputProducer instances (ps2-keyboard, ps2-mouse), keyboard events route to keyboard_input, mouse events to mouse_input, named-first with legacy fallback
• usbhidd migrated: one InputProducer per interface instance (usb-{port}-if{n}), named-first with legacy fallback

Remaining (requires downstream consumer/driver migration, not inputd scheme changes):

• Migrate i2c-hidd to named producers (still uses legacy ProducerHandle)
• Expose hotplug add/remove behavior to downstream consumers via evdevd migration

Where: recipes/core/base/source/drivers/input/usbhidd/, 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

Status: Storage quality improved; userspace API story still low-level.

Completed (Red Bear patch):

• usbscsid BOT transport: all panic!() replaced with stall recovery and error returns
• Correct endpoint addresses for CLEAR_FEATURE and get_max_lun
• Iterative bounded CSW read loop
• SCSI block descriptor parsing with bounds checks
• usbscsid SCSI layer: plain::from_bytes().unwrap() replaced with typed ScsiError and fallible parse_bytes/parse_mut_bytes helpers
• usbscsid main.rs: fallible run() helper, event loop continues on individual failures
• ReadCapacity16 implemented with automatic fallback when ReadCapacity10 returns max LBA (0xFFFFFFFF)
• usbscsid now issues bounded SYNCHRONIZE CACHE(10/16) commands when the runtime storage quirk set includes needs_sync_cache, using Linux sd.c sync-cache behavior as a donor reference for command selection and tolerant error handling.

Remaining (all require hardware or design decisions):

• Runtime I/O validation: prove stall recovery works under real device I/O (requires hardware)
• Decide whether BOT-only is sufficient short-term or UAS is needed (design decision)
• Bring libusb to a runtime-tested state or replace with Red Bear-native API (large scope, deferred)
• Choose the next USB class families explicitly (design decision)

Suggested class priority: storage baseline → generic userspace API → USB networking or Bluetooth dongle → audio/video only after controller maturity justifies it

Where: recipes/core/base/source/drivers/storage/usbscsid/, recipes/wip/libs/other/libusb/, local/recipes/system/redbear-hwutils/

Exit criteria: one USB storage path validated on target profile; one coherent userspace USB API story documented and works in practice; next supported class families named explicitly.

---

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

Status: Partially complete.

Completed:

• test-usb-qemu.sh — full USB stack validation harness (6 checks)
• test-usb-storage-qemu.sh — USB mass storage autospawn check
• test-xhci-irq-qemu.sh — xHCI interrupt delivery mode check
• test-xhci-device-lifecycle-qemu.sh — bounded xHCI attach/configure/detach hotplug proof
• USB-VALIDATION-RUNBOOK.md — operator documentation with Paths A and B
• redbear-usb-check — in-guest scheme-tree checker (now installed in image)
• lsusb — full USB scheme walk with descriptor parsing and quirks integration
• redbear-info — passive USB controller reporting

Remaining (all require hardware):

• Add hardware-matrix coverage for target controllers and class families
• Add USB storage data I/O validation (read/write to block device)
• Add repeated hardware hot-plug stress testing beyond the bounded QEMU lifecycle slice

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 with improved error handling, but is not yet a broad hardware support claim"
• "USB error handling and correctness carry significant Red Bear patches over upstream; see local/patches/base/redox.patch for details"

Linux Kernel USB Data Mining

linux-kpi Scope Clarification

The linux-kpi compatibility layer (local/recipes/drivers/linux-kpi/) is used exclusively for GPU and Wi-Fi drivers — it provides Linux kernel API headers and Rust FFI implementations for porting Linux C drivers in those domains to Redox. It does not cover USB and contains no USB headers, USB device ID tables, or USB driver implementations.

The linux-kpi header inventory (src/c_headers/) covers: PCI, DMA, IRQ, firmware, networking (netdevice, skbuff, ieee80211, nl80211, cfg80211, mac80211), DRM, workqueue, timer, wait, sync, memory, and related kernel infrastructure — but zero USB content. This is documented globally in AGENTS.md and local/AGENTS.md.

Linux 7.0 Source Availability

Linux kernel 7.0 (stable, released 2026-04-13) is extracted at build/linux-kernel-cache/linux-7.0/ for USB data mining purposes. This is a build cache, not a tracked source tree — it can be re-fetched from cdn.kernel.org at any time.

# Re-fetch if needed:
curl -L -o build/linux-kernel-cache/linux-7.0.tar.xz \
  "https://cdn.kernel.org/pub/linux/kernel/v7.x/linux-7.0.tar.xz"
tar xf build/linux-kernel-cache/linux-7.0.tar.xz -C build/linux-kernel-cache/

Mining Inventory — What Linux 7.0 Contains

Data Source	Linux Path	Entries	Lines	Relevance
USB device quirks	drivers/usb/core/quirks.c	64 device + 5 AMD-resume + 4 endpoint-ignore	800	Directly feed our quirk tables
USB quirk flag definitions	include/linux/usb/quirks.h	19 flags	84	We have 9 of 19; 10 missing
USB storage unusual devices	drivers/usb/storage/unusual_devs.h	323 entries	2513	Mass storage device workarounds
USB hub driver	drivers/usb/core/hub.c	—	6567	TT handling, hub descriptor parsing
xHCI host driver	drivers/usb/host/xhci*.c/h	~15 files	~30000	Controller quirks, TRB handling
SCSI disk driver	drivers/scsi/sd.c	—	4467	SCSI command support tables
USB core headers	include/linux/usb/*.h	75 headers	—	ch9.h (descriptors), hcd.h, storage.h, uas.h

Extraction Tool

local/scripts/extract-linux-quirks.py parses Linux kernel source and generates Red Bear TOML quirk entries. Handles three source formats:

• drivers/usb/core/quirks.c → [[usb_quirk]] TOML entries (146 entries from Linux 7.0)
• drivers/usb/storage/unusual_devs.h → [[usb_storage_quirk]] TOML entries (214 entries from Linux 7.0)
• drivers/pci/quirks.c → [[pci_quirk]] TOML entries (explicit high-confidence handler-body mappings only, requires review)

USB quirk extraction is direct and does not require review. PCI quirk extraction now emits only explicit high-confidence handler-body mappings and still requires manual review before committing.

The extraction script needs extension to also handle drivers/usb/storage/unusual_devs.h for mass storage device entries (323 entries, different macro format UNUSUAL_DEV).

Flag Gap Analysis

Flags we have (22, fully aligned with Linux 7.0): NO_STRING_FETCH, RESET_DELAY, NO_USB3, NO_SET_CONFIG, NO_SUSPEND, NEED_RESET, BAD_DESCRIPTOR, NO_LPM, NO_U1U2, NO_SET_INTF, CONFIG_INTF_STRINGS, NO_RESET, HONOR_BNUMINTERFACES, DEVICE_QUALIFIER, IGNORE_REMOTE_WAKEUP, DELAY_CTRL_MSG, HUB_SLOW_RESET, NO_BOS, SHORT_SET_ADDR_TIMEOUT, FORCE_ONE_CONFIG, ENDPOINT_IGNORE, LINEAR_FRAME_BINTERVAL

All 19 Linux 7.0 USB_QUIRK flags are now covered. The mapping table below documents the correspondence for future reference.

Linux Flag	Purpose	Impact	Mapping Notes
USB_QUIRK_RESET_RESUME	Device can't resume, needs reset instead	High — many devices	Roughly maps to our NEED_RESET
USB_QUIRK_NO_SET_INTF	Device can't handle SetInterface requests	Medium — composite devices	Our NO_SET_CONFIG targets SET_CONFIGURATION, not SET_INTERFACE
USB_QUIRK_CONFIG_INTF_STRINGS	Device can't handle config/interface strings	Low — enumeration robustness	New concept
USB_QUIRK_RESET	Device can't be reset at all	Medium — prevents crashes on morph devices	No equivalent
USB_QUIRK_HONOR_BNUMINTERFACES	Wrong interface count in descriptor	Medium — composite devices	New concept
USB_QUIRK_DEVICE_QUALIFIER	Device can't handle device_qualifier descriptor	Low — skip descriptor fetch	New concept
USB_QUIRK_IGNORE_REMOTE_WAKEUP	Device generates spurious wakeup	Low — power management	New concept
USB_QUIRK_DELAY_CTRL_MSG	Device needs pause after every control message	Medium — prevents timeouts	New concept
USB_QUIRK_HUB_SLOW_RESET	Hub needs extra delay after port reset	High — our Terminus hub entry (0x1A40:0x0101) currently has no_lpm but Linux marks it HUB_SLOW_RESET	New concept
USB_QUIRK_NO_BOS	Skip BOS descriptor (hangs at SuperSpeedPlus)	High — we added BOS fetching, some devices hang	New concept
USB_QUIRK_SHORT_SET_ADDRESS_REQ_TIMEOUT	Short timeout for SET_ADDRESS	Low — controller-specific	New concept
USB_QUIRK_FORCE_ONE_CONFIG	Device claims zero configs, force to 1	Low — edge case	New concept
USB_QUIRK_ENDPOINT_IGNORE	Device has endpoints that should be ignored	Medium — audio devices	New concept
USB_QUIRK_LINEAR_FRAME_INTR_BINTERVAL	bInterval is linear frames, not exponential	Low — interrupt endpoint timing	Related to our BAD_DESCRIPTOR

Note: Some Linux flags overlap semantically with our existing flags. The exact mapping requires a per-flag design decision — either extend existing flags with clarified semantics or add new parallel flags.

Duplicate Quirk Table Problem

xhcid carries its own copy of the USB quirk table at recipes/core/base/source/drivers/usb/xhcid/src/usb_quirks.rs. The canonical table is in local/recipes/drivers/redox-driver-sys/source/src/quirks/usb_table.rs.

Both tables now carry the expanded 22-flag set and synchronized entries. The xhcid copy contains a representative subset of the most common entries (early-boot fallback when /etc/quirks.d/ is not yet mounted), while the full 146-entry table and TOML runtime loading serve as the complete runtime source.

Long-term resolution: xhcid should import from redox-driver-sys directly rather than maintaining a duplicate. Until then, both must be kept in sync when adding new entries.

Prioritized Mining Targets

Tier 1 — COMPLETED:

1. ✅ USB device quirk table expansion — All 146 entries from Linux 7.0 quirks.c extracted into usb_table.rs and 20-usb.toml. Covers HP, Microsoft, Logitech, Lenovo, SanDisk, Corsair, Realtek, NVIDIA, ASUS, Dell, Elan, Genesys, Razer, and others.

2. ✅ USB_QUIRK_NO_BOS flag — Added. 4 devices that hang at SuperSpeedPlus BOS fetch are now flagged: ASUS TUF 4K PRO (0x0B05:0x1AB9), Avermedia GC553G2 (0x07CA:0x2553), Elgato 4K X (0x0FD9:0x009B), UGREEN 35871 (0x2B89:0x5871), ezcap401 (0x32ED:0x0401).

3. ✅ USB_QUIRK_HUB_SLOW_RESET flag — Added. Terminus hub (0x1A40:0x0101) corrected from no_lpm to hub_slow_reset.

4. ✅ Flag gap closed — All 19 Linux 7.0 USB_QUIRK flags now mapped. 13 new flags added: NO_SET_INTF, CONFIG_INTF_STRINGS, NO_RESET, HONOR_BNUMINTERFACES, DEVICE_QUALIFIER, IGNORE_REMOTE_WAKEUP, DELAY_CTRL_MSG, HUB_SLOW_RESET, NO_BOS, SHORT_SET_ADDR_TIMEOUT, FORCE_ONE_CONFIG, ENDPOINT_IGNORE, LINEAR_FRAME_BINTERVAL.

5. ✅ Duplicate quirk tables synchronized — Both usb_table.rs (redox-driver-sys) and usb_quirks.rs (xhcid) now carry the expanded flag set and synchronized entries.

6. ✅ USB storage unusual_devs.h — 214 entries extracted from Linux 7.0 into local/recipes/system/redbear-quirks/source/quirks.d/30-storage.toml (1716 lines). Extraction script extended to handle UNUSUAL_DEV macro format. Most common flags: ignore_residue (46), fix_capacity (34), single_lun (28), max_sectors_64 (22), fix_inquiry (22). Includes initial_read10 entries for Feiya SD/SDHC reader and Corsair Padlock v2.

7. ✅ usbscsid storage quirk integration — Storage quirks are now active at runtime. usbscsid/src/quirks.rs reads [[usb_storage_quirk]] entries from /etc/quirks.d/*.toml and applies them to the BOT transport and SCSI command layers. Active behavioral flags:

   • IGNORE_RESIDUE: suppresses CSW residue in BOT send_command
   • FIX_CAPACITY: adjusts block count from READ CAPACITY(10) by -1
   • SINGLE_LUN: enforces LUN=0 in CBW (future-proof for multi-LUN support)
   • MAX_SECTORS_64: clamps transfer length to 64 sectors in SCSI read/write
   • INITIAL_READ10: uses READ(10)/WRITE(10) instead of READ(16)/WRITE(16) Vendor/product IDs are extracted from DevDesc at daemon startup. A compiled-in fallback table covers 5 common devices for early-boot correctness.

8. ✅ xhcid USB device quirk consumption — xhcid now stores per-device UsbQuirkFlags in PortState and applies them during enumeration and runtime requests. Active behavioral flags:

   • NO_STRING_FETCH: skips manufacturer/product/serial/configuration string fetches
   • BAD_DESCRIPTOR: tolerates language/string descriptor fetch failures and continues interface parsing when malformed endpoint descriptors appear
   • RESET_DELAY: extends first-touch post-reset settle time via early PortId-based lookup
   • HUB_SLOW_RESET: uses a longer hub-oriented reset settle time via early PortId-based lookup
   • NO_BOS: skips BOS descriptor fetch and leaves superspeed capability detection false
   • SHORT_SET_ADDR_TIMEOUT: uses a shorter Address Device command timeout via early PortId-based lookup
   • FORCE_ONE_CONFIG: limits enumeration to configuration index 0 (configuration value 1 path)
   • HONOR_BNUMINTERFACES: stops interface parsing at bNumInterfaces
   • DELAY_CTRL_MSG: inserts a short post-control-transfer delay
   • NO_SET_CONFIG: skips SET_CONFIGURATION
   • NO_SET_INTF: skips SET_INTERFACE
   • NEED_RESET: issues xHC Reset Device automatically after transfer failures The early-enumeration timing path now uses optional TOML port = "<root>[.<route>...]" selectors in [[usb_quirk]] entries for quirks that must act before vendor/product are known.

9. ✅ xhcid suspend/resume API skeleton — xhcid now exposes explicit port<n>/suspend and port<n>/resume endpoints plus matching XhciClientHandle::{suspend_device,resume_device} helpers. PortState now tracks PortPmState::{Active,Suspended} and xhcid enforces NO_SUSPEND by rejecting suspend with EOPNOTSUPP. While suspended, control/data/reset activity returns EBUSY.

10. ✅ usbhubd suspend coordination slice — usbhubd now tracks downstream child suspend state and mirrors USB 2 hub-port suspend status into child xhcid devices via suspend_device() / resume_device(). This gives us the first real cross-layer coordination path for hub-attached devices without inventing a separate PM daemon. Remaining gap: suspend policy/origination is still external, and USB 3 link-state-driven coordination is not yet implemented.

Tier 2 — Medium-term (improves robustness):

5. TT handling from hub.c — Linux's hub driver reads wHubDelay and bNbrPorts from hub descriptors to populate TT think time and MTT capability. Our xHCI driver hardcodes ttt = 0 and mtt = false. Mining the hub descriptor parsing logic from hub.c would replace these stubs with correct values.

6. xHCI controller quirks from xhci-pci.c — Linux has per-vendor controller workarounds (Intel PCH, AMD, Etron, Fresco, VIA). Our driver has no controller-specific paths. Mining the quirk table and applying it through our existing PCI quirk system would add real-hardware robustness.

7. SCSI command selection from sd.c — READ(10)/WRITE(10) support is now implemented (triggered by INITIAL_READ10 quirk flag). Remaining: REPORT LUNS for multi-LUN devices, SYNCHRONIZE CACHE (triggered by NEEDS_SYNC_CACHE flag), and START STOP UNIT for power management.

Tier 3 — Future (enables new device classes):

8. USB class/subclass/protocol tables from ch9.h — Complete class code definitions for device matching in drivers.toml.

9. USB endpoint descriptor parsing from message.c — Extended endpoint type mapping for streams and isochronous support.

Mining into the Build

The Linux kernel source at build/linux-kernel-cache/ is a build cache, not a tracked dependency. Mined data must be materialized into durable locations:

Mined Data	Target Location	Format
USB device quirks	local/recipes/system/redbear-quirks/source/quirks.d/20-usb.toml	TOML (146 entries ✅)
USB compiled-in quirks	local/recipes/drivers/redox-driver-sys/source/src/quirks/usb_table.rs	Rust (146 entries ✅)
PCI controller quirks	local/recipes/system/redbear-quirks/source/quirks.d/10-pci.toml	TOML
Storage device flags	local/recipes/system/redbear-quirks/source/quirks.d/30-storage.toml	TOML (214 entries ✅, active at runtime ✅)
Flag definitions	local/recipes/drivers/redox-driver-sys/source/src/quirks/mod.rs	Rust bitflags (22 USB flags ✅)

The extraction script at local/scripts/extract-linux-quirks.py should be extended to also handle drivers/usb/storage/unusual_devs.h for mass storage device entries.

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.

The Red Bear patch layer carries substantial error handling and correctness improvements over the upstream source: 88 error handling fixes (mutex poisoning recovery, expect/panic replacement, Result conversions), multiple correctness bug fixes, real event ring growth, class driver error handling improvements (all three USB class daemons now use Result types with zero unwrap()/expect() panics), interrupt-driven hub change detection, ReadCapacity16 for large disk support, and a USB quirk table expanded from 8 to 146 entries with 22 quirk flags mined from Linux 7.0.

Recent bounded maturity progress:

• xhcid now tracks active alternate settings per interface in PortState and resolves endpoint descriptors through that active-alternate map instead of flattening all interface descriptors indiscriminately.
• Direct unit coverage now exists for both default-alternate endpoint selection and alternate-setting-aware endpoint remapping.
• xhcid now also preserves previously selected alternates on the same configuration and applies a requested interface/alternate override before endpoint planning, so alternate-setting reconfiguration no longer silently falls back to all-zero defaults.
• xhcid endpoint-direction lookup now also follows the active interface/alternate selection state instead of reading from the first configuration/interface pair unconditionally.
• xhcid driver spawning now also follows the selected configuration and active alternate map instead of hardcoding the first configuration and ignoring non-zero alternates.
• xhcid now keeps per-port lifecycle state so detach blocks new transfer/configure/suspend/resume work, waits for in-flight operations to drain, and removes the published port state only after slot disable succeeds.
• xhcid endpoint configuration is now transactional: software endpoint bookkeeping stays staged until CONFIGURE_ENDPOINT and optional SET_CONFIGURATION succeed, and the input context is restored with an explicit rollback attempt on failure.
• the xHCI IRQ reactor now replaces the old TODO: grow event ring stub with a preserve-and-grow path that copies unread event TRBs into a larger event ring and reprograms ERST registers instead of dropping pending events during EventRingFull recovery.
• usbhubd now derives USB 2 hub TT Think Time from the hub descriptor using the same bounded Linux-compatible encoding and passes it through ConfigureEndpointsReq, and xhcid now writes that value into the Slot Context TT information bits for hub devices.
• xHCI endpoint-context calculations are now protocol-speed-aware for SuperSpeedPlus, so interval and ESIT-payload selection use the resolved port protocol speed instead of relying only on endpoint companion presence.

All validation is QEMU-only. No real hardware USB testing exists.

The remaining gaps now fall into two categories:

Broader architectural work (cross-cutting, not a small bounded USB-only fix):

• Any remaining USB composite/device-model issues now belong to wider device-model/design cleanup rather than one more isolated helper patch.
• HID producer modernization: per-device streams via named producers, hotplug add/remove (inputd redesign complete, ps2d and usbhidd migrated)
• Userspace USB API: libusb WIP, no coherent native story

Hardware-dependent or design decisions:

• Real hardware validation: no controller tested outside QEMU
• Hot-plug stress testing beyond the new bounded QEMU lifecycle harness
• Storage write validation (bounded sector-0 readback proof now exists in QEMU via test-usb-storage-qemu.sh, but guest-side write verification to the USB-backed block device is still open)
• usbhubd 1-second polling fallback (only exercisable with real hub hardware)
• Modern USB scope decision: device mode / USB-C / PD

Software items are tracked in Phase U1 (xHCI internals) and Phase U2 (configuration/composite). Architectural and hardware items are tracked in Phase U1 (controller hardware validation), Phase U2 (hub polling fallback), Phase U3 (HID), Phase U4 (storage/API), Phase U5 (modern USB scope decision), and Phase U6 (validation).

Linux kernel USB data mining is documented in the "Linux Kernel USB Data Mining" section above. Linux 7.0 source is available at build/linux-kernel-cache/linux-7.0/ with 146 USB device quirks, 22 quirk flags (all 19 Linux USB_QUIRK flags covered), 214 active storage device quirks consumed at runtime by usbscsid, and extensive xHCI/hub/SCSI reference code ready for extraction.