# Spike: Ingest external USB host compatibility research

Status: complete
Type: spike
Research Depth: deep
Updated: 2026-08-01
Next Action: use this crosswalk as design input when the owner authorizes USB compatibility code changes; first inventory and trace the exact failing layer, then select only standards-based, device-class behavior
Campaign: 003-complete-bounded-hpt-slow-export-firmware-ticket
Parent: work/maps/map-smi-firmware-stabilization-and-qualification.md
Disposition: planned
Produces: work/wp/completed/wp-restore-broad-usb-compatibility-baseline.md
Canonical Truth: AGENTS.md broad USB mass-storage compatibility policy and docs/firmware-update-validation-and-recovery.md

## Question

What findings from the independent Codex research at
`E:/vsc_instances/usb_drive_research/research/` are sufficiently supported and
applicable to guide the next controller USB compatibility correction, without
mistaking proposed policy values or per-device desktop quirks for proven SMI
requirements?

## Timebox and Scope

One ingestion pass on 2026-08-01. Review all nine supplied files, preserve
source identity, compare their findings with the current repository policy,
active USB work, documentation, and representative USBX/FileX source surfaces,
and record future investigation gates. No firmware, vendored middleware,
configuration, build, deployment, or target operation is authorized by this
spike.

## Source Manifest

Research snapshot stated by the source: 2026-08-01. The files remain in the
external research workspace; this artifact preserves their identity and the
findings needed here. Hashes are SHA-256.

| File | Bytes | SHA-256 | Role |
| --- | ---: | --- | --- |
| `diagnostic-test-matrix.md` | 8,110 | `23E596A32274292E98575E9E160F0F743218208B57F5DFE20E9DE863F540187B` | stage-gated diagnostic and qualification matrix |
| `forum-findings.md` | 26,242 | `69A06C6A60F8C383FFD44AA1C268485870D84B32F9188D3CDC1855988A68936E` | normalized field reports and confidence labels |
| `host-hardening-blueprint.md` | 7,072 | `F16C9F76A8474A55A170C65CAC068A06B4CEBE29CD5A27D32C75AABA39406E30` | vendor-neutral architecture proposal |
| `problem-solution-catalog.md` | 15,473 | `CC01240AE9B39443A4BE6ED636EE925AEED03845DE51CDABF0924701B06B3183` | symptom-to-layer catalog |
| `research-method.md` | 2,378 | `AC5297168218B1F0FF45DDB59B62DF63FE42192137F9D62696E887F8C3ACAC50` | scope, inclusion criteria, and limits |
| `sources.csv` | 20,181 | `89D8831D0B50378233285E589C9674D28C4A070DD6D67F8D666290CCCA99CF56` | source ledger |
| `standards-and-mature-hosts.md` | 7,633 | `6E614D5F193C5A028DF70833821691C975D10C9DF80018DA093BBD56B04DFE1C` | USB-IF/T10 and Linux/FreeBSD synthesis |
| `wide-compatibility-profile.csv` | 20,801 | `30817CF42EE913D7C4981D8682CB541CA4A1E895E844591984C03B6658A6AA53` | machine-sortable proposed settings |
| `wide-compatibility-profile.md` | 32,327 | `183E6C64706E86DB80913D9638E7D962C5D7165DD1D77848DD181650A9A6B196` | conservative host-policy proposal |

## Evidence Classification

The research deliberately mixes four evidence classes: specification (`S`),
mature-host implementation (`M`), MCU vendor material (`V`), and derived
product policy (`P`). That distinction must survive ingestion.

- USB-IF/T10 requirements and directly inspected controller behavior are
  design constraints or evidence.
- Linux/FreeBSD behavior demonstrates useful recovery patterns, but their
  global tolerances and VID/PID quirk tables are not automatically suitable for
  this controller.
- Vendor reports and forum cases are diagnostic hypotheses unless their layer
  and mechanism are reproduced on SMI.
- Numeric defaults in the wide profile are proposed starting points, not USB
  requirements and not accepted SMI constants.

## Findings Accepted as Design Constraints

