From e425017fa4d077d4b1a082566ea3ebc8fd0413ee Mon Sep 17 00:00:00 2001 From: Tim Gover Date: Tue, 13 May 2025 20:02:20 +0100 Subject: [PATCH] conditional: Document the new expression filter and new Pi5 boot variables --- .../computers/config_txt/conditional.adoc | 96 +++++++++++++++++-- .../computers/configuration/device-tree.adoc | 27 ++++-- 2 files changed, 109 insertions(+), 14 deletions(-) diff --git a/documentation/asciidoc/computers/config_txt/conditional.adoc b/documentation/asciidoc/computers/config_txt/conditional.adoc index f33a3d3206..23432cb452 100644 --- a/documentation/asciidoc/computers/config_txt/conditional.adoc +++ b/documentation/asciidoc/computers/config_txt/conditional.adoc @@ -96,9 +96,6 @@ 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. @@ -123,25 +120,108 @@ 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 `[boot_partition=N]` filter -The `boot_partition` filter can be used to select alternate OS files (e.g. `cmdline.txt`) to be loaded, depending on which partition `config.txt` was loaded from after processing `autoboot.txt`. This is intended for use with an `A/B` boot-system with `autoboot.txt` where it is desirable to be able to have identical files installed to the boot partition for both the `A` and `B` images. +=== The expression filter + +The expression filter provides support for comparing unsigned integer "boot variables" to constants using a simple set of operators. It is intended to support OTA update mechanisms, debug and test. + +* The "boot variables" are `boot_arg1`, `boot_count`, `boot_partition` and `partition`. +* Boot variables are always lower case. +* Integer constants may either be written as decimal or as hex. +* Expression conditional filters have no side-effects e.g. no assignment operators. +* As with other filter types the expression filter cannot be nested. +* Use the `[all]` filter to reset expressions and all other conditional filter types. + +Syntax: +[source,ini] +---- +# ARG is a boot-variable +# VALUE and MASK are unsigned integer constants +[ARG=VALUE] # selected if (ARG == VALUE) +[ARG&MASK] # selected if ((ARG & VALUE) != 0) +[ARG&MASK=VALUE] # selected if ((ARG & MASK) == VALUE) +[ARGVALUE] # selected if (ARG > VALUE) + +---- + +==== `boot_arg1` +Raspberry Pi 5 and newer flagship devices only. + +The `boot_arg1` variable is a 32-bit user defined value which is stored in a reset-safe register allowing parameters to be passed accross a reboot. + +Setting `boot_arg1` to 42 via `config.txt`: +[source,ini] +---- +set_reboot_arg1=42 +---- +The `set_reboot_arg1` property sets the value for the next boot. It does not change the current value as seen by the config parser. + +Setting `boot_arg1` to 42 via vcmailbox: +[source,console] +---- +sudo vcmailbox 0x0003808c 8 8 1 42 +---- + +Reading `boot_arg1` via vcmailbox: +[source,console] +---- +sudo vcmailbox 0x0003008c 8 8 1 0 +# Example output - boot_arg1 is 42 +# 0x00000020 0x80000000 0x0003008c 0x00000008 0x80000008 0x00000001 0x0000002a 0x0000000 +---- +The value of the `boot_arg1` variable when the OS was started can be read via xref:configuration.adoc#part4[device-tree] at `/proc/device-tree/chosen/bootloader/arg1` + +==== `boot_count` +Raspberry Pi 5 and newer flagship devices only. + +The `boot_count` variable is an 8-bit value stored in a reset-safe register that is incremented at boot (wrapping back to zero at 256). It is cleared if power is disconnected. -Example `config.txt` - select the matching root filesystem for the `A/B` boot file-system. +To read `boot_count` via vcmailbox: +[source,console] +---- +sudo vcmailbox 0x0003008d 4 4 0 +# Example - boot count is 3 +# 0x0000001c 0x80000000 0x0003008d 0x00000004 0x80000004 0x00000003 0x00000000 +---- + +Setting/clearing `boot_count` via vcmailbox: +[source,console] +---- +# Clear boot_count by setting it to zero. +sudo vcmailbox 0x0003808d 4 4 0 +---- +The value of `boot_count` when the OS was started can be read via xref:configuration.adoc#part4[device-tree] at `/proc/device-tree/chosen/bootloader/count` + +==== `boot_partition` +The `boot_partition` variable can be used to select alternate OS files (e.g. `cmdline.txt`) to be loaded, depending on which partition `config.txt` was loaded from after processing xref:config_txt.adoc#autoboot-txt[autoboot.txt]. This is intended for use with an `A/B` boot-system with `autoboot.txt` where it is desirable to be able to have identical files installed to the boot partition for both the `A` and `B` images. + +The value of the `boot_partition` can be different to the requested `partition` variable if it was overriden by setting `boot_partition` in xref:config_txt.adoc#autoboot-txt[autoboot.txt] or if the specified partion was not bootable and xref:raspberry-pi.adoc#PARTITION_WALK[PARTITION_WALK] was enabled in the EEPROM config. + +Example `config.txt` - select the matching root filesystem for the `A/B` boot file-system: [source,ini] ---- +# Use different cmdline files to point to different root filesystems based on which partition the system booted from. [boot_partition=1] -cmdline=cmdline_rootfs_a.txt +cmdline=cmdline_rootfs_a.txt # Points to root filesystem A [boot_partition=2] -cmdline=cmdline_rootfs_b.txt +cmdline=cmdline_rootfs_b.txt # Points to root filesystem B ---- +The value of `boot_partition` i.e. the partition used to boot the OS can be read from xref:configuration.adoc#part4[device-tree] at `/proc/device-tree/chosen/bootloader/partition` + +==== `partition` +The `partition` variable can 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. + + === The `[tryboot]` filter This filter succeeds if the `tryboot` reboot flag was set. It is intended for use in xref:config_txt.adoc#autoboot-txt[autoboot.txt] to select a different `boot_partition` in `tryboot` mode for fail-safe OS updates. +The value of `tryboot` at the start of boot can be read via xref:configuration.adoc#part4[device-tree] at `/proc/device-tree/chosen/bootloader/tryboot` + === The `[EDID=*]` filter When switching between multiple monitors while using a single SD card in your Raspberry Pi, and where a blank config isn't sufficient to automatically select the desired resolution for each one, this allows specific settings to be chosen based on the monitors' EDID names. diff --git a/documentation/asciidoc/computers/configuration/device-tree.adoc b/documentation/asciidoc/computers/configuration/device-tree.adoc index 45aa30698f..561ec68a29 100644 --- a/documentation/asciidoc/computers/configuration/device-tree.adoc +++ b/documentation/asciidoc/computers/configuration/device-tree.adoc @@ -833,7 +833,16 @@ For a list of supported overlays and parameters, see the https://github.com/rasp [[part4]] === Firmware parameters -The firmware uses the special https://www.kernel.org/doc/html/latest/devicetree/usage-model.html#runtime-configuration[/chosen] node to pass parameters between the bootloader and/or firmware and the operating system. Each property is stored as a 32-bit integer unless indicated otherwise. +The firmware uses the special https://www.kernel.org/doc/html/latest/devicetree/usage-model.html#runtime-configuration[/chosen] node to pass parameters between the bootloader and/or firmware and the operating system. + +* Each property is stored as a 32-bit unsigned integer unless indicated otherwise. +* Numbers in device-tree are stored in binary and are big-endian. + +Example shell command for reading a 32-bit unsigned integer property: +[source,console] +---- +printf "%d" "0x$(od "/proc/device-tree/chosen/bootloader/partition" -v -An -t x1 | tr -d ' ' )" +---- `overlay_prefix`:: _(string)_ The xref:config_txt.adoc#overlay_prefix[overlay_prefix] string selected by `config.txt`. @@ -849,8 +858,6 @@ The firmware uses the special https://www.kernel.org/doc/html/latest/devicetree/ ==== Common bootloader properties `/chosen/bootloader` -Each property is stored as a 32-bit integer unless indicated otherwise. - `boot-mode`:: The boot-mode used to load the kernel. See the xref:raspberry-pi.adoc#BOOT_ORDER[BOOT_ORDER] documentation for a list of possible boot-mode values. `partition`:: The partition number used during boot. If a `boot.img` ramdisk is loaded then this refers to partition that the ramdisk was loaded from rather than the partition number within the ramdisk. @@ -859,9 +866,17 @@ Each property is stored as a 32-bit integer unless indicated otherwise. `tryboot`:: Set to `1` if the `tryboot` flag was set at boot. +==== Boot variables `/chosen/bootloader` + +Raspberry Pi 5 only. + +`arg1`:: The value of the user defined reboot argument from the previous boot. See xref:config_txt.adoc#boot_arg1[boot_arg1] + +`count`:: The value of the 8-bit `boot_count` variable when the OS was started. See xref:config_txt.adoc#boot_count[boot_count] + ==== Power supply properties `/chosen/power` -Raspberry Pi 5 only. Each property is stored as a 32-bit integer unless indicated otherwise. +Raspberry Pi 5 only. `max_current`:: The maximum current in mA that the power supply can supply. The firmware reports the value indicated by the USB-C, USB-PD or PoE interfaces. For bench power supplies (e.g. connected to the GPIO header) define `PSU_MAX_CURRENT` in the bootloader configuration to indicate the power supply current capability. @@ -898,7 +913,7 @@ The format is defined by the https://usb.org/document-library/usb-power-delivery ==== BCM2711 and BCM2712 specific bootloader properties `/chosen/bootloader` -The following properties are specific to the BCM2711 and BCM2712 SPI EEPROM bootloaders. Each property is stored as a 32-bit integer unless indicated otherwise. +The following properties are specific to the BCM2711 and BCM2712 SPI EEPROM bootloaders. `build_timestamp`:: The UTC build time for the EEPROM bootloader. @@ -959,7 +974,7 @@ The following properties are specific to the BCM2711 and BCM2712 SPI EEPROM boot ==== BCM2711 and BCM2712 USB boot properties `/chosen/bootloader/usb` -The following properties are defined if the system was booted from USB. These may be used to uniquely identify the USB boot device. Each property is stored as a 32-bit integer. +The following properties are defined if the system was booted from USB. These may be used to uniquely identify the USB boot device. `usb-version`:: The USB major protocol version (2 or 3).