Add rpi-eeprom-update documentation (raspberrypi#1270)

timg236 · lurch · commit e20f8dc7ae6e · 2019-09-07T15:01:22.000+01:00
* Add rpi-eeprom-update documentation

rpi-eeprom-update is now available in the standard Debian repository instead of untested. Update the documentation to cover this and remove the sed hacks for tweaking configuration parameters.
diff --git a/hardware/raspberrypi/booteeprom.md b/hardware/raspberrypi/booteeprom.md
@@ -7,38 +7,95 @@ The Raspberry Pi 4 has an SPI-attached EEPROM (4MBits/512KB), which contains cod
  - 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 PXE or USB mass storage boot on the Raspberry Pi 4. There are no user-modifiable OTP bootmode bits on Pi 4.
+ - 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.
 
-## PXE and USB Boot
+## Network and USB boot
 
-Support for these additional bootmodes will be added in the future via optional bootloader updates. The current schedule is to release PXE boot first, then USB boot.
+Support for these additional bootmodes will be added in the future via optional bootloader updates. The current schedule is to release network boot first, then USB boot.
 
 ## 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.bin
+## Recovery image
 
-If the EEPROM needs updating or has somehow become corrupted, it can be reflashed using a fresh SD card with a copy of `recovery.bin` in the first partition of an SD card, formatted to FAT32.
+If the Raspberry Pi is not booting it's possible that the bootloader EEPROM is corrupted. This can easily be reprogrammed using the Recovery image available on the [raspberrypi.org downloads page](https://www.raspberrypi.org/downloads/).
 
-`recovery.bin` is a special utility which runs directly from the SD card and updates the EEPROM — it is not in itself a bootloader. It flashes the green LED rapidly (forever) upon success. Because it's not a bootloader, it won't load `start*.elf`, so once you see the green LED flashing rapidly, just re-insert a regular Raspbian SD card and reboot the Pi.
+## Updating the bootloader
 
-It can be downloaded from the [raspberrypi.org downloads page](https://www.raspberrypi.org/downloads/).
+We recommend setting up your Pi so that it automatically updates the bootloader: this means you will get new features and bug fixes as they are released. Bootloader updates are performed by the `rpi-eeprom` package, which installs a service that runs at boot-time to check for critical updates.
+
+```
+sudo apt update
+sudo apt upgrade
+sudo apt install rpi-eeprom
+```
+
+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.
+
+```
+# Prevent the service from running, this can be run before the package is installed to prevent it ever running automatically.
+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 that the EEPROM should not be updated on this board. 
 
 ## Write protection of EEPROM
 
 There is no software write protection for the boot EEPROM but there will be a mechanism in Raspbian to skip any future updates to the EEPROM. However, it is possible to physically write-protect both EEPROMs via a simple resistor change on the board. Details will be published in the [schematics](./schematics/README.md).
 
 ## EEPROM configuration options
 
-The EEPROM image contains a small user-modifiable config file. To change a setting:
+EPROM image files contain a small user-modifiable config file, which may be modified using the `rpi-eeprom-config` script included in the `rpi-eeprom` package.
+
+### Update the EEPROM config
+```
+# Copy the EEPROM of interest from /lib/firmware/raspberrypi/bootloader/critical/
+
+# 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
+# -d means that the configuration in the file should be used, otherwise, rpi-eeprom-update 
+# will automatically migrate the current bootloader's configuration to the new image.
+sudo rpi-eeprom-update -d -f ./pieeprom-new.bin
+```
+
+### 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 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`.
+
+```
+rpi-eeprom-update
+```
+
+### Reading the current EEPROM configuration
+
+To view the configuration file used by the bootloader at boot time
+```
+vcgencmd bootloader_config
+```
+
+### Reading the EEPROM version
+```
+vcgencmd bootloader_version
+```
 
-* Download and unzip the rescue bootloader image from https://www.raspberrypi.org/downloads/
-* Used sed to change setting. Be careful to avoid changing anything else otherwise it will fail to boot.
-  * `sed -i -e "s/BOOT_UART=0/BOOT_UART=1/" pieeprom.bin`
-* Flash the image - see embedded README.txt in rescue image zip.
+### Beta firmware
+Beta firmware files will be stored in `/lib/firmware/raspberrypi/bootloader/beta/`. Developers or beta-testers who are comfortable with using the rescue image to fix boot problems can track the beta firmware by editing `/etc/default/rpi-eeprom-update` 
+```
+Change FIRMWARE_RELEASE_STATUS="critical"
+to FIRMWARE_RELEASE_STATUS="beta"
+```
 
-We will soon be releasing a tool which allows the EEPROM config to be extracted and modified without having to use sed hacks.
+### Configuration options
 
 #### BOOT_UART
 
@@ -62,7 +119,7 @@ Version: 2019-07-15
 
 #### FREEZE_VERSION
 
-If 1 then the Raspbian EEPROM update service (rpi-eeprom package) will skip automatic updates on this board. The parameter is not processed by the EEPROM bootloader or recovery.bin since there is no way in software of fully write protecting the EEPROM. Custom EEPROM update scripts must also check for this flag.
+If 1 then the `rpi-eeprom-update` will skip automatic updates on this board. The parameter is not processed by the EEPROM bootloader or recovery.bin since there is no way in software of fully write protecting the EEPROM. Custom EEPROM update scripts must also check for this flag.
 
 Default: 0  
 Version: All  
