# Qualify all USB mass-storage workflows after USBHS tuning Workpackage

Status: complete
Type: workpackage
Updated: 2026-07-26
Next Action: none

Project Map: work/maps/map-smi-firmware-stabilization-and-qualification.md
Parent: work/wp/active/wp-triple-mirrored-circular-hpt-log-store.md
Canonical Truth: docs/firmware-update-validation-and-recovery.md and docs/sd-card-operation-and-recovery.md

## Current Context

Both controls run cumulative candidate `6484150E...A236E1A`. Its `128 KiB`
CSV aggregation window is isolated in external SDRAM, but its maximum USBHS
FIFO, `128 KiB` USBX BOT phase, `8 KiB` FileX buffer, DMAC path, and USBX pool
are shared by every USB mass-storage consumer.

The active USB thread provides root file discovery, current-image `.imx`
backup, `.imx` firmware restore/update, `W00.wav` through `Wnn.wav` QSPI audio
replacement, PID tuning `.txt` capture, and HPT customer `.csv` publication.
The legacy FileX SD-log writer is unreachable from the USB thread. There is no
standalone WAV export; audio is preserved inside the `.imx` backup.

The owner placed WAV files on the sticks already mounted in Controllers A and
B. WAV installation erases and rewrites the QSPI audio region, and firmware
update replaces executable images. These actions require read-only recovery
baselines, complete file-set preflight, B-first execution, exact candidate
binding, and post-operation configuration/SD/log/Graph verification.

Controller identities remain A=`1751136`/J-Link `69664082`, CID
`035344535330384780976F0084018559`; B=`1751219`/J-Link `69660123`, CID
`035344535330384780976F0085018507`. B must not be formatted or normalized and
must retain oldest lane starts `86 / 86 / 1`.

## Recommendation

Treat the shared USB stack as one subsystem. First harden filename
classification, file-open/close ownership, exact-length reads, WAV capacity
preflight, and durable `.imx` publication. Add executable invariants and
negative models before changing either controller.

Build one exact successor and qualify B before A. On each controller prove
mount/enumeration, WAV load and reboot persistence, sound-table integrity,
`.imx` backup and same-version update, PID capture, and both customer-export
entry points. Verify generated files on the USB media when it is safely
available to the Pi or operator.

Do not remove a USB stick during an operation, use an unverified `.imx`,
perform an update interruption without the separately authorized recovery
case, change configuration, format B, or physically remove an SD card while
powered.

## Current State

Completed:

- Active USB consumers and shared-path risks were inventoried.
- Strict file discovery, WAV preflight/program verification, atomic `.imx`
  publication, and file-ownership error handling were implemented.
- All 35 applicable host gates and the isolated e2 build/package passed.
- Exact candidate `7CB28AA3...A405A` passed B-first/A-second WAV load,
  playback, reboot persistence, `.imx` save/update, raw four-MiB flash
  comparison, audio restore, PID capture, and HPT CSV publication.
- Final CID/configuration/log state passed on both controls; B retained
  `86 / 86 / 1` oldest lanes and `2 / 1 / 0` retirements.
- Both controls were left on Graph, follow-newest, 12-hour zoom, with current
  render sequences.

Deferred/non-blocking:

- Subjective audio-quality judgment and later host-side inspection of PID/CSV
  files when the operator next moves the idle sticks to the Pi.
- Active USB removal and interrupted-update fault cases remain separately
  controlled recovery qualifications.

## Goal

Leave both controls running one exact, clean-built image on which every active
USB mass-storage workflow is proven safe and functional, the intended WAV set
persists and plays, firmware backup/update round-trips without state loss, and
configuration, SD identity, logging, B's abnormal lanes, and Graph behavior are
unchanged.

## Why It Matters

The USB transport tuning is shared below every USB feature. A CSV-only pass
does not prove firmware recovery, audio maintenance, diagnostic capture, file
enumeration, or removal/error handling. Failures in those paths can corrupt
QSPI content, publish unusable recovery images, or reduce operator confidence.

## Major Outcomes

- Strictly enumerate only valid `.imx` and `Wnn.wav` names.
- Reject incomplete, oversized, discontinuous, or malformed WAV sets before
  QSPI erase.
