---
name: schunix-usb-xhci
description: "xHCI enumerates USB2 and USB3 devices and does control transfers; written from the spec because porting BSD's stack means porting newbus first"
metadata: 
  node_type: memory
  type: project
  originSessionId: a665e14b-86bd-4b41-a228-51377f3e9225
  modified: 2026-08-04T23:06:09.296Z
---

**`kernel/drivers/xhci.c`, 2026-08-04.** Working: controller reset, DCBAA,
command ring, event ring + ERST, scratchpad buffers, port reset, Enable Slot,
Address Device, and control transfers. Three QEMU devices (usb-kbd, usb-mouse,
usb-storage) enumerate and answer `GET_DESCRIPTOR`.

**Written from the xHCI 1.2 spec, not ported from BSD** — and that was the
right call, not laziness. FreeBSD's `sys/dev/usb` is ~100k lines welded to
newbus, devclass, `bus_dma`, callouts and taskqueues; porting it means porting
FreeBSD's device framework first. BSD is worth far more as the reference you
check yourself against. (Licensing agrees: BSD is Apache-compatible, Linux is
not — [[schunix-licensing]].)

**Things that would cost hours to rediscover:**

- **Enumeration polls the event ring on purpose.** `pci_bind_all()` runs from
  `kmain()` with interrupts off and no scheduler; a probe that waited for an
  interrupt would wait forever.
- **Context size is 32 *or* 64 bytes**, per `HCCPARAMS1.CSZ`. Hardcoding 32 on
  a 64-byte controller puts every field at half the right offset and commands
  are rejected with no explanation.
- **PORTSC's change bits and PED are write-1-to-clear.** Writing back a value
  you just read clears whatever happened. Mask `PORT_RW1C` off every write.
- **USB3 ports arrive already enabled; USB2 ports need `PORT_PR` first.**
  Check PED rather than trying to work out which is which.
- **Full-speed devices' EP0 max packet size is unknowable until you ask.**
  Start at 8, read 8 bytes of the device descriptor, then Evaluate Context.
- The link TRB's Toggle Cycle bit is what makes a fixed ring endless; set the
  cycle bit *last* when pushing a TRB.
- A No-Op command before enumerating proves the ring and event path, so a
  failure points at our plumbing rather than at a device.

**The USB core and HID landed 2026-08-05.** `kernel/drivers/usb.c` reads the
configuration, selects it, and offers the device to a class-driver table in
`registry.c` (same one-table-you-can-read arrangement as the PCI drivers);
`kernel/drivers/usb_hid.c` does boot-protocol keyboard and mouse. A command
typed on an emulated USB keyboard runs in the shell.

- **Boot protocol, not report descriptors.** A device claiming the boot
  subclass promises a fixed 8-byte keyboard / 3-byte mouse layout, so no
  report-descriptor parser is needed. It still starts in *report* protocol --
  `SET_PROTOCOL(0)` is required or the reports arrive in an unknown shape.
- `SET_IDLE 0` too, or a keyboard resends its state every few ms forever.
- The keyboard report is a *state*, not an event: a held key appears in every
  report. Emit only usages absent from the previous report.
- Characters go into a small queue that `consoleintr()` then drains through
  its getc argument -- that reuses the whole line discipline instead of
  reimplementing it. `mouse_inject()` in mouse.c is the same idea for the
  pointer; HID's Y axis points down and PS/2's points up.
- A configuration descriptor is a *chain* of descriptors of varying types.
  Walk it by each one's length byte; class-specific ones you have never heard
  of sit in the middle and must be skipped, not tripped over.

**The interrupt bug that cost the most time is in
[[schunix-driver-infrastructure]]** -- transfers completed perfectly, events
sat in the ring, and the IRQ count stayed at zero.

**Mass storage landed 2026-08-05** (`kernel/drivers/usb_storage.c`): bulk
endpoints, bulk-only transport, SCSI INQUIRY / READ CAPACITY / READ(10) /
WRITE(10), and a block device at `USBDISK_DEV` (3) routed from `bdevrw()` in
bio.c. A real superblock reads back through `bread()`.

- **A bulk transfer at probe time must not sleep.** This wedged the machine
  mid-enumeration with no message at all. `pci_bind_all()` runs from
  `kmain()` with interrupts off and *before* `pinit()` — so `sleep()` has no
  scheduler to switch to and `wakeup()` would take an uninitialised ptable
  lock. `struct xhci` has a `can_sleep` flag, set once probing is over; until
  then bulk transfers poll the event ring, exactly as enumeration does.
- Bulk-only transport is strictly three phases: 31-byte CBW out, data,
  13-byte CSW in. **The CSW is not optional** — skipping it leaves the
  endpoint out of phase and every later command fails.
- SCSI is big-endian everywhere, and READ CAPACITY returns the address of the
  *last* sector, not a count.
- No GET MAX LUN: single-LUN devices answer it with a STALL, and recovering
  from an EP0 stall needs a Reset Endpoint command that is not written yet.
- `b->data` lives in the buffer cache, not DMA memory, so everything bounces
  through one `dma_alloc`'d block.

**Bugs found in a deliberate audit pass (2026-08-05), all fixed:**

- **Context Entries must be the highest DCI in use, not the one being added.**
  Writing the new endpoint's own DCI works only while endpoints are opened in
  increasing order; open a higher DCI then a lower one and the field shrinks,
  silently invalidating the endpoint that already worked. `xhci_open_ep`
  tracks `slot[].max_dci` now, and `usb_storage.c` deliberately opens bulk
  OUT before bulk IN — the formerly-broken order — so the fix stays tested.
- **The event ring had two unlocked consumers**: `xhci_irq` and the sysrq
  dump. Both take `x->lock` now; `transfer_done` runs with it held.
- **A failed block read left B_VALID clear and returned the stale buffer**,
  which `bread()` hands straight to its caller as though it were disk
  content. Three retries, then panic.
- **`bot_command` skipped the CSW when the data phase failed**, leaving the
  device holding a status nobody asked for — so the *next* command's data
  phase would receive this one's status, turning one failed read into every
  later read failing. The CSW is now always read.
- **The shared descriptor scratch buffer was not cleared between devices**, so
  a short reply left the previous device's descriptor visible past the end of
  its own and the parser walked into it.
- Max ESIT Payload was being set for bulk endpoints; it is periodic-only.
- `irq_unregister` compacted a chain a dispatcher could be walking, and the
  comment above the lock claimed nothing was ever removed. It masks the line
  for the rewrite now.

**Two debug commands:** `echo u > /proc/sysrq` dumps controller state and
drains the event ring by hand — that is what separates "no event" from
"event, no interrupt". `echo s > /proc/sysrq` reads block 1 off the USB disk
through the buffer cache.

**Still not done:** hubs. See `docs/plan/roadmap.md` phase 1.