From 5e1bdc12bd298a9751da4285b7e93c68b1314332 Mon Sep 17 00:00:00 2001 From: salmonik Date: Tue, 4 Aug 2026 03:06:06 +0200 Subject: v0.5.10: USB HID mouse via polled xHCI (rsnix/src/usb.rs) Polled xHCI driver (mouse-only): controller bring-up, port reset, enable-slot -> address-device -> config-descriptor walk -> HID boot mouse IN endpoint, one outstanding IN TRB drained on poll. Cursor task polls usb first, PS/2 second. New 'usb'/'usb rescan' shell cmds. Verified in QEMU (q35 + OVMF + qemu-xhci + usb-mouse): movement and all three buttons tracked exactly; heap stays clean. Fixes en route: MaxPorts=HCSPARAMS1[31:24]; operational regs CRCR=0x18 DCBAAP=0x30 CONFIG=0x38; pass input-context ptr in Address-Device; Input Control Context DW0=Drop DW1=Add; HID walker bInterfaceClass at +5; async discovery from cursor task. --- DEBUG_NOTES.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) (limited to 'DEBUG_NOTES.md') 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 +` 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. -- cgit v1.2.3