From fc8aa553eb722793c5119e54c39f8f20a69068b7 Mon Sep 17 00:00:00 2001 From: Tim Gover Date: Mon, 14 Nov 2022 10:46:51 +0000 Subject: [PATCH 1/4] Fix /proc/device-tree/chosen bootloader hierarchy The common bootloade properties that are implemented for all Raspberry Pi computer versions (e.g. tryboot) were shown a level too high. --- .../computers/configuration/device-tree.adoc | 27 ++++++++++--------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/documentation/asciidoc/computers/configuration/device-tree.adoc b/documentation/asciidoc/computers/configuration/device-tree.adoc index ca6da4fca..635f151bc 100644 --- a/documentation/asciidoc/computers/configuration/device-tree.adoc +++ b/documentation/asciidoc/computers/configuration/device-tree.adoc @@ -801,10 +801,6 @@ As it is too time-consuming to document the individual overlays here, please ref === 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. -`boot-mode` - 32-bit integer - -The boot-mode used to load the kernel. See xref:raspberry-pi.adoc#BOOT_ORDER[BOOT_ORDER]. - `overlay_prefix` - string The xref:config_txt.adoc#overlay_prefix[overlay_prefix] string selected by `config.txt`. @@ -813,14 +809,6 @@ The xref:config_txt.adoc#overlay_prefix[overlay_prefix] string selected by `conf The xref:config_txt.adoc#os_prefix[os_prefix] string selected by `config.txt`. -`partition` - 32-bit integer - -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. - -`pm_rsts` - 32-bit integer - -The value of the `PM_RSTS` register during boot. - `rpi-boardrev-ext` - 32-bit integer The extended board revision code from xref:raspberry-pi.adoc#otp-register-and-bit-definitions[OTP row 33]. @@ -829,11 +817,24 @@ The extended board revision code from xref:raspberry-pi.adoc#otp-register-and-bi The country code used used by https://github.com/raspberrypi-ui/piwiz[PiWiz] - Pi400 only. +==== Common bootloader properties `/chosen/bootloader` +`boot-mode` - 32-bit integer + +The boot-mode used to load the kernel. See xref:raspberry-pi.adoc#BOOT_ORDER[BOOT_ORDER]. + +`partition` - 32-bit integer + +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. + +`pm_rsts` - 32-bit integer + +The value of the `PM_RSTS` register during boot. + `tryboot` - 32-bit integer Set to `1` if the `tryboot` flag was set at boot. -==== BCM2711 bootloader properties `/chosen/bootloader` +==== BCM2711 specific bootloader properties `/chosen/bootloader` The following properties are specific to BCM2711 SPI EEPROM bootloader. `build_timestamp` - 32-bit integer From e86d043e27ff3c53a60e0c3bc54b9783f70bf8e5 Mon Sep 17 00:00:00 2001 From: Tim Gover Date: Mon, 14 Nov 2022 10:43:04 +0000 Subject: [PATCH 2/4] autoboot.txt: Update the example to include pseudo code for usage Add some pseudo code showing how a hypothetical Linux software (swupdate, Mender, custom) updater could use the tryboot feature. Exactly, when/how updates occur or other partition layouts is up to the updater and outside the scope of the bootloader. --- .../computers/config_txt/autoboot.adoc | 44 ++++++++++++++++--- 1 file changed, 38 insertions(+), 6 deletions(-) diff --git a/documentation/asciidoc/computers/config_txt/autoboot.adoc b/documentation/asciidoc/computers/config_txt/autoboot.adoc index e8af9c000..e749869ce 100644 --- a/documentation/asciidoc/computers/config_txt/autoboot.adoc +++ b/documentation/asciidoc/computers/config_txt/autoboot.adoc @@ -24,14 +24,11 @@ Set this property to `1` to load the normal `config.txt` and `boot.img` files in This enables the `tryboot` switch to be made at the partition level rather than the file-level without having to modify configuration files in the A/B partitions. -=== A/B boot example -In the following example partition `3` would be contain the pending OS upgrade and would be tested by rebooting in `tryboot` mode (`sudo reboot "0 tryboot"`). -If the OS determines that the upgrade was successful then it would replace `autoboot.txt` swapping the partition numbers. -Otherwise, if the system is reboot (e.g. watchdog or cold boot) then system would boot from partition `2` as usual. +=== Example update flow for A/B booting -Since the `autoboot.txt` file is a single sector it will normally be possible to update this with a single sector update to the SD/EMMC. +The following pseudo code shows how an hypothetical OS `Update Service` could use `tryboot` + `autoboot.txt` to perform an fail-safe OS upgrade. -`autoboot.txt` +Initial `autoboot.txt` ---- [all] tryboot_a_b=1 @@ -39,3 +36,38 @@ boot_partition=2 [tryboot] boot_partition=3 ---- + +**Installing the update** + +* System is powered on and boots to partition 2 by default. +* An `Update Service` downloads the next version of the OS to partition 3. +* The update is tested by rebooting to partition 3 in `tryboot` mode `reboot "3 tryboot"` + +**Committing or cancelling the update** + +* System boots from partition 3 because the `[tryboot]` filter evaluates to true in `tryboot mode`. +* If tryboot is active (`/proc/device-tree/chosen/bootloader/tryboot == 1`) + ** If the current boot partition (`/proc/device-tree/chosen/bootloader/partition`) matches the `boot_partition` in the `[tryboot]` section of `autoboot.txt` + *** The `Update Service` validates the system to verify that the update was successful. + *** If the update was successful + **** Replace `autoboot.txt` swapping the `boot_partition` configuration. + **** Normal reboot - partition 3 is now the default boot partition. + *** Else + **** `Update Service` marks the update as failed e.g. it removes the update files. + **** Normal reboot - partition 2 is still the default boot partition because the `tryboot` flag is automatically cleared. + *** End if + ** End If +* End If + +Updated `autoboot.txt` +---- +[all] +tryboot_a_b=1 +boot_partition=3 +[tryboot] +boot_partition=2 +---- + +**Notes** +* It's not mandatory to reboot after updating `autoboot.txt`. However, the `Update Service` must be careful to avoid overwriting the current partition since `autoboot.txt` has already been modified to commit the last update.. +* See also: xref:configuration.adoc#device-trees-overlays-and-parameters[Device-tree parameters]. From 47bc7332bc089022da61636fdf31af4711866420 Mon Sep 17 00:00:00 2001 From: Tim Gover Date: Mon, 14 Nov 2022 17:09:34 +0000 Subject: [PATCH 3/4] autoboot.txt - specifiy 0 for the default partition in reboot call --- documentation/asciidoc/computers/config_txt/autoboot.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/asciidoc/computers/config_txt/autoboot.adoc b/documentation/asciidoc/computers/config_txt/autoboot.adoc index e749869ce..5e1c4ee7a 100644 --- a/documentation/asciidoc/computers/config_txt/autoboot.adoc +++ b/documentation/asciidoc/computers/config_txt/autoboot.adoc @@ -41,7 +41,7 @@ boot_partition=3 * System is powered on and boots to partition 2 by default. * An `Update Service` downloads the next version of the OS to partition 3. -* The update is tested by rebooting to partition 3 in `tryboot` mode `reboot "3 tryboot"` +* The update is tested by rebooting to `tryboot` mode `reboot "0 tryboot"` where `0` means the default partition. **Committing or cancelling the update** From 81f22de2899a42e9de3d4f72c20e95d243324636 Mon Sep 17 00:00:00 2001 From: Toby Roberts <29973222+tobybroberts@users.noreply.github.com> Date: Tue, 22 Nov 2022 14:06:10 +0000 Subject: [PATCH 4/4] Updated video url --- documentation/asciidoc/accessories/audio/getting_started.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/asciidoc/accessories/audio/getting_started.adoc b/documentation/asciidoc/accessories/audio/getting_started.adoc index 3be0659d1..10a8729b2 100644 --- a/documentation/asciidoc/accessories/audio/getting_started.adoc +++ b/documentation/asciidoc/accessories/audio/getting_started.adoc @@ -125,7 +125,7 @@ Ctrl X, Y and Enter to save, then reboot your device. The final step is to ensure that everything is operating as expected. Press the button and release it when you hear the burp. The recording will now begin for a period of five seconds. Once you have released the button, press it briefly again to hear the recording. Repeat this process as many times as you wish, and your sounds will be played at random. You can delete all recordings by pressing and holding the button, keeping the button pressed during the first burp and recording process, and releasing it after at least 20 seconds, at which point you will hear another burp sound confirming that the recordings have been deleted. -video::aUD_rcpc08I[youtube] +video::BjXERzu8nS0[youtube] === Next steps