doc/develop/bootstd/overview.rst

.. SPDX-License-Identifier: GPL-2.0+:

Standard Boot Overview
======================

Introduction
------------

Standard boot provides a built-in way for U-Boot to automatically boot
an Operating System without custom scripting and other customisation. It
introduces the following concepts:

   - bootdev  - a device which can hold or access a distro (e.g. MMC, Ethernet)
   - bootmeth - a method to scan a bootdev to find bootflows (e.g. distro boot)
   - bootflow - a description of how to boot (provided by the distro)

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
a way for distributions to boot on any hardware.

Traditionally U-Boot has relied on scripts to implement this feature. See
distro_bootcmd_ for details. This is done because U-Boot has no native support
for scanning devices. While the scripts work remarkably well, they can be hard
to understand and extend, and the feature does not include tests. They are also
making it difficult to move away from ad-hoc CONFIGs, since they are implemented
using the environment and a lot of #defines.

Standard boot is a generalisation of distro boot. It provides a more built-in
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`.

Bootflow
--------

A bootflow is a file that describes how to boot a distro. Conceptually there can
be different formats for that file but at present U-Boot only supports the
BootLoaderSpec_ format which looks something like this::

   menu autoboot Welcome to Fedora-Workstation-armhfp-31-1.9. Automatic boot in # second{,s}. Press a key for options.
   menu title Fedora-Workstation-armhfp-31-1.9 Boot Options.
   menu hidden

   label Fedora-Workstation-armhfp-31-1.9 (5.3.7-301.fc31.armv7hl)
       kernel /vmlinuz-5.3.7-301.fc31.armv7hl
       append ro root=UUID=9732b35b-4cd5-458b-9b91-80f7047e0b8a rhgb quiet LANG=en_US.UTF-8 cma=192MB cma=256MB
       fdtdir /dtb-5.3.7-301.fc31.armv7hl/
       initrd /initramfs-5.3.7-301.fc31.armv7hl.img

As you can see it specifies a kernel, a ramdisk (initrd) and a directory from
which to load Device Tree files. The details are described in distro_bootcmd_.

The bootflow is provided by the distro. It is not part of U-Boot. U-Boot's job
is simply to interpret the file and carry out the instructions. This allows
distros to boot on essentially any device supported by U-Boot.

Typically the first available bootflow is selected and booted. If that fails,
then the next one is tried.


Bootdev
-------

Where does U-Boot find the media that holds the operating systems? That is the
job of bootdev. A bootdev is simply a layer on top of a media device (such as
MMC, NVMe). The bootdev accesses the device, including partitions and
filesystems that might contain things related to an operating system.

For example, an MMC bootdev provides access to the individual partitions on the
MMC device. It scans through these to find filesystems with the boot flag set,
then provides a list of these for consideration.

Some bootdevs are not visible until a bus is enumerated, e.g. flash sticks
attached via USB. To deal with this, each bootdev has an associated 'hunter'
which can hunt for bootdevs of a particular uclass type. For example, the SCSI
bootdev scans the SCSI bus looking for devices, creating a bootdev for each
Logical Unit Number (LUN) that it finds.


Bootmeth
--------

Once the list of filesystems is provided, how does U-Boot find the bootflow
files in these filesystems? That is the job of bootmeth. Each boot method has
its own way of doing this.

For example, the distro bootmeth simply looks through the provided filesystem
for a file called `extlinux/extlinux.conf`. This files constitutes a bootflow.
If the distro bootmeth is used on multiple partitions it may produce multiple
bootflows.

Note: it is possible to have a bootmeth that uses a partition or a whole device
directly, but it is more common to use a filesystem.
For example, the Android bootmeth uses a whole device.

Note that some bootmeths are 'global', meaning that they select the bootdev
themselves. Examples include VBE and EFI boot manager. In this case, they
provide a `read_bootflow()` method which checks whatever bootdevs it likes, then
returns the bootflow, if found. Some of these bootmeths may be very slow, if
they scan a lot of devices.

The extlinux bootmeth also allows for bootmeth specific configuration to be
set. A bootmeth that wishes to support this provides the `set_property()`
method. This allows string properties and values to be passed to the bootmeth.
It is up to the bootmeth to determine what action to take when this method is
called.


Boot process
------------

U-Boot tries to use the 'lazy init' approach wherever possible and distro boot
is no exception. The algorithm is::

   while (get next bootdev)
      while (get next bootmeth)
          while (get next bootflow)
              try to boot it

So U-Boot works its way through the bootdevs, trying each bootmeth in turn to
obtain bootflows, until it either boots or exhausts the available options.

Instead of 500 lines of #defines and a 4KB boot script, all that is needed is
the following command::

   bootflow scan -lb

which scans for available bootflows, optionally listing each find it finds (-l)
and trying to boot it (-b).

When global bootmeths are available, these are typically checked before the
above bootdev scanning.


Controlling ordering
--------------------

By default, faster bootdevs (or those which are assumed to be faster) are used
first, since they are more likely to be able to boot the device quickly.

Several options are available to control the ordering of boot scanning:


boot_targets
~~~~~~~~~~~~

This environment variable can be used to control the list of bootdevs searched
and their ordering, for example::

   setenv boot_targets "mmc0 mmc1 usb pxe"

Entries may be removed or re-ordered in this list to affect the boot order. If
the variable is empty, the default ordering is used, based on the priority of
bootdevs and their sequence numbers.


bootmeths
~~~~~~~~~

By default bootmeths are checked in name order. Use `bootmeth list` to see the
ordering. Note that the `extlinux` and `script` bootmeth is first, to preserve the behaviour
used by the old distro scripts.

This environment variable can be used to control the list of bootmeths used and
their ordering for example::

   setenv bootmeths "extlinux efi"

Entries may be removed or re-ordered in this list to affect the order the
bootmeths are tried on each bootdev. If the variable is empty, the default
ordering is used, based on the bootmeth sequence numbers, which can be
controlled by aliases.

The :ref:`usage/cmd/bootmeth:bootmeth command` (`bootmeth order`) operates in
the same way as setting this variable.

Bootdev uclass
--------------

The bootdev uclass provides a simple API call to obtain a bootflow from a
device::

   int bootdev_get_bootflow(struct udevice *dev, struct bootflow_iter *iter,
                            struct bootflow *bflow);

This takes an iterator which indicates the bootdev, partition and bootmeth to
use. It returns a bootflow. This is the core of the bootdev implementation. The
bootdev drivers that implement this differ depending on the media they are
reading from, but each is responsible for returning a valid bootflow if
available.

A helper called `bootdev_find_in_blk()` makes it fairly easy to implement this
function for each media device uclass, in a few lines of code. For many types
of bootdevs, the `get_bootflow` member can be NULL, indicating that the default
handler is used. This is called `default_get_bootflow()` and it only works with
block devices.


Bootdev drivers
---------------

A bootdev driver is typically fairly simple. Here is one for MMC::

    static int mmc_bootdev_bind(struct udevice *dev)
    {
        struct bootdev_uc_plat *ucp = dev_get_uclass_plat(dev);

        ucp->prio = BOOTDEVP_2_INTERNAL_FAST;

        return 0;
    }

    struct bootdev_ops mmc_bootdev_ops = {
    };

    static const struct udevice_id mmc_bootdev_ids[] = {
        { .compatible = "u-boot,bootdev-mmc" },
        { }
    };

    U_BOOT_DRIVER(mmc_bootdev) = {
        .name        = "mmc_bootdev",
        .id        = UCLASS_BOOTDEV,
        .ops        = &mmc_bootdev_ops,
        .bind        = mmc_bootdev_bind,
        .of_match    = mmc_bootdev_ids,
    };

You may notice that the `get_bootflow` memory is not provided, so is NULL. This
means that `default_get_bootflow()` is used. This simply obtains the
block device and calls a bootdev helper function to do the rest. The
implementation of `bootdev_find_in_blk()` checks the partition table, and
attempts to read a file from a filesystem on the partition number given by the
`@iter->part` parameter. If there are any bootable partitions in the table,
then only bootable partitions are considered.

Each bootdev has a priority, which indicates the order in which it is used,
if `boot_targets` is not used. Faster bootdevs are used first, since they are
more likely to be able to boot the device quickly.


Environment Variables
---------------------

Various environment variables are used by standard boot. These allow the board
to control where things are placed when booting the OS. You should ensure that
your boards sets values for these.

fdtfile
    Name of the flattened device tree (FDT) file to load, e.g.
    "rockchip/rk3399-rockpro64.dtb"

fdt_addr_r
    Address at which to load the FDT, e.g. 0x01f00000

fdtoverlay_addr_r (needed if overlays are used)
    Address at which to load the overlay for the FDT, e.g. 0x02000000

kernel_addr_r
    Address at which to load the kernel, e.g. 0x02080000

kernel_comp_addr_r
    Address to which to decompress the kernel, e.g. 0x08000000

kernel_comp_size
    Size of available space for decompressed kernel, e.g. 0x2000000

pxefile_addr_r
    Address at which to load the PXE file, e.g. 0x00600000

ramdisk_addr_r
    Address at which to load the ramdisk, e.g. 0x06000000

scriptaddr
    Address at which to load the U-Boot script, e.g. 0x00500000

script_offset_f
    SPI flash offset from which to load the U-Boot script, e.g. 0xffe000

script_size_f
    Size of the script to load, e.g. 0x2000

vendor_boot_comp_addr_r
    Address to which to load the vendor_boot Android image, e.g. 0xe0000000

Some variables are set by script bootmeth:

devtype
    Device type being used for boot, e.g. mmc

devnum
    Device number being used for boot, e.g. 1

distro_bootpart
    Partition being used for boot, e.g. 2

prefix
    Directory containing the script

mmc_bootdev
    Device number being used for boot (e.g. 1). This is only used by MMC on
    sunxi boards.


Device hierarchy
----------------

A bootdev device is a child of the media device. In this example, you can see
that the bootdev is a sibling of the block device and both are children of
media device::

    mmc           0  [ + ]   bcm2835-sdhost        |   |-- mmc@7e202000
    blk           0  [ + ]   mmc_blk               |   |   |-- mmc@7e202000.blk
    bootdev       0  [   ]   mmc_bootdev           |   |   `-- mmc@7e202000.bootdev
    mmc           1  [ + ]   sdhci-bcm2835         |   |-- sdhci@7e300000
    blk           1  [   ]   mmc_blk               |   |   |-- sdhci@7e300000.blk
    bootdev       1  [   ]   mmc_bootdev           |   |   `-- sdhci@7e300000.bootdev

The bootdev device is typically created automatically in the media uclass'
`post_bind()` method by calling `bootdev_setup_for_dev()` or
`bootdev_setup_for_sibling_blk()`. The code typically something like this::

    /* dev is the Ethernet device */
    ret = bootdev_setup_for_dev(dev, "eth_bootdev");
    if (ret)
        return log_msg_ret("bootdev", ret);

or::

    /* blk is the block device (child of MMC device)
    ret = bootdev_setup_for_sibling_blk(blk, "mmc_bootdev");
    if (ret)
        return log_msg_ret("bootdev", ret);


Here, `eth_bootdev` is the name of the Ethernet bootdev driver and `dev`
is the Ethernet device. This function is safe to call even if standard boot is
not enabled, since it does nothing in that case. It can be added to all uclasses
which implement suitable media.


The bootstd device
------------------

Standard boot requires a single instance of the bootstd device to make things
work. This includes global information about the state of standard boot. See
`struct bootstd_priv` for this structure, accessed with `bootstd_get_priv()`.

Within the Device Tree, if you add bootmeth devices, they should be children of
the bootstd device. See `arch/sandbox/dts/test.dts` for an example of this.


.. _`Automatic Devices`:

Automatic devices
-----------------

It is possible to define all the required devices in the Device Tree manually,
but it is not necessary. The bootstd uclass includes a `dm_scan_other()`
function which creates the bootstd device if not found. If no bootmeth devices
are found at all, it creates one for each available bootmeth driver.

If your Device Tree has any bootmeth device it must have all of them that you
want to use, since no bootmeth devices will be created automatically in that
case.


Using devicetree
----------------

If a bootdev is complicated or needs configuration information, it can be
added to the Device Tree as a child of the media device. For example, imagine a
bootdev which reads a bootflow from SPI flash. The Device Tree fragment might
look like this::

    spi@0 {
        flash@0 {
            reg = <0>;
            compatible = "spansion,m25p16", "jedec,spi-nor";
            spi-max-frequency = <40000000>;

            bootdev {
                compatible = "u-boot,sf-bootdev";
                offset = <0x2000>;
                size = <0x1000>;
            };
        };
    };

The `sf-bootdev` driver can implement a way to read from the SPI flash, using
the offset and size provided, and return that bootflow file back to the caller.
When distro boot wants to read the kernel it calls distro_getfile() which must
provide a way to read from the SPI flash. See `distro_boot()` at distro_boot_
for more details.

Of course this is all internal to U-Boot. All the distro sees is another way
to boot.


Configuration
-------------

Standard boot is enabled with `CONFIG_BOOTSTD`. Each bootmeth has its own CONFIG
option also. For example, `CONFIG_BOOTMETH_EXTLINUX` enables support for
booting from a disk using an `extlinux.conf` file.

To enable all features of standard boot, use `CONFIG_BOOTSTD_FULL`. This
includes the full set of commands, more error messages when things go wrong and
bootmeth ordering with the bootmeths environment variable.

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 booting from various media:

   - :doc:`Android <android>` bootflow (boot image v4)
   - :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk
   - EFI boot using bootefi from disk
   - EFI boot using boot manager
   - :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
-----------------

Four commands are available:

`bootdev`
    Allows listing of available bootdevs, selecting a particular one and
    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`

