Merge tag 'efi-2024-10-rc1-3' of https://source.denx.de/u-boot/custodians/u-boot-efi

Pull request efi-2024-10-rc1-3

Documentation:

* Move out-of-tree building info to HTML
* Enable ReadTheDocs addon management
* Remove FIT documentation that is elsewhere
* Update table of contents for FIT images
* Add description for more boot methods

UEFI:

* Correct finding distro device-path for media devices
* Fix typo in EFI_RT_VOLATILE_STORE description

Other:

* MAINTAINERS: Rename BOOTDEVICE

19 files changed, 289 insertions, 706 deletions

diff --git a/doc/board/starfive/milk-v_mars_cm.rst b/doc/board/starfive/milk-v_mars_cm.rst
index b31de6043bb..52d4e5e9098 100644
--- a/doc/board/starfive/milk-v_mars_cm.rst
+++ b/doc/board/starfive/milk-v_mars_cm.rst
@@ -89,7 +89,7 @@ provide a default value.
 
 The variable *$fdtfile* is used in the boot process to automatically load
 a device-tree provided by the operating system. For details of the boot
-process refer to the :doc:`U-Boot Standard Boot <../../../develop/bootstd>`
+process refer to the :doc:`/develop/bootstd/index`
 description.
 
 Boot source selection
diff --git a/doc/build/gcc.rst b/doc/build/gcc.rst
index 3c646577272..d8fcfdc4bf2 100644
--- a/doc/build/gcc.rst
+++ b/doc/build/gcc.rst
@@ -118,6 +118,34 @@ Assuming cross compiling on Debian for ARMv8 this would be
 
     CROSS_COMPILE=aarch64-linux-gnu- make
 
+Out-of-tree building
+~~~~~~~~~~~~~~~~~~~~
+
+By default building is performed locally and the objects are saved in the source
+directory. To build out-out-tree use one of the two methods below:
+
+Add O= parameter to the make command line:
+
+.. code-block:: bash
+
+    make O=/tmp/build distclean
+    make O=/tmp/build NAME_defconfig
+    make O=/tmp/build
+
+Use environment variable KBUILD_OUTPUT:
+
+.. code-block:: bash
+
+    export KBUILD_OUTPUT=/tmp/build
+    make distclean
+    make NAME_defconfig
+    make
+
+.. note::
+
+    The command line "O=" parameter overrides the KBUILD_OUTPUT environment
+    variable.
+
 Build parameters
 ~~~~~~~~~~~~~~~~
 
diff --git a/doc/conf.py b/doc/conf.py
index c9138a5a5d4..e79134cc3d7 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -21,6 +21,12 @@ from subprocess import check_output
 # Get Sphinx version
 major, minor, patch = sphinx.version_info[:3]
 
+# Set canonical URL from the Read the Docs Domain
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
+
+# Tell Jinja2 templates the build is running on Read the Docs
+if os.environ.get("READTHEDOCS", "") == "True":
+    html_context["READTHEDOCS"] = True
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
diff --git a/doc/develop/board_best_practices.rst b/doc/develop/board_best_practices.rst
index f44401eab7d..09632c80ce7 100644
--- a/doc/develop/board_best_practices.rst
+++ b/doc/develop/board_best_practices.rst
@@ -7,7 +7,7 @@ In addition to the regular best practices such as using :doc:`checkpatch` and
 following the :doc:`docstyle` and the :doc:`codingstyle` there are some things
 which are specific to creating a new board port.
 
-* Implement :doc:`bootstd` to ensure that most operating systems will be
+* Implement :doc:`bootstd/index` to ensure that most operating systems will be
   supported by the platform.
 
 * The platform defconfig file must be generated via `make savedefconfig`.
