RPI-EEPROM-UPDATE(1)

NAME
rpi-eeprom-update - Checks whether the Raspberry Pi bootloader EEPROM is up-to-date and updates the EEPROM

DESCRIPTION
rpi-eeprom-update [options]... [FILE]

Bootloader EEPROM update tool for the Raspberry Pi 4.

Checks whether the Raspberry Pi 4 bootloader and the VL805 USB controller EEPROMs are up-to-date and optionally updates the EEPROMs at the next reboot.

The default update mechanism writes recovery.bin and the EEPROM update image(s) (pieeprom.upd and vl805.bin) to the boot partition. The SHA256 hash of the corresponding images are written to pieeprom.sig and/or vl805.sig. This guards against file system corruption which could cause the EEPROM to be flashed with an invalid image. This is not a security check.

At the next reboot the ROM runs recovery.bin which updates EEPROM(s). If the update was successful recovery.bin renames itself to recovery.000 to prevent it from running a second time then resets the system. The system should then boot normally.

If /boot does not correspond to the boot partition and this is not a NOOBS system, then the mount point for BOOTFS should be defined in /etc/default/rpi-eeprom-update by defining the BOOTFS variable.

A backup of the current EEPROM config file is written to /var/lib/raspberrypi/bootloader/backup before applying the update.

Unless the -d flag is specified, the current bootloader configuration is retained.

OPTIONS

-a Automatically install bootloader and USB (VLI) EEPROM updates.

-A Specify which type of EEPROM to automatically update (vl805 or bootloader)

-d Use the default bootloader config, or if a file is specified using the -f

    flag use the config in that file. This option only applies when a bootloader EEPROM update is needed; if the bootloader EEPROM is up-to-date then its config will not be changed.

-f Install the given file instead of the latest applicable update

    Ignores the FREEZE_VERSION flag in bootloader and is intended for manual firmware updates.

-h Display help text and exit

-i Ignore package checksums - for rpi-eeprom developers.

-j Write status information using JSON notation

-m Write status information to the given file when run without -a or -f

-r Removes temporary EEPROM update files from the boot partition.

-u Install the specified VL805 (USB EEPROM) image file.

ENVIRONMENT
Environment variables should be defined in /etc/default/rpi-eeprom-update

EEPROM_CONFIG_HOOK

Specifies the path of an optional script which post-processes the configuration file before it is applied to the new image. The modified output must contain at least 3 lines and should contain WAKE_ON_GPIO and POWER_OFF_ON_HALT settings.

USE_FLASHROM

USE_FLASHROM is deprecated and there is no support for this. The muxing of the SPI pins causes too many issues for this to ever be reliable.

The flashrom update mechanism may be enabled by setting USE_FLASHROM=1. This also selects the vl805 tool instead of using recovery.bin to perform the update. This may be desirable if an immediate update is required or if an SD card is not present. However, this not recommended because the SPI pins are muxed with audio and other device drivers may be using SPI (e.g. HATs). This is also not safe in the event of a power failure during the update of the EEPROM. Changing the VL805 firmware whilst USB devices are attached may also cause those devices to stop working until after the system is reboot.

FIRMWARE_RELEASE_STATUS

Specifies the release status of the firmware to apply. The default is 'critical'.

Before selecting a firmware release directory this script checks whether there is a board revision specific variant e.g. critical-c03111. If present then the board-revision specific version is used in preference.

Release status:

critical: The latest production release plus important security or hardware compatibility bug fixes.

stable: Contains new features that have already undergone some beta testing. These are candidates for new production releases.

beta: New features, bug fixes for development/test purposes. Use at your own risk!

As far as rpi-eeprom-update is concerned FIRMWARE_RELEASE_STATUS is just the subdirectory mapping under /home/shift/dev/rpi-eeprom/firmware. Therefore, custom release directories are supported by creating the relevant directory and changing the FIRMWARE_RELEASE_STATUS environment variable.

EXAMPLES

  To extract the configuration file from an EEPROM image:

    rpi-eeprom-config pieeprom.bin --out bootconf.txt

  To update the configuration file in an EEPROM image:

    rpi-eeprom-config pieeprom.bin --config bootconf.txt --out pieeprom-new.bin

  To flash the new image:

    sudo rpi-eeprom-update -d -f ./pieeprom-new.bin

The syntax is the same as config.txt See online documentation for the list of parameters.

The official documentation for the Raspberry Pi bootloader EEPROM is available at https://www.raspberrypi.org/documentation/hardware/raspberrypi/booteeprom.md