How raspberrypi/usbboot works
1. Repository purpose and overall shape
This repository is a hybrid of a host-side provisioning tool and a set of target boot payloads for Raspberry Pi devices. The host tool, rpiboot, talks over USB to a Pi in boot mode and serves it boot content from one of several payload directories.
2. Host-side boot server
The core application lives at the repository root (main.c, bootfiles.c/.h, decode_duid.c/.h, bin2c.c, fmemopen.c). This is the part that:
- discovers the connected Pi over USB,
- negotiates the boot protocol,
- exposes files from the selected boot image directory,
- and optionally emits device metadata from OTP/recovery operations.
3. Protocol and hardware boundary
The key architectural boundary is between the host PC and the Pi boot ROM / firmware over USB. rpiboot is not deploying a full OS directly; it is feeding the Pi’s early boot environment with just enough files and firmware to start a second-stage boot path.
4. Boot payload families
The repo contains several distinct payload types, each with a different target behavior:
- mass-storage-gadget/ and mass-storage-gadget64* for Linux-based provisioning,
- msd/ for the legacy firmware-based mass-storage path,
- recovery/ and recovery5/ for EEPROM recovery/update flows,
- secure-boot-recovery/ and secure-boot-recovery5/ for secure-boot provisioning,
- rpi-imager-embedded/ for running Raspberry Pi Imager on the target,
- secure-boot-example/ as a minimal secure-boot-oriented Linux initrd example.
5. Modern provisioning path vs legacy path
There are two main runtime models:
- Linux mass-storage gadget path: boots a Linux initramfs that scans storage devices and exposes them as USB mass storage using configfs; it can also provide UART/CDC console access.
- Legacy MSD path: boots a special VideoCore firmware that emulates the SD/eMMC as USB mass storage. This is simpler and faster to start, but less capable and lower-performing.
6. EEPROM and recovery subsystem
A major subsystem is the bootloader EEPROM update flow for CM4/CM5 and related devices. The recovery* directories package boot configs and binaries used to update the SPI EEPROM, while firmware/2711 and firmware/2712 hold the corresponding bootloader/recovery artifacts. The rpi-eeprom/ submodule supplies the upstream EEPROM tooling and metadata logic that these flows depend on.
7. Secure boot support
Secure boot is treated as a separate provisioning domain. The secure-boot-* directories contain boot images and configs for flashing bootloader state and provisioning OTP-related secure-boot settings. The docs under docs/secure-boot*.md and the example HSM wrapper files show that signing and key management are first-class parts of this workflow, not just build-time extras.
8. Boot image assembly and helper tools
The tools/ directory contains the utility programs and scripts used to generate boot images, sign boot content, extract OTP/private-key-related material, and update EEPROM assets. These tools are part of the build/release pipeline that turns source trees and firmware blobs into bootable directories and packaged artifacts.
9. Prebuilt firmware and boot assets
The repo includes many binary blobs checked in under firmware/, mass-storage-gadget64*/, secure-boot-example/, and the recovery directories. These are not source code in the usual sense; they are the concrete boot-time payloads that rpiboot serves to the device. They are effectively the deployable outputs of the repository.
10. Platform and packaging boundary
The project is designed to run on Linux, macOS, Windows/Cygwin, and WSL, but the runtime dependency is the same: libusb. The win32/ directory contains the Windows installer and launcher assets, while the main build is driven by Makefile. The README also describes install-time placement under /usr/share/rpiboot or platform equivalents.
11. Device-specific behavior
The repository is explicitly split by target generations:
- older devices that require legacy msd,
- BCM2711-era devices that use 2711 recovery assets,
- BCM2712-era devices that use 2712 assets,
- and newer Pi 5 / CM5 flows that require separate recovery and bootloader handling.
This matters for an architecture diagram because the boot content served depends on the detected SoC/device family.
12. Metadata and provisioning outputs
Some recovery flows can write structured metadata back to the host, such as OTP-derived board and EEPROM details. The README’s JSON example indicates that rpiboot is also a data extraction tool, not just a file server, when used with recovery images.
13. Documentation, CI, and validation
The docs/ directory provides the secure-boot and troubleshooting reference material, while .github/workflows/validate-hsm-wrapper.yml and test/validate-hsm-wrapper.sh indicate automated validation around secure-boot/HSM integration. This suggests the repo has both functional provisioning paths and regression checks around signing/tooling compatibility.
14. How to think about the architecture diagram
The cleanest diagram would show:
- a host-side rpiboot service,
- a USB link to a target Pi in boot mode,
- a set of selectable boot payload trees on disk,
- optional EEPROM/secure-boot provisioning flows,
- and the rpi-eeprom submodule / tools as the support layer for recovery and firmware update workflows.
Main entry points: main.c rpiboot · tools Tools · rpi-eeprom rpi-eeprom · bootfiles.c Boot files
Components 21
Host rpiboot
Host-side USB boot service and protocol handling.
- rpiboot · Main host application that discovers the Pi, speaks the boot protocol, and serves boot files.
main.c - Boot files · Maps the selected payload tree into files exposed over USB.
bootfiles.c - Device ID · Decodes device and recovery metadata returned by the target.
decode_duid.c - bin2c · Converts binary assets into C-friendly embedded data.
bin2c.c - fmemopen · Platform compatibility support for memory-backed file handling.
fmemopen.c
Boot payloads
Selectable boot trees served to the target Pi.
- MS gadget · Linux-based mass-storage gadget provisioning image.
mass-storage-gadget64 - MS gadget CM3 · Variant of the Linux mass-storage gadget flow for CM3-class targets.
mass-storage-gadget64-cm3 - Legacy MSD · Older firmware-based mass-storage provisioning path.
msd - Imager boot · Boot image that launches Raspberry Pi Imager on the target.
rpi-imager-embedded - Secure example · Minimal secure-boot-oriented Linux initrd example with signing artifacts.
secure-boot-example - Recovery 2711 · EEPROM recovery/update assets for BCM2711-era devices.
recovery - Recovery 2712 · EEPROM recovery/update assets for BCM2712-era devices.
recovery5 - Secure recovery · Secure-boot-oriented EEPROM recovery flow and boot configuration.
secure-boot-recovery - Secure recovery 5 · Secure-boot recovery flow for Pi 5 / newer EEPROM update paths.
secure-boot-recovery5
Firmware assets
Checked-in bootloader and recovery binaries for specific SoCs.
- FW 2711 · Prebuilt bootloader and recovery binaries for BCM2711 devices.
firmware/2711 - FW 2712 · Prebuilt bootloader and recovery binaries for BCM2712 devices.
firmware/2712 - rpi-eeprom · Upstream EEPROM tooling and metadata logic used by recovery flows.
rpi-eeprom
Build tools
Utilities used to assemble, sign, and release boot artifacts.
- Tools · Scripts and utilities for boot image generation, signing, and EEPROM updates.
tools
Support files
Documentation, packaging, CI, and validation helpers.
- Windows pkg · Windows launcher, installer, and redistribution assets.
win32 - Docs · Secure-boot and troubleshooting documentation.
docs - CI checks · Workflow and test coverage for HSM wrapper and signing integration.
.github/workflows/validate-hsm-wrapper.yml
Connections 25
- rpiboot → Boot files: serves · Main service resolves and exposes payload files.
- rpiboot → Device ID: reads · Host app decodes device metadata returned by recovery flows.
- rpiboot → MS gadget: boots · Selects the Linux gadget image for modern provisioning.
- rpiboot → MS gadget CM3: boots · Selects the CM3-specific Linux gadget image when needed.
- rpiboot → Legacy MSD: boots · Selects the legacy mass-storage firmware path for older devices.
- rpiboot → Imager boot: boots · Can serve the embedded Imager payload.
- rpiboot → Recovery 2711: boots · Serves EEPROM recovery assets for BCM2711 devices.
- rpiboot → Recovery 2712: boots · Serves EEPROM recovery assets for BCM2712 devices.
- rpiboot → Secure recovery: boots · Serves secure-boot recovery assets.
- rpiboot → Secure recovery 5: boots · Serves secure-boot recovery assets for newer devices.
- Boot files → FW 2711: uses · Recovery payloads draw on BCM2711 firmware assets.
- Boot files → FW 2712: uses · Recovery payloads draw on BCM2712 firmware assets.
- Recovery 2711 → rpi-eeprom: depends on · Uses upstream EEPROM tooling and config metadata.
- Recovery 2712 → rpi-eeprom: depends on · Uses upstream EEPROM tooling and config metadata.
- Secure recovery → rpi-eeprom: depends on · Secure recovery flows rely on EEPROM tooling.
- Secure recovery 5 → rpi-eeprom: depends on · Secure recovery flows rely on EEPROM tooling.
- Tools → Imager boot: builds · Generates and packages boot images and signed artifacts.
- Tools → Secure example: signs · Supports secure-boot image signing and key handling.
- Tools → Recovery 2711: updates · Produces EEPROM update assets and boot configs.
- Tools → Recovery 2712: updates · Produces EEPROM update assets and boot configs.
- Tools → Secure recovery: updates · Produces secure-boot recovery assets.
- Tools → Secure recovery 5: updates · Produces secure-boot recovery assets.
- Docs → Secure example: describes · Documentation explains secure boot and signing flow.
- CI checks → Tools: validates · Checks HSM wrapper and signing integration.
- Windows pkg → rpiboot: packages · Windows installer and launcher bundle the host tool.