1 files changed, 90 insertions, 0 deletions

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