From: Simon Glass <sjg@chromium.org> Add some information about this new bootmeth, including how to enable it and how it works. Signed-off-by: Simon Glass <sjg@chromium.org> --- doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/vbe_os.rst | 61 ++++++++++++++++++++++++++++++++++ doc/develop/vbe.rst | 2 ++ 3 files changed, 64 insertions(+) create mode 100644 doc/develop/bootstd/vbe_os.rst diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index 4c4e26ccdb7..342228064e6 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -14,3 +14,4 @@ Standard Boot cros script sandbox + vbe_os diff --git a/doc/develop/bootstd/vbe_os.rst b/doc/develop/bootstd/vbe_os.rst new file mode 100644 index 00000000000..36c1539dcd8 --- /dev/null +++ b/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" diff --git a/doc/develop/vbe.rst b/doc/develop/vbe.rst index cca193c8fd4..d951e4e7772 100644 --- a/doc/develop/vbe.rst +++ b/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_i... .. _vbe-bootflows: https://docs.google.com/document/d/e/2PACX-1vR0OzhuyRJQ8kdeOibS3xB1rVFy3J4M_... .. _vbe-fwupdate: https://docs.google.com/document/d/e/2PACX-1vTnlIL17vVbl6TVoTHWYMED0bme7oHHN... -- 2.43.0