# Ticket: Investigate USB drive enumeration and post-save workflow compatibility

Status: complete
Type: ticket
Updated: 2026-08-01
Next Action: none; retain the resolved specimen observations as historical evidence, not an approved-drive policy
Campaign: 003-complete-bounded-hpt-slow-export-firmware-ticket
Parent: work/maps/map-smi-firmware-stabilization-and-qualification.md
Evidence Source: work/spikes/spike-explore-usb-drive-workflow-compatibility-across-controllers-a-and-b.md

## Continuation Point — 2026-07-29

- The standards-based planning update is complete.
- Implemented USBX's documented 2,000 ms storage initialization allowance;
  the prior local value was 200 ms.
- Added the 56-byte
  `g_ux_host_class_storage_bringup_diagnostic` record with initialization
  sequence, stage, status, elapsed ticks, LUN, sector size, dynamically
  discovered bulk endpoint addresses, and mount status.
- Extended `script/invoke-usb-workflow-qualification.ps1` to capture that
  record plus `gUsbMediaEventLastStatus` and
  `gUsbMediaSessionGeneration`.
- Canonical managed Debug rebuild passed.
- Exact deployed Debug S-record SHA-256:
  `FA098554D11735B14CFCB180C79B3EA31FFAD25D3A9A70352846A3518EF4A734`.
- The exact image was programmed successfully to Controller A through J-Link
  `69664082` and Controller B through J-Link `69660123`.
- Post-deployment read-only captures showed both controllers healthy with
  their expected SD CIDs and no USB drive inserted. The new bring-up record
  was consequently still zeroed.
- Compact live captures are routed beneath the controller-specific ignored
  `work/evidence/hpt-log-store-circular-mirror/controller-*/usb-compat-live/`
  paths because workspace preflight reports the repository evidence budget is
  already exceeded.

Resume with the operator move:

```text
DRIVE: USB05_4G
TO: Controller A

DRIVE: USB06_1G
TO: Controller B
```

Keep both controllers powered during USB insertion. After the operator reports
`done`, capture both controller states before triggering any write workflow.

## USB06_1G focused diagnosis — 2026-07-29

- The owner stopped the broader workflow matrix and narrowed work to making
  `USB06_1G` enumerate on Controller B.
- Initial and delayed captures showed no media generation, no storage bring-up
  record, and no USB mount.
- The VBUS diagnostic and qualification harness were corrected so a guarded
  port power cycle can run before media mount.
- Added read-only host-port telemetry covering device-attached state, HCD port
  state, root-hub/HCD signals, and USBHS `SYSCFG`, `SYSSTS0`, `DVSTCTR0`,
  `INTENB1`, and `INTSTS1`.
- A verified VBUS off/on cycle completed, but the PHY remained at
  `SYSSTS0.LNST = 3` (SE1), with no attach, descriptor, class, or storage
  event. USBX therefore never reached the existing storage bring-up
  telemetry.
- A bounded full-speed/HSE-disabled probe did not change SE1.
- A single diagnostic forced root-hub reset attempt produced no device
  response and no descriptor-stage progress.
- Both experimental probes were removed. The final safe diagnostic image
  `8F426161C731FDFBCA6DF4EF91D75CCA5F684DAF9922C132321AFF693309F6C9`
  and its ELF were archived for possible future diagnosis. Controller B was
  then restored from Controller A's exact internal-flash capture; their full
  4 MiB readback hashes match at
  `9E07298BD9B6FFD066F5D086E2D0D9F5C7EE4627B5D21C6D1F22AFF82A9F2AB8`.
  See `work/evidence/controller-a-b-exact-firmware-sync-20260729.md`.
- Further blind firmware retries are not justified while the bus remains in
  SE1. The next discriminator is direct D+/D-/VBUS observation and comparison
  with the same drive on a Linux host.

### Owner disposition

`USB06_1G` is incompatible with this controller platform. The completed
cross-controller attempts, guarded VBUS recovery, host-port telemetry,
full-speed diagnostic, and bounded reset attempt constitute reasonable
compatibility effort. Do not perform further controller insertion, VBUS,
reset, middleware, or firmware experiments for this specimen. Preserve it and
the existing evidence; this is a specimen disposition, not an approved-drive
list or a general model-family claim.

## Problem

The exploratory four-drive/two-controller matrix found two repeatable
compatibility classes under the same accepted 32 KiB firmware:

