danos/docs/usb-hub.md

USB hubs (M22)

A hub is USB bus infrastructure, not an application peripheral, so hub topology is handled inside the usb-xhci-bus driver — the process that owns the controller's device slots and contexts. A device behind a hub is not reached by any hub-specific software path: it is reached by the controller, programmed with a route string in its slot context. Route strings and slot contexts are xHCI hardware concepts that only exist inside the controller driver, so that is where hub handling belongs. Class drivers (HID, storage) stay separate and unaware — the hub is transparent to them; a keyboard behind a hub reaches the same usb-hid-keyboard driver as one on a root port.

This is a deliberate scoping choice, not a microkernel compromise: the USB bus driver handles USB bus topology. The alternative — a separate usb-hub class-driver process plus a cross-process enumeration protocol — would only shuttle the bus's own topology state (slot ids, route strings, TT linkage) out to another process and back, since the hub driver cannot build a slot context itself.

The compound-hub reality

A USB 3.0 hub is physically two hubs sharing each connector: a SuperSpeed hub and a USB 2.0 companion hub, enumerated as separate devices on separate root ports. A full- or low-speed device plugged into a USB 3.0 hub attaches to the USB 2.0 companion, not the SuperSpeed hub. So supporting full-speed devices (keyboards, mice) behind a hub means driving the USB 2.0 companion and handling transaction translators — there is no SuperSpeed-only shortcut that reaches a full-speed keyboard.

Slot-context fields for a downstream device

buildAddressInputContext fills the Slot Context. Today it hardcodes route 0 and the root-hub port. A downstream device additionally needs:

• Route String (Slot Context dword 0, bits 19:0) — 5 tiers × 4 bits, each tier the downstream hub-port number. Composed as route = (parent_route << 4) | hub_port, capped at the xHCI 5-tier max.
• Root Hub Port Number (dword 1, bits 23:16) — the root port the whole hub chain hangs off, inherited from the parent hub (not the hub's own port number).
• Speed (dword 0, bits 23:20) — read from the hub's downstream port status after reset, not assumed.
• Parent Hub Slot ID (dword 2, bits 7:0) + Parent Port Number (dword 2, bits 13:8) — the transaction translator: set when a full/low-speed device sits behind a high-speed hub, so the controller routes split transactions through that hub's TT. For a multi-TT hub, MTT (Slot Context dword 0 bit 25) is set and the TT port is the device's own hub port.

Detection: the status-change interrupt endpoint

A hub has one interrupt IN endpoint that returns a port-status-change bitmap (bit N set = port N changed). The bus arms an interrupt transfer on it (reusing the controller's existing interrupt-endpoint machinery, but serviced in-process — no class-driver subscription IPC), and on each report:

1. For each changed port, GET_STATUS (hub class request) reads the port's connect/enable/reset state and speed, and CLEAR_FEATURE(C_PORT_*) acknowledges the change.
2. On a connect: SET_FEATURE(PORT_RESET), wait for reset-complete via a later status-change report, read the enabled speed, then setupDevice with the composed route string / root port / TT fields, enumerate, and register the interfaces — exactly the existing path, recursing if the new device is itself a hub.
3. On a disconnect: tear down the downstream device (report each interface ChildRemoved, Disable Slot) — the B3 teardown path, keyed by the device's route rather than a root port.

Hub setup (once, when the hub enumerates)

When the bus scan (or a hot-plug bring-up) finds a device of class 9:

1. Read the hub descriptor (class GET_DESCRIPTOR, type 0x2A for a USB 3.0 hub / 0x29 for USB 2.0) → downstream port count, characteristics.
2. For a USB 3.0 hub, SET_FEATURE(BH_PORT_RESET) semantics and the depth (SET_HUB_DEPTH) so the hub knows its tier for route-string forwarding.
3. SET_FEATURE(PORT_POWER) each downstream port.
4. Configure the hub's slot as a hub: Hub bit (Slot Context dword 0 bit 26), Number of Ports (dword 1, bits 31:24), TT Think Time and MTT for a USB 2.0 multi-TT hub — via an Evaluate/Configure Endpoint on the hub's slot.
5. Arm the status-change interrupt endpoint.

Testing

QEMU's usb-hub is a USB 2.0 single-TT hub. A static boot topology (-device usb-hub,bus=xhci.0,id=h -device usb-kbd,bus=h.0) presents the downstream device connected from the start, so the bus reads it on the first status-change report — exercising the full path (hub setup, TT slot context, downstream enumerate, class-driver bind) without needing a hot-plug event. A new usb-hub QEMU case asserts the hub enumerates, the downstream keyboard enumerates behind it, and usb-hid-keyboard binds.

Real-hardware validation (the user's SuperSpeed Genesys hub + full-speed keyboard/mouse on its USB 2.0 companion) is flagged separately — the compound USB 3.0 hub path is not modelled by QEMU's USB 2.0 hub.

Milestones (all complete)

• B4a ✓ — hub recognition + setup: detect class 9 in the scan, read the hub descriptor, configure the slot as a hub, power downstream ports, log the topology.
• B4b ✓ — downstream enumeration: the in-process status-change subscription, port reset, Address Device with route string + root port + TT fields, enumerate + register. A full-speed keyboard behind a USB2 hub binds usb-hid-keyboard in QEMU.
• B4c ✓ — disconnect teardown (recursive: a hub takes its subtree with it) and hub-behind-hub recursion (route strings compose across tiers). QEMU's hub does raise downstream status changes, so both connect and disconnect are harness-tested (usb-hub, usb-hub-nested, usb-hub-unplug).

Real-hardware validation of the user's SuperSpeed Genesys hub with full-speed devices on its USB 2.0 companion remains pending — QEMU's USB 2.0 hub does not model the compound USB 3.0 hub.