# Training on an RX 580 through a USB storage bridge

A blog-agent handoff and source distribution for one hardware experiment:
an externally powered RX 580, an M.2-to-PCIe riser, and an RTL9210B NVMe-to-USB
enclosure. A standalone userspace runtime ran real FP32 transformer training
without replacing the enclosure firmware.

## Start here

- [Blog brief](BLOG_BRIEF.md): suggested angle, outline and editorial facts.
- [Hardware and wiring](HARDWARE.md), with an editable [SVG diagram](assets/wiring.svg).
- [Technical story](STORY.md): the obstacles, decisions and solutions.
- [Measured results](RESULTS.md): workload definitions and scoped comparisons.
- [Reproduction guide](REPRODUCING.md): building, configuration and execution.
- [Source map](SOURCE_MAP.md): where the relevant implementations live.
- [Third-party sources](THIRD_PARTY.md): attribution and pinned dependencies.
- [Verification](VERIFICATION.md): checks performed on this distribution.

`runtime/` and `training/` contain the working execution path. `research/`
contains the earlier firmware-analysis, discovery and VM work, clearly separated
from training. `deployment/` contains editable configuration, not machine state.
`SOURCE_MANIFEST.json` records every packaged source revision and file digest.

The runtime supports buffers, tensors, externally compiled gfx803 kernels,
resident execution plans, buffered submissions, telemetry and checkpoints.
The included transformer harness implements the particular 11.64M baseline
used here; the lower-level runtime is not tied to that model.

Model weights, datasets, installed firmware blobs, device identities, local
service configuration and Git history are not bundled. The small runtime
training smoke workflow uses generated inputs; reproducing the recorded full
baseline additionally requires its frozen corpus and seeded initialization.

No hardware is accessed by unpacking or building the project. Device-access
commands are explicitly identified in the reproduction guide.