# Source: boot-eeprom.adoc

*Note: This file could not be automatically converted from AsciiDoc.*

== Raspberry Pi boot EEPROM

The following Raspberry Pi models use an EEPROM to boot the system:

* Flagship models since Raspberry Pi 4B
* Compute Module models since CM4 (including CM4S)
* Keyboard models since Pi 400

All other models of Raspberry Pi computer use the `bootcode.bin` file located in the boot filesystem.

NOTE: You can find the scripts and pre-compiled binaries used to create `rpi-eeprom`  in the https://github.com/raspberrypi/rpi-eeprom/[rpi-eeprom GitHub repository].

=== Diagnostics

If an error occurs during boot, then an xref:configuration.adoc#led-warning-flash-codes[error code] will be displayed via the green LED. Newer versions of the bootloader will display a xref:raspberry-pi.adoc#boot-diagnostics[diagnostic message] on all HDMI displays.

[[bootloader_update_stable]]
=== Update the bootloader

There are multiple ways to update the bootloader of your Raspberry Pi.

==== Flagship models since Raspberry Pi 4B; Compute Modules since CM5; Keyboard models since Pi 400

Raspberry Pi OS automatically updates the bootloader for important bug fixes. To manually update the bootloader or change the boot order, use xref:configuration.adoc#raspi-config[raspi-config].

NOTE: Compute Module 4 and Compute Module 4S do not support automatic bootloader updates because the bootrom cannot load the `recovery.bin` file from eMMC. The recommended update mechanism is `rpiboot` or via `flashrom` - see `rpi-eeprom-update -h` for more information.

[[imager]]
==== Use Raspberry Pi Imager to update the bootloader

Raspberry Pi Imager provides a GUI for updating the bootloader and selecting the boot mode.

