Skip to content

Update booteeprom.md #1690

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Oct 5, 2020
Merged

Update booteeprom.md #1690

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
30c8cc6
Update booteeprom.md
timg236 Oct 2, 2020
9b437d8
Update booteeprom.md
timg236 Oct 2, 2020
8d29522
Update booteeprom.md
timg236 Oct 4, 2020
581c82b
Update booteeprom.md
timg236 Oct 5, 2020
88207ba
Update booteeprom.md
timg236 Oct 5, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 89 additions & 46 deletions hardware/raspberrypi/booteeprom.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,82 +2,119 @@

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.

## Why use an SPI EEPROM?
## Boot diagnostics
If an error occurs during boot then an [error code](../../configuration/led_blink_warnings.md) will be displayed via the green LED. Newer versions of the bootloader will display a [diagnostic message](boot_diagnostics.md) which will be shown on both HDMI displays.

- Raspberry Pi 4 bootup procedure and SDRAM setup is considerably more complicated than on the previous Raspberry Pi models, so there is more risk inherent in code that's permanently incorporated in the ROM of the SoC.
- USB has moved to a PCIe bus, and the Gigabit Ethernet driver is completely different to previous models, so again, having it permanently fixed into the ROM of the SoC was not feasible.
- A small SPI EEPROM allows bugs to be fixed and features to be added after launch, in the field.
- The local modifiable state means that OTP bootmode settings will not be required for network or USB mass storage boot on the Raspberry Pi 4. There are no user-modifiable OTP bootmode bits on Pi 4.

## USB boot

USB boot support is currently being beta-tested. See the "USB mass storage boot" section of the [Bootloader Configuration Page](./bcm2711_bootloader_config.md) for further details.

## Is the bootloader working correctly?

To check that the bootloader is working correctly, turn off the power, unplug everything from the Raspberry Pi 4, including the SD card, and then turn the power back on. If the green LED blinks with a repeating pattern then the bootloader is running correctly, and indicating that `start*.elf` has not been found. Any other actions imply that the bootloader is not working correctly and should be reinstalled using `recovery.bin`.

## Recovery image
## Updating the bootloader

If the Raspberry Pi is not booting it's possible that the bootloader EEPROM is corrupted. This can easily be reprogrammed using the Raspberry Pi Imager tool which is available via the [raspberrypi.org downloads page](https://www.raspberrypi.org/downloads/).
### Raspberry Pi Imager
The easiest way to to update the bootloader to the latest version with default settings is to use the [Raspberry Pi Imager](https://www.raspberrypi.org/downloads/) to install a boot recovery image onto a spare SD card.

Using the recovery image will erase any custom configuration options, resetting the bootloader back to factory defaults.
Select "Choose OS -> Misc utility images -> Raspberry Pi 4 EEPROM boot recovery"

## Updating the bootloader
Raspberry Pi OS also keeps the EEPROM up-to-date: new EEPROM images are applied when the Raspberry Pi 4 next boots.

### Updating from Raspberry Pi OS
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 the `rpi-eeprom` package, which installs a service that runs at boot-time to check for critical 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
```

If you wish to control when the updates are applied you can disable the systemd service from running automatically and run `rpi-eeprom-update` manually, as shown in the 'Manually checking if an update is available' section below.
## Manually checking if an update is available
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/critical`) 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`.

```
# Disable
sudo systemctl mask rpi-eeprom-update
sudo rpi-eeprom-update
```

# Enable it again
sudo systemctl unmask rpi-eeprom-update
If an update is available, you can install it using:
```
sudo rpi-eeprom-update -a
sudo reboot
```

The `FREEZE_VERSION` option in the EEPROM config file may be used to indicate that the EEPROM should not be updated on this board.
### Reading the current EEPROM version
```
vcgencmd bootloader_version
```

Note that by default, updating the bootloader (automatically or manually) will retain any custom configuration options of the previous installed version. You can override the migration by manually updating and using the `-d` option with `rpi-eeprom-update`. This will force the updated bootloader to use its inbuilt defaults.
## Updating the EEPROM configuration
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.

## Manually checking if an update is available
See the [Bootloader Configuration Page](./bcm2711_bootloader_config.md) for details of the configuration file.

Running the `rpi-eeprom-update` command with no parameters indicates whether an update is required. An update is required if the timestamp of the most recent file in the firmware directory (normally `/lib/firmware/raspberrypi/bootloader/critical`) 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 update`.
### Reading the current EEPROM configuration
To view the configuration file used by the bootloader at boot time run `rpi-eeprom-config` or `vcgencmd bootloader_config`.

### Reading the configuration file from an EEPROM image
To read the configuration file from an EEPROM image file:
```
sudo rpi-eeprom-update
rpi-eeprom-config pieeprom.bin
```

If an update is available, you can install it using :
### Editing the current bootloader configuration
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 rpi-eeprom-update -a
sudo -E rpi-eeprom-config --edit
sudo reboot
```
If the updated configuration file is identical or empty then no changes are made.

### Reading the current EEPROM configuration
The editor is selected by the `EDITOR` environment variable.

To view the configuration file used by the bootloader at boot time
### Applying a saved configuration file
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.
```
vcgencmd bootloader_config
sudo rpi-eeprom-config --apply boot.conf
sudo reboot
```

### Reading the EEPROM version
### Low level commands

#### Updating the configuration in an EEPROM image
The following command reads `pieeprom.bin` and replaces the configuration file with the contents of `boot.conf`. The result is written to `new.bin`
```
vcgencmd bootloader_version
rpi-eeprom-config --config boot.conf --out new.bin pieeprom.bin
```

For more information about advanced options please run `rpi-eeprom-config -h`.

#### Updating the bootloader EEPROM
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`.

### recovery.bin
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.

#### EEPROM update files
| 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.upd` then `recovery.bin` renames itself to `recovery.000` and resets the CPU. Since `recovery.bin` is 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.bin` the `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. Otherwise, the HDMI output will be red and an [error code](../../configuration/led_blink_warnings.md) will be displayed via the activity LED.
* The `.sig` files 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.bin` from 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. See `ENABLE_SELF_UPDATE` on the (bootloader configuration)[bcm2711_bootloader_config.md] page.
* The temporary EEPROM update files are automatically deleted by the `rpi-eeprom-update` service at startup.

### Firmware 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. By default, Raspberry Pi OS only selects critical updates (security fixes or major hardware compatiblity changes) since most users do not use alternate boot modes (TFTP, USB etc)
Expand All @@ -90,10 +127,22 @@ Since the release status string is just a subdirectory name then it's possible t

### Changing the firmware release

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

### EEPROM write protect
For more information about the `rpi-eeprom-update` configuration file please run `rpi-eeprom-update -h`.

### Disabling automatic updates
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](bcm2711_bootloader_config.md) may be used to indicate to the `rpi-eeprom-update` service that the EEPROM should not be updated on this board.

### EEPROM write protect
Write protecting the EEPROMs on the Raspberry Pi 4 Model B requires both a software change and a small board modification.

**This is only recommended for advanced users or industrial customers.**
Expand All @@ -110,11 +159,5 @@ If `eeprom_write_protect=1` is defined in `config.txt` then `recovery.bin` will

N.B `flashrom` does not support clearing of the write-protect regions and will fail to update the EEPROM if write-protect regions are defined.

## EEPROM Bootloader configuration options

See the [Bootloader Configuration Page](./bcm2711_bootloader_config.md) for configuration details.

## Release Notes
* [Release notes](https://github.com/raspberrypi/rpi-eeprom/blob/master/firmware/release-notes.md) for bootloader EEPROMs.