1 files changed, 55 insertions, 0 deletions

diff --git a/DEBUG_NOTES.md b/DEBUG_NOTES.md
index a1f2d75..19fe5cf 100644
--- a/DEBUG_NOTES.md
+++ b/DEBUG_NOTES.md
@@ -281,3 +281,58 @@ with the `klog` shell command.
 (QEMU control arm is green with and without a forced EBS failure:
 `verify: ok`, probe NOT free, shadow base NOT in free list, full shell
 sequence clean.  `0x00AAAAAA` = gray text colour; shadow far rows stay 0.)
+
+---
+
+## ✅ v0.5.10 — USB HID mouse driver (polled xHCI, `rsnix/src/usb.rs`)
+
+Handoff: HEAD = `v0.5.10` (workspace Cargo.toml + boot banner). Adds a
+polled xHCI controller driver (mouse-only) announced via `usb: xHCI at
+<bus.dev.fn>` during boot; `cursor.rs` polls `usb::poll_mouse().or_else(ps2)`
+so a USB mouse supersedes PS/2. New shell cmd: `usb` (diagnose), `usb rescan`.
+
+### How it works
+- Bring up controller (`OPC=0`, set `RCS`+`CRR`, `CNR`→0), discover a
+  mouse asynchronously from the cursor task (`maybe_discover`), reset the
+  port, enable slot, address device, read device + config descriptors,
+  find the HID boot-mouse IN endpoint, SET_CONFIGURATION, configure EP,
+  arm an IN TRB and drain transfer-completions into `ps2::MouseEvent`.
+- Kernel is identity-mapped + PIC-only (no MSI): DMA is plain kernel
+  heap pointers; no IRQ — keep one IN report armed and drain on each poll.
+
+### QEMU bring-up observations / gotchas that bit us
+- **MaxPorts = bits 31:24 of `HCSPARAMS1`**, not 16:23 (`MaxIntrs`). Using
+  the wrong nibble silently yielded 0 ports ("ports=0", every PORTSC read 0).
+- **Operational registers** (xHCI >=1.1, matches QEMU/Linux): `CRCR=0x18`,
+  `DCBAAP=0x30`, `CONFIG=0x38`. Wrong offsets made Enable-Slot never
+  complete (only Port-Status-Change events → "Enable-Slot never completed").
+- **`issue_cmd` must pass the input-context pointer** in TRB parameter
+  (never drop it); Address-Device failed with code 5 (`CC_TRB_ERROR`) until
+  `code5issue_cmd_ptr(d3, ptr)` passed `INCTX`, and
+- **Input Context is DW0=Drop, DW1=Add** (reverse of what looks natural).
+  QEMU validates `ictl[0]==0 && ictl[1]==0x3`, else `CC_TRB_ERROR`.
+- **HID walker: `bInterfaceClass` is `+5` in the interface descriptor**,
+  not `+2` (`cfg[i+5]`). A reverse-engineering of the mouse's config dump
+  (`09 04 00 00 01 03 01 02 00 … 07 05 81 03 04 00 07`) made it obvious.
+- QEMU monitor **`mouse_button` help ("1=L 2=M 4=R") is wrong for the
+  usb-mouse path**: the value is a direct HID bitmask — `1`=bit0 L,
+  `2`=bit1 R, `4`=bit2 M (matches a real boot-mouse report byte). Bump monitors
+  semantics: transport `mouse_move dx dy`; button via `mouse_button 1|2|4`.
+- A long-lived QEMU session sometimes stopped forwarding `mouse_move`
+  after heavy use; a fresh relaunch always revived it — not a driver bug.
+- Diagnose cmd `usb` prints `xhci mmio=… mapped=… ports=… mouse=… slot=…`
+  plus per-port `PORTS` dwords and a `  hid ep-index=… mps=… armed=true` line.
+
+### Boot log (good path)
+```
+usb: xHCI at 00:03.0
+usb: controller up (8 ports) — mouse discovery deferred to cursor task
+usb: port 4 connect (speed 3)
+usb: dev 0627:0001 class=0x0 mps0=64
+usb: HID mouse IN ep mps=4 interval=7 euid=3
+usb: HID boot mouse armed (slot 1)
+```
+
+### Known limitations
+- Mouse-only, no HID descriptor protocol selection (`SET_PROTOCOL` boot),
+  no high-rate intervals, no keyboard/tablet, no hot-unplug handling, no MSI.