`bootmeth`
    Allow listing of available bootmethds, setting the order in which they are
    tried and bootmeth specific configuration. See :doc:`/usage/cmd/bootmeth`

`bootstd`
    Allow access to standard boot itself, so far only for listing images across
    all bootflows. See :doc:`/usage/cmd/bootstd`

Images
------

Standard boot keeps track of images which can or have been loaded. These are
kept in a list attached to each bootflow. They can be listed using the
``bootstd images`` command (see :doc:`/usage/cmd/bootstd`).

For now most bootmeths load their images when scanning. Over time, some may
adjust to load them only when needed, but in this case the images will still
be visible.

Once a bootflow has been selected, images for those that are not selected can
potentially be dropped from the memory map. For now, this is not implemented.


.. _BootflowStates:

Bootflow states
---------------

Here is a list of states that a bootflow can be in:

=======  =======================================================================
State    Meaning
=======  =======================================================================
base     Starting-out state, indicates that no media/partition was found. For an
         SD card socket it may indicate that the card is not inserted.
media    Media was found (e.g. SD card is inserted) but no partition information
         was found. It might lack a partition table or have a read error.
part     Partition was found but a filesystem could not be read. This could be
         because the partition does not hold a filesystem or the filesystem is
         very corrupted.
fs       Filesystem was found but the file could not be read. It could be
         missing or in the wrong subdirectory.