- `USB06_1G` and `USB08_8G` did not enumerate on either controller, including
  one powered reseat per case, while controller and internal-SD health
  remained normal.
- `USB05_4G` enumerated and durably saved the full image on both controllers,
  but HPT USB publication terminated with USB status 17 and produced no CSV
  on both. The clean Controller A repeat also accepted two PID triggers
  without starting the PID durability operation or creating a PID file.

`USB07_32G` enumerated on both controllers and completed WAV, image, PID, and
HPT publication. Across all enumerated cases, the saved image was not exposed
to the update selector during the bounded session, so self-update coverage
remains inconclusive rather than failed.

## Final resolution — 2026-07-30

The command-class compatibility implementation and final Release qualification
resolve the actionable controller issues in this ticket:

- `USB05_4G` now passes WAV, PID, immediate subsequent image publication,
  fresh-session durability verification, and saved-image update/reboot on both
  controllers. Independent Pi inspection passed.
- `USB07_32G` passes the equivalent B-then-A workflow on the normal compliant
  cache path. Independent Pi inspection passed.
- `USB08_8G` passes image, PID, and HPT publication through the bounded
  unsupported-command compatibility path.
- `USB04_32G` remains the compliant-cache control.
- `USB06_1G` retains the owner's terminal controller-incompatible
  disposition; no further attempts were made.
- Final A/B 4 MiB flash captures match exactly at
  `5DA4A19C10DAEEC6B812B314FF2D155F1ED044AE62F43B226CB13BB31060E932`.

Evidence:

- `work/evidence/usb05-final-release-qualification-20260730.md`
- `work/evidence/usb07-final-release-qualification-20260730.md`
- `work/evidence/usb-command-compatibility-final-release-closeout-20260730.md`

## Expected Behavior

The compatibility target is standards-conforming USB Mass Storage Class,
SCSI transparent command set, Bulk-Only Transport media using the controller's
supported FAT16/FAT32 geometries. Compatibility behavior shall be based on USB
and SCSI protocol state, not VID/PID exceptions or timings derived from the
available specimens.

Supported media should enumerate consistently on both controllers. After a
successful image save, PID capture, HPT publication, and the update selector
should each enter an attributable request state and reach a truthful terminal
result. Successful HPT publication must produce a durable CSV with a matching
`COMPLETE` trailer.

## Standards-Derived Timing And Recovery Requirements

- Preserve the USB 2.0 enumeration requirements, including at least 100 ms of
  stable attachment before reset/enumeration, the specified port-reset
  duration, and at least the required reset-recovery interval before the next
  control request. Confirm the Renesas HCD behavior with telemetry or a bus
  trace rather than assuming the existing constants prove compliance.
- Restore or explicitly supersede USBX's documented two-second storage-device
  initialization allowance. The current USBX source documents two seconds
  immediately before media-characteristics discovery, while the local header
  defines only 200 ms.
- Do not treat two seconds as a USB-IF media-ready mandate. After USB
  enumeration, determine logical-unit readiness through TEST UNIT READY and
  REQUEST SENSE.
- Retry only recognized transient SCSI states, including becoming-ready,
  operation-in-progress, power-on/reset Unit Attention, and
  medium-may-have-changed. Use bounded backoff and proceed immediately when
  ready.
- Treat action-required and permanent sense conditions distinctly; do not
  collapse them into a generic not-mounted result or retry them indefinitely.
- Implement the USB Mass Storage Bulk-Only Transport Reset Recovery sequence
  when required by invalid CSW, phase error, or a transport state that remains
  stalled: mass-storage class reset followed by clear-halt on both discovered
  bulk endpoints and restoration of usable endpoint state.
- Discover endpoint addresses from descriptors. Do not assume bulk-IN endpoint
  `0x81`; `USB08_8G` using `0x82` is standards-valid.
- Use an explicit product deadline rather than a specimen-derived timing
  limit. Initial planning bounds are a five-second normal readiness window and
  up to ten seconds while the device continues returning a legitimate
  transient state. These bounds require evidence review before production
  adoption and are not unconditional sleeps.

## Planned Work

1. **Observation-only telemetry**
   - Record USB attach, debounce/stabilization, reset, reset recovery,
     descriptor/configuration, class activation, GET MAX LUN, endpoint
     discovery, Inquiry, TEST UNIT READY, REQUEST SENSE key/ASC/ASCQ, Read
     Capacity, sector-zero classification, FileX open, volume validation, and
     application-session publication.
   - Preserve the first failing stage, status, retry count, and elapsed time.
   - Represent device-present, USB-configured, storage-active,
     block-media-ready, filesystem-mounted, and application-session-ready as
     distinct states.

