# USB Mass-Storage Workflow Qualification — 2026-07-26

Status: embedded functional qualification passed on Controllers B then A

## Exact candidate

- Debug S-record SHA-256:
  `7CB28AA397A08A404CDC4223A927367FD6C91F7B9D36B7B3E0B065F9895A405A`
- Debug ELF SHA-256:
  `402B6458A6710A8B5350CEE1D85009DF49D6976565AA9CF72847AFD83EAB4790`
- Raw four-MiB internal-flash SHA-256:
  `078D3B633188CD2849B2C3AEB3C96985C51F448980CB4A2387C62D9AA3EE77E8`
- Clean isolated e2 build and release packaging: pass
- Applicable repository host gates: 35/35 pass
- SDRAM USB buffer: `0x91AAA080..0x91ACA07F`, 128 KiB, linker
  bounded to the authorized 1024 KiB maximum

The exact build artifacts are in `Debug/`. Source/configuration/model gates are
`script/check-usb-mass-storage-workflows.ps1` and
`script/test-usb-mass-storage-workflows.py`.

## Implemented safety changes

- `.imx` discovery requires a literal, case-insensitive `.imx` suffix.
- WAV discovery accepts only exact, case-insensitive `Wnn.wav` names with
  `00 <= nn < 25`.
- WAV installation proves unique contiguous numbering, valid mono/44.1-kHz/
  16-bit PCM headers, declared data length, exact full-payload readability,
  and aggregate padded QSPI capacity before erase.
- WAV programming starts after the eight-byte `data` chunk header, pads only
  the final page, propagates QSPI program/ready failures, erases exactly the
  defined 56-sector audio partition, and reads back address/length tables
  before success.
- Firmware backup writes `SMI_IMAGE.TMP`, closes and flushes it, preserves the
  previous image as `SMI_IMAGE.BAK`, atomically renames the completed temp file
  to the release `.imx`, flushes the directory state, and rolls back on publish
  failure.
- Firmware update and PID capture now close only successfully opened files.
  Update file ownership can no longer be acquired by a failed open/layout
  branch.
- The existing 128 KiB SDRAM CSV buffer, 128 KiB USBX BOT transfer, 8 KiB
  FileX buffer, and 2 KiB USBHS FIFO remain common qualified transport
  settings.

## Controller identity and preserved state

| Result | Controller A | Controller B |
| --- | --- | --- |
| Assembly / J-Link | 1751136 / 69664082 | 1751219 / 69660123 |
| Raw CID | `035344535330384780976F0084018559` | `035344535330384780976F0085018507` |
| Protocol / CID valid / representative read | 6 / 1 / 0 | 6 / 1 / 0 |
| Final system errors | 0 | 0 |
| Final config operational / findings / blocks identical | 1 / 0 / yes | 1 / 0 / yes |
| Final oldest lane starts | 1 / 1 / 1 | 86 / 86 / 1 |
| Final active lane starts | 1024 / 1024 / 1024 | 1109 / 1109 / 1024 |
| Final retired segments | 0 / 0 / 0 | 2 / 1 / 0 |

B was not formatted or normalized. Its abnormal lane topology and CID remained
unchanged through programming, WAV replacement, reboots, image backup/update,
PID publication, and CSV export.

Baseline and final identity/configuration artifacts:

- A:
  `work/evidence/hpt-log-store-circular-mirror/controller-a/usb-workflow-qualification-20260726/`
- B:
  `work/evidence/hpt-log-store-circular-mirror/controller-b/usb-workflow-qualification-20260726/`

## Workflow results

Both sticks enumerated exactly `W00.WAV` and `W01.WAV`. Both controllers:

1. preflighted and loaded both WAV files;
2. published sound 0 at `0x60480800`, length 198,450 bytes;
3. published sound 1 at `0x604B1000`, length 176,400 bytes;
4. completed SOUND_1 playback with the audio state returning to idle and no
   system error;
5. retained byte-identical 2 KiB QSPI audio index/length evidence across
   reboot;
6. saved and remounted exactly `7520553_SMI_00_05_00.imx`;
7. updated from that self-generated image and rebooted;
8. produced a byte-for-byte match between all four MiB of internal flash and
   the exact successor S-record;
9. restored byte-identical QSPI audio index/length data from the `.imx`;
10. completed a PID text header plus one RAM-record publication with no USB or
    system error; and
11. completed retained-range HPT CSV publication through final flush/rename.

Timing values below are conservative trigger-to-capture upper bounds for WAV
and image workflows. CSV timing is firmware telemetry spanning the exact
phases stated.

| Workflow | Controller A | Controller B |
| --- | ---: | ---: |
| WAV preflight/load upper bound | 22.5 s | 27.9 s |
| Full ~8 MiB `.imx` save upper bound | 231.9 s (3:52) | 477.2 s (7:57) |
| `.imx` validation/stage/install/reboot upper bound | 133.3 s (2:13) | 197.2 s (3:17) |
| HPT records in CSV | 1,981 healthy / 0 degraded | 1,828 healthy / 81 degraded |
| HPT stage time | 2.54 s | 2.40 s |
| USB publication time | 0.30 s | 0.41 s |
| Total CSV time | 2.86 s | 2.86 s |
| FileX writes / largest write | 1 / 100,199 B | 1 / 96,583 B |

The image-save spread is approximately 2.06x for identical firmware and WAV
content. It is isolated to the legacy 1 KiB-at-a-time recovery-image path and
the physical USB/controller combination; the coalesced CSV path does not show
the same total-time spread.

## Operator-ready handoff

| Graph state | Controller A | Controller B |
| --- | ---: | ---: |
| Screen active | yes | yes |
| Follow newest | yes | yes |
| Render sequence current | 14 / 14 | 54 / 54 |
| Zoom | 12 h | 12 h |
| RTC-to-newest age at capture | 59 s | 21 s |

Both controls were left running the exact candidate with Graph visible.

The controller-side qualification proves FileX creation, full close/flush/
rename, remount and embedded reread for `.imx`, and successful final
publication telemetry for PID/CSV. A later host-side directory/content
inspection may be performed when the operator next moves the idle USB sticks
to `srv-rpi00.local`; no USB stick was removed by automation.

## Residual qualification boundaries

- Subjective speaker/audio-quality judgment was not automated; the electronic
  playback state completed without an error.
- USB removal during an active operation and interrupted firmware update are
  separately controlled recovery/fault cases and were not introduced here.
- CRC proves image integrity, not publisher authenticity; that accepted risk
  remains governed by `work/adr/adr-smi-firmware-update-authentication.md`.
