# Optimize IMX backup and update with shared SDRAM buffering Workpackage

Status: complete
Type: workpackage
Updated: 2026-07-26
Next Action: Use this qualification in the successor candidate/release decision; keep interruption faults separately controlled

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

## Current Context

Both controls run exact candidate `7CB28AA3...A405A`. Its complete shared-USB
qualification passed WAV load/playback/persistence, atomic `.imx` save/update,
PID publication, HPT CSV publication, full internal-flash comparison, and
Graph restoration. B remains intentionally abnormal with oldest lanes
`86 / 86 / 1`, active starts `1109 / 1109 / 1024`, retirements `2 / 1 / 0`,
and CID `035344535330384780976F0085018507`.

The HPT CSV path owns a statically allocated, 64-byte-aligned `128 KiB` SDRAM
window and publishes current retained exports with one FileX write. The `.imx`
path instead writes a 256-byte header followed by approximately eight MiB of
firmware/audio in 1 KiB calls—about 8,192 FileX writes. Conservative measured
save upper bounds were `3:52` on A and `7:57` on B. The update path similarly
reads 1 KiB at a time for payload CRC and QSPI staging.

All USB work is serialized by `Thread_Usb`, so the qualified SDRAM window can
be shared by CSV, image save, image preflight, and image staging without
allocating another large buffer.

## Recommendation

Rename/generalize the current SDRAM window as the shared sequential USB buffer.
Keep its qualified `128 KiB` size, alignment, linker section, and authorized
`1024 KiB` ceiling. Preserve the existing temporary/backup/flush/rename/rollback
transaction and coalesce firmware/audio save calls into complete buffer writes.

Exact contiguous FileX preallocation was implemented and rejected on B before
publication. Both 128 KiB and 64 KiB first payload writes were followed by
USBX `UX_TRANSFER_TIMEOUT (0x5C)` failures, while allocation itself returned
success. The prior image remained intact. Preallocation is therefore excluded
from the selected safe path on this SSP/FileX/USBX/device combination.

Use the same buffer for large update reads. CRC preflight consumes each large
block before the next read; QSPI staging reads one large block and programs its
256-byte pages before reuse. Add public timing/write-shape telemetry so
performance claims come from firmware rather than debugger polling.

Do not format either SD card, normalize B, allocate a second multi-megabyte
buffer, increase the selected buffer without evidence, weaken payload CRC or
exact-read gates, or interrupt an update.

## Current State

Completed:

- Exact predecessor and complete dual-controller USB qualification are
  recorded in
  `work/evidence/usb-mass-storage-workflow-qualification-20260726.md`.
- The 128 KiB SDRAM/USBHS/USBX/FileX configuration already passed real CSV
  publication on B then A.
- One shared 128 KiB SDRAM window, buffered image save/read paths, retained
  telemetry, source/model gates, and clean-build memory proof are implemented.
- B preserved CID `035344535330384780976F0085018507`, abnormal lanes
  `86 / 86 / 1`, and the prior published image through both rejected
  preallocation trials.

Incomplete:

- Passing no-preallocation save/update performance qualification on B then A.
- Final flash/audio/config/CID/lane/Graph verification and evidence closeout.

## Goal

Reduce safe `.imx` backup and update time and A/B variance by eliminating
thousands of small USB transfers while preserving image integrity, rollback,
configuration, SD identity, logging, audio, and operator-ready Graph state.

## Why It Matters

Recovery-image operations currently take minutes and vary substantially across
the two installed USB devices. That discourages backups and increases operator
exposure time during maintenance. The product already pays for a qualified
large sequential buffer; reusing it is the lowest-resource deterministic
mitigation.

## Major Outcomes

- Rejected preallocation evidence plus atomic publication without replacing
  the prior image.
- At most one 256-byte header write plus bounded 128 KiB payload writes.
- Buffered exact-read CRC and QSPI staging with unchanged page verification.
- Firmware telemetry for allocation, build/copy, write, close, flush, rename,
  update read, QSPI program, and total durations plus call/byte maxima.
- Identical successor qualified on B then A and left Graph-ready.

## Delivery Stages

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

| Stage | Outcome | Entry Evidence | Exit Evidence |
| --- | --- | --- | --- |
| 1 | Safe implementation | exact predecessor/baselines | source/model gates |
| 2 | Exact successor | passing implementation | clean build/hash/map proof |
| 3 | Controller B | verified image and CID | save/update/integrity/timing pass |
| 4 | Controller A | selected B result | parity and timing pass |
| 5 | Handoff | dual-controller final state | Graph/docs/evidence/index closed |

## Related Artifacts

- Predecessor:
  `work/wp/completed/wp-qualify-all-usb-mass-storage-workflows-after-usbhs-tuning.md`
- USB tuning:
  `work/wp/completed/wp-move-hpt-usb-buffer-to-sdram-and-tune-usbhs-throughput.md`
- Evidence:
  `work/evidence/usb-mass-storage-workflow-qualification-20260726.md`
- Update contract: `docs/firmware-update-validation-and-recovery.md`

## Rough Sequence

1. Capture exact A/B firmware, CID, configuration, lanes, audio, USB, and
   Graph baselines.
2. Generalize the existing SDRAM buffer and add ownership/timing contracts.
3. Buffer `.imx` save while preserving atomic publication; reject contiguous
   preallocation if target evidence shows device incompatibility.
4. Buffer update CRC/staging reads and retain QSPI 256-byte verification.
5. Add source/model checks; run every host gate and isolated build/package.
6. Program B; save/remount/update/verify flash, audio, state, and timing.
7. Repeat on A and compare against predecessor upper bounds.
8. Restore Graph, promote current truth, capture evidence, and close Tool Shed.

## Milestones

### Milestone 1: Safe buffered implementation

Completion criteria:

- [x] One qualified 128 KiB SDRAM buffer is shared only by serialized USB work.
- [x] Exact preallocation was tested on B and safely rejected after target
  timeouts without replacing the prior image.
- [x] Save and update use bounded large transfers with exact-byte checks.
- [x] Atomic publication, CRC, QSPI, rollback, and failure contracts remain.
- [x] Telemetry makes phase timing, error status, and write shape target-visible.

### Milestone 2: Exact successor

- [x] All source/model/regression gates and isolated build/package pass.
- [x] S-record/ELF hashes and SDRAM/internal-RAM bounds are recorded.

### Milestone 3: B-first/A-second target qualification

- [x] B passes without CID/config/lane/retirement normalization.
- [x] A passes the selected B workflow.
- [x] Both self-updates match exact internal flash and restore audio tables.
- [x] Measured save/update results are compared with predecessor evidence.
- [x] Both Graph screens are active, current, and following newest.

## Open Questions

- Exact FileX contiguous preallocation is not safe on B: its interaction with
  subsequent BOT writes produces `UX_TRANSFER_TIMEOUT`. The selected path
  relies on ordinary FileX cluster growth under the unchanged atomic
  temp/close/flush/rename transaction.

## Completion Standard

This workpackage is complete when one exact clean-built image uses the existing
bounded SDRAM window to safely coalesce `.imx` save and update reads, exposes
target timing/write telemetry, passes every software gate, passes B-first and
A-second save/remount/update/flash/audio/state verification, preserves B's
abnormal media, and leaves both controls on a current Graph screen.

## Closeout Routing

- Current truth promoted to: `docs/firmware-update-validation-and-recovery.md`
- Historical context remains in: predecessor USB qualification workpackage
- Runtime/status evidence:
  `work/evidence/imx-shared-sdram-buffer-qualification-20260727.md`
- Cleanup deferred to: separately controlled update-interruption cases