1. Diagnose by layer: power/PHY, enumeration/control, BOT, SCSI/sense,
   HCD/DMA/ownership, block geometry, FileX, and application publication must
   retain distinct outcomes. A mount failure alone does not identify the layer.
2. BOT framing and recovery must be auditable: a 31-byte CBW, 13-byte CSW,
   matching tag, valid status/residue policy, one command at a time, and the
   specification-ordered reset recovery of Mass Storage Reset, clear Bulk-In
   halt, then clear Bulk-Out halt. Host toggle state must match endpoint
   recovery.
3. `GET_MAX_LUN` STALL is a legal single-LUN result. It must not poison the
   control or class session.
4. A valid CSW command failure normally leads to `REQUEST SENSE`; malformed
   status, phase error, or transport failure belongs to BOT recovery. Sense
   outcomes such as unit attention, becoming ready, no medium, illegal request,
   and data protect require different bounded policies.
5. Unsupported optional commands are capabilities, not generic transport
   failures. The always-required production command surface should remain as
   small as the product workflow permits.
6. Transfer planning must respect both the SCSI request and the smaller proven
   HCD/DMA/alignment boundary. Exact-size failures should first reopen host
   descriptor, count, segmentation, cache, and ownership analysis.
7. Detach and retry behavior need connection-generation ownership, finite
   deadlines, cancellation, and exactly one host-stack owner context. No
   endpoint stall or dropped completion may leave a permanent `BUSY` state.
8. Raw-block proof precedes partition parsing and filesystem mount. Unsupported
   partition, sector, or filesystem geometry must not be reported as a USB
   disconnect.
9. “Saved,” “published,” “flushed,” and “safe to remove” are distinct claims.
   Write replay after an uncertain completion is unsafe unless identical
   LBA/data replay semantics and the frozen buffer are explicitly accepted.
10. Compact telemetry should retain connection generation, state/BOT phase,
    endpoint, requested and actual lengths, opcode, CBW/CSW fields, sense tuple,
    retry, recovery action, and the exact FileX/USBX/HCD status namespace.

These constraints reinforce, rather than replace, the repository-wide rule in
`AGENTS.md`: production firmware targets the standards-conforming MSC device
class and must not accumulate specimen-specific behavior.

## Proposed Policies Requiring SMI Validation

Do not implement these values merely because the research recommends them:

- 250 ms stable-attach debounce, 60 ms root reset, 50 ms recovery, four
  enumeration passes, or a 1 s post-configuration settle;
- 20.5 s Inquiry, 30 s ordinary command, 60 s flush, or 100 s becoming-ready
  windows;
- one zero-length-CSW retry, residue/signature tolerance, a fixed 6 s BOT-reset
  quiet interval, or three transport recoveries per connection;
- a 32 KiB SCSI command limit, 16 KiB HCD segment limit, 4 KiB/one-block read
  fallbacks, or one-block access in the final eight LBAs;
- Capacity(16), exFAT/GPT/4 KiB sector support, or multi-LUN support beyond the
  product's documented media contract;
- a VBUS cycle as an escalation rung.

Each is a testable candidate policy. Any adopted value must be traced to the
SSP 2.6.1/USBX/FileX and S7G2 USBHS implementation, measured on both controller
variants where relevant, and covered by the established representative drive
matrix. VBUS cycling remains qualification/diagnostic-only unless a separately
approved product requirement and standards analysis changes that rule.

## Workspace Crosswalk