diff --git a/doc/develop/bootstd/cros.rst b/doc/develop/bootstd/cros.rst
new file mode 100644
index 00000000000..85af10588c1
--- /dev/null
+++ b/doc/develop/bootstd/cros.rst
@@ -0,0 +1,33 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+ChromiumOS Bootmeth
+===================
+
+ChromiumOS provides a mechanism for booting its Operating System from a block
+device, described
+`here <https://www.chromium.org/chromium-os/chromiumos-design-docs/verified-boot/>`_.
+
+U-Boot includes support for reading the associated data structures from the
+device and identifying a bootable ChromiumOS image. This structure includes the
+kernel itself, boot arguments (kernel command line), as well as the x86 setup
+block (for x86 only).
+
+When invoked on a bootdev, this bootmeth searches for kernel partitions with
+the appropriate GUID (Globally Unique Identifier). When found, the information
+is loaded and a bootflow is created.
+
+When the bootflow is booted, the bootmeth reads the kernel and boot arguments.
+It then boots the kernel using zboot (on x86) or bootm (on ARM). The boot
+arguments are adjusted to replace `%U` with the UUID of the selected kernel
+partition. This results in the correct root disk being used, which is the next
+partition after the kernel partition.
+
+For ARM, a :doc:`/usage/fit/index` is used. The `CONFIG_FIT_BEST_MATCH` option
+must be enabled for U-Boot to select the correct devicetree to boot with.
+
+Note that a ChromiumOS image typically has two copies of the Operating System,
+each with its own kernel and root disk. There is no initial ramdisk (initrd).
+This means that this bootmeth typically locates two separate images.
+
+The compatible string "u-boot,cros" is used for the driver. It is present
+if `CONFIG_BOOTMETH_CROS` is enabled.
diff --git a/doc/develop/bootstd/extlinux.rst b/doc/develop/bootstd/extlinux.rst
new file mode 100644
index 00000000000..bf27dc57aaa
--- /dev/null
+++ b/doc/develop/bootstd/extlinux.rst
@@ -0,0 +1,29 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Extlinux Bootmeth
+=================
+
+`Extlinux <https://uapi-group.org/specifications/specs/boot_loader_specification>`_
+(sometimes called syslinux) allows U-Boot to provide a menu of available
+operating systems from which the user can choose.
+
+U-Boot includes a parser for the `extlinux.conf` file. It consists primarily of
+a list of named operating systems along with the kernel, initial ramdisk and
+other settings. The file is stored in the `extlinux/` subdirectory, possibly
+under the `boot/` subdirectory. This list of prefixes (``{"/", "/boot"}`` by
+default) can be selected with the `filename-prefixes` property in the bootstd
+device.
+
+Note that the :doc:`pxelinux` uses the same file format, but in a
+network context.
+
+When invoked on a bootdev, this bootmeth searches for the file and creates a
+bootflow if found.
+
+When the bootflow is booted, the bootmeth calls ``pxe_setup_ctx()`` to set up
+the context, then ``pxe_process()`` to process the file. Depending on the
+contents, this may boot an operating system or provide a list of options to
+the user, perhaps with a timeout.
+
+The compatible string "u-boot,extlinux" is used for the driver. It is present
+if `CONFIG_BOOTMETH_EXTLINUX` is enabled.
diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
new file mode 100644
index 00000000000..9d35b567d55
--- /dev/null
+++ b/doc/develop/bootstd/index.rst
@@ -0,0 +1,15 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Standard Boot
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
+   extlinux
+   pxelinux
+   qfw
+   cros
+   script
+   sandbox
diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd/overview.rst
index bdda90fae3f..ff3cc48eb64 100644
--- a/doc/develop/bootstd.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -1,7 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0+:
 
-U-Boot Standard Boot
-====================
+Standard Boot Overview
+======================
 
 Introduction
 ------------
@@ -17,7 +17,7 @@ introduces the following concepts:
 For Linux, the distro (Linux distribution, e.g. Debian, Fedora) is responsible
 for creating a bootflow for each kernel combination that it wants to offer.
 These bootflows are stored on media so they can be discovered by U-Boot. This
-feature is typically called `distro boot` (see :doc:`distro`) because it is
+feature is typically called `distro boot` (see :doc:`../distro`) because it is
 a way for distributions to boot on any hardware.
 
 Traditionally U-Boot has relied on scripts to implement this feature. See
@@ -32,7 +32,7 @@ way to boot with U-Boot. The feature is extensible to different Operating
 Systems (such as Chromium OS) and devices (beyond just block and network
 devices). It supports EFI boot and EFI bootmgr too.
 
-Finally, standard boot supports the operation of :doc:`vbe`.
+Finally, standard boot supports the operation of :doc:`../vbe`.
 
 Bootflow
 --------
@@ -410,20 +410,39 @@ You should probably also enable `CONFIG_BOOTSTD_DEFAULTS`, which provides
 several filesystem and network features (if `CONFIG_NET` is enabled) so that
 a good selection of boot options is available.
 
+Some devicetree properties are supported in the bootstd node when
+`CONFIG_BOOTSTD_FULL` is enabled:
+
+    filename-prefixes
+        List of prefixes to use when searching for files on block devices. This
+        defaults to {"/", "/boot/"} if not provided.
+
+    bootdev-order
+        Lists the bootdev ordering to use. Note that the deprecated
+        `boot_targets` environment variable overrides this, if present.
+
+    theme (subnode)
+        Sets the theme to use for menus. See :doc:`/develop/expo`.
 
 Available bootmeth drivers
 --------------------------
 
-Bootmeth drivers are provided for:
+Bootmeth drivers are provided for booting from various media:
 
-   - extlinux / syslinux boot from a disk
-   - extlinux boot from a network (PXE)
-   - U-Boot scripts from disk, network or SPI flash
+   - Android bootflow (boot image v4)
+   - :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk
    - EFI boot using bootefi from disk
-   - VBE
    - EFI boot using boot manager
-   - Android bootflow (boot image v4)
+   - :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:`U-Boot scripts <script>` from disk, network or SPI flash
+   - :doc:`QFW <qfw>`: QEMU firmware interface
+   - :doc:`VBE </develop/vbe>`: Verified Boot for Embedded
 
+Each driver is controlled by a Kconfig option. If no bootmeth driver is
+selected by a compatible string in the devicetree, all available bootmeth
+drivers are bound automatically.
 
 Command interface
 -----------------
@@ -432,16 +451,16 @@ Three commands are available:
 
 `bootdev`
     Allows listing of available bootdevs, selecting a particular one and
-    getting information about it. See :doc:`../usage/cmd/bootdev`
+    getting information about it. See :doc:`/usage/cmd/bootdev`
 
 `bootflow`
     Allows scanning one or more bootdevs for bootflows, listing available
     bootflows, selecting one, obtaining information about it and booting it.
