PIBOOT-TRY(8)

NAME
piboot-try - manages A/B boot assets for the Raspberry Pi bootloader

SYNOPSIS
piboot-try [--reboot] [--validate] [--test] [--reset-new] [--restore-old]
piboot-try -h
piboot-try --help

DESCRIPTION
piboot-try implements the A/B boot mechanism on the Raspberry Pi for those boards using the "pi-try" method in the flash-kernel(8) database. The script expects to find boot assets in three locations on the boot partition, typically mounted under /boot/firmware (see FK_BOOT_MOUNT under ENVIRONMENT VARIABLES).

current/
    This sub-directory must always exist and contains the current "known good" boot assets.

new/
    If this sub-directory exists, it typically contains new, as yet untested boot assets, or assets that have been tested but failed and are marked "bad".

old/
    If this sub-directory exists, it contains older "known good" boot assets. These exist purely as a backup and are never implicitly booted.

Each time flash-kernel is run, the old/ sub-directory will be removed (if it exists), and new boot assets will be written to the new/ sub-directory. A state file will also be written (under new/state) indicating the status of the new boot assets. This will contain one of the following strings:

unknown
    The initial state for new, untested boot assets.

trying
    The state boot assets are set to immediately before rebooting to try them.

bad Indicates the boot assets failed to boot successfully.

good
    Indicates the boot assets booted successfully and passed validation.

The next time the Pi is booted (or rebooted), the piboot-try-reboot service will check the new/state file. If it contains "unknown", this will be updated to "trying" and the machine will be immediately rebooted into the tryboot mode to test the new boot assets. In the tryboot mode, the boot configuration (found in config.txt) will direct the bootloader load assets from new/ instead of current/ as usual. Because the tryboot mode is ephemeral, any failure of the boot will cause the next boot to be from the "known good" assets under current/ instead. In this case, the piboot-try-reboot service will write "bad" to the new/state file to prevent further attempts.

Alternatively, if the boot succeeds and reaches the point of running the (later) piboot-try-validate service, this will switch the sub-directories around such that current/ becomes old/ and new/ becomes current/. The old/state and current/state files always contain the state "good" under normal circumstances.

OPTIONS

--test
    Test whether new, untested boot assets are present. If they are, exit with 0, otherwise with 1. This can be used in scripts to test whether the next reboot will be a double-boot (see DOUBLE BOOT below).

--reboot
    If new, untested boot assets are present, mark them as "trying" and immediately reboot into the tryboot mode to test them. This can be used in scripts to avoid the double-boot which would otherwise occur (see DOUBLE BOOT below).

--validate
    Invoke the validation phase. This is typically called from the piboot-try-validate service. If we are in the tryboot state, mark the new assets "good" and move the current/ and new/ directories to old/ and current/ respectively. There should never be a need to execute this mode manually.

--reset-new
    Reset the state of the boot assets under new/ to "unknown". This can be used to re-test boot assets after they have failed. This option merely resets the state. The --reboot option should additionally be specified if you wish to immediately test the reset assets.

--restore-old
    Move the boot assets under current/ back to new/ and the boot assets under old/ back to current/.

    Note that after this operation, the system will be in the unusual state of having the assets under new/ marked "good". In this state, these assets will not be used. They will not be tested, or swapped in at the next boot which will simply proceed with the assets under current/. In this state, the next run of flash-kernel will overwrite the assets under new/. Alternatively, if you wish to re-test the assets under new/ directly, you may use the --reset-new option to do so.

DOUBLE BOOT
This setup does have the (potentially undesirable) side-effect that, when new boot assets are present the next boot (warm or cold) will necessarily be a double-boot. While this is a mild inconvenience for the assurance of a reliable boot setup, it is possible to avoid by triggering the tryboot mode manually.

The piboot-try script may be executed with the --test option. If there are new, untested boot assets present, this will return 0, indicating that the next boot would be a double-boot. If no untested boot assets exist, this will return 1. If new assets are present, you may invoke piboot-try with --reboot to manually trigger a tryboot mode reboot directly.

FILES

/etc/flash-kernel/piboot-validate
    This script is used by piboot-try to validate whether a set of boot assets has produced a "good" boot. It is called by the piboot-try-validate service, and must return 0 in the event that a boot is "good", and non-zero if a boot is "bad". In the latter case, after marking the assets under new/ "bad", the system will be immediately rebooted into the "known good" assets under current/.

    The default script simply returns 0, in other words simply getting to the point the script can run is considered a "good" boot. If additional tests are defined in this script, it is recommended that such tests are confined to checking for the existence of kernel devices, rather than testing their operation. This avoids potentially transient issues (e.g. failure of a DHCP server) from causing a false negative, i.e. from boot assets being marked "bad" when they should not be.

The boot assets managed by piboot-try (and by flash-kernel) consist of the following files (which can be found under the three sub-directories of the boot partition):

bootcode.bin, start*.elf, fixup*.dat
    The Pi's bootloader files (for those models where these are not present in the EEPROM).

bcm*-rpi-*.dtb
    The base device-trees.

vmlinuz
    The Linux kernel.

cmdline.txt
    The Linux kernel command line.

initrd.img
    The initial ram-disk image.

overlays/*.dtbo
    The sub-directory containing all device-tree overlays (along with the HAT and overlay maps, and README).

state
    The current state of this set of boot assets. May contain one of the strings "good", "bad", "unknown", or "trying".

ENVIRONMENT VARIABLES

FK_BOOT_MOUNT
    Specify the mount point of the (FAT formatted) boot partition. Defaults to /boot/firmware.

FK_ETC_VALIDATE
    Specify the script (or binary) to execute in order to validate the current boot assets. Defaults to /etc/flash-kernel/piboot-validate. Ideally, you should edit the script rather than override this variable, but if you need to do so, override the environment of the piboot-try-validate service.

SEE ALSO
flash-kernel(8)

AUTHOR
Dave Jones <dave.jones@canonical.com>