. Download https://www.raspberrypi.com/software/[Raspberry Pi Imager].
. Select an unused SD card. All data on this SD card is overwritten by Imager.
. Connect the SD card to the computer where Imager runs.
. Launch Raspberry Pi Imager.
. In the **Device** tab, select your Raspberry Pi model from the list. Select **Next**.
. In the **OS** tab, choose **Misc utility images**
+
image::images/misc-utility-images.png[alt="Select Misc utility images",width="60%"]
. Select **Bootloader** for your version of Raspberry Pi.
+
image::images/bootloader-family-select.png[alt="Choose a family for your bootloader",width="60%"]
. Select a boot mode. We recommend **SD Card Boot**. Select **Next**.
+
image::images/bootloader-storage-select.png[alt="Choose the storage from which you'd like to boot",width="60%"]
. In the **Storage** tab, select your SD card. Select **Next**.`
. In the **Writing** tab, review your choices and select **Write** to proceed.
. You're prompted to confirm overwriting the data on the SD card. To continue, select **I understand, erase and write**.
. Wait until Imager has finished writing and verifying the SD card
. Connect the SD card to the Raspberry Pi device where you want to update the bootloader.
. Boot the Raspberry Pi with the new image and wait for at least ten seconds.
. When the green activity LED blinks with a steady pattern and the HDMI display shows a green screen, you've successfully written the bootloader.
. Power off the Raspberry Pi and remove the SD card.

[[raspi-config]]
==== Use `raspi-config` to update the bootloader

To change the boot-mode or bootloader version from within Raspberry Pi OS, run xref:configuration.adoc#raspi-config[raspi-config].

. xref:os.adoc#update-software[Update] Raspberry Pi OS to get the latest version of the `rpi-eeprom` package.
. Run `sudo raspi-config`.
. Select `Advanced Options`.
. Select `Bootloader Version`.
. Select `Default` for factory default settings or `Latest` for the latest bootloader release.
. Reboot with `sudo reboot`.

=== Update the bootloader configuration

The `default` version of the bootloader represents the latest factory default firmware image. It updates to provide critical bug fixes, hardware support and periodically after features have been tested in the `latest` release.
The `latest` bootloader updates more often to include the latest fixes and improvements.

Advanced users can switch to the `latest` bootloader to get the latest functionality.

First, ensure that your Raspberry Pi runs the latest software. Run the following command to update:

[source,console]
----
$ sudo apt update && sudo apt full-upgrade
----

Next, run the following command to open `raspi-config`:

[source,console]
----
$ sudo raspi-config
----

Navigate to `Advanced Options` > `Bootloader Version`. Select `Latest`, then choose `Yes` to confirm. Select `Finish` and confirm that you want to reboot.

If you run `sudo rpi-eeprom-update`, you should see that a more recent version of the bootloader is available and it's the `latest` release.

----
*** UPDATE AVAILABLE ***
BOOTLOADER: update available
   CURRENT: Thu 18 Jan 13:59:23 UTC 2024 (1705586363)
    LATEST: Mon 22 Jan 10:41:21 UTC 2024 (1705920081)
   RELEASE: latest (/lib/firmware/raspberrypi/bootloader-2711/latest)
            Use raspi-config to change the release.

  VL805_FW: Using bootloader EEPROM
     VL805: up to date
   CURRENT: 000138c0
    LATEST: 000138c0
----

Now you can update your bootloader.

[source,console]
----
$ sudo rpi-eeprom-update -a
$ sudo reboot
----

Reboot, then run `sudo rpi-eeprom-update`. You should now see that the `CURRENT` date has updated to the latest version of the bootloader:

----
BOOTLOADER: up to date
   CURRENT: Mon 22 Jan 10:41:21 UTC 2024 (1705920081)
    LATEST: Mon 22 Jan 10:41:21 UTC 2024 (1705920081)
   RELEASE: latest (/lib/firmware/raspberrypi/bootloader-2711/latest)
            Use raspi-config to change the release.

  VL805_FW: Using bootloader EEPROM
     VL805: up to date
   CURRENT: 000138c0
    LATEST: 000138c0
----

==== Read the current bootloader configuration

To view the configuration used by the current running bootloader, run the following command:

[source,console]
----
$ rpi-eeprom-config
----

==== Read the configuration from an bootloader image

To read the configuration from a bootloader image:

[source,console]
----
$ rpi-eeprom-config pieeprom.bin
----

==== Editing the current bootloader configuration

The following command loads the current bootloader configuration into a text editor. When the editor is closed, `rpi-eeprom-config` applies the updated configuration to latest available bootloader release and uses `rpi-eeprom-update` to schedule an update when the system is rebooted:

[source,console]
----
$ sudo -E rpi-eeprom-config --edit
$ sudo reboot
----

If the updated configuration is identical or empty, then no changes are made.

The editor is selected by the `EDITOR` environment variable.

==== Applying a saved configuration

The following command applies `boot.conf` to the latest available bootloader image and uses `rpi-eeprom-update` to schedule an update when the system is rebooted.

[source,console]
----
$ sudo rpi-eeprom-config --apply boot.conf
$ sudo reboot
----

[[automaticupdates]]
=== Automatic updates

The `rpi-eeprom-update` `systemd` service runs at startup and applies an update if a new image is available, automatically migrating the current bootloader configuration.

To disable automatic updates:

[source,console]
----
$ sudo systemctl mask rpi-eeprom-update
----

To re-enable automatic updates:

[source,console]
----
$ sudo systemctl unmask rpi-eeprom-update
----

NOTE: If the xref:raspberry-pi.adoc#FREEZE_VERSION[FREEZE_VERSION] bootloader config is set then the update service will skip any automatic updates. This removes the need to individually disable the update service if there are multiple operating systems installed, or when swapping SD cards.

==== `rpi-eeprom-update`

Raspberry Pi OS uses the `rpi-eeprom-update` script to implement an <<automaticupdates,automatic update>> service. The script can also be run interactively or wrapped to create a custom bootloader update service.

Reading the current bootloader version:

[source,console]
----
$ vcgencmd bootloader_version
----

Check if an update is available:

[source,console]
----
$ sudo rpi-eeprom-update
----

Install the update:

[source,console]
----
$ sudo rpi-eeprom-update -a
$ sudo reboot
----

Cancel the pending update:

[source,console]
----
$ sudo rpi-eeprom-update -r
----

Installing a specific bootloader image:

[source,console]
----
$ sudo rpi-eeprom-update -d -f pieeprom.bin
----

The `-d` flag instructs `rpi-eeprom-update` to use the configuration in the specified image file instead of automatically migrating the current configuration.

Display the built-in documentation:

[source,console]
----
$ rpi-eeprom-update -h
----

[[bootloader-release]]
=== Bootloader release status

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.

* `default` - Updated for new hardware support, critical bug fixes and periodic update for new features that have been tested via the `latest` release
* `latest` - Updated when new features are available

Since the release status string is just a subdirectory name, it is possible to create your own release streams e.g. a pinned release or custom network boot configuration.

==== Changing the bootloader release

NOTE: 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.

==== Updating the bootloader configuration in an bootloader image file

The following command replaces the bootloader configuration in `pieeprom.bin` with `boot.conf` and writes the new image to `new.bin`:

[source,console]
----
$ rpi-eeprom-config --config boot.conf --out new.bin pieeprom.bin
----

==== `recovery.bin`

At power on, the ROM found on BCM2711 and BCM2712 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 contents of the EEPROM. This mechanism ensures that the bootloader flash image can always be reset to a valid image with factory default settings.

For more information, see xref:raspberry-pi.adoc#eeprom-boot-flow[EEPROM bootflow].

==== Bootloader update files

[cols="1,1"]
|===
| Filename | Purpose

| `recovery.bin`
| Bootloader recovery executable

| `pieeprom.upd`
| Bootloader EEPROM image

| `pieeprom.bin`
| Bootloader EEPROM image - same as `pieeprom.upd` but changes `recovery.bin` behaviour to not rename itself to `RECOVERY.000`.

| `pieeprom.sig`
| The sha256 checksum (and optional timestamp) of bootloader image (`pieeprom.upd`/`pieeprom.bin`)

| `vl805.bin`
| The VLI805 USB firmware EEPROM image - Raspberry Pi 4B revision 1.3 and earlier only.

| `vl805.sig`
| The sha256 checksum of vl805.bin
|===

* If the bootloader update image is called `pieeprom.upd` then `recovery.bin` is renamed to `recovery.000` once the update has completed, then the system is rebooted. Since `recovery.bin` is no longer present the ROM loads the newly updated bootloader from SPI flash and the OS is booted as normal.
* If the bootloader update image is called `pieeprom.bin` then `recovery.bin` will stop after the update has completed. On success the HDMI output will be green and the green activity LED is flashed rapidly. If the update fails, the HDMI output will be red and an xref:configuration.adoc#led-warning-flash-codes[error code] will be displayed via the activity LED.
* The `.sig` files contain the hexadecimal sha256 checksum of the corresponding image file on the first line, optionally followed by the timestamp of the image (`ts: unixtime`) on the next line; additional fields may be added in the future.
* The ROM found on BCM2711 and BCM2712 does not support loading `recovery.bin` from USB mass storage or TFTP. Instead, newer versions of the bootloader support a self-update mechanism where the bootloader is able to reflash the SPI flash itself. See `ENABLE_SELF_UPDATE` on the xref:raspberry-pi.adoc#raspberry-pi-bootloader-configuration[bootloader configuration] page.
* The temporary EEPROM update files are automatically deleted by the `rpi-eeprom-update` service at startup.

For more information about the `rpi-eeprom-update` configuration file see `rpi-eeprom-update -h`.

==== EEPROM write protect

Both the bootloader and VLI EEPROMs support hardware write protection.  See the xref:config_txt.adoc#eeprom_write_protect[`eeprom_write_protect`] option for more information about how to enable this when flashing the EEPROMs.