Merge patch series "bootstd: New bootmeth for RAUC A/B systems"

Martin Schwan <[email protected]> says:

This series implements a new bootmeth for RAUC A/B systems. RAUC (Robust
Auto Update Controller) is a lightweight update client, providing "Safe
and Secure OTA Updates for Embedded Linux". See the following links for
more information about RAUC:

  https://rauc.io/
  https://rauc.readthedocs.io/en/latest/

PHYTEC uses RAUC in its Yocto based distribution "Ampliphy" as the
default way of updating embedded devices based on PHYTEC hardware. So
far, the logic selecting the correct partitions and files to boot was
being implemented in the U-Boot environment. While this is a
straightforward way to do it, adding and supporting new platforms became
somewhat tedious and is platform-specific. The introduction of U-Boot's
"Standard Boot" provided a convincing alternative, promising a simpler
and more portable way of booting, even for RAUC systems. This led me to
implement a new bootmeth supporting RAUC A/B systems. Note, that this
new bootmeth is not proprietary to PHYTEC products and is designed to
work on other hardware with a RAUC A/B system, too.

The bootmeth currently only supports symmetric A/B partitioning layouts.
E.g. A/rescue is not (yet) supported. The partition indexes and default
slot tries can be specified via configuration options.

For now, the bootmeth_rauc uses a similar approach for loading the
Kernel and device tree as the bootmeth_script, in that it requires a FIT
containing a U-Boot script loading the desired distro. It could be
possible to support booting without a script and load the Kernel and DT
directly with this bootmeth, but I found the script method to be very
flexible for now, in letting the distro decide what to load.

The bootmeth_rauc was tested on a phyBOARD-Pollux i.MX8M Plus [1] with
BSP-Yocto-Ampliphy-i.MX8MP-PD24.1.2 [2].

Supported boot devices are currently only MMC devices, but it should be
possible to add SPI flashes in the future.

To test this patch stack with PHYTEC's phyBOARD-Pollux i.MX8M Plus
board, you need to adjust the boot files to include the boot.scr.uimg
containing the distro's boot script and set "optargs" to "${raucargs}"
in it. Also disable any legacyboot in the U-Boot environment and simply
boot with Standard Boot:

  bootmeth order rauc
  bootflow scan -lb

[1]: https://www.phytec.eu/en/produkte/single-board-computer/phyboard-pollux/
[2]: https://download.phytec.de/Software/Linux/BSP-Yocto-i.MX8MP/BSP-Yocto-Ampliphy-i.MX8MP-PD24.1.2/

Link: https://lore.kernel.org/r/[email protected]
[trini: Don't enable by default]

3 files changed, 58 insertions, 0 deletions

diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
index 4c4e26ccdb7..ec74fc2fb9d 100644
--- a/doc/develop/bootstd/index.rst
+++ b/doc/develop/bootstd/index.rst
@@ -12,5 +12,6 @@ Standard Boot
    qfw
    android
    cros
+   rauc
    script
    sandbox
diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
index 9fe5630ab16..0a237359575 100644
--- a/doc/develop/bootstd/overview.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -443,6 +443,7 @@ Bootmeth drivers are provided for booting from various media:
    - :doc:`extlinux / syslinux <extlinux>` boot from a storage device
    - :doc:`extlinux / syslinux <extlinux>` boot from a network (PXE)
    - :doc:`sandbox <sandbox>` used only for testing
+   - :doc:`RAUC distro <rauc>`: A/B system with RAUC from MMC
    - :doc:`U-Boot scripts <script>` from disk, network or SPI flash
    - :doc:`QFW <qfw>`: QEMU firmware interface
    - :doc:`VBE </develop/vbe>`: Verified Boot for Embedded
diff --git a/doc/develop/bootstd/rauc.rst b/doc/develop/bootstd/rauc.rst
new file mode 100644
index 00000000000..b2661d18da4
--- /dev/null
+++ b/doc/develop/bootstd/rauc.rst
@@ -0,0 +1,56 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+RAUC Bootmeth
+=============
+
+This bootmeth provides a way to locate and run an A/B system with RAUC as its
+update client. The booted distro must supply a script on an MMC device
+containing the final boot instructions necessary.
+
+This bootmeth assumes a symmetric A/B partition layout, with a separate boot
+partition containing the kernel image and another partition for the root
+filesystem each. The partition numbers must be specified with
+``CONFIG_BOOTMETH_RAUC_PARTITIONS``. The content must be a list of pairs, with
+the following syntax: ``1,2 3,4``, where 1 and 3 are the slots' boot partition
+and 2 and 4 the slots' root partition.
+
+Each pair of boot and rootfs partition form a "slot". The default order in which
+available slots are tried is set through ``CONFIG_BOOTMETH_RAUC_BOOT_ORDER``,
+with the left one tried first.
+
+The default number of boot tries of each slot is set by
+``CONFIG_BOOTMETH_RAUC_DEFAULT_TRIES``.
+
+In case no valid slot can be found and/or all slots have zero tries left, the
+boot order and slot tries are reset to their default values, if
+``CONFIG_BOOTMETH_RAUC_RESET_ALL_ZERO_TRIES`` is enabled. This prevents a system
+from locking up in the bootloader and tries booting again after a specified
+number of tries.
+
+The boot script must be located in each boot partition. The bootmeth searches
+for "boot.scr.uimg" first, then "boot.scr" if not found.
+
+When the bootflow is booted, the bootmeth sets these environment variables:
+
+devtype
+    device type (e.g. "mmc")
+
+devnum
+    device number, corresponding to the device 'sequence' number
+    ``dev_seq(dev)``
+
+distro_bootpart
+    partition number of the boot partition on the device (numbered from 1)
+
+distro_rootpart
+    partition number of the rootfs partition on the device (numbered from 1)
+
+raucargs
+    kernel command line arguments needed for RAUC to detect the currently booted
+    slot
+
+The script file must be a FIT or a legacy uImage. It is loaded into memory and
+executed.
+
+The compatible string "u-boot,distro-rauc" is used for the driver. It is present
+if ``CONFIG_BOOTMETH_RAUC`` is enabled.