Merge pull request #4037 from timg236/bootloader-reliability

Document new bootloader options

Author: nathan-contino

documentation/asciidoc/computers/config_txt/conditional.adoc

@@ -96,6 +96,34 @@ Some models of Raspberry Pi, including Zero, Compute Module, and Keyboard models
 
 The `[none]` filter prevents any settings that follow from being applied to any hardware. Although there is nothing that you can't do without `[none]`, it can be a useful way to keep groups of unused settings in config.txt without having to comment out every line.
 
+=== The `[partition=N]` filter
+This `partition` filter can be be used to select alternate boot flows according to the requested partition number (`sudo reboot N`) or via direct usage of the `PM_RSTS` watchdog register.
+
+[source,ini]
+----
+# Bootloader EEPROM config.
+# If PM_RSTS is partition 62 then set bootloader properties to disable
+# SD high speed and show HDMI diagnostics
+# Boot from partition 2 with debug option.
+[partition=62]
+# Only high (>31) partition can be remapped.
+PARTITION=2
+SD_QUIRKS=0x1
+HDMI_DELAY=0
+----
+
+Example `config.txt` - (Currently Raspberry Pi 5 onwards)
+[source,ini]
+----
+# config.txt - If the original requested partition number in PM_RSTS was a
+# special number then use an alternate cmdline.txt
+[partition=62]
+cmdline=cmdline-recovery.txt
+----
+
+The raw value of the `PM_RSTS` register at bootup is available via `/proc/device-tree/chosen/bootloader/rsts` and the final partition number used for booting is available via `/proc/device-tree/chosen/bootloader/partition`. These are big-endian binary values.
+
+
 === The `[tryboot]` filter
 
 This filter succeeds if the `tryboot` reboot flag was set.

documentation/asciidoc/computers/configuration/device-tree.adoc

@@ -845,6 +845,8 @@ The firmware uses the special https://www.kernel.org/doc/html/latest/devicetree/
 
 `rpi-duid`:: _(string)_ Raspberry Pi 5 only. A string representation of the QR code on the PCB.
 
+`rpi-serial64`:: _(string)_ A string representation of the 64-bit serial number. On flagship models since Raspberry Pi 5 this is same as the normal serial number (`/proc/device-tree/serial-number`). On earlier models the default serial number is still 32-bit but with newer firmware a 64-bit serial number is now available and is visible through this node.
+
 ==== Common bootloader properties `/chosen/bootloader`
 
 Each property is stored as a 32-bit integer unless indicated otherwise.

documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc

@@ -34,7 +34,7 @@ Default: `0`
 [[UART_BAUD]]
 ==== `UART_BAUD`
 
-Raspberry Pi 5 only.
+Flagship models since Raspberry Pi 5 only.
 
 Changes the baud rate for the bootloader UART.
 
@@ -62,6 +62,15 @@ On Flagship models since Raspberry Pi 5 and Keyboard models since Pi 500, this p
 
 Default: `1` on Compute Modules since CM5 and Keyboard models; otherwise `0`
 
+[[WAIT_FOR_POWER_BUTTON]]
+==== `WAIT_FOR_POWER_BUTTON`
+
+Flagship models since Raspberry Pi 5 only.
+
+If this property and `POWER_OFF_ON_HALT` are both set to `1` then the bootloader will immediately power-off and wait for the power to be pressed on the first boot after the power supply has been removed. This means that instead of booting immediately after power-loss the system will wait for the power button to be pressed.
+
+Default: `0`
+
 [[BOOT_ORDER]]
 ==== `BOOT_ORDER`
 
@@ -151,6 +160,24 @@ The number of times that SD boot will be retried after failure before moving to
 
 `-1` means infinite retries.
 
+Default: `0`
+
+[[SD_QUIRKS]]
+==== `SD_QURIKS`
+
+The `SD_QUIRKS` property provides a set of options to support device bringup and workaround interoperability issues.
+
+The flags are implemented as a bit-field. Undefined bits are reserved for future use and should be set to zero.
+
+[cols="1m,3"]
+|===
+| Value | Behaviour
+
+| 0x1
+| Disable SD High Speed modes. The card clock is limited to 12.5 MHz
+|===
+
+
 Default: `0`
 
 [[NET_BOOT_MAX_RETRIES]]
@@ -472,6 +499,19 @@ Max length: 32 characters
 The `PARTITION` option may be used to specify the boot partition number, if it has not explicitly been set by the `reboot` command (e.g. `sudo reboot N`) or by `boot_partition=N` in `autoboot.txt`.
 This could be used to boot from a rescue partition if the user presses a button.
 
+The latest firmware also allows high partition numbers (> 31) to be overriden. This allows a custom setup of the system hardware watchdog to trigger a reboot with a special high partition number (e.g. 62) which can be detected by the bootloader (using a conditional filter) and remapped to a recovery partition.
+
+Example:
+[source,ini]
+----
+# System watchdog fired - boot the rescue partition with additional options
+# Disable SD high speed mode and enable HDMI diagnostics immediately.
+[partition=62]
+PARTITION=2
+HDMI_DELAY=0
+SD_QUIRKS=1
+----
+
 [source,ini]
 ----
 # Boot from partition 2 if GPIO 7 is pulled low
@@ -481,6 +521,14 @@ PARTITION=2
 
 Default: 0
 
+[[PARTITION_WALK]]
+==== `PARTITION_WALK`
+This property is designed to improve the reliability of `A/B` boot schemes using `autoboot.txt` by searching for bootable partitions if the specified partition does not appear to be bootable. If `PARTITION_WALK=1` and the requested partition is not bootable and does not have a valid `autoboot.txt` then the bootloader will check each partition in turn (up to 8 and wrapping to 0) to see if it is bootable (contains `start4.elf` on a Pi4, or `config.txt` and a suitable device-tree on Pi 5 or newer).
+
+During the "partition walk" `autoboot.txt` files are not processed to avoid cycling dependencies. It is assumed that the requested boot partition has failed and the system is attempting recovery. 
+
+Default: `0`
+
 [[PSU_MAX_CURRENT]]
 ==== `PSU_MAX_CURRENT`
 

documentation/asciidoc/computers/raspberry-pi/otp-bits.adoc

@@ -54,6 +54,7 @@ This is available via device-tree in `/proc/device-tree/chosen/rpi-boardrev-ext`
 * Raspberry Pi 400
  ** Bits 0-7: The default keyboard country code used by https://github.com/raspberrypi-ui/piwiz[piwiz]
 
+`35` :: High 32 bits of 64-bit serial number
 `36-43`:: xref:raspberry-pi.adoc#industrial-use-of-the-raspberry-pi[customer OTP values]
 `45`:: MPG2 decode key
 `46`:: WVC1 decode key