# Migrate USB VBUS control out of SSP Workpackage

Status: complete
Type: workpackage
Updated: 2026-08-17
Next Action: none
Campaign: 008-prove-usb-vbus-adapter-regeneration-safety
Project Map: work/maps/map-smi-firmware-stabilization-and-qualification.md
Canonical Truth: docs/firmware-update-validation-and-recovery.md

## 2026-08-17 Regeneration and Build Closeout

The owner authorized and one e2 Studio `Generate Project Content` action was
performed. The user-owned adapter and `configuration.xml` retained their exact
recorded hashes. e2 also rewrote or reverted unrelated managed/vendor files;
that churn was rejected back to the clean checkpoint before any build, and no
generated source change was admitted.

The Aug. 9 raw hashes for the two SSP power stubs were not reproducible from
Git, e2 output, Eclipse local history, or available workspace copies. Git
history instead proves both files unchanged since the SSP 2.6.1 update commit
`f8dad720`; the working files match those Git blobs and remain unsupported
stubs. The historical artifact was preserved and the discrepancy is
adjudicated in
`work/evidence/usb-vbus-adapter-regeneration-safety-closeout-20260817.md`.

The focused USB workflow check, canonical Debug and Release rebuilds, and all
27 repository invariant suites passed. The Release S-record remained
`D1FBFC257043DFFB04DA9B883F26992DF4D8EE1525089BE63485E43A0519E761`.
No target, USB-drive, deployment, programming, or production-lifecycle action
occurred. This satisfies the current completion standard; the unchecked
historical production-power-cycle items below remain superseded and do not
gate this diagnostic-only closeout.

## 2026-08-01 Semantic Reconciliation

This workpackage remains active for one repository-ownership gate only: prove
that a clean e2 regeneration and canonical rebuild preserve the user-owned
diagnostic VBUS adapter while leaving the vendor SSP power stubs unchanged.
That gate requires separate build authorization and no controller action.
If a later target regression is separately authorized, the exact SMI bundle and
test contract are handed to the `srv-rpi00.local` qualification app; this
workspace does not coordinate Controller A/B execution.

The production power-cycle, SYNCHRONIZE CACHE, STOP UNIT, remount, retry, and
full-reread lifecycle planned below is superseded historical planning. It is
not a current product requirement. The canonical production policy is the
minimal FileX lifecycle in `docs/firmware-update-validation-and-recovery.md`.
The adapter is retained only as a guarded diagnostic/qualification surface.

Controller A and B electrical proof, functional parity, legacy-media evidence,
and the 32 KiB production baseline are complete. Interruption and additional
electrical campaigns are separate qualification profiles and do not block this
adapter-migration closeout. Nothing in this package authorizes reopening T00,
changing Controller B, or adding a production VBUS lifecycle.

## Current Context

The Renesas SSP implementations of `ux_hcd_synergy_power_down_port()` and
`ux_hcd_synergy_power_on_port()` are unsupported stubs. A diagnostic candidate
temporarily corrected those vendor files and physically proved USB VBUS removal
on Controller A, including successful legacy-General-UDisk qualification.
Editing SSP-owned source is undesirable because an e2 regeneration or SSP
refresh can overwrite the change.

The controller has one USB host port. Deliberate VBUS removal affects every USB
function even though ordinary reads, writes, enumeration, and mounting do not
use the power-cycle path.

## Superseded 2026-07-28 Recommendation

Restore the vendor SSP power files unchanged and move physical VBUS ownership
into a user-owned `src/UsbVbusControl.c/.h` adapter. The adapter will use the
exposed Synergy HCD register helpers to control and read back
`DVSTCTR0.VBUSEN`. All durability workflows will call the adapter through one
serialized Thread_Usb operation.

Keep the VBUS migration and 64 KiB HPT write-size change in separate
candidates. First prove that the user-owned VBUS adapter preserves behavior at
the current production write sizes. Only then create a second candidate whose
sole intended behavioral change is the 64 KiB HPT maximum FileX write.

The owner authorized plan execution, deployment, and end-to-end qualification
on 2026-07-28.

## Goal

Provide regeneration-safe, fail-closed physical USB power control without
altering normal USB behavior or allowing one USB workflow to invalidate
another.

## Scope

Included:

- user-owned USBHS VBUS adapter;
- register-state readback and invalid-target rejection;
- serialized, port-wide power-cycle coordination;
- stale FileX/USBX object audit after disconnect and remount;
- exact-sense legacy compatibility integration;
- clean-regeneration protection;
- complete Controller A and B USB parity qualification.

Excluded:

- adding a customer USB-format feature;
- changing the separately selected 64 KiB production HPT write-size cap during
  the VBUS-control migration;