-    See :doc:`../usage/cmd/bootflow`
+    See :doc:`/usage/cmd/bootflow`
 
 `bootmeth`
     Allow listing of available bootmethds and setting the order in which they
-    are tried. See :doc:`../usage/cmd/bootmeth`
+    are tried. See :doc:`/usage/cmd/bootmeth`
 
 .. _BootflowStates:
 
diff --git a/doc/develop/bootstd/pxelinux.rst b/doc/develop/bootstd/pxelinux.rst
new file mode 100644
index 00000000000..c4b7fbb4c9c
--- /dev/null
+++ b/doc/develop/bootstd/pxelinux.rst
@@ -0,0 +1,27 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+PXE Bootmeth
+============
+
+PXE (Preboot eXecution-Environment) provides a way to boot an operating system
+over a network interface. The PXE bootmeth supports PXELINUX and allows U-Boot to
+provide a menu of possible Operating Systems from which the user can choose.
+
+U-Boot includes a parser for the `extlinux.conf` file described
+`here <https://uapi-group.org/specifications/specs/boot_loader_specification>`_.
+It consists primarily of a list of named operating systems along with the
+kernel, initial ramdisk and other settings. The file is retrieved from a network
+server using the TFTP protocol.
+
+When invoked on a bootdev, this bootmeth searches for the file and creates a
+bootflow if found. See
+`PXELINUX <https://wiki.syslinux.org/wiki/index.php?title=PXELINUX>`_ for
+a full description of the search procedure.
+
+When the bootflow is booted, the bootmeth calls ``pxe_setup_ctx()`` to set up
+the context, then ``pxe_process()`` to process the file. Depending on the
+contents, this may boot an Operating System or provide a list of options to the
+user, perhaps with a timeout.
+
+The compatible string "u-boot,extlinux-pxe" is used for the driver. It is
+present if `CONFIG_BOOTMETH_EXTLINUX_PXE` is enabled.
diff --git a/doc/develop/bootstd/qfw.rst b/doc/develop/bootstd/qfw.rst
new file mode 100644
index 00000000000..70086ad1817
--- /dev/null
+++ b/doc/develop/bootstd/qfw.rst
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+QFW Bootmeth
+============
+
+`QEMU <hhttps://www.qemu.org/>`_ is a system emulator which is able to boot
+Operating Systems. QEMU provides specific support for booting an OS image
+provided on the QEMU command line.
+
+When invoked on a bootdev for UCLASS_QFW, this bootmeth reads the kernel
+provided by the QEMU `-kernel` argument, the initial ramdisk provided by
+`-initrd` and the boot arguments (command line) provided by `-append` into
+memory ready for booting.
+
+When the bootflow is booted, the bootmeth tries the `booti` command first, then
+falls back to the `bootz` command. U-Boot's 'control' devicetree is passed
+through to the kernel.
+
+The compatible string "u-boot,qfw-bootmeth" is used for the driver. It is
+present if `CONFIG_QFW` is enabled.
diff --git a/doc/develop/bootstd/sandbox.rst b/doc/develop/bootstd/sandbox.rst
new file mode 100644
index 00000000000..d501518c39a
--- /dev/null
+++ b/doc/develop/bootstd/sandbox.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Sandbox Bootmeth
+================
+
+The sandbox bootmeth is only used for testing. It does not provide any facility
+for booting an OS. While sandbox can do all the processing before the actual
+boot, it is not connected in this bootmeth.
+
+When invoked on a bootdev, this bootmeth pretends to find a bootflow and creates
+the associated structure.
+
+When the bootflow is booted, the bootmeth returns `-ENOTSUPP` indicating that it
+is not supported.
+
+The compatible string "u-boot,sandbox-bootmeth" is used for the driver. It is present
+if `CONFIG_BOOTMETH_SANDBOX` is enabled.
diff --git a/doc/develop/bootstd/script.rst b/doc/develop/bootstd/script.rst
new file mode 100644
index 00000000000..47f3684b86b
--- /dev/null
+++ b/doc/develop/bootstd/script.rst
@@ -0,0 +1,52 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Script Bootmeth
+===============
+
+This bootmeth provides a way to locate and run a script on a block or network
+device. It can also support SPI flash.
+
+For a block device the file is read from the selected partition, which must use
+a supported filesystem. The subdirectory to search in is defined by the bootstd
+list of prefixes (``{"/", "/boot"}`` by default) and can be adjust with the
+`filename-prefixes` property in the bootstd device.
+
+For a network device, the filename is obtained from the `boot_script_dhcp`
+environment variable and the file is read using tftp. It must be in the
+top-level directory of the tftp server.
+
+In either case (file or network), the bootmeth searches for the file and creates
+a bootflow if found. The bootmeth searches for "boot.scr.uimg" first, then
+"boot.scr" if not found.
+
+For SPI flash, a script is read from flash using the offset provided by the
+"script_offset_f" environment variable.
+
+Some attempt is made to identify the Operating System: so far this only detects
+an `Armbian <https://www.armbian.com>`_
+distro. For block devices, if a file called "boot.bmp" exists in the same
+directory then it is used as the bootflow logo.
+
+When the bootflow is booted, the bootmeth sets these environment variables:
+
+    devtype
+        device type (e.g. "usb", "mmc", "ethernet" or "spi_flash")
+
+    devnum
+        device number, corresponding to the device 'sequence' number
+        ``dev_seq(dev)``
+
+    distro_bootpart
+        (block devices only) partition number on the device (numbered from 1)
+
+    prefix
+        prefix used to find the file
+
+    mmc_bootdev
+        device number (same as `devnum`), set for sunxi mmc devices only
+
+The script file must be a FIT or a legacy uImage. It is loaded into memory and
+executed.
+
+The compatible string "u-boot,script" is used for the driver. It is present
+if `CONFIG_BOOTMETH_SCRIPT` is enabled.
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index f9c4bf839ee..c0107a783fc 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -29,7 +29,7 @@ Implementation
 
    directories
    bloblist