file     File was found and its size detected, but it could not be read. This
         could indicate filesystem corruption.
ready    File was loaded and is ready for use. In this state the bootflow is
         ready to be booted.
=======  =======================================================================


Migrating from distro_boot
--------------------------

To migrate from distro_boot:

#. Update your board header files to remove the BOOTENV and BOOT_TARGET_xxx
   defines. Standard boot finds available boot devices automatically.

#. Remove the "boot_targets" variable unless you need it. Standard boot uses a
   default order from fastest to slowest, which generally matches the order used
   by boards.

#. Make sure that CONFIG_BOOTSTD_DEFAULTS is enabled by your board, so it can
   boot common Linux distributions.

An example patch is at migrate_patch_.

If you are using custom boot scripts for your board, consider creating your
own bootmeth to hold the logic. There are various examples at
`boot/bootmeth_...`.


Theory of operation
-------------------

This describes how standard boot progresses through to booting an operating
system.

To start, all the necessary devices must be bound, including bootstd, which
provides the top-level `struct bootstd_priv` containing optional configuration
information. The bootstd device also holds the various lists used while
scanning. This step is normally handled automatically by driver model, as
described in `Automatic Devices`_.

Bootdevs are also required, to provide access to the media to use. These are not
useful by themselves: bootmeths are needed to provide the means of scanning
those bootdevs. So, all up, we need a single bootstd device, one or more bootdev
devices and one or more bootmeth devices.

