122 lines
5.4 KiB
Markdown
122 lines
5.4 KiB
Markdown
# Pi 5 EEPROM configuration
|
|
|
|
[Boot images](developer/boot.md) · [Recovery](recovery.md) · [User manual](README.md)
|
|
|
|
The profile tool creates reviewable firmware/configuration files on the
|
|
workstation. Applying them to a Pi is a separate maintenance operation. Preserve
|
|
the machine's original firmware and configuration before changing them.
|
|
|
|
## Preview a profile on the build workstation
|
|
|
|
From the repository root:
|
|
|
|
```sh
|
|
./tools/configure-pi-eeprom --profile production
|
|
./tools/configure-pi-eeprom --profile development
|
|
```
|
|
|
|
The first invocation downloads three checksum-pinned inputs into
|
|
`.host/eeprom/`: the official configuration script, the Pi 5 preview firmware and
|
|
its upstream license. Later calls verify and reuse them. `FDS_OFFLINE=1` requires
|
|
all inputs to exist and refuses a network download.
|
|
|
|
The command prints its new `out/eeprom-PROFILE.*` directory. It contains:
|
|
|
|
| File | Purpose |
|
|
| --- | --- |
|
|
| `base.bin` | Exact input firmware retained unchanged |
|
|
| `original.conf` | Configuration to restore |
|
|
| `configured.conf` | Reviewed profile merged with the supplied settings |
|
|
| `configured.bin` | Real EEPROM image with the new configuration |
|
|
| `rollback.bin` | Same base firmware with `original.conf` restored |
|
|
| `review.diff` | Human-readable configuration changes |
|
|
| `manifest.json` | Input identity, selected settings and output SHA-256 hashes |
|
|
| `LICENSE` | Complete upstream tool and firmware notices |
|
|
|
|
Default inputs are **preview defaults, not a backup of your Pi**. A rollback image
|
|
restores the configuration supplied to this command on the supplied base firmware.
|
|
It cannot reconstruct a different firmware version or settings that were never
|
|
provided. Retain the actual machine's configuration and matching firmware input
|
|
before applying anything to that machine.
|
|
|
|
## Profile behavior
|
|
|
|
| Setting | Production | Development |
|
|
| --- | --- | --- |
|
|
| `BOOT_ORDER` | `0xf6`: NVMe, repeat | `0xf16`: NVMe, SD, repeat |
|
|
| `BOOT_UART` | `0` | `1` |
|
|
| `NET_INSTALL_ENABLED` | `0` | `0` |
|
|
| `NET_INSTALL_AT_POWER_ON` | `0` | `0` |
|
|
| `POWER_OFF_ON_HALT` | `1` | `1` |
|
|
| `WAIT_FOR_POWER_BUTTON` | `0` | `0` |
|
|
|
|
Boot order is read from the right. Both profiles avoid scanning the twelve USB
|
|
cartridges for firmware boot. Development retains an SD rescue path. Both disable
|
|
network-install keyboard detection; Raspberry Pi documents that this detection
|
|
adds USB initialization and enumeration work. [Official bootloader configuration](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#bootloader-configuration).
|
|
|
|
On Pi 5, the power-off setting requests PMIC standby on halt; the dedicated power
|
|
button remains the wake mechanism. The wait setting leaves cold power-on boot
|
|
enabled. After shutdown, check that attached power hardware follows the selected policy. [Official power settings](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#POWER_OFF_ON_HALT).
|
|
|
|
The source profiles are [production.conf](../config/eeprom/production.conf) and
|
|
[development.conf](../config/eeprom/development.conf). Review these files before choosing a profile.
|
|
|
|
## Preserve the machine's settings
|
|
|
|
In a Raspberry Pi maintenance environment with the official EEPROM utilities,
|
|
collect its configuration and version information before changing firmware:
|
|
|
|
```sh
|
|
rpi-eeprom-config > pi-current.conf
|
|
rpi-eeprom-update > pi-eeprom-status.txt
|
|
```
|
|
|
|
Retain the matching original firmware image separately. The status report helps
|
|
identify it; it is not a binary backup. Copy the saved inputs to the workstation,
|
|
then prepare a new directory:
|
|
|
|
```sh
|
|
./tools/configure-pi-eeprom \
|
|
--profile production \
|
|
--base-image /absolute/path/to/original-pi5-firmware.bin \
|
|
--current-config /absolute/path/to/pi-current.conf \
|
|
--output-directory /absolute/path/to/new-eeprom-review
|
|
```
|
|
|
|
The base must be a regular 2 MiB Pi 5 image, not a device node. The output directory
|
|
must not already exist. The helper preserves unrelated configuration lines and
|
|
conditional sections. It replaces all occurrences of the six managed settings,
|
|
including conditional overrides, with the selected profile's final `[all]`
|
|
settings. Review that change in `review.diff`; the exact original conditional
|
|
configuration remains in `original.conf` and `rollback.bin`.
|
|
|
|
The upstream parser reads the generated images back before success is reported.
|
|
This checks file construction and configuration roundtrip, not hardware
|
|
compatibility. No secure-boot key, fuse, customer signature or OTP setting is
|
|
modified by this helper.
|
|
|
|
## Apply and roll back
|
|
|
|
Apply the reviewed configuration from a Raspberry Pi maintenance environment
|
|
with the official EEPROM utilities, then follow the updater's restart instructions.
|
|
|
|
```sh
|
|
sudo rpi-eeprom-config --apply ./configured.conf ./base.bin
|
|
```
|
|
|
|
The updater may program EEPROM immediately or schedule an update depending on
|
|
its platform and update method. Follow its output and verify the resulting
|
|
configuration/version after the required restart. To restore the supplied
|
|
configuration on the same supplied firmware:
|
|
|
|
```sh
|
|
sudo rpi-eeprom-config --apply ./original.conf ./base.bin
|
|
```
|
|
|
|
If the firmware version itself changed, use the saved matching original firmware
|
|
for the rollback operation. Keep the maintenance SD and an external EEPROM rescue
|
|
route available; internal recovery cannot repair an EEPROM that prevents internal
|
|
boot. The official [EEPROM update and recovery guide](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#raspberry-pi-boot-eeprom)
|
|
describes that physical workflow.
|