- changing USB connector hardware;
- executing builds, deployment, or physical tests without separate authority.

## Historical Delivery Stages

| Stage | Outcome | Entry gate | Exit evidence |
| --- | --- | --- | --- |
| 1 | Design freeze | owner approves execution | adapter, workflow, retry, STOP, and diagnostics contracts reviewed |
| 2 | Isolate vendor code | VBUS-only rollback captured | SSP files restored; user adapter builds at current write sizes |
| 3 | Integrate safely | adapter unit/static checks pass | every VBUS cycle routes through one Thread_Usb helper |
| 4 | Regeneration proof | correct managed builder selected | clean e2 regeneration preserves behavior and checks |
| 5 | Deploy VBUS-only A | exact image and rollback hashes | program/verify and electrical VBUS proof |
| 6 | USB parity A | physical VBUS proof passes | all USB functions, interruption recovery, and legacy compatibility pass |
| 7 | Deploy/qualify VBUS-only B | A gates and B hardware review complete | Controller B electrical and functional parity |
| 8 | Larger-cap disposition | VBUS-only A/B candidate accepted | no action; owner accepted 32 KiB and declined 64 KiB-or-greater pursuit |
| 9 | Promote | A/B evidence complete | diagnostic cleanup, current docs, and release gates updated |

## Historical Planned Implementation

### User-owned adapter

- Add `UsbVbusControl_Enable()` and `UsbVbusControl_Disable()`.
- Validate the active HCD pointer, controller base, and single root-port index.
- Select polarity for the active USBHS/USBFS controller rather than assuming
  the USBHS macro universally.
- Set or clear `DVSTCTR0.VBUSEN` through the existing SSP register helpers.
- Read the register back and return failure if it does not match the requested
  electrical state.
- Keep calls serialized under Thread_Usb ownership.

### Fail-closed power-cycle contract

1. Reject the request if another USB operation is active.
2. Close and flush the operation's files.
3. Use SYNCHRONIZE CACHE when supported.
4. Issue SCSI STOP UNIT.
5. Require a bounded post-STOP cache-quiescence interval before removing
   VBUS; STOP command success alone is not proof that a legacy drive has
   finished internal flash programming.
6. Disable VBUS through the user adapter.
7. Require an observed disconnect; API success alone is insufficient.
8. Maintain the qualified off interval.
9. Re-enable VBUS and require fresh enumeration and FileX remount.
10. Reacquire media, storage, and file objects; do not reuse stale pointers.
11. Use a bounded post-remount readiness check before opening the published
    file; a mount callback can precede directory/file availability.
12. Verify exact size/markers and completely reread the published file.
13. Report success only after every required stage passes.

The physical power cycle occurs once per completed published file, never once
per transfer chunk or ordinary FileX flush.

### Workflow coverage

Use the durability/fallback contract for every operation that publishes a file
to customer USB media:

- HPT CSV export;
- firmware/image backup;
- PID capture/export;
- any additional customer-created USB file.

Read-only WAV discovery/use and firmware-update input do not require a
durability power cycle. They must nevertheless be idle before VBUS removal and
must not begin until fresh enumeration/remount completes.

### Legacy-media policy

- Detect synchronize-cache capability from the inserted device's actual SCSI
  command result rather than manufacturer, model, capacity, or USB ID.
- Select compatibility only for SYNCHRONIZE CACHE sense key `0x05`, ASC
  `0x24`, ASCQ `0x00`.
- Classify the drive as `sync supported`, `sync unsupported`, or `failed` for
  the current enumeration session.
- Cache `sync unsupported` only for that physical USB session so subsequent
  publications do not repeatedly treat the expected unsupported command as a
  new fault.
- Clear the classification on disconnect, VBUS removal, replacement, failed
  enumeration, or controller reboot; a newly enumerated device must be
  detected independently.
- Keep transport errors, timeouts, medium/hardware errors, and every other
  sense response terminal.
- Retain the five-second VBUS-off interval and complete post-remount CRC
  verification for compatibility publication.
- For `sync unsupported`, substitute physical VBUS removal, fresh
  enumeration/remount, and complete file reread as the durability barrier.
- Never use the fallback to convert an ordinary write, transport, media,
  hardware, remount, or verification failure into success.

### STOP UNIT policy decision

Before implementation, decide and document how an otherwise healthy device
that rejects SCSI STOP UNIT is handled:

- default fail-closed behavior is terminal failure;
- an optional unsupported-STOP fallback may proceed only for a precisely
  identified unsupported-command sense response;
- if authorized, it must still require physical VBUS loss, fresh remount, and
  complete reread;
