# raspberrypi/usbboot architecture

> Architecture diagram of the GitHub repository raspberrypi/usbboot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raspberrypi/usbboot
- Repository: https://github.com/raspberrypi/usbboot

## Overview

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`](https://github.com/raspberrypi/usbboot/blob/master/main.c) (rpiboot), [`tools`](https://github.com/raspberrypi/usbboot/tree/master/tools) (Tools), [`rpi-eeprom`](https://github.com/raspberrypi/usbboot/tree/master/rpi-eeprom) (rpi-eeprom), [`bootfiles.c`](https://github.com/raspberrypi/usbboot/blob/master/bootfiles.c) (Boot files)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host rpiboot"]
  node_main["rpiboot<br/>USB boot server<br/>[main.c]"]
  node_bootfiles["Boot files<br/>file resolver<br/>[bootfiles.c]"]
  node_duid["Device ID<br/>metadata decode<br/>[decode_duid.c]"]
  node_bin2c["bin2c<br/>embed helper<br/>[bin2c.c]"]
  node_fmemopen["fmemopen<br/>compat shim<br/>[fmemopen.c]"]
end

subgraph group_payloads["Boot payloads"]
  node_mass_gadget["MS gadget<br/>linux payload"]
  node_mass_gadget_cm3["MS gadget CM3<br/>linux payload"]
  node_msd["Legacy MSD<br/>firmware payload"]
  node_imager["Imager boot<br/>app payload"]
  node_sec_example["Secure example<br/>secure boot example"]
  node_recovery2711["Recovery 2711<br/>eeprom recovery"]
  node_recovery2712["Recovery 2712<br/>eeprom recovery"]
  node_sec_recovery["Secure recovery<br/>secure boot recovery"]
  node_sec_recovery5["Secure recovery 5<br/>secure boot recovery"]
end

subgraph group_firmware["Firmware assets"]
  node_fw2711[("FW 2711<br/>bootloader assets")]
  node_fw2712[("FW 2712<br/>bootloader assets")]
  node_rpi_eeprom[("rpi-eeprom<br/>upstream submodule")]
end

subgraph group_tools["Build tools"]
  node_tools_suite["Tools"]
end

subgraph group_support["Support files"]
  node_win32["Windows pkg<br/>installer assets"]
  node_docs["Docs<br/>reference"]
  node_ci["CI checks<br/>validation"]
end

node_main -->|"serves"| node_bootfiles
node_main -->|"reads"| node_duid
node_main -->|"boots"| node_mass_gadget
node_main -->|"boots"| node_mass_gadget_cm3
node_main -->|"boots"| node_msd
node_main -->|"boots"| node_imager
node_main -->|"boots"| node_recovery2711
node_main -->|"boots"| node_recovery2712
node_main -->|"boots"| node_sec_recovery
node_main -->|"boots"| node_sec_recovery5
node_bootfiles -->|"uses"| node_fw2711
node_bootfiles -->|"uses"| node_fw2712
node_recovery2711 -->|"depends on"| node_rpi_eeprom
node_recovery2712 -->|"depends on"| node_rpi_eeprom
node_sec_recovery -->|"depends on"| node_rpi_eeprom
node_sec_recovery5 -->|"depends on"| node_rpi_eeprom
node_tools_suite -->|"builds"| node_imager
node_tools_suite -->|"signs"| node_sec_example
node_tools_suite -->|"updates"| node_recovery2711
node_tools_suite -->|"updates"| node_recovery2712
node_tools_suite -->|"updates"| node_sec_recovery
node_tools_suite -->|"updates"| node_sec_recovery5
node_docs -->|"describes"| node_sec_example
node_ci -->|"validates"| node_tools_suite
node_win32 -->|"packages"| node_main

click node_main "https://github.com/raspberrypi/usbboot/blob/master/main.c"
click node_bootfiles "https://github.com/raspberrypi/usbboot/blob/master/bootfiles.c"
click node_duid "https://github.com/raspberrypi/usbboot/blob/master/decode_duid.c"
click node_bin2c "https://github.com/raspberrypi/usbboot/blob/master/bin2c.c"
click node_fmemopen "https://github.com/raspberrypi/usbboot/blob/master/fmemopen.c"
click node_mass_gadget "https://github.com/raspberrypi/usbboot/tree/master/mass-storage-gadget64"
click node_mass_gadget_cm3 "https://github.com/raspberrypi/usbboot/tree/master/mass-storage-gadget64-cm3"
click node_msd "https://github.com/raspberrypi/usbboot/tree/master/msd"
click node_imager "https://github.com/raspberrypi/usbboot/tree/master/rpi-imager-embedded"
click node_sec_example "https://github.com/raspberrypi/usbboot/tree/master/secure-boot-example"
click node_recovery2711 "https://github.com/raspberrypi/usbboot/tree/master/recovery"
click node_recovery2712 "https://github.com/raspberrypi/usbboot/tree/master/recovery5"
click node_sec_recovery "https://github.com/raspberrypi/usbboot/tree/master/secure-boot-recovery"
click node_sec_recovery5 "https://github.com/raspberrypi/usbboot/tree/master/secure-boot-recovery5"
click node_fw2711 "https://github.com/raspberrypi/usbboot/tree/master/firmware/2711"
click node_fw2712 "https://github.com/raspberrypi/usbboot/tree/master/firmware/2712"
click node_rpi_eeprom "https://github.com/raspberrypi/usbboot/tree/master/rpi-eeprom"
click node_tools_suite "https://github.com/raspberrypi/usbboot/tree/master/tools"
click node_win32 "https://github.com/raspberrypi/usbboot/tree/master/win32"
click node_docs "https://github.com/raspberrypi/usbboot/tree/master/docs"
click node_ci "https://github.com/raspberrypi/usbboot/blob/master/.github/workflows/validate-hsm-wrapper.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_bootfiles,node_duid,node_bin2c,node_fmemopen toneBlue
class node_mass_gadget,node_mass_gadget_cm3,node_msd,node_imager,node_sec_example,node_recovery2711,node_recovery2712,node_sec_recovery,node_sec_recovery5 toneAmber
class node_fw2711,node_fw2712,node_rpi_eeprom toneMint
class node_tools_suite toneRose
class node_win32,node_docs,node_ci toneIndigo
```

