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 diff --git a/documentation/asciidoc/computers/config_txt/autoboot.adoc b/documentation/asciidoc/computers/config_txt/autoboot.adoc index e8af9c000..5e1c4ee7a 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 `tryboot` mode `reboot "0 tryboot"` where `0` means the default partition. + +**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]. 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