- Publish `.imx` backups at exact size through a durable transaction.
- Close/flush only successfully opened files and retain accurate terminal
  status.
- Pass all software gates and one exact B-first/A-second target image.
- Record timings and integrity results for all active USB workflows.

## Delivery Stages

Use stages when sequencing, parity gates, or handoff cost matter.

| Stage | Outcome | Entry Evidence | Exit Evidence |
| --- | --- | --- | --- |
| 1 | Safe shared implementation | USB inventory and current source audit | source/model/static gates pass |
| 2 | Exact successor | clean implementation | clean build, hashes, memory headroom |
| 3 | Controller B qualification | B baseline and verified WAV set | WAV/IMX/PID/CSV and reboot proof pass |
| 4 | Controller A qualification | selected B result | parity proof passes |
| 5 | Operator handoff | dual-controller evidence | Graphs current, docs/work state closed |

## Related Artifacts

- Parent: `work/wp/active/wp-triple-mirrored-circular-hpt-log-store.md`
- USB tuning predecessor:
  `work/wp/completed/wp-move-hpt-usb-buffer-to-sdram-and-tune-usbhs-throughput.md`
- Update contract: `docs/firmware-update-validation-and-recovery.md`
- Current SD/USB contract: `docs/sd-card-operation-and-recovery.md`
- Authorization:
  `work/decisions/decision-remaining-qualification-authorization.md`

## Rough Sequence

1. Capture A/B firmware, configuration, CID, lane, USB mount/file list, audio
   table, error counters, and Graph baselines.
2. Prove each WAV set is complete, valid, bounded, and consistently named.
3. Harden shared USB file handling and add invariant/model tests.
4. Run all repository gates and clean-build/package one exact image.
5. Program B; qualify enumeration, WAV installation, playback/persistence,
   `.imx` backup/update, PID capture, CSV export, and post-state.
6. Repeat on A.
7. Compare timings/errors, restore both Graph screens, promote current truth,
   capture compact evidence, and close Tool Shed state.

## Milestones

### Milestone 1: Software safety

Completion criteria:

- [x] File discovery accepts only real `.imx` and exact `Wnn.wav` names.
- [x] WAV preflight validates exact reads, contiguous numbering, aggregate
  capacity, and complete readability before QSPI erase.
- [x] Firmware backup cannot leave a stale-tail or nominal incomplete `.imx`.
- [x] PID and all other paths close/flush only owned open files.
- [x] Relevant source/model/static tests and clean build pass.

### Milestone 2: Controller B

Completion criteria:

- [x] CID and `86 / 86 / 1` lane state remain unchanged.
- [x] Intended WAV set installs, persists across reboot, and SOUND_1 completes
  with valid table bounds and no audio/USB/system errors.
- [x] `.imx` backup passes structural/CRC validation and same-version update
  restores the exact candidate without configuration/logging loss.
- [x] PID `.txt` and HPT `.csv` publication pass through FileX close/flush and
  durable final publication. Host-side inspection is a later optional
  physical-media check.

### Milestone 3: Controller A and handoff

Completion criteria:

- [x] A passes the selected B workflow with unchanged CID/configuration.
- [x] Both controllers retain normal logging and current Graph behavior.
- [x] Timings, hashes, file manifests, negative-gate results, and state
  preservation are documented.
- [x] Tool Shed work state is reconciled and stale-path-free.

## Open Questions

- Whether the two physical sticks contain identical, contiguous WAV sets is
  resolved by the read-only target baseline.
- Active-removal and interrupted-update testing remain separately controlled
  recovery cases; they are not implied by this functional qualification.

## Completion Standard

This workpackage is complete when one exact successor image passes software
gates and B-first/A-second validation of every active USB mass-storage
workflow, with recoverable image/audio content, accurate errors, unchanged
configuration/SD/logging state, and both Graph screens restored.

## Closeout Routing

- Current truth promoted to: `docs/firmware-update-validation-and-recovery.md`
  and `docs/sd-card-operation-and-recovery.md`
- Historical context remains in:
  `work/evidence/hpt-usb-sdram-buffer-and-usbhs-tuning-20260726.md`
- Runtime/status evidence:
  `work/evidence/usb-mass-storage-workflow-qualification-20260726.md`
- Cleanup deferred to: separately authorized active-removal/update-interruption
  recovery cases
