Skip to content

Push to production #2701

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

Merged
merged 7 commits into from
Nov 22, 2022
Merged

Push to production #2701

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
fc8aa55
Fix /proc/device-tree/chosen bootloader hierarchy
timg236 Nov 14, 2022
e86d043
autoboot.txt: Update the example to include pseudo code for usage
timg236 Nov 14, 2022
fe96110
Merge pull request #2697 from timg236/autoboot-pseudo-code
Nov 14, 2022
47bc733
autoboot.txt - specifiy 0 for the default partition in reboot call
timg236 Nov 14, 2022
437af5d
Merge pull request #2698 from timg236/autoboot-partition-0
Nov 14, 2022
81f22de
Updated video url
tobybroberts Nov 22, 2022
323bb77
Merge pull request #2700 from raspberrypi/tobybroberts-patch-1
Nov 22, 2022
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
2 changes: 1 addition & 1 deletion documentation/asciidoc/accessories/audio/getting_started.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
44 changes: 38 additions & 6 deletions documentation/asciidoc/computers/config_txt/autoboot.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,18 +24,50 @@ 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
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].
27 changes: 14 additions & 13 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 @@ -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`.
Expand All @@ -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].
Expand All @@ -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
Expand Down