2. **Standards and implementation timing verification**
   - Verify the Renesas HCD's actual attachment, reset, and reset-recovery
     timing.
   - Compare Raspberry Pi/Linux traces as a behavioral reference for the same
     protocol transitions, not as the source of controller timing limits.
   - Confirm whether `USB06_1G` and `USB08_8G` fail before SCSI discovery,
     during readiness, during BOT recovery, or during media open.

3. **Readiness and BOT correction**
   - Apply USBX's documented initialization allowance or a justified
     state-driven equivalent.
   - Add bounded TEST UNIT READY/REQUEST SENSE handling with transient-state
     classification and backoff.
   - Verify GET MAX LUN control-stall fallback to LUN 0.
   - Verify mandatory BOT Reset Recovery and dynamic endpoint handling.

4. **Media layout and command compatibility**
   - Preserve and explicitly verify both FAT-at-LBA0 and MBR-partitioned
     layouts without reformatting the specimens.
   - Prefer broadly supported mandatory SCSI commands; treat rejection of
     optional commands as nonfatal when the reported sense permits it.
   - Validate FAT geometry and partition bounds without relying on obsolete
     CHS values.

5. **Generation-bound media lifecycle**
   - Prevent raw FileX/USBX media pointers from surviving disconnect, VBUS
     cycling, or remount.
   - Acquire and validate the current media generation at the start of every
     workflow and abort if it changes.
   - Use this state model to isolate and correct `USB05_4G` status 17
     (`FX_MEDIA_NOT_OPEN`), accepted-but-not-started PID behavior, and stale
     post-save update selection.

6. **Targeted modernization decision**
   - After the first-failure evidence and local corrections are known, compare
     the USBX 6.2.1 storage activation, endpoint, media-open, and BOT paths
     against the Renesas-supported 6.4.0 generation.
   - Prefer a narrow, traceable backport or separately qualified SSP migration;
     do not replace the Renesas USB stack wholesale or edit generated/vendor
     code as an undocumented production fix.

7. **Capability-based regression**
   - Exercise both controllers with all available specimens as representatives
     of capabilities, not as an approved-drive list.
   - Cover dynamic endpoint numbers, MBR and FAT-at-LBA0, SCSI-2/newer
     reporting, USB 2.0/3.x devices operating at supported speed, readiness and
     Unit Attention recovery, and all controller USB workflows.
   - Preserve the qualified 32 KiB application write cap. Evaluate USBX
     transport limits separately only when transport evidence justifies it.

## Acceptance Criteria

- Historical planning item: Identify the protocol/session difference that causes both controllers
      to reject `USB06_1G` and `USB08_8G` while accepting `USB05_4G` and
      `USB07_32G`; preserve the specimens and their current FAT32 layouts.
- [x] Disposition `USB06_1G` as controller-incompatible after reasonable
      cross-controller and recovery effort; stop further attempts on this
      specimen.
- Historical planning item: Demonstrate the actual controller attachment, reset, reset-recovery, and
      first-storage-command timing, and reconcile it with the USB 2.0
      requirements and the USBX initialization guidance.
- Historical planning item: Capture stage-specific status and SCSI sense data so a failed insertion
      identifies the first failing layer rather than only reporting not
      mounted.
- Historical planning item: Verify standards-compliant dynamic bulk endpoint discovery and mandatory
      BOT Reset Recovery without a VID/PID-specific workaround.
- Historical planning item: Verify bounded readiness handling for retryable SCSI states and immediate
      termination for permanent/action-required states.
- Historical planning item: Capture the first failing USB/FileX layer and status for the
      `USB05_4G` HPT status-17 publication failure on both controllers.
- Historical planning item: Prove that no stale FileX/USBX media pointer crosses a disconnect, VBUS
      transition, remount, or media-session generation change.
- Historical planning item: Explain or correct the accepted-but-not-started PID behavior observed
      on the clean A/`USB05_4G` repeat.
- Historical planning item: Explain or correct post-save update-list refresh without relying on
      physical reseating as normal workflow synchronization.
- Historical planning item: Re-run focused A/B regression with request-specific terminal telemetry
      and independent read-only Pi validation.
