From e55e0f186b384b398261f41f4de36625f8c5c727 Mon Sep 17 00:00:00 2001 From: vasilito Date: Sun, 19 Jul 2026 11:17:21 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20P3-A=20runtime=20validation=20=E2=80=94?= =?UTF-8?q?=20hub=20chain=20proven,=20hub-child=20gap=20recorded?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit USB-IMPLEMENTATION-PLAN.md P3-A: record the 2026-07-19 QEMU runtime validation (test-usb-hub-qemu.sh) β€” full usbhubd chain proven (descriptor, EP1 change detection, initial scan, debounce, reset to port-enable), the five latent bugs it surfaced and that were fixed (scheme attach bootstrap, bitmap off-by-one, missing initial scan, unbounded EP1 wait, debounce clear deadlock), QEMU's ClearPortFeature stall handled gracefully by P2-C recovery, and the remaining gap: hub-child device enumeration (usb-kbd to HID driver) blocked on xhcid's hub-child attach path (debug-level; TT/route investigation) plus an intermittent xhcid IRQ-reactor startup race. HARDWARE-VALIDATION-MATRIX.md: hub row to QEMU-validated for the enumeration chain, with the hub-child gap noted. --- local/docs/HARDWARE-VALIDATION-MATRIX.md | 2 +- local/docs/USB-IMPLEMENTATION-PLAN.md | 21 +++++++++++++++++++++ 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/local/docs/HARDWARE-VALIDATION-MATRIX.md b/local/docs/HARDWARE-VALIDATION-MATRIX.md index 0e2ef1e11d..9edc9b46c1 100644 --- a/local/docs/HARDWARE-VALIDATION-MATRIX.md +++ b/local/docs/HARDWARE-VALIDATION-MATRIX.md @@ -20,7 +20,7 @@ | xHCI host controller | βœ… | πŸ”² | Interrupt-driven mode proven (test-xhci-irq-qemu.sh); 51-flag quirk table + HCCPARAMS2 gating (P2-A/B); 36-code error recovery (P2-C); not HW-validated | | EHCI/UHCI/OHCI controllers | πŸ”² | πŸ”² | Compile clean; runtime enumeration proofs planned (P8-B) | | USB storage (BOT) | βœ… | πŸ”² | usbscsid autospawn + bounded sector readback proven (test-usb-storage-qemu.sh); guest-side write verify open | -| USB hub (non-root) | πŸ”² | πŸ”² | P3-A enumeration core complete (debounce/reset-wait/U0-wait/wHubDelay, 14 unit tests); runtime hub proof pending (P8-B test-usb-hub-qemu.sh) | +| USB hub (non-root) | βœ… | πŸ”² | Hub enumeration chain proven in QEMU (test-usb-hub-qemu.sh): descriptor, EP1 change detection, initial scan, debounce, resetβ†’enable; hub-child device enumeration (kbdβ†’HID) blocked on xhcid TT/debug path | | **GPU/Display** | | | | | VESA | βœ… | πŸ”² | QEMU framebuffer works | | virtio-gpu | βœ… | N/A | 2D only, QEMU | diff --git a/local/docs/USB-IMPLEMENTATION-PLAN.md b/local/docs/USB-IMPLEMENTATION-PLAN.md index b71b825ae3..e37807389b 100644 --- a/local/docs/USB-IMPLEMENTATION-PLAN.md +++ b/local/docs/USB-IMPLEMENTATION-PLAN.md @@ -371,6 +371,27 @@ U1/U2 LPM on hub ports (P7); interrupt-EP usage on USB 3 hubs without one **Exit met:** complete hub enumeration including power timing, USB 3 hub handling, and TT accumulation. +**Runtime validation (2026-07-19, `test-usb-hub-qemu.sh` on QEMU +`usb-hub` + `usb-kbd` behind it):** the full usbhubd chain is proven at +runtime β€” hub descriptor read (8 ports), EP1 interrupt-driven change +detection, initial full port scan, connection debounce, port reset with +completion wait, and port enable all observed in the boot log. The proof +also surfaced and we fixed five latent bugs: the xhcid scheme refused +port-dir opens for unenumerated hub children (attach bootstrap +deadlock), a status-bitmap off-by-one (bit Nβˆ’1 vs spec's bit N), a +missing initial scan (daemon could block on EP1 before ever polling), +an unbounded EP1 wait (state changes during synchronous waits produce +no new interrupt), and a debounce that could deadlock on a hung +C_PORT_CONNECTION clear (stability is now judged on connection state, +with the change bit cleared post-attach). QEMU's hub stalls +ClearPortFeature on change indicators β€” handled gracefully by the P2-C +stall recovery (best-effort, no crash). **Remaining gap:** the hub-child +device (usb-kbd) reaches `enabled: true` but does not complete +enumeration to a HID driver β€” xhcid's hub-child attach path progresses +only at debug level and needs TT/route investigation with debug +logging. Also observed: an intermittent xhcid IRQ-reactor startup race +(one boot showed no reactor start; retry passed). + ### P3-B: Hub interrupt-driven change detection βœ… COMPLETE (verified 2026-07-18) **Reference:** `linux-7.1/drivers/usb/core/hub.c:1000+` `hub_irq()`.