# Move HPT USB buffer to SDRAM and tune USBHS throughput Workpackage

Status: complete
Type: workpackage
Updated: 2026-07-26
Next Action: retain exact image 6484150E...A236E1A for remaining HPT release gates

Project Map: work/maps/map-smi-firmware-stabilization-and-qualification.md
Parent: work/wp/active/wp-triple-mirrored-circular-hpt-log-store.md
Depends On: work/wp/completed/wp-tune-hpt-usb-csv-buffer-window.md
Canonical Truth: docs/sd-card-operation-and-recovery.md

## Current Context

The accepted image uses a statically allocated `32 KiB` HPT CSV buffer in the
S7G2's `640 KiB` internal SRAM. Its exact link leaves `18.6 KiB` after all
configured heap and stacks. The external `32 MiB` SDRAM has approximately
`5.34 MiB` free after display, export, graph-cache, and SD-check sections.

The accepted real exports are approximately `90 KiB`. A completed in `0.45 s`
of USB publication using three FileX writes; B completed in `2.04 s`, including
`0.69 s` in three writes and `0.55 s` in the two required durable media
flushes. B intentionally retains abnormal lane starts `86 / 86 / 1`.

USBHS already uses DMAC channels 0 and 1 at interrupt priority 2 while USBHS is
priority 3. High speed is enabled and no isochronous pipes are reserved. The
remaining generated defaults are conservative: a 512-byte bulk FIFO, 1 KiB
FileX media buffer, and 1 KiB maximum BOT data phase. USBX has 128 TDs and a
63,488-byte internal pool.

Renesas material supports static placement in SDRAM and identifies large
sequential transfers, DMAC, maximum USBHS FIFO, increased FileX memory, and
increased BOT transfer size as the relevant performance controls. The SSP
2.6.1 metadata supports a maximum `2 KiB` USBHS FIFO and explicitly says larger
BOT phases improve throughput when enough TDs are configured.

## Recommendation

Move only the HPT CSV aggregation buffer into a dedicated, linker-guarded
SDRAM section. Default it to the Renesas-supported `128 KiB` throughput knee
and reject any build above the owner-authorized `1024 KiB` maximum. Retain
complete-row buffering and direct fallback for a record larger than the
window.

Set the supported USBHS FIFO maximum (`2 KiB`), a `128 KiB` BOT phase, and an
`8 KiB` FileX media buffer. Keep the current 128-TD pool: at a 2 KiB payload a
128 KiB phase uses 64 data TDs plus control/tail overhead, leaving margin.
Increase the USBX pool by exactly the added 7 KiB FileX buffer allocation so
the tuning does not consume its existing reserve.

Do not remove close/flush/rename/final-flush durability, preallocate the FAT
file, change CSV content, format or normalize B, alter SD configuration, or
request powered media removal. Do not increase the BOT phase beyond 128 KiB
without separately increasing and requalifying the TD and internal-memory
pools.

## Current State

Completed:

- Accepted 32 KiB internal-SRAM predecessor is qualified on B then A.
- SDRAM capacity and section ordering were audited from the accepted map.
- USBHS/DMAC priorities and SSP-supported FIFO values were audited.
- USBX BOT, FileX memory-buffer, TD, and pool limits were audited.
- The selected 128 KiB candidate passed B twice, A once, Graph restoration,
  Tool Shed closeout, index refresh, and stale-path validation.

Incomplete:

- None for this workpackage. Remaining release gates belong to the active
  parent workpackage.

## Goal

Install one exact image on both controls that publishes HPT CSV data from a
bounded static SDRAM buffer through the fastest supported and measured safe
USBHS configuration, while preserving export durability, card identity, lane
state, and operator Graph behavior.

## Why It Matters

Long retained-range exports are operator-facing. The current application
buffer reduced FileX calls, but the USB stack still splits each call into 1 KiB
BOT phases and the large buffer consumes scarce internal SRAM. Moving the
buffer frees internal margin while the supported USBHS/USBX tuning reduces
protocol overhead without weakening the publication transaction.

## Major Outcomes

- Recover the 32 KiB internal-SRAM allocation and retain at least the
  predecessor's configured heap/stack margin.
- Place the aggregation window in a non-overlapping SDRAM section with link
  assertions and a hard `1024 KiB` build ceiling.
- Use the supported 2 KiB USBHS FIFO and a BOT size that fits the existing TD
  pool with margin.
- Measure the complete HPT staging, USB publication, write, close, flush, and
  rename phases on real media.
- Leave B's abnormal layout and both controls' CIDs unchanged.
- Restore both Graph screens on the selected exact image.