Once these are ready, typically a `bootflow scan` command is issued. This kicks
off the iteration process, which involves hunting for bootdevs and looking
through the bootdevs and their partitions one by one to find bootflows.

Iteration is kicked off using `bootflow_scan_first()`.

The iterator is set up with `bootflow_iter_init()`. This simply creates an
empty one with the given flags. Flags are used to control whether each
iteration is displayed, whether to return iterations even if they did not result
in a valid bootflow, whether to iterate through just a single bootdev, etc.

Then the iterator is set up to according to the parameters given:

- When `dev` is provided, then a single bootdev is scanned. In this case,
  `BOOTFLOWIF_SKIP_GLOBAL` and `BOOTFLOWIF_SINGLE_DEV` are set. No hunters are
  used in this case

- Otherwise, when `label` is provided, then a single label or named bootdev is
  scanned. In this case `BOOTFLOWIF_SKIP_GLOBAL` is set and there are three
  options (with an effect on the `iter_incr()` function described later):

  - If `label` indicates a numeric bootdev number (e.g. "2") then
    `BOOTFLOW_METHF_SINGLE_DEV` is set. In this case, moving to the next bootdev
    simply stops, since there is only one. No hunters are used.
  - If `label` indicates a particular media device (e.g. "mmc1") then
    `BOOTFLOWIF_SINGLE_MEDIA` is set. In this case, moving to the next bootdev
    processes just the children of the media device. Hunters are used, in this
    example just the "mmc" hunter.
  - If `label` indicates a particular partition in a particular media device
    (e.g. "mmc1:3") then `BOOTFLOWIF_SINGLE_PARTITION` is set. In this case,
    only a single partition within a bootdev is processed. Hunters are used, in
    this example just the "mmc" hunter.
  - If `label` indicates a media uclass (e.g. "mmc") then
    `BOOTFLOWIF_SINGLE_UCLASS` is set. In this case, all bootdevs in that uclass
    are used. Hunters are used, in this example just the "mmc" hunter

