From 363e24bcd18a28948f63fa78ac8a4eaa8784fe59 Mon Sep 17 00:00:00 2001 From: salmonik Date: Sun, 1 Nov 2026 16:33:09 +0100 Subject: scripts: add test-usb; fix duplicate -bios in the test harness - test-usb boots an EHCI and an xHCI controller with a mouse + keyboard and asserts enumeration, report decoding, and input reaching the shell. The EHCI case asserts one key end-to-end (QEMU's EHCI model delivers only the first report through root-port split transactions); the xHCI case asserts a whole typed command. - lib.sh: qemu_args() already supplies -bios, so the fresh OVMF varstore copy was silently overridden by the system firmware. Pass the copy last (QEMU honours the last -bios) so tests really boot clean NVRAM. - DEBUG_NOTES: document why USB never worked on the OptiPlex (EHCI shipped with DEBUG_MATRIX enabled, no RMH/hub support, only the first controller, no boot protocol, unbounded DMA), the success/failure log to look for on hardware, and the QEMU coverage limits. - Makefile: add test-usb and include it in `make test`. --- DEBUG_NOTES.md | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) (limited to 'DEBUG_NOTES.md') diff --git a/DEBUG_NOTES.md b/DEBUG_NOTES.md index 5730ca5..b7c0e08 100644 --- a/DEBUG_NOTES.md +++ b/DEBUG_NOTES.md @@ -541,3 +541,93 @@ ehci: HID boot mouse armed (device 1) ``` Periodic schedule: 2200+ EXECUTEs/frame with 0 qtd halts; idle mouse NAKs. + +--- + +## 🔌 USB real-hardware status (OptiPlex 7010 / Q77) — v0.6.x rework + +### Why USB "straight out did not work" + +1. **EHCI was disabled in the shipped build.** `ehci.rs` had + `static DEBUG_MATRIX: bool = true` (since `be868a4`): every boot ran the + one-shot transfer-variant bisection matrix and then `return false` before + enumerating. No committed build had ever brought an EHCI device up. +2. **No hub support.** On 7-series PCH the EHCI root port presents the + **integrated Rate Matching Hub** (8087:0024, device class 9); FS/LS mice + and keyboards sit *behind* it. The driver read the RMH's descriptors, + found no HID endpoint and gave up. Split transactions were hardcoded to + hub address 0 + root port (the QEMU topology). +3. **Only the first EHCI was initialized** (`find_ehci()` returned the first + match). The 7010 has two: `00:1a.0` and `00:1d.0`. +4. **No `SET_PROTOCOL(boot)`** on EHCI/xHCI; UHCI asked for report protocol + (`wValue=1`). Report protocol layouts are device-defined. +5. **EHCI DMA had no <4 GiB bound** (32-bit DMA pointers), while the page + bitmap spans all RAM. A buffer above 4 GiB silently breaks transfers. +6. **xHCI**: no scratchpad buffers (HCSPARAMS2), `MaxSlotsEn=1`, and DMA + from the heap allocator rather than physical pages. + +### What the drivers do now + +- `ehci.rs`: both controllers; hub class requests (power / reset / status); + TT splits with the hub address + child port; HID mouse **and** keyboard; + boot protocol; per-device periodic QH (chained into the frame list); + DMA from `alloc_pages_range(16 MiB, 4 GiB)`; 2 ms recovery after + `SET_ADDRESS`. +- `usb.rs` (xHCI): scratchpad buffers, `MaxSlotsEn = min(MaxSlots, 4)`, + per-slot EP0 + interrupt rings, page-allocator DMA, boot protocol, + mouse + keyboard. +- `hid.rs`: shared HID boot-keyboard decoding (one scancode FIFO feeding + `ps2::feed_scancode`), used by UHCI, EHCI and xHCI. +- First-report lines are logged (`ehci: mouse report …`, `usb: kbd report …`) + and the `usb` shell command lists controller(s) and device(s) with + armed/fails/reports counters. + +### OptiPlex 7010 — expected serial log (success path) + +``` +ehci: 00:1a.0 mmio=… ports=… 64-bit-caps=… +ehci: USB legacy handed over by BIOS +ehci: controller up (… ports) +ehci: port N connected (high-speed) +ehci: dev 8087:0024 class=0x9 … addr=1 ← rate matching hub +ehci: hub addr=1 ports=8 +ehci: hub port K: full-speed device (split) +ehci: dev …:… class=0x0 … addr=2 sp=0 (split) +ehci: HID mouse armed (addr 2 ep0x81 mps … ) +ehci: periodic schedule enabled (1 device(s) on ctrl 0) +ehci: mouse report dx=… dy=… b=0x… +``` + +Then the same on `00:1d.0` for the keyboard, and `> ` followed by typed keys. +Failure signatures to report: + +- `ehci: no EHCI controller` — PCI probe/class mismatch (should not happen). +- `ehci: USB legacy claim timed out` — BIOS still owns the controller. +- `ehci: hub descriptor failed` / `hub port K reset timeout` — hub class + request stage; note the code. +- `ehci: get-dev-desc failed (addr 0 sp 0 tt Some(…))` — split transaction + did not reach the child; note the TT tuple. +- `ehci: no HID mouse/keyboard endpoint in config` — descriptor walk. +- `ehci: xfer fail stage=…` — transfer engine; the QR band has the state. + +### QEMU coverage (make test-usb) + +- EHCI root-port FS mouse/keyboard (split path), two devices chained. +- xHCI mouse/keyboard on two slots. +- Keyboard report → scancode → WM → shell echo is asserted in both cases. +- **Not coverable in QEMU**: an EHCI high-speed hub (`usb-hub` is FS-only and + refuses a HS EHCI root port), so the RMH code path is hardware-only. +- **QEMU EHCI split limit**: for full/low-speed devices behind root-port + split transactions QEMU delivers only the *first* report (125 NAKs after + it, even though the qTD is re-armed). The re-arm shape is the standard one + (`qh->next_qtd = qtd`, qTD re-activated; the HC owns the status/toggle + overlay), so `test-usb` asserts one key end-to-end on EHCI and a full + command on xHCI. + +### Known gaps + +- EHCI: hub support is one level deep; no hotplug once a device of that kind + is armed; no isochronous/other transfer types. +- xHCI: no hub support; no USB3 warm-reset subtleties beyond the current + port-reset sequence. +- AHCI/PS2 behaviour unchanged (PS/2 remains the fallback input path). -- cgit v1.2.3