- Historical planning item: Keep the outcome as compatibility evidence; do not publish an approved
      model list without a separately authorized qualification plan.
- Historical planning item: Preserve the accepted 32 KiB application write cap and show no regression
      on `USB03_32G`, `USB04_32G`, or `USB07_32G`.

## 2026-07-29 USB08_8G first-failure resolution

- Controller B enumerated `USB08_8G` through USBX storage bring-up, but the
  application did not publish a FileX session.
- Deferred handoff telemetry proved the callback was initially early
  (`acceptance_mask=11`): status, media pointer, and storage-instance identity
  were valid while `fx_media_id` was still zero.
- Propagating the previously discarded media-open result exposed
  `FX_BUFFER_ERROR` (`0x21`). A read-only target inspection then found FileX
  had decoded `0x9090` as bytes per sector.
- The retained sector-zero buffer began `EB 63 90` and contained MBR bootstrap
  code. USBX's jump-only heuristic had misclassified that MBR as a FAT boot
  sector and interpreted bootstrap bytes 11-12 (`90 90`) as the BPB sector
  size.
- The focused correction now recognizes a direct FAT boot sector only when
  bytes per sector is one of 512/1024/2048/4096, or recognizes exFAT by its
  exact OEM signature. Otherwise the signed sector is parsed as an MBR.
- With Debug S-record SHA-256
  `3958AC3A56075139B6D0AAB3D4DCB439A581FA1C47F4433835FE801B69B5AC87`,
  Controller B mounted `USB08_8G`: `usb_mounted=1`,
  `media_generation=1`, `acceptance_mask=15`, `system_errors=0`, and
  `W00.wav`/`W01.wav` were listed.
- Evidence:
  `work/evidence/hpt-log-store-circular-mirror/controller-b/usb-compat-live/20260729-141637-usb08-mbr-fix/`.

This resolves the first-failure cause for `USB08_8G`. It does not change the
owner's terminal retirement of `USB06_1G`.

## 2026-07-30 USB08_8G compatibility candidate

- The executable transaction inventory and the capacity, inquiry, retry,
  ambiguous-write, synchronize-cache classification, and fresh-session
  handoff corrections are implemented.
- Debug S-record
  `3577E3AFDD9AD9758B0DB0BBEF954A712586D1B10FA8D74F479A3856A14E3D4E`
  passed Controller B then Controller A with their expected SD CIDs.
- On both controllers, `USB08_8G` reached acceptance mask `15` and passed WAV,
  PID durability, full 8,388,864-byte image publication with post-VBUS CRC,
  image update staging, and explicit VBUS/remount with zero live system errors.
- Five seconds of passive cache drain was insufficient for the drive's
  late-committing rename. Thirty seconds passed but is operationally excessive.
  Test 10 seconds next and 15 seconds only if required; do not substitute TEST
  UNIT READY or read success for physical-persistence evidence.
- The Release image built with S-record SHA-256
  `E706B043AC4C7BCB41FBECD5C92C2D2E8A5372C0662A981D99D19F312DDA22A0`,
  but deployment was interrupted before completion or verification.

## 2026-07-30 USB08_8G final resolution

- The selected 10-second unsupported-cache drain passed three consecutive
  image durability trials on B and three on A.
- Final Release S-record
  `838645AF04F6718231AE892A7F2EB16EC6710A8354DA270A6601CFEAC8E6ABE9`
  was deployed B first, then A.
- Both full internal-flash captures matched:
  `FFBA2B680B07543416D8A6357FDE17A47F433626519824E6182491976FFD1B03`.
- Release image-save and explicit VBUS/remount tests passed on both targets
  with acceptance mask `15`, exact post-cycle verification, and zero errors.
- Final Pi `fsck.vfat -vn` was clean and no temporary files remained.
- `USB08_8G` is qualified for this controller firmware. Evidence:
  `work/evidence/usb08-command-compatibility-release-qualification-20260730.md`.

## Verification

Use the exact controller identities, accepted Debug S-record SHA-256
`157DC86B781FCE23B9D8F048B3F4F8C7524FFCBF0029E001310282338BDF1DFB`,
and evidence conventions from the parent spike. Require controller-specific
SD CID capture, one bounded insertion retry, non-repairing FAT checks, exact
file hashes/sizes, and absence of temporary files. Do not reformat or repair
the four specimens during diagnosis.