- Otherwise, none of the above flags is set and iteration is set up to work
  through `boot_targets` environment variable (or `bootdev-order` device tree
  property) in order, running the relevant hunter first. In this case
  `cur_label` is used to indicate the label being processed. If there is no list
  of labels, then all bootdevs are processed in order of priority, running the
  hunters as it goes.

With the above it is therefore possible to iterate in a variety of ways.

No attempt is made to determine the ordering of bootdevs, since this cannot be
known in advance if we are using the hunters. Any hunter might discover a new
bootdev and disturb the original ordering.

Next, the ordering of bootmeths is determined, by `bootmeth_setup_iter_order()`.
By default the ordering is again by sequence number, i.e. the `/aliases` node,
or failing that the order in the Device Tree. But the `bootmeth order` command
or `bootmeths` environment variable can be used to set up an ordering. If that
has been done, the ordering is in `struct bootstd_priv`, so that ordering is
simply copied into the iterator. Either way, the `method_order` array it set up,
along with `num_methods`.

Note that global bootmeths are always put at the end of the ordering. If any are
present, `cur_method` is set to the first one, so that global bootmeths are done
first. Once all have been used, these bootmeths are dropped from the iteration.
When there are no global bootmeths, `cur_method` is set to 0.

At this point the iterator is ready to use, with the first bootmeth selected.
Most of the other fields are 0. This means that the current partition
is 0, which is taken to mean the whole device, since partition numbers start at
1. It also means that `max_part` is 0, i.e. the maximum partition number we know
about is 0, meaning that, as far as we know, there is no partition table on this
bootdev.

With the iterator ready, `bootflow_scan_first()` checks whether the current
settings produce a valid bootflow. This is handled by `bootflow_check()`, which
either returns 0 (if it got something) or an error if not (more on that later).
If the `BOOTFLOWIF_ALL` iterator flag is set, even errors are returned as
incomplete bootflows, but normally an error results in moving onto the next
iteration.

Note that `bootflow_check()` handles global bootmeths explicitly, by calling
`bootmeth_get_bootflow()` on each one. The `doing_global` flag indicates when
the iterator is in that state.

The `bootflow_scan_next()` function handles moving onto the next iteration and
checking it. In fact it sits in a loop doing that repeatedly until it finds
something it wants to return.

The actual 'moving on' part is implemented in `iter_incr()`. This is a fairly
simple function. It increments the first counter. If that hits its maximum, it
sets it to zero and increments the second counter. You can think of all the
counters together as a number with three digits which increment in order, with
the least-sigificant digit on the right, counting like this:

   ========    =======    =======
   bootdev     part       method
   ========    =======    =======
   0           0          0
   0           0          1
   0           0          2
   0           1          0
   0           1          1
   0           1          2
   1           0          0
   1           0          1
   ...
   ========    =======    =======

