update docs
This commit is contained in:
@@ -0,0 +1,152 @@
|
||||
# Pi 5 EEPROM configuration
|
||||
|
||||
Development reference and historical context. For current operating instructions, use the [user manual](../README.md). Acceptance applies only to the source and artifacts identified in each record.
|
||||
|
||||
|
||||
[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).
|
||||
Reference in New Issue
Block a user