| Research area | Current workspace evidence | Ingestion disposition |
| --- | --- | --- |
| Minimal production lifecycle | Active workpackage already removed mandatory optional SCSI, VBUS cycle, re-enumeration, remount, and full reread from normal exports | preserve; do not regress |
| Transfer size | Current vendored `UX_HOST_CLASS_STORAGE_MAX_TRANSFER_SIZE` is 1,024 bytes; the application HPT publication cap and observed 32 KiB FileX call shape are a different boundary | future audit must distinguish FileX request, CBW data length, USBX chunk, and HCD segment before changing any constant |
| Enumeration recovery | Repeated below-class first-insertion misses motivated one bounded recovery attempt per physical attachment; deterministic proof is the current operational next action | retain the narrow proof; do not infer broader timing changes yet |
| Sense handling | Vendored USBX has REQUEST SENSE and readiness paths, but the completeness of sense classification and optional-command fallback has not been established here | inventory exact current paths before modification |
| BOT recovery | Stock transport sources perform BOT operations, but this ingestion did not prove exact CBW wire length, CSW edge handling, toggle recovery, or full reset-recovery ordering on S7G2 | packet/source audit plus deterministic tests required |
| Optional probes | Vendored source contains MODE SENSE, READ FORMAT CAPACITY, START STOP, and related paths | identify which commands the actual configured production lifecycle reaches; disable or alter nothing until traced |
| Status observability | Existing diagnostic candidates retain USBX/HCD/application state, but the research calls for finer BOT/SCSI fields and namespace separation | extend only after an explicit telemetry design review |
| Filesystem geometry | Current product qualification is FAT-oriented; broad exFAT/GPT/4 KiB claims are not established | document supported media contract or qualify extensions separately |
| Desktop quirks | Linux/FreeBSD contain extensive per-device exceptions and generic tolerances | use them to identify failure classes, never as authorization for VID/PID production tables |

## Diagnostic Order for the Next Failure

Before changing firmware for another drive, collect the smallest evidence that
locates the boundary:

1. Preserve canonical drive identity and topology; distinguish direct root
   port, powered hub, and reference-host observations.
2. Record the last successful enumeration/control/BOT/SCSI/FileX/application
   phase and the exact raw status namespace.
3. Determine whether the failure is before class activation, a valid SCSI check
   condition, a BOT transport/phase error, an HCD/DMA boundary, or a filesystem
   condition.
4. For transfer-size failures, test immediately below, at, and above the
   suspected FileX, USBX, HCD, DMA, and alignment boundaries with unchanged
   media and workload.
5. Use sense data or packet/transport tracing before selecting retry, clear
   halt, BOT reset, port reset, or quarantine.
6. Regress the complete established drive/controller matrix and explain why
   the correction generalizes to unseen standards-conforming devices.

Physical USB insertion/removal remains the controller's normal powered
operation. This research ingestion does not authorize destructive media tests,
controller-driven VBUS cycling, deployment, or hardware fault injection.

## Recommendation

Use the research as a design and diagnostic crosswalk inside
`work/wp/completed/wp-restore-broad-usb-compatibility-baseline.md`. When code work
is authorized, begin with a read-only transaction/state-machine inventory and
a failure-layer trace. Prioritize specification violations and generic state,
ownership, timeout, sense, and recovery defects. Do not begin by importing the
wide profile's constants, enabling optional commands, or adding drive identity
rules.

## Follow-Up

- [x] Review and hash all nine external research files.
- [x] Separate specification/mature-host evidence from proposed product policy.
- [x] Cross-reference the findings with the active USB workpackage and current
  SSP 2.6.1 USBX/FileX surfaces.
- [x] Record the no-code-change boundary.
- Historical planning item: After explicit authorization, inventory the exact production command and
  recovery paths from FileX through USBX and S7G2 USBHS.
- [x] Add deterministic tests only after the inventory identifies the
  standards or architecture gap they are intended to prove.
- [x] Reconcile the stale USB cache-compatibility section in
  `docs/firmware-update-validation-and-recovery.md` with the newer active
  workpackage before treating that document as current production truth.

## Post-ingestion application

On 2026-08-01 the authorized BOT follow-up identified the firmware's linked
blocking path as `ux_host_class_storage_transport_bo.c`, not the separately
compiled-out standalone transport. The active path lacked exact CSW length,
signature, tag, residue, and status validation; its shared reset helper already
used the required Reset/Bulk-In/Bulk-Out order. Commit `ca6f573a` adds only the
missing command-class CSW checks, with deterministic malformed-CSW coverage
and a bounded Controller B normal-drive smoke. See
`work/evidence/usb-bot-csw-validation-and-smoke-20260801.md`.
