150 lines
7.1 KiB
Markdown
150 lines
7.1 KiB
Markdown
# Pi 5 EEPROM configuration
|
|
|
|
[Boot images](boot.md) · [Recovery](recovery.md) · [Implementation ledger](implementation-status.md)
|
|
|
|
M12 now provides an offline configuration workflow using the pinned official
|
|
Raspberry Pi tool and a real Pi 5 firmware image. The host checks passed;
|
|
application to a physical Pi, boot order, PMIC behavior and timing remain deferred.
|
|
`tools/configure-pi-eeprom` only creates files. It never reads or writes a hardware
|
|
EEPROM, invokes a firmware updater, or reboots a machine.
|
|
|
|
## Preview a profile on the build workstation
|
|
|
|
From the repository root:
|
|
|
|
```sh
|
|
./tools/configure-pi-eeprom --profile production
|
|
./tools/configure-pi-eeprom --profile development
|
|
make eeprom-test
|
|
```
|
|
|
|
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. These settings do not establish a
|
|
measured FDS boot improvement. [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. Whether the assembled computer and attached hardware behave as intended
|
|
still needs a physical test. [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). No GPIO wake option or
|
|
unmeasured HDMI tuning is added.
|
|
|
|
## 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 during physical testing
|
|
|
|
This step is deliberately outside the host/VM acceptance run. Use the Pi's
|
|
maintenance environment and the official installed EEPROM utilities. Once the
|
|
reviewed files and saved original inputs are available there, the upstream
|
|
configuration interface is:
|
|
|
|
```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. FDS has not yet tested it on your Pi.
|
|
|
|
## Inputs, dependencies and software evidence
|
|
|
|
The input lock is [inputs.json](../config/eeprom/inputs.json), pinned to
|
|
`raspberrypi/rpi-eeprom` commit `2fee426f27b6c54d3f5b6f36efd9a2fe1286a45d` and
|
|
Pi 5 preview firmware `pieeprom-2026-09-12.bin`. Every download is SHA-256 checked;
|
|
a changed cached input is rejected. The
|
|
[official source tool](https://github.com/raspberrypi/rpi-eeprom/blob/2fee426f27b6c54d3f5b6f36efd9a2fe1286a45d/rpi-eeprom-config)
|
|
is stored unchanged in the cache. Void's tracked source remains unchanged.
|
|
|
|
The host workflow uses existing Python and curl. It does not add a target daemon,
|
|
package or Rust dependency. The upstream parser's optional signing dependencies
|
|
are not needed for configuration-only operations.
|
|
|
|
`make eeprom-test` passed production/development roundtrips, unchanged firmware
|
|
payloads, repeatable binary output, refusal to overwrite an existing directory,
|
|
preservation of custom settings, exact rollback of conditional settings, and
|
|
rejection of malformed images, device nodes and oversized configuration files.
|
|
Initial evidence is `out/m12-eeprom.zi144zib/`, with log
|
|
`out/logs/m12-eeprom-check.log`. The complete local release acceptance is recorded in [M12 validation](m12-validation.md).
|