boot: Add documentation for the VBE-OS bootmeth

Add some information about this new bootmeth, including how to enable it
and how it works.

Series-to: concept
Cover-letter:
boot: Enhance VBE to support a separate devicetree FIT
It is sometimes desirable to have the devicetrees packaged with firware,
or in a different FIT from the OS. This series adds support for this,
including a test.

The new bootmeth can automatically locate a state file and use that to
decide what images to use when booting. The OS must update the file
before rebooting, if a different selection is required.

For now there is no logic to deal with boot failures.
END

Signed-off-by: Simon Glass <sjg@chromium.org>

doc/develop/bootstd/index.rst

@@ -14,3 +14,4 @@ Standard Boot
    cros
    script
    sandbox
+   vbe_os

doc/develop/bootstd/vbe_os.rst

@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+VBE OS Bootmeth
+===============
+
+VBE supports a separate FIT for devicetrees and the OS. This bootmeth detects
+the `vbe-state` file on the media and uses this to determine the bootflow to
+use: there may be two or three separate FITs, for the A, B and recovery flows.
+
+In embedded systems it is common to package the devicetrees with the OS in
+a FIT. Thus both can be updated together by writing a single file.
+
+For distros which want to provide broad hardware support, it is sometimes
+desirable to package the devicetrees separately from the OS, so they can have
+their own OEM-controlled lifecycle. This allows the OS package to be somewhat
+smalller than if it had all the devicetrees included.
+
+In terms of lifecycle, the OEM may update the devicetree FIT as part of firmware
+update, or a separate OS package.
+
+There are challenges with this approach and it is best suited for fairly stable
+platforms. Particularly in the early days of Linux supporting a particular
+SoC, the devicetree/kernel interface may not be fully stable. It is often more
+desirable to transition to using an OEM FIT once stability is achieved.
+
+It is also possible to put small overlays in the OS FIT, e.g. to enable a
+feature which was not working at launch. This results in smaller FITs tha
+packaging the entire devicetree for each board.
+
+The compatible string "vbe,abrec-os" is used for the driver. It is present
+if `CONFIG_BOOTMETH_VBE_ABREC_OS` is enabled.
+
+For more information on VBE, see :doc:`../vbe`.
+
+Partition format
+----------------
+
+Boot files should be stored on a separate boot partition, formatted as ext4.
+
+Each slot (A, B, recovery) has a subdirectory containing an
+`extlinux/extlinux.conf` file. This provides information about the OS fit for
+each OS version.
+
+The VBE bootmeth requires a file called `vbe-state` to be present in the root
+directory of the boot partition, to indicate which slot to boot.
+
+The `vbe-state` file is a devicetree blob, with the following schema:
+
+root node
+    compatible: "vbe,abrec-state"
+
+/os node:
+    compatible: "vbe,os-state"
+
+/os/next-boot:
+    Indicates the slot that will be used on the next boot. It has a single
+    property:
+
+    slot (string)
+        Indicates the slot that will be used on the next boot; valid values
+        are "a", "b", and "recovery"

doc/develop/vbe.rst

@@ -21,6 +21,8 @@ For a detailed overview of VBE, see vbe-intro_. A fuller description of
 bootflows is at vbe-bootflows_ and the firmware-update mechanism is described at
 vbe-fwupdate_. VBE OS requests are described at  vbe-osrequests_.
 
+See also :doc:`bootstd/vbe_os`.
+
 .. _vbe-intro: https://docs.google.com/document/d/e/2PACX-1vQjXLPWMIyVktaTMf8edHZYDrEvMYD_iNzIj1FgPmKF37fpglAC47Tt5cvPBC5fvTdoK-GA5Zv1wifo/pub
 .. _vbe-bootflows: https://docs.google.com/document/d/e/2PACX-1vR0OzhuyRJQ8kdeOibS3xB1rVFy3J4M_QKTM5-3vPIBNcdvR0W8EXu9ymG-yWfqthzWoM4JUNhqwydN/pub
 .. _vbe-fwupdate: https://docs.google.com/document/d/e/2PACX-1vTnlIL17vVbl6TVoTHWYMED0bme7oHHNk-g5VGxblbPiKIdGDALE1HKId8Go5f0g1eziLsv4h9bocbk/pub