The maximum value for `method` is `num_methods - 1` so when it exceeds that, it
goes back to 0 and the next `part` is considered. The maximum value for that is
`max_part`, which is initially zero for all bootdevs. If we find a partition
table on that bootdev, `max_part` can be updated during the iteration to a
higher value - see `bootdev_find_in_blk()` for that, described later. If that
exceeds its maximum, then the next bootdev is used. In this way, iter_incr()
works its way through all possibilities, moving forward one each time it is
called.

Note that global bootmeths introduce a subtlety into the above description.
When `doing_global` is true, the iteration takes place only among the bootmeths,
i.e. the last column above. The global bootmeths are at the end of the list.
Assuming that they are entries 3 and 4 in the list, the iteration then looks
like this:

   ========    =======    =======   =======================================
   bootdev     part       method    notes
   ========    =======    =======   =======================================
   .           .          3         doing_global = true, method_count = 5
   .           .          4
   0           0          0         doing_global = false, method_count = 3
   0           0          1
   0           0          2
   0           1          0
   0           1          1
   0           1          2
   1           0          0
   1           0          1
   ...
   ========    =======    =======   =======================================

The changeover of the value of `doing_global` from true to false is handled in
`iter_incr()` as well.

Note that the value in the `bootdev` column above is not actually stored - it is
just for illustration. In practice, `iter_incr()` uses the flags to determine
whether to move to the next bootdev in the uclass, the next child of the media
device, the next label, or the next priority level, depending on the flag
settings (see `BOOTFLOW_METHF_SINGLE_DEV`, etc. above).

There is no expectation that iteration will actually finish. Quite often a
valid bootflow is found early on. With `bootflow scan -b`, that causes the
bootflow to be immediately booted. Assuming it is successful, the iteration never
completes.

Also note that the iterator holds the **current** combination being considered.
So when `iter_incr()` is called, it increments to the next one and returns it,
the new **current** combination.

Note also the `err` field in `struct bootflow_iter`. This is normally 0 and has
thus no effect on `iter_inc()`. But if it is non-zero, signalling an error,
it indicates to the iterator what it should do when called. It can force moving
to the next partition, or bootdev, for example. The special values
`BF_NO_MORE_PARTS` and `BF_NO_MORE_DEVICES` handle this. When `iter_incr` sees
`BF_NO_MORE_PARTS` it knows that it should immediately move to the next bootdev.
When it sees `BF_NO_MORE_DEVICES` it knows that there is nothing more it can do
so it should immediately return. The caller of `iter_incr()` is responsible for
updating the `err` field, based on the return value it sees.

The above describes the iteration process at a high level. It is basically a
very simple increment function with a checker called `bootflow_check()` that
checks the result of each iteration generated, to determine whether it can
produce a bootflow.

So what happens inside of `bootflow_check()`? It simply calls the uclass
method `bootdev_get_bootflow()` to ask the bootdev to return a bootflow. It
passes the iterator to the bootdev method, so that function knows what we are
talking about. At first, the bootflow is set up in the state `BOOTFLOWST_BASE`,
with just the `method` and `dev` initialised. But the bootdev may fill in more,
e.g. updating the state, depending on what it finds. For global bootmeths the
`bootmeth_get_bootflow()` function is called instead of
`bootdev_get_bootflow()`.

Based on what the bootdev or bootmeth responds with, `bootflow_check()` either
returns a valid bootflow, or a partial one with an error. A partial bootflow
is one that has some fields set up, but did not reach the `BOOTFLOWST_READY`
state. As noted before, if the `BOOTFLOWIF_ALL` iterator flag is set, then all
bootflows are returned, even partial ones. This can help with debugging.

So at this point you can see that total control over whether a bootflow can
be generated from a particular iteration, or not, rests with the bootdev (or
global bootmeth). Each one can adopt its own approach.

Going down a level, what does the bootdev do in its `get_bootflow()` method?
Let us consider the MMC bootdev. In that case the call to
`bootdev_get_bootflow()` ends up in `default_get_bootflow()`. It locates the
parent device of the bootdev, i.e. the `UCLASS_MMC` device itself, then finds
the block device associated with it. It then calls the helper function
`bootdev_find_in_blk()` to do all the work. This is common with just about any
bootdev that is based on a media device.

