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::
+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.
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 devicetree files. The details are described in distro_bootcmd_.
+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
--------
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
+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
Boot process
------------
-U-Boot tries to use the 'lazy init' approach whereever possible and distro boot
+U-Boot tries to use the 'lazy init' approach wherever possible and distro boot
is no exception. The algorithm is::
while (get next bootdev)
Bootdev uclass
--------------
-The bootdev uclass provides an simple API call to obtain a bootflows from a
+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 a iterator which indicates the bootdev, partition and bootmeth to
+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
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
-ot bootdevs, the `get_bootflow` member can be NULL, indicating that the default
+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::
+A bootdev driver is typically fairly simple. Here is one for MMC::
static int mmc_bootdev_bind(struct udevice *dev)
{
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
+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.
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 devicetree, if you add bootmeth devices, they should be children of
+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
-----------------
-It is possible to define all the required devices in the devicetree manually,
+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 devicetree has any bootmeth device it must have all of them that you
+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.
----------------
If a bootdev is complicated or needs configuration information, it can be
-added to the devicetree as a child of the media device. For example, imagine a
-bootdev which reads a bootflow from SPI flash. The devicetree fragment might
+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 {
option also. For example, `CONFIG_BOOTMETH_EXTLINUX` enables support for
booting from a disk using an `extlinux.conf` file.
-To enable all feature sof standard boot, use `CONFIG_BOOTSTD_FULL`. This
+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.
This describes how standard boot progresses through to booting an operating
system.
-To start. all the necessary devices must be bound, including bootstd, which
+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 is also holds the various lists used while
+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`_.
devices and one or more bootmeth devices.
Once these are ready, typically a `bootflow scan` command is issued. This kicks
-of the iteration process, which involves hunting for bootdevs and looking
+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()`.
- 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
- simple stops, since there is only one. No hunters are used.
+ 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
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 devicetree. But the `bootmeth order` command
+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,
bootflow to be immediately booted. Assuming it is successful, the iteration never
completes.
-Also note that the iterator hold the **current** combination being considered.
+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 has no effect on `iter_inc()`. But if it is non-zero, signalling an error,
+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
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` intiialised. But the bootdev may fill in more,
+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()`.
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 bootmethds should support reading
+`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 bootmethds to find bootflows.
+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
projects / u-boot.git / commitdiff