- timeouts, transport failures, medium/hardware errors, and all other sense
  responses remain terminal.

Do not infer unsupported STOP from manufacturer/model identity and do not
silently ignore a failed STOP command.

### Retry and operator policy

- Use one bounded disconnect/remount timeout.
- Permit at most one separately defined controlled retry.
- Never enter an indefinite USB power-cycle loop.
- After the retry budget is exhausted, stop with a terminal `USB write error`.
- Compatibility fallback is normally transparent to the customer.
- Service telemetry must identify the exact failed phase rather than requiring
  the operator to diagnose SCSI details.
- If insertion, enumeration, mounting, or the bounded initialization recovery
  establishes that the currently detected device cannot be used, disable USB
  operations for that insertion and display:

  **The detected USB drive cannot be used with this control. Remove it and
  insert another USB drive.**

- Do not describe the USB model as permanently unsupported. Clear the unusable
  state after physical removal and evaluate the next insertion independently.
- If a drive initially mounted but a later publication operation fails, retain
  the operation-specific message:

  **The USB operation failed and the file may not have been saved. Remove the
  drive and try another USB drive.**

- Do not show a warning when an exact unsupported-command response enters the
  compatibility fallback and physical power-cycle/remount/full-file
  verification succeeds.

### Service telemetry

Record at least:

- synchronization supported, unsupported, or failed;
- sense key, ASC, and ASCQ;
- STOP result and sense data;
- fallback attempted and retry count;
- requested and read-back VBUS register states;
- disconnect, off, and remount timing;
- exact-size/marker and complete-reread results;
- final operation result and first failure phase.

## Historical Full USB Impact Audit

The following functions must be idle during a VBUS cycle and must pass parity
after the migration:

- USB insertion, enumeration, removal, and reinsertion;
- WAV discovery and file use;
- firmware image discovery and update;
- firmware/image backup;
- PID capture/export;
- HPT CSV export;
- diagnostic write-size publication;
- HPT CSV publication at the selected 64 KiB maximum FileX write size;
- compatible and legacy USB media;
- failure reporting, retry, and recovery.

The audit must identify every cached `FX_MEDIA`, `FX_FILE`,
`UX_HOST_CLASS_STORAGE`, and device pointer and prove it is either not retained
across disconnect or is reacquired after remount.

## Historical Hardware Revision Gate

- Record the display-board assembly/revision for each controller.
- Confirm its VBUS-enable polarity, switch topology, overcurrent path, and USB
  connector power route before programming.
- Do not transfer Controller A electrical proof to Controller B or another
  hardware revision without schematic equivalence or a separate illuminated-
  stick/electrical proof.

## Current Regeneration Gate and Historical Build Gates

- No application source calls the SSP power-on/off stubs.
- Vendor SSP power files match their preserved baseline.
- Every physical power request routes through the user adapter.
- Adapter checks controller identity, polarity, register write, and readback.
- Durability success requires disconnect, remount, and complete verification.
- Correct managed e2 builder is used.
- Debug and Release builds pass.
- All repository check suites pass.
- A clean e2 regeneration followed by rebuild does not remove or bypass the
  adapter.
- VBUS-only and 64 KiB candidates have separately recorded source/artifact
  identities so a failure can be attributed to one behavioral change.

## Historical Physical Qualification Gates

- Capture exact firmware hashes, J-Link identity, rollback image, and SD CID
  block before each controller campaign.
- Prove VBUS removal with an illuminated stick on Controller A and Controller B.
- Prove that a missing disconnect cannot report success.
- Run compliant-media USB parity on each controller.
- Repeat the 1 MiB and 7 MiB legacy General UDisk qualification.
- On Controller B, specifically repeat the USB02_8G legacy-drive case
  (historical label A-CTRL) that
  created exact-size directory entries but lost cached payload data after
  immediate VBUS removal. Pi evidence showed a clean FAT, a partly correct
  16 KiB file, and erased `0xFF` payloads in the remaining tiers. Do not accept
  file size or FileX write success as durability evidence.
- Interrupt whole-controller power separately during file write,
  close/rename, VBUS-off, remount, and complete verification; after reboot the
  prior request must not report success or reuse stale USB state.
- Prove the timeout/retry budget terminates without an endless cycle.
- Independently verify exact sizes, hashes, byte equality, and unmounted FAT
  consistency on `srv-rpi00.local`.
- Repeat reboot and bounded lifecycle cycles before production promotion.

## Historical Milestones

### Milestone 1: Design and isolation

- [x] Owner separately authorizes execution.
- [x] Adapter contract and call-site inventory are reviewed.
- Historical planning item: STOP UNIT policy, retry budget, operator behavior, and service telemetry
  are reviewed.
