1 files changed, 33 insertions, 0 deletions

diff --git a/DEBUG_NOTES.md b/DEBUG_NOTES.md
index b7c0e08..cd2b9ae 100644
--- a/DEBUG_NOTES.md
+++ b/DEBUG_NOTES.md
@@ -631,3 +631,36 @@ Failure signatures to report:
 - 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).
+
+### OptiPlex 7010 — first hardware QR decode
+
+The first hardware run booted to the shell with no USB input and displayed
+the EHCI failure QR:
+
+```
+EHCI fail stage=4 t=20ms sp=0 dev=0 in=true len=18
+cmd=00000020 sts=0000b013
+prtsc0=0x00001005 hp=0x00003000
+qh1=48084000 qh2=40800000 nqtd=012080c0
+setup=00080e80 data=80120d80 stat=80008c80
+```
+
+- `sts` bit4 = **HSE (Host System Error)** plus HCH: the controller aborted
+  the very first DMA pass after 20 ms, so this is a bus/DMA fault, not a
+  protocol error.
+- `cmd=0x20`: RUNSTOP self-cleared, only ASE remains.
+- `qh1/qh2/qTD tokens` are structurally correct: control QH, DTC, MPS 8,
+  split hub 0 / port 1, qTD active with TBYTES.
+- `prtsc0` PED=0: full-speed device on the root port (companion/TT path).
+
+**Root cause: 64-bit addressing capability.**  The PCH EHCI advertises
+HCCPARAMS bit0, which extends every QH with `bufptr_hi[5]` (68 B) and every
+qTD with `bufptr_hi[5]` (52 B).  The driver packed them 32-bit-style (48/32
+B), so the HC read the *next qTD* as the overlay's high buffer pointer and
+DMA'd to a bogus 64-bit address -> HSE.  QEMU reports `caps64=false`, so only
+hardware exposed this.
+
+**Fix:** always reserve the 64-bit layout (32-bit controllers ignore the
+tail): HID qTD at QH+0x80; control qTDs at +0x100/+0x140/+0x180 and the setup
+packet at +0x1C0.  The failure QR now prints `c64=` and the DMA bases
+(async/xfer/setup/buf) so the next run is self-describing.