Skip to content

secure-boot-recovery5: Update docs to improve developer experience #325

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 10, 2025
Merged

secure-boot-recovery5: Update docs to improve developer experience #325

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7e26f76
secure-boot-recovery5: Added verbose docs about debug serial ports.
jack-obrien Aug 9, 2025
a4aa3c4
secure-boot-recovery5: BCM2712 needs burnt OTP for signed pieeprom
jack-obrien Aug 9, 2025
9c5ab41
secure-boot-recovery5: Clarify docs about config.txt
jack-obrien Aug 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions secure-boot-recovery5/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,19 @@ mkdir -p metadata
../rpiboot -d . -j metadata
```

## Requirement for flashed OTP
The BCM2712 will not boot a signed EEPROM image unless it holds the public key in its One Time Programmable (OTP) memory. If you try to boot a signed EEPROM image without burning the public key into OTP:

* The EEPROM firmware will not run and there will be no output on the debug header. The device will not boot.
* On the BCM2712 C1 stepping (found on older Pi 5B models), the boot LED on the Raspberry Pi 5B will display an error code by flashing green 2 times.
* On the BCM2712 D0 stepping (found on Pi 500, CM5, and newer Pi 5Bs), the boot LED will not display an error code, however the device will still not boot.

This is different from the BCM2711 chip used in the Raspberry Pi 4B and CM4. On the BCM2711, it was possible to test out the secure boot flow without making irreversible changes to the OTP. The user could flash a signed `pieeprom.bin` EEPROM firmware image and test that it would verify the signature of the `boot.img` file correctly. On the Pi 5, this is not possible.

However, it is possible to check that your signed `boot.img` file is bootable on the BCM2712. To do this, place the files `boot.img` and `boot.sig` in the `boot` partition of your Raspberry Pi OS image. Then modify the file `config.txt` on the boot partition to contain the entry `boot_ramdisk=1`. On the next boot, the Raspberry Pi will unpack the `boot.img` into memory and treat it as the boot partition.

### Example UART output
This output is given by the EEPROM bootloader when it verifies the signature of a `boot.img`. It can be read over the [3-pin Serial Debug Port](https://datasheets.raspberrypi.com/debug/debug-connector-specification.pdf). This is accessible via a JST-SH header on the Pi 5B. On the CM5, it is unpopulated on the top side of the board.
```
3.04 OTP boardrev b04170 bootrom a a
3.06 Customer key hash 8251a63a2edee9d8f710d63e9da5d639064929ce15a2238986a189ac6fcd3cee
Expand Down Expand Up @@ -113,6 +125,11 @@ onwards:


To enable this, edit the `config.txt` file in this directory and set `program_pubkey=1`
before flashing the Pi firmware as described in the section `Programming the EEPROM image using rpiboot`.

Note that the file `config.txt` in this directory is unrelated to the `config.txt` commonly
found in the boot parition of Raspberry Pi OS. The file `config.txt` in this directory
is used to configure the `rpiboot` tool.

## Disabling VideoCore JTAG

Expand Down
Loading