Skip to content

conditional: Document the new expression filter and new Pi5 boot variables #4106

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

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

conditional: Document the new expression filter and new Pi5 boot variables #4106

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
96 changes: 88 additions & 8 deletions documentation/asciidoc/computers/config_txt/conditional.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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)
[ARG<VALUE] # selected if (ARG < VALUE)
[ARG>VALUE] # 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.
Expand Down
27 changes: 21 additions & 6 deletions documentation/asciidoc/computers/configuration/device-tree.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand All @@ -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.
Expand All @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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).

Expand Down
Loading