- [x] SSP files are restored to the vendor baseline.
- [x] User-owned adapter replaces all application power calls.

### Milestone 2: Fail-closed integration

- Historical planning item: Invalid HCD, port, polarity, writeback, disconnect, and remount paths fail.
- Historical planning item: No stale USBX/FileX pointer crosses a physical disconnect.
- Historical planning item: Concurrent USB work is rejected or deferred safely.
- Historical planning item: Exact-sense legacy behavior remains narrowly gated.
- Historical planning item: Per-enumeration SCSI capability state is cleared and redetected whenever
  the USB device identity/session changes.
- Historical planning item: Unsupported-sync media uses the physical-VBUS/full-reread fallback while
  all other SCSI and USB failures remain terminal.
- Historical planning item: Every customer USB write workflow uses the publication durability
  contract, and every read-only workflow is excluded during a VBUS cycle.
- Historical planning item: One power cycle occurs per completed file, not per write or flush.
- Historical planning item: Retry and timeout behavior is bounded and terminal.
- Historical planning item: Insertion-time unusable media displays the approved detected-drive
  message and blocks USB operations until physical removal.
- Historical planning item: Successful compatibility fallback remains transparent, while a later
  failed publication states that the file may not have been saved.

### Milestone 3: Regeneration and build safety

- [x] Correct managed Debug build passes.
- [x] Correct managed Release build passes.
- [x] Repository checks pass.
- [x] Clean e2 regeneration preserves the implementation and checks; unrelated generated churn was rejected.

### Milestone 4: Controller A qualification

- [x] VBUS-only candidate is qualified on Controller A at the existing production write sizes.
- [x] Electrical VBUS proof passes on Controller A.
- [x] Complete USB feature parity passes on Controller A.
- [x] Legacy General UDisk qualification passes on Controller A.
- Historical planning item: Controlled interruption at each publication/power/remount phase recovers
  without false success or stale state.
- Historical planning item: Independent Pi verification is clean.

### Milestone 5: Controller B and production promotion

- [x] Controller B has a separate illuminated-drive electrical VBUS proof.
- [x] Controller B compliant-drive USB feature parity passes, including WAV,
  PID, image backup/update, real HPT export, 1 MiB and 7 MiB tiers, and
  independent Pi verification.
- [x] Controller B legacy General UDisk durability passes after a legacy-only
  five-second post-STOP cache-quiescence barrier. Both 1 MiB and 7 MiB
  16/32/64/96 KiB tiers passed controller verification; independent Pi FAT,
  exact-size, known-hash, edge-byte, and byte-equality gates passed.
- [x] Controller A passed the identical legacy 1 MiB and 7 MiB tier sets on
  the same frozen candidate, followed by independent Pi FAT, known-hash, and
  byte-equality verification.
- [x] A 64 KiB-or-greater successor is dispositioned as no action by owner
  decision; any future reopening must use a separate candidate, rollback,
  hashes, A/B qualification, lifecycle, specimen, and independent Pi evidence.
- Historical planning item: Reboot and lifecycle gates pass.
- Historical planning item: Vendor SSP files match baseline and diagnostic-only surfaces are removed
  or intentionally retained behind a documented service guard.
- Historical planning item: Current documentation is updated.
- Historical planning item: Production candidate and rollback artifacts are recorded.

## Stop Conditions

- Do not build, deploy, program hardware, power-cycle USB, or modify SSP files
  from this plan without separate owner authorization.
- Stop if the managed builder regenerates or changes unrelated SSP content.
- Stop if VBUS register readback disagrees with the requested state.
- Stop if disconnect/remount evidence is absent.
- Stop if any other USB workflow is active or any stale object remains in use.
- Stop if the VBUS-only candidate contains the 64 KiB HPT change.
- Stop if Controller B hardware equivalence has not been established.
- Stop if interruption recovery can reuse or report success for the prior
  incomplete request.

## Related Artifacts

- `work/evidence/controller-a-usb-vbus-electrical-proof-20260728.md`
- `work/evidence/controller-a-general-udisk-legacy-compatibility-qualification-20260728.md`
- `work/wp/active/wp-characterize-usb-filex-write-size-durability.md`
- `work/wp/completed/wp-mitigate-and-diagnose-hpt-usb-publication-durability.md`
- `docs/firmware-update-validation-and-recovery.md`

## Completion Standard

The workpackage is complete when one separately authorized clean e2
regeneration and canonical rebuild prove that the user-owned diagnostic adapter
survives and the vendor SSP power stubs remain unchanged. Existing A/B
electrical and functional evidence is retained; no production VBUS lifecycle,
target campaign, interruption campaign, or Controller B change is required for
this closeout.