-   bootstd
+   bootstd/index
    ci_testing
    commands
    config_binding
diff --git a/doc/usage/cmd/bootdev.rst b/doc/usage/cmd/bootdev.rst
index f759abab354..98a0f43c580 100644
--- a/doc/usage/cmd/bootdev.rst
+++ b/doc/usage/cmd/bootdev.rst
@@ -22,7 +22,7 @@ Description
 The `bootdev` command is used to manage bootdevs. It can list available
 bootdevs, select one and obtain information about it.
 
-See :doc:`../../develop/bootstd` for more information about bootdevs in general.
+See :doc:`/develop/bootstd/index` for more information about bootdevs in general.
 
 
 bootdev list
diff --git a/doc/usage/cmd/bootflow.rst b/doc/usage/cmd/bootflow.rst
index 6519e4880a9..5d41fe37a7a 100644
--- a/doc/usage/cmd/bootflow.rst
+++ b/doc/usage/cmd/bootflow.rst
@@ -26,7 +26,7 @@ Description
 The `bootflow` command is used to manage bootflows. It can scan bootdevs to
 locate bootflows, list them and boot them.
 
-See :doc:`../../develop/bootstd` for more information.
+See :doc:`/develop/bootstd/index` for more information.
 
 Note that `CONFIG_BOOTSTD_FULL` (which enables `CONFIG_CMD_BOOTFLOW_FULL) must
 be enabled to obtain full functionality with this command. Otherwise, it only
diff --git a/doc/usage/cmd/bootmeth.rst b/doc/usage/cmd/bootmeth.rst
index bac9fdf85cd..c3d2ec1574b 100644
--- a/doc/usage/cmd/bootmeth.rst
+++ b/doc/usage/cmd/bootmeth.rst
@@ -21,7 +21,7 @@ Description
 The `bootmeth` command is used to manage bootmeths. It can list them and change
 the order in which they are used.
 
-See :doc:`../../develop/bootstd` for more information.
+See :doc:`/develop/bootstd/index` for more information.
 
 
 .. _bootmeth_order:
diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst
index 7d4b448cb30..cc33d3ec0f2 100644
--- a/doc/usage/environment.rst
+++ b/doc/usage/environment.rst
@@ -100,7 +100,7 @@ to add environment variables.
 
 Board maintainers are encouraged to migrate to the text-based environment as it
 is easier to maintain. The distro-board script still requires the old-style
-environments, so use :doc:`../develop/bootstd` instead.
+environments, so use :doc:`/develop/bootstd/index` instead.
 
 
 List of environment variables
diff --git a/doc/usage/fit/index.rst b/doc/usage/fit/index.rst
index bd25bd30b28..a822bf20cb2 100644
--- a/doc/usage/fit/index.rst
+++ b/doc/usage/fit/index.rst
@@ -4,16 +4,29 @@ Flat Image Tree (FIT)
 =====================
 
 U-Boot uses Flat Image Tree (FIT) as a standard file format for packaging
-images that it it reads and boots. Documentation about FIT is available at
-doc/uImage.FIT
+images that it reads and boots. Documentation about FIT is available in
+`the Flattened Image Tree project <https://fitspec.osfw.foundation/>`_.
 
 .. toctree::
     :maxdepth: 1
 
-    source_file_format
+    beaglebone_vboot
     howto
-    x86-fit-boot
+    kernel_fdt
+    kernel_fdts_compressed
+    kernel
+    multi
+    multi_spl
+    multi-with-fpga
+    multi-with-loadables
+    overlay-fdt-boot
+    sec_firmware_ppa
     signature
+    sign-configs
+    sign-images
+    source_file_format
+    uefi
+    update3
+    update_uboot
     verified-boot
-    beaglebone_vboot
-    overlay-fdt-boot
+    x86-fit-boot
\ No newline at end of file
diff --git a/doc/usage/fit/source_file_format.rst b/doc/usage/fit/source_file_format.rst
index 15990e3ff54..2bd8e792350 100644
--- a/doc/usage/fit/source_file_format.rst
+++ b/doc/usage/fit/source_file_format.rst
@@ -1,684 +1,8 @@
-.. SPDX-License-Identifier: GPL-2.0+
+.. SPDX-License-Identifier: GPL-2.0-or-later
 
 Flattened Image Tree (FIT) Format
 =================================
 
-Introduction
-------------
-
-The number of elements playing a role in the kernel booting process has
-increased over time and now typically includes the devicetree, kernel image and
-possibly a ramdisk image. Generally, all must be placed in the system memory and
-booted together.
-
-For firmware images a similar process has taken place, with various binaries
-loaded at different addresses, such as ARM's ATF, OpenSBI, FPGA and U-Boot
-itself.
-
-FIT provides a flexible and extensible format to deal with this complexity. It
-provides support for multiple components. It also supports multiple
-configurations, so that the same FIT can be used to boot multiple boards, with
-some components in common (e.g. kernel) and some specific to that board (e.g.
-devicetree).
-
-Terminology
-~~~~~~~~~~~
-
-This document defines FIT by providing FDT (Flat Device Tree) bindings. These
-describe the final form of the FIT at the moment when it is used. The user
-perspective may be simpler, as some of the properties (like timestamps and
-hashes) are filled in automatically by the U-Boot mkimage tool.
-
-To avoid confusion with the kernel FDT the following naming convention is used:
-
-FIT
-    Flattened Image Tree
-
-FIT is formally a flattened devicetree (in the libfdt meaning), which conforms
-to bindings defined in this document.
-
-.its
-    image tree source
-
-.itb
-    flattened image tree blob
-
-Image-building procedure
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following picture shows how the FIT is prepared. Input consists of
-image source file (.its) and a set of data files. Image is created with the
-help of standard U-Boot mkimage tool which in turn uses dtc (device tree
-compiler) to produce image tree blob (.itb). The resulting .itb file is the
-actual binary of a new FIT::
-
-    tqm5200.its
-    +
-    vmlinux.bin.gz     mkimage + dtc               xfer to target
-    eldk-4.2-ramdisk  --------------> tqm5200.itb --------------> boot
-    tqm5200.dtb                          /|\
-                                          |
-                                     'new FIT'
-
-Steps:
-
-#. Create .its file, automatically filled-in properties are omitted
-
-#. Call mkimage tool on a .its file
-
-#. mkimage calls dtc to create .itb image and assures that
-   missing properties are added
-
-#. .itb (new FIT) is uploaded onto the target and used therein
-
-
-Unique identifiers
-~~~~~~~~~~~~~~~~~~
-
-To identify FIT sub-nodes representing images, hashes, configurations (which
-are defined in the following sections), the "unit name" of the given sub-node
-is used as it's identifier as it assures uniqueness without additional
-checking required.
-
-
-External data
-~~~~~~~~~~~~~
-
-FIT is normally built initially with image data in the 'data' property of each
-image node. It is also possible for this data to reside outside the FIT itself.
-This allows the 'FDT' part of the FIT to be quite small, so that it can be
-loaded and scanned without loading a large amount of data. Then when an image is
-needed it can be loaded from an external source.
-
-External FITs use 'data-offset' or 'data-position' instead of 'data'.
-
-The mkimage tool can convert a FIT to use external data using the `-E` argument,
-optionally using `-p` to specific a fixed position.
-
-It is often desirable to align each image to a block size or cache-line size
-(e.g. 512 bytes), so that there is no need to copy it to an aligned address when
-reading the image data. The mkimage tool provides a `-B` argument to support
-this.
-
-Root-node properties
---------------------
-
-The root node of the FIT should have the following layout::
-
-    / o image-tree
-        |- description = "image description"
-        |- timestamp = <12399321>
-        |- #address-cells = <1>
-        |
-        o images
-        | |
-        | o image-1 {...}
-        | o image-2 {...}
-        | ...
-        |
-        o configurations
-          |- default = "conf-1"
-          |
-          o conf-1 {...}
-          o conf-2 {...}
-          ...
-
-Optional property
-~~~~~~~~~~~~~~~~~
-
-description
-    Textual description of the FIT
-
-Mandatory property
-~~~~~~~~~~~~~~~~~~
-
-timestamp
-    Last image modification time being counted in seconds since
-    1970-01-01 00:00:00 - to be automatically calculated by mkimage tool.
-
-Conditionally mandatory property
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-#address-cells
-    Number of 32bit cells required to represent entry and
-    load addresses supplied within sub-image nodes. May be omitted when no
-    entry or load addresses are used.
-
-Mandatory nodes
-~~~~~~~~~~~~~~~
-
-images
-    This node contains a set of sub-nodes, each of them representing
-    single component sub-image (like kernel, ramdisk, etc.). At least one
-    sub-image is required.
-
-configurations
-    Contains a set of available configuration nodes and
-    defines a default configuration.
-
-
-'/images' node
---------------
-
-This node is a container node for component sub-image nodes. Each sub-node of
-the '/images' node should have the following layout::
-
-    o image-1
-        |- description = "component sub-image description"
-        |- data = /incbin/("path/to/data/file.bin")
-        |- type = "sub-image type name"
-        |- arch = "ARCH name"
-        |- os = "OS name"
-        |- compression = "compression name"
-        |- load = <00000000>
-        |- entry = <00000000>
-        |
-        o hash-1 {...}
-        o hash-2 {...}
-        ...
-
-Mandatory properties
-~~~~~~~~~~~~~~~~~~~~
-
-description
-    Textual description of the component sub-image
-
-type
-    Name of component sub-image type. Supported types are:
-
-    ====================  ==================
-    Sub-image type        Meaning
-    ====================  ==================
-    invalid               Invalid Image
-    aisimage              Davinci AIS image
-    atmelimage            ATMEL ROM-Boot Image
-    copro                 Coprocessor Image
-    fdt_legacy            legacy Image with Flat Device Tree
-    filesystem            Filesystem Image
-    firmware              Firmware
-    firmware_ivt          Firmware with HABv4 IVT
-    flat_dt               Flat Device Tree
-    fpga                  FPGA Device Image (bitstream file, vendor specific)
-    gpimage               TI Keystone SPL Image
-    imx8image             NXP i.MX8 Boot Image
-    imx8mimage            NXP i.MX8M Boot Image
-    imximage              Freescale i.MX Boot Image
-    kernel                Kernel Image
-    kernel_noload         Kernel Image (no loading done)
-    kwbimage              Kirkwood Boot Image
-    lpc32xximage          LPC32XX Boot Image
-    mtk_image             MediaTek BootROM loadable Image
-    multi                 Multi-File Image
-    mxsimage              Freescale MXS Boot Image
-    omapimage             TI OMAP SPL With GP CH
-    pblimage              Freescale PBL Boot Image
-    pmmc                  TI Power Management Micro-Controller Firmware
-    ramdisk               RAMDisk Image
-    rkimage               Rockchip Boot Image
-    rksd                  Rockchip SD Boot Image
-    rkspi                 Rockchip SPI Boot Image
-    script                Script
-    socfpgaimage          Altera SoCFPGA CV/AV preloader
-    socfpgaimage_v1       Altera SoCFPGA A10 preloader
-    spkgimage             Renesas SPKG Image
-    standalone            Standalone Program
-    stm32image            STMicroelectronics STM32 Image
-    sunxi_egon            Allwinner eGON Boot Image
-    sunxi_toc0            Allwinner TOC0 Boot Image
-    tee                   Trusted Execution Environment Image
-    ublimage              Davinci UBL image
-    vybridimage           Vybrid Boot Image
-    x86_setup             x86 setup.bin
-    zynqimage             Xilinx Zynq Boot Image
-    zynqmpbif             Xilinx ZynqMP Boot Image (bif)
-    zynqmpimage           Xilinx ZynqMP Boot Image
-    ====================  ==================
-
-compression
-    Compression used by included data. If no compression is used, the
-    compression property should be set to "none". If the data is compressed but
-    it should not be uncompressed by the loader (e.g. compressed ramdisk), this
-    should also be set to "none".
-
-    Supported compression types are:
-
-    ====================  ==================
-    Compression type      Meaning
-    ====================  ==================
-    none                  uncompressed
-    bzip2                 bzip2 compressed
-    gzip                  gzip compressed
-    lz4                   lz4 compressed
-    lzma                  lzma compressed
-    lzo                   lzo compressed
-    zstd                  zstd compressed
-    ====================  ==================
-
-
-Conditionally mandatory property
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-data
-    Path to the external file which contains this node's binary data. Within
-    the FIT this is the contents of the file. This is mandatory unless
-    external data is used.
-
-data-offset
-    Offset of the data in a separate image store. The image store is placed
-    immediately after the last byte of the device tree binary, aligned to a
-    4-byte boundary. This is mandatory if external data is used, with an offset.
-
-data-position
-    Machine address at which the data is to be found. This is a fixed address
-    not relative to the loading of the FIT. This is mandatory if external data
-    used with a fixed address.
-
-data-size
-    Size of the data in bytes. This is mandatory if external data is used.
-
-os
-    OS name, mandatory for types "kernel". Valid OS names are:
-
-    ====================  ==================
-    OS name               Meaning
-    ====================  ==================
-    invalid               Invalid OS
-    4_4bsd                4_4BSD
-    arm-trusted-firmware  ARM Trusted Firmware
-    dell                  Dell
-    efi                   EFI Firmware
-    esix                  Esix
-    freebsd               FreeBSD
-    integrity             INTEGRITY
-    irix                  Irix
-    linux                 Linux
-    ncr                   NCR
-    netbsd                NetBSD
-    openbsd               OpenBSD
-    openrtos              OpenRTOS
-    opensbi               RISC-V OpenSBI
-    ose                   Enea OSE
-    plan9                 Plan 9
-    psos                  pSOS
-    qnx                   QNX
-    rtems                 RTEMS
-    sco                   SCO
-    solaris               Solaris
-    svr4                  SVR4
-    tee                   Trusted Execution Environment
-    u-boot                U-Boot
-    vxworks               VxWorks
-    ====================  ==================
-
-arch
-    Architecture name, mandatory for types: "standalone", "kernel",
-    "firmware", "ramdisk" and "fdt". Valid architecture names are:
-
-    ====================  ==================
-    Architecture type     Meaning
-    ====================  ==================
-    invalid               Invalid ARCH
-    alpha                 Alpha
-    arc                   ARC
-    arm64                 AArch64
-    arm                   ARM
-    avr32                 AVR32
-    blackfin              Blackfin
-    ia64                  IA64
-    m68k                  M68K
-    microblaze            MicroBlaze
-    mips64                MIPS 64 Bit
-    mips                  MIPS
-    nds32                 NDS32
-    nios2                 NIOS II
-    or1k                  OpenRISC 1000
-    powerpc               PowerPC
-    ppc                   PowerPC
-    riscv                 RISC-V
-    s390                  IBM S390
-    sandbox               Sandbox
-    sh                    SuperH
-    sparc64               SPARC 64 Bit
-    sparc                 SPARC
-    x86_64                AMD x86_64
-    x86                   Intel x86
-    xtensa                Xtensa
-    ====================  ==================
-
-entry
-    entry point address, address size is determined by
-    '#address-cells' property of the root node.
-    Mandatory for types: "firmware", and "kernel".
-
-load
-    load address, address size is determined by '#address-cells'
-    property of the root node.
-    Mandatory for types: "firmware", and "kernel".
-
-compatible
-    compatible method for loading image.
-    Mandatory for types: "fpga", and images that do not specify a load address.
-    Supported compatible methods:
-
-    ==========================  =========================================
-    Compatible string           Meaning
-    ==========================  =========================================
-    u-boot,fpga-legacy          Generic fpga loading routine.
-    u-boot,zynqmp-fpga-ddrauth  Signed non-encrypted FPGA bitstream for
-                                Xilinx Zynq UltraScale+ (ZymqMP) device.
-    u-boot,zynqmp-fpga-enc      Encrypted FPGA bitstream for Xilinx Zynq
-                                UltraScale+ (ZynqMP) device.
-    ==========================  =========================================
-
-phase
-    U-Boot phase for which the image is intended.
-
-    "spl"
-        image is an SPL image
-
-    "u-boot"
-        image is a U-Boot image
-
-Optional nodes:
-
-hash-1
-    Each hash sub-node represents separate hash or checksum
-    calculated for node's data according to specified algorithm.
-
-signature-1
-    Each signature sub-node represents separate signature
-    calculated for node's data according to specified algorithm.
-
-
-Hash nodes
-----------
-
-::
-
-    o hash-1
-        |- algo = "hash or checksum algorithm name"
-        |- value = [hash or checksum value]
-
-Mandatory properties
-~~~~~~~~~~~~~~~~~~~~
-
-algo
-    Algorithm name. Supported algoriths and their value sizes are:
-
-    ==================== ============ =========================================
-    Sub-image type       Size (bytes) Meaning
-    ==================== ============ =========================================
-    crc16-ccitt          2            Cyclic Redundancy Check 16-bit
-                                      (Consultative Committee for International
-                                      Telegraphy and Telephony)
-    crc32                4            Cyclic Redundancy Check 32-bit
-    md5                  16           Message Digest 5 (MD5)
-    sha1                 20           Secure Hash Algorithm 1 (SHA1)
-    sha256               32           Secure Hash Algorithm 2 (SHA256)
-    sha384               48           Secure Hash Algorithm 2 (SHA384)
-    sha512               64           Secure Hash Algorithm 2 (SHA512)
-    ==================== ============ =========================================
-
-value
-    Actual checksum or hash value.
-
-Image-signature nodes
----------------------
-
-::
-
-    o signature-1
-        |- algo = "algorithm name"
-        |- key-name-hint = "key name"
-        |- value = [hash or checksum value]
-
-
-Mandatory properties
-~~~~~~~~~~~~~~~~~~~~
-
-_`FIT Algorithm`:
-
-algo
-    Algorithm name. Supported algoriths and their value sizes are shown below.
-    Note that the hash is specified separately from the signing algorithm, so
-    it is possible to mix and match any SHA algorithm with any signing
-    algorithm. The size of the signature relates to the signing algorithm, not
-    the hash, since it is the hash that is signed.
-
-    ==================== ============ =========================================
-    Sub-image type       Size (bytes) Meaning
-    ==================== ============ =========================================
-    sha1,rsa2048         256          SHA1 hash signed with 2048-bit
-                                      Rivest–Shamir–Adleman algorithm
-    sha1,rsa3072         384          SHA1 hash signed with 2048-bit RSA
-    sha1,rsa4096         512          SHA1 hash signed with 2048-bit RSA
-    sha1,ecdsa256        32           SHA1 hash signed with 256-bit  Elliptic
-                                      Curve Digital Signature Algorithm
-    sha256,...
-    sha384,...
-    sha512,...
-    ==================== ============ =========================================
-
-key-name-hint
-    Name of key to use for signing. The keys will normally be in
-    a single directory (parameter -k to mkimage). For a given key <name>, its
-    private key is stored in <name>.key and the certificate is stored in
-    <name>.crt.
-
-sign-images
-    A list of images to sign, each being a property of the conf
-    node that contains then. The default is "kernel,fdt" which means that these
-    two images will be looked up in the config and signed if present. This is
-    used by mkimage to determine which images to sign.
-
-The following properies are added as part of signing, and are mandatory:
-
-value
-    Actual signature value. This is added by mkimage.
-
-hashed-nodes
-    A list of nodes which were hashed by the signer. Each is
-    a string - the full path to node. A typical value might be::
-
-	hashed-nodes = "/", "/configurations/conf-1", "/images/kernel",
-	    "/images/kernel/hash-1", "/images/fdt-1",
-	    "/images/fdt-1/hash-1";
-
-hashed-strings
-    The start and size of the string region of the FIT that was hashed. The
-    start is normally 0, indicating the first byte of the string table. The size
-    indicates the number of bytes hashed as part of signing.
-
-The following properies are added as part of signing, and are optional:
-
-timestamp
-    Time when image was signed (standard Unix time_t format)
-
-signer-name
-    Name of the signer (e.g. "mkimage")
-
-signer-version
-    Version string of the signer (e.g. "2013.01")
-
-comment
-    Additional information about the signer or image
-
-padding
-    The padding algorithm, it may be pkcs-1.5 or pss,
-    if no value is provided we assume pkcs-1.5
-
-
-'/configurations' node
-----------------------
-
-The 'configurations' node creates convenient, labeled boot configurations,
-which combine together kernel images with their ramdisks and fdt blobs.
-
-The 'configurations' node has the following structure::
-
-    o configurations
-        |- default = "default configuration sub-node unit name"
-        |
-        o config-1 {...}
-        o config-2 {...}
-        ...
-
-
-Optional property
-~~~~~~~~~~~~~~~~~
-
-default
-    Selects one of the configuration sub-nodes as a default configuration.
-
-Mandatory nodes
-~~~~~~~~~~~~~~~
-
-configuration-sub-node-unit-name
-    At least one of the configuration sub-nodes is required.
-
-Optional nodes
-~~~~~~~~~~~~~~
-
-signature-1
-    Each signature sub-node represents separate signature
-    calculated for the configuration according to specified algorithm.
-
-
-Configuration nodes
--------------------
-
-Each configuration has the following structure::
-
-    o config-1
-        |- description = "configuration description"
-        |- kernel = "kernel sub-node unit name"
-        |- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...]
-        |- loadables = "loadables sub-node unit-name"
-        |- script = "
-        |- compatible = "vendor,board-style device tree compatible string"
-        o signature-1 {...}
-
-Mandatory properties
-~~~~~~~~~~~~~~~~~~~~
-
-description
-    Textual configuration description.
-
-kernel or firmware
-    Unit name of the corresponding kernel or firmware
-    (u-boot, op-tee, etc) image. If both "kernel" and "firmware" are specified,
-    control is passed to the firmware image.
-
-Optional properties
-~~~~~~~~~~~~~~~~~~~
-
-fdt
-    Unit name of the corresponding fdt blob (component image node of a
-    "fdt type"). Additional fdt overlay nodes can be supplied which signify
-    that the resulting device tree blob is generated by the first base fdt
-    blob with all subsequent overlays applied.
-
-fpga
-    Unit name of the corresponding fpga bitstream blob
-    (component image node of a "fpga type").
-
-loadables
-    Unit name containing a list of additional binaries to be
-    loaded at their given locations.  "loadables" is a comma-separated list
-    of strings. U-Boot will load each binary at its given start-address and
-    may optionally invoke additional post-processing steps on this binary based
-    on its component image node type.
-
-script
-    The image to use when loading a U-Boot script (for use with the
-    source command).
-
-compatible
-    The root compatible string of the U-Boot device tree that
-    this configuration shall automatically match when CONFIG_FIT_BEST_MATCH is
-    enabled. If this property is not provided, the compatible string will be
-    extracted from the fdt blob instead. This is only possible if the fdt is
-    not compressed, so images with compressed fdts that want to use compatible
-    string matching must always provide this property.
-
-The FDT blob is required to properly boot FDT based kernel, so the minimal
-configuration for 2.6 FDT kernel is (kernel, fdt) pair.
-
-Older, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases
-'struct bd_info' must be passed instead of FDT blob, thus fdt property *must
-not* be specified in a configuration node.
-
-Configuration-signature nodes
------------------------------
-
-::
-
-    o signature-1
-        |- algo = "algorithm name"
-        |- key-name-hint = "key name"
-        |- sign-images = "path1", "path2";
-        |- value = [hash or checksum value]
-        |- hashed-strings = <0 len>
-
-
-Mandatory properties
-~~~~~~~~~~~~~~~~~~~~
-
-algo
-    See `FIT Algorithm`_.
-
-key-name-hint
-    Name of key to use for signing. The keys will normally be in
-    a single directory (parameter -k to mkimage). For a given key <name>, its
-    private key is stored in <name>.key and the certificate is stored in
-    <name>.crt.
-
-The following properies are added as part of signing, and are mandatory:
-
-value
-    Actual signature value. This is added by mkimage.
-
-The following properies are added as part of signing, and are optional:
-
-timestamp
-    Time when image was signed (standard Unix time_t format)
-
-signer-name
-    Name of the signer (e.g. "mkimage")
-
-signer-version
-    Version string of the signer (e.g. "2013.01")
-
-comment
-    Additional information about the signer or image
-
-padding
-    The padding algorithm, it may be pkcs-1.5 or pss,
-    if no value is provided we assume pkcs-1.5
-
-
-
-Examples
---------
-
-Some example files are available here, showing various scenarios
-
-.. toctree::
-    :maxdepth: 1
-
-    kernel
-    kernel_fdt
-    kernel_fdts_compressed
-    multi
-    multi_spl
-    multi-with-fpga
-    multi-with-loadables
-    sec_firmware_ppa
-    sign-configs
-    sign-images
-    uefi
-    update3
-    update_uboot
-
-.. sectionauthor:: Marian Balakowicz <m8@semihalf.com>
-.. sectionauthor:: External data additions, 25/1/16 Simon Glass <sjg@chromium.org>
+FIT format documentation has been moved to
+`a separate project <https://fitspec.osfw.foundation/>`_. Updates to the
+format/specification should be submitted there.