The `bootdev_find_in_blk()` helper is implemented in the bootdev uclass. It
names the bootflow and copies the partition number in from the iterator. Then it
calls the bootmeth device to check if it can support this device. This is
important since some bootmeths only work with network devices, for example. If
that check fails, it stops.

Assuming the bootmeth is happy, or at least indicates that it is willing to try
(by returning 0 from its `check()` method), the next step is to try the
partition. If that works it tries to detect a file system. If that works then it
calls the bootmeth device once more, this time to read the bootflow.

Note: Normally a filesystem is needed for the bootmeth to be called on block
devices, but bootmeths which don't need that can set the BOOTMETHF_ANY_PART
flag to indicate that they can scan any partition. An example is the ChromiumOS
bootmeth which can store a kernel in a raw partition. Note also that sandbox is
a special case, since in that case the host filesystem can be accessed even
though the block device is NULL.

If we take the example of the `bootmeth_extlinux` driver, this call ends up at
`extlinux_read_bootflow()`. It has the filesystem ready, so tries various
filenames to try to find the `extlinux.conf` file, reading it if possible. If
all goes well the bootflow ends up in the `BOOTFLOWST_READY` state.

At this point, we fall back from the bootmeth driver, to
`bootdev_find_in_blk()`, then back to `default_get_bootflow()`, then to
`bootdev_get_bootflow()`, then to `bootflow_check()` and finally to its caller,
either `bootflow_scan_first()` or `bootflow_scan_next()`. In either case,
the bootflow is returned as the result of this iteration, assuming it made it to
the  `BOOTFLOWST_READY` state.

That is the basic operation of scanning for bootflows. The process of booting a
bootflow is handled by the bootmeth driver for that bootflow. In the case of
extlinux boot, this parses and processes the `extlinux.conf` file that was read.
See `extlinux_boot()` for how that works. The processing may involve reading
additional files, which is handled by the `read_file()` method, which is
`extlinux_read_file()` in this case. All bootmeths should support reading
files, since the bootflow is typically only the basic instructions and does not
include the operating system itself, ramdisk, device tree, etc.

The vast majority of the bootstd code is concerned with iterating through
partitions on bootdevs and using bootmeths to find bootflows.

How about bootdevs which are not block devices? They are handled by the same
methods as above, but with a different implementation. For example, the bootmeth
for PXE boot (over a network) uses `tftp` to read files rather than `fs_read()`.
But other than that it is very similar.


Tests
-----

Tests are located in `test/boot` and cover the core functionality as well as
the commands. All tests use sandbox so can be run on a standard Linux computer
and in U-Boot's CI.

For testing, a DOS-formatted disk image is used with a FAT partition on it and
a second unused partition. This is created in `setup_bootflow_image()`, with a
canned one from the source tree used if it cannot be created (e.g. in CI).


Bootflow internals
------------------

The bootstd device holds a linked list of scanned bootflows as well as the
currently selected bootdev and bootflow (for use by commands). This is in
`struct bootstd_priv`.

Each bootdev device has its own `struct bootdev_uc_plat` which holds a
list of scanned bootflows just for that device.

The bootflow itself is documented in bootflow_h_. It includes various bits of
information about the bootflow and a buffer to hold the file.


Future
------

Apart from the to-do items below, different types of bootflow files may be
implemented in future, e.g. Chromium OS support which is currently only
available as a script in chromebook_coral.


To do
-----

Some things that need to be done to completely replace the distro-boot scripts:

- implement extensions (devicetree overlays with add-on boards)
- implement legacy (boot image v2) android boot flow

Other ideas:

- `bootflow prep` to load everything preparing for boot, so that `bootflow boot`
  can just do the boot.
- automatically load kernel, FDT, etc. to suitable addresses so the board does
  not need to specify things like `pxefile_addr_r`


.. _distro_bootcmd: https://github.com/u-boot/u-boot/blob/master/include/config_distro_bootcmd.h
.. _BootLoaderSpec: http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/
.. _distro_boot: https://github.com/u-boot/u-boot/blob/master/boot/distro.c
.. _bootflow_h: https://github.com/u-boot/u-boot/blob/master/include/bootflow.h
.. _migrate_patch: https://patchwork.ozlabs.org/project/uboot/patch/20230727215433.578830-2-sjg@chromium.org/