# USB enumeration diagnostic software candidate

Status: complete
Result: complete; historical diagnostic software evidence
Type: evidence
Updated: 2026-08-01
Next Action: none; the successor sequence and current broad baseline are complete
Campaign: 003-complete-bounded-hpt-slow-export-firmware-ticket
Final Evidence: work/evidence/usb-bot-representative-delta-regression-20260801.md

Project Map: work/maps/map-smi-firmware-stabilization-and-qualification.md
Workpackage: work/wp/completed/wp-restore-broad-usb-compatibility-baseline.md
Checklist: work/checklists/checklist-stage-1b-four-drive-usb-compatibility-baseline.md

## Outcome

The repeated first-insertion miss is now isolated from the proven write path.
Four prior misses occurred before USB Mass Storage class publication, FileX
media handoff, or any 32 KiB write. Three showed electrical attachment with
`SYSSTS0=0x8001`, `DVSTCTR0=0x0200`, no negotiated root-hub speed, no fresh
media generation, and no retry signal. A fresh USB03_32G insertion on
Controller A during this diagnostic preparation initially showed no
electrical attachment at all and then mounted normally after one clean
reseat. The successful state was high-speed `DVSTCTR0=0x0213`, fresh media
generation `6`, valid FileX publication, and zero USB errors.

Source commit `a3fe1593` adds observation and null-safe failure routing only.
It does not add automatic recovery, VBUS cycling, optional SCSI commands,
drive identification, controller-specific behavior, new timeouts, transport
replay, or any change to the isolated 32 KiB HPT FileX write cap.

## Diagnostic coverage

The candidate records the live USBX/HCD state needed to distinguish an
exhausted enumeration from a lost root-hub retry:

- HCD operational state, root-hub connection bitmap, and device count;
- enumeration-semaphore count and root-hub/HCD signal counts;
- USBX system error count and last error;
- first live USB device handle, state, address, and speed;
- generic connection/disconnection notification counts;
- null-class connection failures and the associated unconfigured device
  snapshot;
- existing physical-attach, port, USBHS-register, media-generation, FileX,
  application-session, and full SD identity state.

USBX intentionally emits generic connection and disconnection notifications
with a null class pointer. The prior application and generated router compared
that pointer as if it were a class-name buffer. The candidate now records the
generic event and returns safely, while the generated storage router skips its
class comparison when the pointer is null. This is a correctness correction;
it does not manufacture a successful enumeration or weaken the FileX-ready
publication gate.

## Software gates

- `script/check-usb-mass-storage-workflows.ps1`: PASS.
- `script/check-usb-write-size-diagnostic.ps1`: PASS, 9/9.
- `script/check-hpt-customer-export.ps1`: PASS, 34/34.
- `script/check-usb-transaction-inventory.ps1`: PASS.
- `script/test-usb-mass-storage-workflows.py`: PASS, 9/9.
- `script/check-code-review-mitigations.ps1`: PASS, 15/15.
- `script/check-sd-card-cid.ps1`: PASS, 25/25.
- Canonical managed Debug rebuild: PASS.
- Canonical managed Release rebuild: PASS.
- Debug and Release packaging: PASS; stable and versioned artifacts matched
  within each configuration.

The managed builds completed with the repository's established warning set
and no new diagnostic-code build failure.

## Exact candidate artifacts

| Artifact | Bytes | SHA-256 |
| --- | ---: | --- |
| `work/evidence/generated/usb-enumeration-diagnostic-candidate-20260731/7520553_SMI_FW-Debug.elf` | 14,690,680 | `4D1C2F56D9F1DC2638577C95FB3EAA74EF611FC98AC69E559930A75BAEF8D5C5` |
| `work/evidence/generated/usb-enumeration-diagnostic-candidate-20260731/7520553_SMI_FW-Debug.srec` | 8,641,242 | `767CAAC5B49B4A7EFB717F5AE5880F4495CA3674D6609EAF938534CB10CC3075` |
| `work/evidence/generated/usb-enumeration-diagnostic-candidate-20260731/7520553_SMI_FW-Release.elf` | 11,359,784 | `BF8E86A33AF72660D8AAD38862A25F50452CB5D471CF74890C9140B14602A613` |
| `work/evidence/generated/usb-enumeration-diagnostic-candidate-20260731/7520553_SMI_FW-Release.srec` | 8,641,242 | `1EE060BF161F292C92C6520926DE665321647957A7333E2A5BFEF7008E9EA904` |

The generated directory is intentionally ignored. Deployment must use the
explicit frozen Release ELF and S-record paths above. Production promotion
remains blocked until the added evidence identifies and dispositions the
first-insertion failure without weakening broad compatibility.

Deployment subsequently passed Controller B first and Controller A second,
including independent full-flash comparison and fresh post-reboot SD identity
gates. See
`work/evidence/usb-enumeration-diagnostic-controller-deployment-20260731.md`.