## Delivery Stages

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

| Stage | Outcome | Entry Evidence | Exit Evidence |
| --- | --- | --- | --- |
| 1 | Implement memory and USB stack tuning | Accepted map and SSP metadata audit | Source gates and clean candidate build |
| 2 | Prove SDRAM/DMAC compatibility on B | Exact candidate hash and baseline CID/lane capture | Successful durable export with no gaps/errors |
| 3 | Select the safe buffer knee | 128 KiB B result and Renesas knee | Measured comparison and explicit size disposition |
| 4 | Qualify the winner | B-first result | B repeat, A result, identical image and preserved state |
| 5 | Restore and close | Qualification evidence | Both Graphs active, docs current, Tool Shed package complete |

## Related Artifacts

- Evidence:
  `work/evidence/hpt-usb-sdram-buffer-and-usbhs-tuning-20260726.md`
- Predecessor:
  `work/evidence/hpt-usb-csv-buffer-window-tuning-20260726.md`
- Renesas USB performance discussion:
  `https://community.renesas.com/mcu/synergy-mcu/f/forum/15485/how-to-increase-the-speed-of-writing-to-usb-flash-driver-ssp-1-7-0`
- Renesas static SDRAM allocation discussion:
  `https://community.renesas.com/mcu/synergy-mcu/f/forum/10733/synergy---how-can-i-setup-the-heap-to-use-sdram/36661`
- Renesas USBX Synergy Port Framework guide:
  `https://www.renesas.com/en/document/apn/usbx-synergy-port-framework-module-guide-application-project`

## Rough Sequence

1. Add `.smi_usb`, source placement, maximum guard, and invariant checks.
2. Apply the supported FIFO, BOT, FileX buffer, and USBX pool configuration.
3. Run source/model gates and build the exact candidate.
4. Verify section placement, internal headroom, SDRAM headroom, and hashes.
5. Capture B baseline, program B, export, and compare against 32 KiB.
6. If 128 KiB does not establish the supported knee, test only the next
   justified window up to `1024 KiB`; otherwise retain 128 KiB.
7. Repeat B on the selected image, qualify A, and calculate 30/90-day
   projections.
8. Restore Graphs, promote evidence/current truth, close Tool Shed work, and
   leave the reviewed change set ready for the active parent release gates.

## Milestones

### Milestone 1: Static and build proof

Completion criteria:

- [x] HPT USB buffer links in external SDRAM, not internal SRAM.
- [x] Section ordering and capacity assertions pass.
- [x] Builds over `1024 KiB` fail at preprocessing/link time.
- [x] Generated configuration and `configuration.xml` agree.
- [x] Repository checks, models, and isolated build pass.

### Milestone 2: Controller B tuning proof

Completion criteria:

- [x] Same-run CID block matches `035344535330384780976F0085018507`.
- [x] Oldest starts remain `86 / 86 / 1`, active starts remain
  `1109 / 1109 / 1024`, and retirements remain `2 / 1 / 0`.
- [x] Export completes and publishes with zero gaps, errors, fallbacks, or
  drops.
- [x] File write count and every publication phase are recorded.
- [x] Buffer size is selected by measured result and the Renesas 128 KiB knee,
  not by consuming the owner-authorized maximum by default.

### Milestone 3: Dual-controller acceptance

Completion criteria:

- [x] Selected exact image repeats successfully on B and then passes A.
- [x] A CID matches `035344535330384780976F0084018559`.
- [x] Temporary-file/count/trailer/close/flush/rename/final-flush ordering is
  unchanged.
- [x] 30- and 90-day projections are compared with the 32 KiB predecessor.
- [x] Both controls are left on active, current, follow-newest Graph screens.

## Open Questions

- Resolved: B's cold durable flush remains the dominant variable phase; its
  repeat result removes that penalty.
- Resolved: `128 KiB` produces one write for every measured export, so larger
  application windows have no benefit for this workload.

## Completion Standard

This workpackage is complete when a single exact image with a statically
allocated SDRAM aggregation buffer of no more than `1024 KiB` passes all
software gates, real B-first/A-second exports, CID and lane-state preservation,
durability checks, performance comparison, and operator Graph restoration.

## Closeout Routing

- Current truth promoted to: `docs/sd-card-operation-and-recovery.md`
- Historical context remains in:
  `work/evidence/hpt-usb-csv-buffer-window-tuning-20260726.md`
- Runtime/status evidence:
  `work/evidence/hpt-usb-sdram-buffer-and-usbhs-tuning-20260726.md`
- Cleanup deferred to: none