## Components

### Host rpiboot

Host-side USB boot service and protocol handling.

- [rpiboot](https://github.com/raspberrypi/usbboot/blob/master/main.c): USB boot server · Main host application that discovers the Pi, speaks the boot protocol, and serves boot files. · `main.c`
- [Boot files](https://github.com/raspberrypi/usbboot/blob/master/bootfiles.c): file resolver · Maps the selected payload tree into files exposed over USB. · `bootfiles.c`
- [Device ID](https://github.com/raspberrypi/usbboot/blob/master/decode_duid.c): metadata decode · Decodes device and recovery metadata returned by the target. · `decode_duid.c`
- [bin2c](https://github.com/raspberrypi/usbboot/blob/master/bin2c.c): embed helper · Converts binary assets into C-friendly embedded data. · `bin2c.c`
- [fmemopen](https://github.com/raspberrypi/usbboot/blob/master/fmemopen.c): compat shim · Platform compatibility support for memory-backed file handling. · `fmemopen.c`

### Boot payloads

Selectable boot trees served to the target Pi.

- [MS gadget](https://github.com/raspberrypi/usbboot/tree/master/mass-storage-gadget64): linux payload · Linux-based mass-storage gadget provisioning image. · `mass-storage-gadget64`
- [MS gadget CM3](https://github.com/raspberrypi/usbboot/tree/master/mass-storage-gadget64-cm3): linux payload · Variant of the Linux mass-storage gadget flow for CM3-class targets. · `mass-storage-gadget64-cm3`
- [Legacy MSD](https://github.com/raspberrypi/usbboot/tree/master/msd): firmware payload · Older firmware-based mass-storage provisioning path. · `msd`
- [Imager boot](https://github.com/raspberrypi/usbboot/tree/master/rpi-imager-embedded): app payload · Boot image that launches Raspberry Pi Imager on the target. · `rpi-imager-embedded`
- [Secure example](https://github.com/raspberrypi/usbboot/tree/master/secure-boot-example): secure boot example · Minimal secure-boot-oriented Linux initrd example with signing artifacts. · `secure-boot-example`
- [Recovery 2711](https://github.com/raspberrypi/usbboot/tree/master/recovery): eeprom recovery · EEPROM recovery/update assets for BCM2711-era devices. · `recovery`
- [Recovery 2712](https://github.com/raspberrypi/usbboot/tree/master/recovery5): eeprom recovery · EEPROM recovery/update assets for BCM2712-era devices. · `recovery5`
- [Secure recovery](https://github.com/raspberrypi/usbboot/tree/master/secure-boot-recovery): secure boot recovery · Secure-boot-oriented EEPROM recovery flow and boot configuration. · `secure-boot-recovery`
- [Secure recovery 5](https://github.com/raspberrypi/usbboot/tree/master/secure-boot-recovery5): secure boot recovery · 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](https://github.com/raspberrypi/usbboot/tree/master/firmware/2711): bootloader assets · Prebuilt bootloader and recovery binaries for BCM2711 devices. · `firmware/2711`
- [FW 2712](https://github.com/raspberrypi/usbboot/tree/master/firmware/2712): bootloader assets · Prebuilt bootloader and recovery binaries for BCM2712 devices. · `firmware/2712`
- [rpi-eeprom](https://github.com/raspberrypi/usbboot/tree/master/rpi-eeprom): upstream submodule · Upstream EEPROM tooling and metadata logic used by recovery flows. · `rpi-eeprom`

### Build tools

Utilities used to assemble, sign, and release boot artifacts.

- [Tools](https://github.com/raspberrypi/usbboot/tree/master/tools): build/release tools · Scripts and utilities for boot image generation, signing, and EEPROM updates. · `tools`

### Support files

Documentation, packaging, CI, and validation helpers.

- [Windows pkg](https://github.com/raspberrypi/usbboot/tree/master/win32): installer assets · Windows launcher, installer, and redistribution assets. · `win32`
- [Docs](https://github.com/raspberrypi/usbboot/tree/master/docs): reference · Secure-boot and troubleshooting documentation. · `docs`
- [CI checks](https://github.com/raspberrypi/usbboot/blob/master/.github/workflows/validate-hsm-wrapper.yml): validation · Workflow and test coverage for HSM wrapper and signing integration. · `.github/workflows/validate-hsm-wrapper.yml`

## Connections

- 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.
