You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Update booteeprom.md
@lurch
Work in progress - make this page easier to understand and rework to use the new rpi-eeprom-config --edit and --apply options
* Remove out of date statements about USB MSD
* Remove section about why there is an SPI EEPROM - it was only relevant at launch
* Describe the --edit and --apply arguments
* Describe the friendly commands first
* Update booteeprom.md
* Update booteeprom.md
Tweak --edit documentation to add -E to sudo to preserve the environment variable.
* Update booteeprom.md
* Update booteeprom.md
Copy file name to clipboardExpand all lines: hardware/raspberrypi/booteeprom.md
+89-46Lines changed: 89 additions & 46 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,82 +2,119 @@
2
2
3
3
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.
4
4
5
-
## Why use an SPI EEPROM?
5
+
## Boot diagnostics
6
+
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.
6
7
7
-
- 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.
8
-
- 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.
9
-
- A small SPI EEPROM allows bugs to be fixed and features to be added after launch, in the field.
10
-
- 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.
11
-
12
-
## USB boot
13
-
14
-
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.
15
-
16
-
## Is the bootloader working correctly?
17
-
18
-
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`.
19
-
20
-
## Recovery image
8
+
## Updating the bootloader
21
9
22
-
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/).
10
+
### Raspberry Pi Imager
11
+
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.
23
12
24
-
Using the recovery image will erase any custom configuration options, resetting the bootloader back to factory defaults.
13
+
Select "Choose OS -> Misc utility images -> Raspberry Pi 4 EEPROM boot recovery"
25
14
26
-
## Updating the bootloader
15
+
Raspberry Pi OS also keeps the EEPROM up-to-date: new EEPROM images are applied when the Raspberry Pi 4 next boots.
27
16
17
+
### Updating from Raspberry Pi OS
28
18
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.
29
19
30
-
Bootloader updates are performed by the `rpi-eeprom` package, which installs a service that runs at boot-time to check for critical updates.
20
+
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.
31
21
32
22
To update your system, including the bootloader:
33
-
34
23
```
35
24
sudo apt update
36
25
sudo apt full-upgrade
37
26
sudo reboot
38
27
```
39
28
40
-
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.
29
+
## Manually checking if an update is available
30
+
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.
31
+
The images under `/lib/firmware/raspberrypi/bootloader` are part of the `rpi-eeprom` package and are only updated via `apt upgrade`.
41
32
42
33
```
43
-
# Disable
44
-
sudo systemctl mask rpi-eeprom-update
34
+
sudo rpi-eeprom-update
35
+
```
45
36
46
-
# Enable it again
47
-
sudo systemctl unmask rpi-eeprom-update
37
+
If an update is available, you can install it using:
38
+
```
39
+
sudo rpi-eeprom-update -a
40
+
sudo reboot
48
41
```
49
42
50
-
The `FREEZE_VERSION` option in the EEPROM config file may be used to indicate that the EEPROM should not be updated on this board.
43
+
### Reading the current EEPROM version
44
+
```
45
+
vcgencmd bootloader_version
46
+
```
51
47
52
-
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.
48
+
## Updating the EEPROM configuration
49
+
The bootloader EEPROM image contains an embedded configuration file to define the boot behaviour (e.g. selecting between SD, network and USB boot).
50
+
The `rpi-eeprom-config` tool may be used to modify embedded configuration file in an EEPROM image file.
53
51
54
-
## Manually checking if an update is available
52
+
See the [Bootloader Configuration Page](./bcm2711_bootloader_config.md) for details of the configuration file.
55
53
56
-
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.
57
-
The images under `/lib/firmware/raspberrypi/bootloader` are part of the `rpi-eeprom` package and are only updated via `apt update`.
54
+
### Reading the current EEPROM configuration
55
+
To view the configuration file used by the bootloader at boot time run `rpi-eeprom-config` or `vcgencmd bootloader_config`.
58
56
57
+
### Reading the configuration file from an EEPROM image
58
+
To read the configuration file from an EEPROM image file:
59
59
```
60
-
sudo rpi-eeprom-update
60
+
rpi-eeprom-config pieeprom.bin
61
61
```
62
62
63
-
If an update is available, you can install it using :
63
+
### Editing the current bootloader configuration
64
+
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:
64
65
65
66
```
66
-
sudo rpi-eeprom-update -a
67
+
sudo -E rpi-eeprom-config --edit
67
68
sudo reboot
68
69
```
70
+
If the updated configuration file is identical or empty then no changes are made.
69
71
70
-
### Reading the current EEPROM configuration
72
+
The editor is selected by the `EDITOR` environment variable.
71
73
72
-
To view the configuration file used by the bootloader at boot time
74
+
### Applying a saved configuration file
75
+
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.
73
76
```
74
-
vcgencmd bootloader_config
77
+
sudo rpi-eeprom-config --apply boot.conf
78
+
sudo reboot
75
79
```
76
80
77
-
### Reading the EEPROM version
81
+
### Low level commands
82
+
83
+
#### Updating the configuration in an EEPROM image
84
+
The following command reads `pieeprom.bin` and replaces the configuration file with the contents of `boot.conf`. The result is written to `new.bin`
For more information about advanced options please run `rpi-eeprom-config -h`.
90
+
91
+
#### Updating the bootloader EEPROM
92
+
The following will cause the bootloader EEPROM to be updated the next time the system is rebooted.
93
+
```
94
+
# -d instructs rpi-eeprom-update to use the EEPROM configuration inside new.bin instead of
95
+
# of replacing it with the current configuration from vcgencmd bootloader.
96
+
sudo rpi-eeprom-update -d -f new.bin
80
97
```
98
+
For more information about advanced options please run `rpi-eeprom-update -h`.
99
+
100
+
### recovery.bin
101
+
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.
| pieeprom.bin | Bootloader EEPROM image - same as pieeprom.upd but changes recovery.bin behaviour |
109
+
| pieeprom.sig | The sha256 checksum of bootloader image (pieeprom.upd/pieeprom.bin) |
110
+
| vl805.bin | The VLI805 USB firmware EEPROM image - ignored on 1.4 board revision which does not have a dedicated VLI EEPROM|
111
+
| vl805.sig | The sha256 checksum of vl805.bin |
112
+
113
+
* 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.
114
+
* 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.
115
+
* The `.sig` files should just contain the sha256 checksum (in hex) of the corresponding image file. Other fields may be added in the future.
116
+
* 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.
117
+
* The temporary EEPROM update files are automatically deleted by the `rpi-eeprom-update` service at startup.
81
118
82
119
### Firmware release status
83
120
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)
@@ -90,10 +127,22 @@ Since the release status string is just a subdirectory name then it's possible t
90
127
91
128
### Changing the firmware release
92
129
93
-
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.
130
+
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.
94
131
95
-
### EEPROM write protect
132
+
For more information about the `rpi-eeprom-update` configuration file please run `rpi-eeprom-update -h`.
96
133
134
+
### Disabling automatic updates
135
+
If you wish to control when the updates are applied you can disable the `rpi-eeprom-update` systemd service.
136
+
```
137
+
# Disable
138
+
sudo systemctl mask rpi-eeprom-update
139
+
140
+
# Enable it again
141
+
sudo systemctl unmask rpi-eeprom-update
142
+
```
143
+
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.
144
+
145
+
### EEPROM write protect
97
146
Write protecting the EEPROMs on the Raspberry Pi 4 Model B requires both a software change and a small board modification.
98
147
99
148
**This is only recommended for advanced users or industrial customers.**
@@ -110,11 +159,5 @@ If `eeprom_write_protect=1` is defined in `config.txt` then `recovery.bin` will
110
159
111
160
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.
112
161
113
-
## EEPROM Bootloader configuration options
114
-
115
-
See the [Bootloader Configuration Page](./bcm2711_bootloader_config.md) for configuration details.
116
-
117
162
## Release Notes
118
163
*[Release notes](https://github.com/raspberrypi/rpi-eeprom/blob/master/firmware/release-notes.md) for bootloader EEPROMs.
0 commit comments