The Raspberry Pi 4 has an SPI-attached EEPROM (4MBits/512KB), which contains code to boot up the system and replaces bootcode.bin previously found in the boot partition of the SD card. Note that if a bootcode.bin is present in the boot partition of the SD card in a Pi 4, it is ignored.
If an error occurs during boot then an error code will be displayed via the green LED. Newer versions of the bootloader will display a diagnostic message which will be shown on both HDMI displays.
Bootloader EEPROM updates on Compute Module 4 require rpiboot which is also used for flashing the EMMC. Please see the Compute Module flashing guide for instructions.
The easiest way to to update the bootloader to the latest version with default settings is to use the Raspberry Pi Imager to install a boot recovery image onto a spare SD card.
Select "Choose OS -> Misc utility images -> Raspberry Pi 4 EEPROM boot recovery"
Raspberry Pi OS also keeps the EEPROM up-to-date: new EEPROM images are applied when the Raspberry Pi 4 next boots.
Bootloader updates are instigated during a normal apt update, apt full-upgrade cycle, this means you will get new features and bug fixes during your normal updates.
Bootloader updates are performed by rpi-eeprom-update service provided by the rpi-eeprom package. This service runs at boot and updates the bootloader at the next reboot if a new production release is available. The service automatically migrates the current boot settings to the new bootloader release.
To update your system, including the bootloader:
sudo apt update
sudo apt full-upgrade
sudo reboot
Running the rpi-eeprom-update command with no parameters indicates whether an update is required. An update is required if the version of the most recent file in the firmware directory (normally /lib/firmware/raspberrypi/bootloader/default) is newer than that reported by the current bootloader.
The images under /lib/firmware/raspberrypi/bootloader are part of the rpi-eeprom package and are only updated via apt upgrade.
sudo rpi-eeprom-update
If an update is available, you can install it using:
sudo rpi-eeprom-update -a
sudo reboot
vcgencmd bootloader_version
The bootloader EEPROM image contains an embedded configuration file to define the boot behaviour (e.g. selecting between SD, network and USB boot).
The rpi-eeprom-config tool may be used to modify embedded configuration file in an EEPROM image file.
See the Bootloader Configuration Page for details of the configuration file.
To view the configuration file used by the bootloader at boot time run rpi-eeprom-config or vcgencmd bootloader_config.
To read the configuration file from an EEPROM image file:
rpi-eeprom-config pieeprom.bin
The following command loads the current EEPROM configuration into a text editor. When the editor is closed, rpi-eeprom-config applies the updated configuration to latest available EEPROM release and uses rpi-eeprom-update to schedule an update when the system is rebooted:
sudo -E rpi-eeprom-config --edit
sudo reboot
If the updated configuration file is identical or empty then no changes are made.
The editor is selected by the EDITOR environment variable.
The following command applies boot.conf to the latest available EEPROM image and uses rpi-eeprom-update to schedule an update when the system is rebooted.
sudo rpi-eeprom-config --apply boot.conf
sudo reboot
The following command reads pieeprom.bin and replaces the configuration file with the contents of boot.conf. The result is written to new.bin
rpi-eeprom-config --config boot.conf --out new.bin pieeprom.bin
For more information about advanced options please run rpi-eeprom-config -h.
The following will cause the bootloader EEPROM to be updated the next time the system is rebooted.
# -d instructs rpi-eeprom-update to use the EEPROM configuration inside new.bin instead of
# of replacing it with the current configuration from vcgencmd bootloader.
sudo rpi-eeprom-update -d -f new.bin
For more information about advanced options please run rpi-eeprom-update -h.
At power on, the BCM2711 ROM looks for a file called recovery.bin in the root directory of the boot partition on the sd-card. If a valid recovery.bin is found then the ROM executes this instead of the SPI EEPROM image. This mechanism ensures that the bootloader SPI EEPROM can always be reset to a valid image with factory default settings.
| Filename | Purpose |
|---|---|
| recovery.bin | VideoCore EEPROM recovery executable |
| pieeprom.upd | Bootloader EEPROM image |
| pieeprom.bin | Bootloader EEPROM image - same as pieeprom.upd but changes recovery.bin behaviour |
| pieeprom.sig | The sha256 checksum of bootloader image (pieeprom.upd/pieeprom.bin) |
| vl805.bin | The VLI805 USB firmware EEPROM image - ignored on 1.4 board revision which does not have a dedicated VLI EEPROM |
| vl805.sig | The sha256 checksum of vl805.bin |
- If the bootloader update image is called
pieeprom.updthenrecovery.binrenames itself torecovery.000and resets the CPU. Sincerecovery.binis no longer present the ROM loads the newly updated bootloader from SPI EEPROM and the OS is booted as normal. - If the bootloader update image is called
pieeprom.bintherecovery.binwill stop after the update has completed. On success the HDMI output will be green and the green activity LED is flashed rapidly. Otherwise, the HDMI output will be red and an error code will be displayed via the activity LED. - The
.sigfiles should just contain the sha256 checksum (in hex) of the corresponding image file. Other fields may be added in the future. - The BCM2711 ROM does not support loading
recovery.binfrom USB mass storage or TFTP. Instead, newer versions of the bootloader support a self-update mechanism where the SPI bootloader is able to reflash the SPI EEPROM itself. SeeENABLE_SELF_UPDATEon the bootloader configuration page. - The temporary EEPROM update files are automatically deleted by the
rpi-eeprom-updateservice at startup.
The firmware release status corresponds to a particular subdirectory of bootloader firmware images (/lib/firmware/raspberrypi/bootloader/...), and can be changed to select a different release stream. By default, Raspberry Pi OS automatically updates the bootloader if 'default' image in the 'rpi-eeprom' image is newer than the current bootloader image. The bootloader EEPROM config is migrated during the upgrade.
default- Updated for new hardware support, critical bug fixes and periodic update for new features that have been tested via thelatestrelease.latest- Updated when new features have been successfully beta tested.beta- New or experimental features are tested here first.
Since the release status string is just a subdirectory name then it's possible to create your own release streams e.g. a pinned release or custom network boot configuration.
N.B. default and latest are symbolic links to the older release names of critical and stable.
You can change which release stream is to be used during an update by editing the /etc/default/rpi-eeprom-update file and changing the FIRMWARE_RELEASE_STATUS entry to the appropriate stream.
For more information about the rpi-eeprom-update configuration file please run rpi-eeprom-update -h.
If you wish to control when the updates are applied you can disable the rpi-eeprom-update systemd service.
# Disable
sudo systemctl mask rpi-eeprom-update
# Enable it again
sudo systemctl unmask rpi-eeprom-update
The FREEZE_VERSION option in the EEPROM config file may be used to indicate to the rpi-eeprom-update service that the EEPROM should not be updated on this board.
Both the bootloader and VLI SPI EEPROMs support hardware write-protection. See the eeprom_write_protect option for more information about how to enabled this when flashing the EEPROMs.
- Release notes for bootloader EEPROMs.