1 .. SPDX-License-Identifier: GPL-2.0+:
9 Standard boot provides a built-in way for U-Boot to automatically boot
10 an Operating System without custom scripting and other customisation. It
11 introduces the following concepts:
13 - bootdev - a device which can hold or access a distro (e.g. MMC, Ethernet)
14 - bootmeth - a method to scan a bootdev to find bootflows (e.g. distro boot)
15 - bootflow - a description of how to boot (provided by the distro)
17 For Linux, the distro (Linux distribution, e.g. Debian, Fedora) is responsible
18 for creating a bootflow for each kernel combination that it wants to offer.
19 These bootflows are stored on media so they can be discovered by U-Boot. This
20 feature is typically called `distro boot` (see :doc:`distro`) because it is
21 a way for distributions to boot on any hardware.
23 Traditionally U-Boot has relied on scripts to implement this feature. See
24 distro_bootcmd_ for details. This is done because U-Boot has no native support
25 for scanning devices. While the scripts work remarkably well, they can be hard
26 to understand and extend, and the feature does not include tests. They are also
27 making it difficult to move away from ad-hoc CONFIGs, since they are implemented
28 using the environment and a lot of #defines.
30 Standard boot is a generalisation of distro boot. It provides a more built-in
31 way to boot with U-Boot. The feature is extensible to different Operating
32 Systems (such as Chromium OS) and devices (beyond just block and network
33 devices). It supports EFI boot and EFI bootmgr too.
35 Finally, standard boot supports the operation of :doc:`vbe`.
40 A bootflow is a file that describes how to boot a distro. Conceptually there can
41 be different formats for that file but at present U-Boot only supports the
42 BootLoaderSpec_ format. which looks something like this::
44 menu autoboot Welcome to Fedora-Workstation-armhfp-31-1.9. Automatic boot in # second{,s}. Press a key for options.
45 menu title Fedora-Workstation-armhfp-31-1.9 Boot Options.
48 label Fedora-Workstation-armhfp-31-1.9 (5.3.7-301.fc31.armv7hl)
49 kernel /vmlinuz-5.3.7-301.fc31.armv7hl
50 append ro root=UUID=9732b35b-4cd5-458b-9b91-80f7047e0b8a rhgb quiet LANG=en_US.UTF-8 cma=192MB cma=256MB
51 fdtdir /dtb-5.3.7-301.fc31.armv7hl/
52 initrd /initramfs-5.3.7-301.fc31.armv7hl.img
54 As you can see it specifies a kernel, a ramdisk (initrd) and a directory from
55 which to load devicetree files. The details are described in distro_bootcmd_.
57 The bootflow is provided by the distro. It is not part of U-Boot. U-Boot's job
58 is simply to interpret the file and carry out the instructions. This allows
59 distros to boot on essentially any device supported by U-Boot.
61 Typically the first available bootflow is selected and booted. If that fails,
62 then the next one is tried.
68 Where does U-Boot find the media that holds the operating systems? That is the
69 job of bootdev. A bootdev is simply a layer on top of a media device (such as
70 MMC, NVMe). The bootdev accesses the device, including partitions and
71 filesystems that might contain things related to an operating system.
73 For example, an MMC bootdev provides access to the individual partitions on the
74 MMC device. It scans through these to find filesystems with the boot flag set,
75 then provides a list of these for consideration.
77 Some bootdevs are not visible until a bus is enumerated, e.g. flash sticks
78 attached via USB. To deal with this, each bootdev has an associated 'hunter'
79 which can hunt for bootdevs of a particular uclass type. For example, the SCSI
80 bootdev scans the SCSI bus looking for devices, creating a bootdev for each
81 Logical Unit Number (LUN) that it finds.
87 Once the list of filesystems is provided, how does U-Boot find the bootflow
88 files in these filesystems. That is the job of bootmeth. Each boot method has
89 its own way of doing this.
91 For example, the distro bootmeth simply looks through the provided filesystem
92 for a file called `extlinux/extlinux.conf`. This files constitutes a bootflow.
93 If the distro bootmeth is used on multiple partitions it may produce multiple
96 Note: it is possible to have a bootmeth that uses a partition or a whole device
97 directly, but it is more common to use a filesystem.
99 Note that some bootmeths are 'global', meaning that they select the bootdev
100 themselves. Examples include VBE and EFI boot manager. In this case, they
101 provide a `read_bootflow()` method which checks whatever bootdevs it likes, then
102 returns the bootflow, if found. Some of these bootmeths may be very slow, if
103 they scan a lot of devices.
109 U-Boot tries to use the 'lazy init' approach whereever possible and distro boot
110 is no exception. The algorithm is::
112 while (get next bootdev)
113 while (get next bootmeth)
114 while (get next bootflow)
117 So U-Boot works its way through the bootdevs, trying each bootmeth in turn to
118 obtain bootflows, until it either boots or exhausts the available options.
120 Instead of 500 lines of #defines and a 4KB boot script, all that is needed is
121 the following command::
125 which scans for available bootflows, optionally listing each find it finds (-l)
126 and trying to boot it (-b).
128 When global bootmeths are available, these are typically checked before the
129 above bootdev scanning.
135 Several options are available to control the ordering of boot scanning:
141 This environment variable can be used to control the list of bootdevs searched
142 and their ordering, for example::
144 setenv boot_targets "mmc0 mmc1 usb pxe"
146 Entries may be removed or re-ordered in this list to affect the boot order. If
147 the variable is empty, the default ordering is used, based on the priority of
148 bootdevs and their sequence numbers.
154 This environment variable can be used to control the list of bootmeths used and
155 their ordering for example::
157 setenv bootmeths "extlinux efi"
159 Entries may be removed or re-ordered in this list to affect the order the
160 bootmeths are tried on each bootdev. If the variable is empty, the default
161 ordering is used, based on the bootmeth sequence numbers, which can be
162 controlled by aliases.
164 The :ref:`usage/cmd/bootmeth:bootmeth command` (`bootmeth order`) operates in
165 the same way as setting this variable.
171 The bootdev uclass provides an simple API call to obtain a bootflows from a
174 int bootdev_get_bootflow(struct udevice *dev, struct bootflow_iter *iter,
175 struct bootflow *bflow);
177 This takes a iterator which indicates the bootdev, partition and bootmeth to
178 use. It returns a bootflow. This is the core of the bootdev implementation. The
179 bootdev drivers that implement this differ depending on the media they are
180 reading from, but each is responsible for returning a valid bootflow if
183 A helper called `bootdev_find_in_blk()` makes it fairly easy to implement this
184 function for each media device uclass, in a few lines of code. For many types
185 ot bootdevs, the `get_bootflow` member can be NULL, indicating that the default
186 handler is used. This is called `default_get_bootflow()` and it only works with
193 A bootdev driver is typically fairly simple. Here is one for mmc::
195 static int mmc_bootdev_bind(struct udevice *dev)
197 struct bootdev_uc_plat *ucp = dev_get_uclass_plat(dev);
199 ucp->prio = BOOTDEVP_2_INTERNAL_FAST;
204 struct bootdev_ops mmc_bootdev_ops = {
207 static const struct udevice_id mmc_bootdev_ids[] = {
208 { .compatible = "u-boot,bootdev-mmc" },
212 U_BOOT_DRIVER(mmc_bootdev) = {
213 .name = "mmc_bootdev",
214 .id = UCLASS_BOOTDEV,
215 .ops = &mmc_bootdev_ops,
216 .bind = mmc_bootdev_bind,
217 .of_match = mmc_bootdev_ids,
220 You may notice that the `get_bootflow` memory is not provided, so is NULL. This
221 means that `default_get_bootflow()` is used. This simply obtains the
222 block device and calls a bootdev helper function to do the rest. The
223 implementation of `bootdev_find_in_blk()` checks the partition table, and
224 attempts to read a file from a filesystem on the partition number given by the
225 `@iter->part` parameter. If there are any bootable partitions in the table,
226 then only bootable partitions are considered.
228 Each bootdev has a priority, which indicates the order in which it is used,
229 if `boot_targets` is not used. Faster bootdevs are used first, since they are
230 more likely to be able to boot the device quickly.
233 Environment Variables
234 ---------------------
236 Various environment variables are used by standard boot. These allow the board
237 to control where things are placed when booting the OS. You should ensure that
238 your boards sets values for these.
241 Name of the flattened device tree (FDT) file to load, e.g.
242 "rockchip/rk3399-rockpro64.dtb"
245 Address at which to load the FDT, e.g. 0x01f00000
247 fdtoverlay_addr_r (needed if overlays are used)
248 Address at which to load the overlay for the FDT, e.g. 0x02000000
251 Address at which to load the kernel, e.g. 0x02080000
254 Address to which to decompress the kernel, e.g. 0x08000000
257 Size of available space for decompressed kernel, e.g. 0x2000000
260 Address at which to load the PXE file, e.g. 0x00600000
263 Address at which to load the ramdisk, e.g. 0x06000000
266 Address at which to load the U-Boot script, e.g. 0x00500000
269 SPI flash offset from which to load the U-Boot script, e.g. 0xffe000
272 Size of the script to load, e.g. 0x2000
274 Some variables are set by script bootmeth:
277 Device type being used for boot, e.g. mmc
280 Device number being used for boot, e.g. 1
283 Partition being used for boot, e.g. 2
286 Directory containing the script
289 Device number being used for boot (e.g. 1). This is only used by MMC on
296 A bootdev device is a child of the media device. In this example, you can see
297 that the bootdev is a sibling of the block device and both are children of
300 mmc 0 [ + ] bcm2835-sdhost | |-- mmc@7e202000
301 blk 0 [ + ] mmc_blk | | |-- mmc@7e202000.blk
302 bootdev 0 [ ] mmc_bootdev | | `-- mmc@7e202000.bootdev
303 mmc 1 [ + ] sdhci-bcm2835 | |-- sdhci@7e300000
304 blk 1 [ ] mmc_blk | | |-- sdhci@7e300000.blk
305 bootdev 1 [ ] mmc_bootdev | | `-- sdhci@7e300000.bootdev
307 The bootdev device is typically created automatically in the media uclass'
308 `post_bind()` method by calling `bootdev_setup_for_dev()` or
309 `bootdev_setup_sibling_blk()`. The code typically something like this::
311 /* dev is the Ethernet device */
312 ret = bootdev_setup_for_dev(dev, "eth_bootdev");
314 return log_msg_ret("bootdev", ret);
318 /* blk is the block device (child of MMC device)
319 ret = bootdev_setup_sibling_blk(blk, "mmc_bootdev");
321 return log_msg_ret("bootdev", ret);
324 Here, `eth_bootdev` is the name of the Ethernet bootdev driver and `dev`
325 is the ethernet device. This function is safe to call even if standard boot is
326 not enabled, since it does nothing in that case. It can be added to all uclasses
327 which implement suitable media.
333 Standard boot requires a single instance of the bootstd device to make things
334 work. This includes global information about the state of standard boot. See
335 `struct bootstd_priv` for this structure, accessed with `bootstd_get_priv()`.
337 Within the devicetree, if you add bootmeth devices, they should be children of
338 the bootstd device. See `arch/sandbox/dts/test.dts` for an example of this.
341 .. _`Automatic Devices`:
346 It is possible to define all the required devices in the devicetree manually,
347 but it is not necessary. The bootstd uclass includes a `dm_scan_other()`
348 function which creates the bootstd device if not found. If no bootmeth devices
349 are found at all, it creates one for each available bootmeth driver.
351 If your devicetree has any bootmeth device it must have all of them that you
352 want to use, since no bootmeth devices will be created automatically in that
359 If a bootdev is complicated or needs configuration information, it can be
360 added to the devicetree as a child of the media device. For example, imagine a
361 bootdev which reads a bootflow from SPI flash. The devicetree fragment might
367 compatible = "spansion,m25p16", "jedec,spi-nor";
368 spi-max-frequency = <40000000>;
371 compatible = "u-boot,sf-bootdev";
378 The `sf-bootdev` driver can implement a way to read from the SPI flash, using
379 the offset and size provided, and return that bootflow file back to the caller.
380 When distro boot wants to read the kernel it calls distro_getfile() which must
381 provide a way to read from the SPI flash. See `distro_boot()` at distro_boot_
384 Of course this is all internal to U-Boot. All the distro sees is another way
391 Standard boot is enabled with `CONFIG_BOOTSTD`. Each bootmeth has its own CONFIG
392 option also. For example, `CONFIG_BOOTMETH_EXTLINUX` enables support for
393 booting from a disk using an `extlinux.conf` file.
395 To enable all feature sof standard boot, use `CONFIG_BOOTSTD_FULL`. This
396 includes the full set of commands, more error messages when things go wrong and
397 bootmeth ordering with the bootmeths environment variable.
399 You should probably also enable `CONFIG_BOOTSTD_DEFAULTS`, which provides
400 several filesystem and network features (if `CONFIG_NET` is enabled) so that
401 a good selection of boot options is available.
404 Available bootmeth drivers
405 --------------------------
407 Bootmeth drivers are provided for:
409 - extlinux / syslinux boot from a disk
410 - extlinux boot from a network (PXE)
411 - U-Boot scripts from disk, network or SPI flash
412 - EFI boot using bootefi from disk
414 - EFI boot using boot manager
420 Three commands are available:
423 Allows listing of available bootdevs, selecting a particular one and
424 getting information about it. See :doc:`../usage/cmd/bootdev`
427 Allows scanning one or more bootdevs for bootflows, listing available
428 bootflows, selecting one, obtaining information about it and booting it.
429 See :doc:`../usage/cmd/bootflow`
432 Allow listing of available bootmethds and setting the order in which they
433 are tried. See :doc:`../usage/cmd/bootmeth`
440 Here is a list of states that a bootflow can be in:
442 ======= =======================================================================
444 ======= =======================================================================
445 base Starting-out state, indicates that no media/partition was found. For an
446 SD card socket it may indicate that the card is not inserted.
447 media Media was found (e.g. SD card is inserted) but no partition information
448 was found. It might lack a partition table or have a read error.
449 part Partition was found but a filesystem could not be read. This could be
450 because the partition does not hold a filesystem or the filesystem is
452 fs Filesystem was found but the file could not be read. It could be
453 missing or in the wrong subdirectory.
454 file File was found and its size detected, but it could not be read. This
455 could indicate filesystem corruption.
456 ready File was loaded and is ready for use. In this state the bootflow is
458 ======= =======================================================================
464 This describes how standard boot progresses through to booting an operating
467 To start. all the necessary devices must be bound, including bootstd, which
468 provides the top-level `struct bootstd_priv` containing optional configuration
469 information. The bootstd device is also holds the various lists used while
470 scanning. This step is normally handled automatically by driver model, as
471 described in `Automatic Devices`_.
473 Bootdevs are also required, to provide access to the media to use. These are not
474 useful by themselves: bootmeths are needed to provide the means of scanning
475 those bootdevs. So, all up, we need a single bootstd device, one or more bootdev
476 devices and one or more bootmeth devices.
478 Once these are ready, typically a `bootflow scan` command is issued. This kicks
479 of the iteration process, which involves hunting for bootdevs and looking
480 through the bootdevs and their partitions one by one to find bootflows.
482 Iteration is kicked off using `bootflow_scan_first()`.
484 The iterator is set up with `bootflow_iter_init()`. This simply creates an
485 empty one with the given flags. Flags are used to control whether each
486 iteration is displayed, whether to return iterations even if they did not result
487 in a valid bootflow, whether to iterate through just a single bootdev, etc.
489 Then the iterator is set up to according to the parameters given:
491 - When `dev` is provided, then a single bootdev is scanned. In this case,
492 `BOOTFLOWIF_SKIP_GLOBAL` and `BOOTFLOWIF_SINGLE_DEV` are set. No hunters are
495 - Otherwise, when `label` is provided, then a single label or named bootdev is
496 scanned. In this case `BOOTFLOWIF_SKIP_GLOBAL` is set and there are three
497 options (with an effect on the `iter_incr()` function described later):
499 - If `label` indicates a numeric bootdev number (e.g. "2") then
500 `BOOTFLOW_METHF_SINGLE_DEV` is set. In this case, moving to the next bootdev
501 simple stops, since there is only one. No hunters are used.
502 - If `label` indicates a particular media device (e.g. "mmc1") then
503 `BOOTFLOWIF_SINGLE_MEDIA` is set. In this case, moving to the next bootdev
504 processes just the children of the media device. Hunters are used, in this
505 example just the "mmc" hunter.
506 - If `label` indicates a media uclass (e.g. "mmc") then
507 `BOOTFLOWIF_SINGLE_UCLASS` is set. In this case, all bootdevs in that uclass
508 are used. Hunters are used, in this example just the "mmc" hunter
510 - Otherwise, none of the above flags is set and iteration is set up to work
511 through `boot_targets` environment variable (or `bootdev-order` device tree
512 property) in order, running the relevant hunter first. In this case
513 `cur_label` is used to indicate the label being processed. If there is no list
514 of labels, then all bootdevs are processed in order of priority, running the
517 With the above it is therefore possible to iterate in a variety of ways.
519 No attempt is made to determine the ordering of bootdevs, since this cannot be
520 known in advance if we are using the hunters. Any hunter might discover a new
521 bootdev and disturb the original ordering.
523 Next, the ordering of bootmeths is determined, by `bootmeth_setup_iter_order()`.
524 By default the ordering is again by sequence number, i.e. the `/aliases` node,
525 or failing that the order in the devicetree. But the `bootmeth order` command
526 or `bootmeths` environment variable can be used to set up an ordering. If that
527 has been done, the ordering is in `struct bootstd_priv`, so that ordering is
528 simply copied into the iterator. Either way, the `method_order` array it set up,
529 along with `num_methods`.
531 Note that global bootmeths are always put at the end of the ordering. If any are
532 present, `cur_method` is set to the first one, so that global bootmeths are done
533 first. Once all have been used, these bootmeths are dropped from the iteration.
534 When there are no global bootmeths, `cur_method` is set to 0.
536 At this point the iterator is ready to use, with the first bootmeth selected.
537 Most of the other fields are 0. This means that the current partition
538 is 0, which is taken to mean the whole device, since partition numbers start at
539 1. It also means that `max_part` is 0, i.e. the maximum partition number we know
540 about is 0, meaning that, as far as we know, there is no partition table on this
543 With the iterator ready, `bootflow_scan_first()` checks whether the current
544 settings produce a valid bootflow. This is handled by `bootflow_check()`, which
545 either returns 0 (if it got something) or an error if not (more on that later).
546 If the `BOOTFLOWIF_ALL` iterator flag is set, even errors are returned as
547 incomplete bootflows, but normally an error results in moving onto the next
550 Note that `bootflow_check()` handles global bootmeths explicitly, by calling
551 `bootmeth_get_bootflow()` on each one. The `doing_global` flag indicates when
552 the iterator is in that state.
554 The `bootflow_scan_next()` function handles moving onto the next iteration and
555 checking it. In fact it sits in a loop doing that repeatedly until it finds
556 something it wants to return.
558 The actual 'moving on' part is implemented in `iter_incr()`. This is a fairly
559 simple function. It increments the first counter. If that hits its maximum, it
560 sets it to zero and increments the second counter. You can think of all the
561 counters together as a number with three digits which increment in order, with
562 the least-sigificant digit on the right, counting like this:
564 ======== ======= =======
566 ======== ======= =======
576 ======== ======= =======
578 The maximum value for `method` is `num_methods - 1` so when it exceeds that, it
579 goes back to 0 and the next `part` is considered. The maximum value for that is
580 `max_part`, which is initially zero for all bootdevs. If we find a partition
581 table on that bootdev, `max_part` can be updated during the iteration to a
582 higher value - see `bootdev_find_in_blk()` for that, described later. If that
583 exceeds its maximum, then the next bootdev is used. In this way, iter_incr()
584 works its way through all possibilities, moving forward one each time it is
587 Note that global bootmeths introduce a subtlety into the above description.
588 When `doing_global` is true, the iteration takes place only among the bootmeths,
589 i.e. the last column above. The global bootmeths are at the end of the list.
590 Assuming that they are entries 3 and 4 in the list, the iteration then looks
593 ======== ======= ======= =======================================
594 bootdev part method notes
595 ======== ======= ======= =======================================
596 . . 3 doing_global = true, method_count = 5
598 0 0 0 doing_global = false, method_count = 3
607 ======== ======= ======= =======================================
609 The changeover of the value of `doing_global` from true to false is handled in
610 `iter_incr()` as well.
612 Note that the value in the `bootdev` column above is not actually stored - it is
613 just for illustration. In practice, `iter_incr()` uses the flags to determine
614 whether to move to the next bootdev in the uclass, the next child of the media
615 device, the next label, or the next priority level, depending on the flag
616 settings (see `BOOTFLOW_METHF_SINGLE_DEV`, etc. above).
618 There is no expectation that iteration will actually finish. Quite often a
619 valid bootflow is found early on. With `bootflow scan -b`, that causes the
620 bootflow to be immediately booted. Assuming it is successful, the iteration never
623 Also note that the iterator hold the **current** combination being considered.
624 So when `iter_incr()` is called, it increments to the next one and returns it,
625 the new **current** combination.
627 Note also the `err` field in `struct bootflow_iter`. This is normally 0 and has
628 thus has no effect on `iter_inc()`. But if it is non-zero, signalling an error,
629 it indicates to the iterator what it should do when called. It can force moving
630 to the next partition, or bootdev, for example. The special values
631 `BF_NO_MORE_PARTS` and `BF_NO_MORE_DEVICES` handle this. When `iter_incr` sees
632 `BF_NO_MORE_PARTS` it knows that it should immediately move to the next bootdev.
633 When it sees `BF_NO_MORE_DEVICES` it knows that there is nothing more it can do
634 so it should immediately return. The caller of `iter_incr()` is responsible for
635 updating the `err` field, based on the return value it sees.
637 The above describes the iteration process at a high level. It is basically a
638 very simple increment function with a checker called `bootflow_check()` that
639 checks the result of each iteration generated, to determine whether it can
642 So what happens inside of `bootflow_check()`? It simply calls the uclass
643 method `bootdev_get_bootflow()` to ask the bootdev to return a bootflow. It
644 passes the iterator to the bootdev method, so that function knows what we are
645 talking about. At first, the bootflow is set up in the state `BOOTFLOWST_BASE`,
646 with just the `method` and `dev` intiialised. But the bootdev may fill in more,
647 e.g. updating the state, depending on what it finds. For global bootmeths the
648 `bootmeth_get_bootflow()` function is called instead of
649 `bootdev_get_bootflow()`.
651 Based on what the bootdev or bootmeth responds with, `bootflow_check()` either
652 returns a valid bootflow, or a partial one with an error. A partial bootflow
653 is one that has some fields set up, but did not reach the `BOOTFLOWST_READY`
654 state. As noted before, if the `BOOTFLOWIF_ALL` iterator flag is set, then all
655 bootflows are returned, even partial ones. This can help with debugging.
657 So at this point you can see that total control over whether a bootflow can
658 be generated from a particular iteration, or not, rests with the bootdev (or
659 global bootmeth). Each one can adopt its own approach.
661 Going down a level, what does the bootdev do in its `get_bootflow()` method?
662 Let us consider the MMC bootdev. In that case the call to
663 `bootdev_get_bootflow()` ends up in `default_get_bootflow()`. It locates the
664 parent device of the bootdev, i.e. the `UCLASS_MMC` device itself, then finds
665 the block device associated with it. It then calls the helper function
666 `bootdev_find_in_blk()` to do all the work. This is common with just about any
667 bootdev that is based on a media device.
669 The `bootdev_find_in_blk()` helper is implemented in the bootdev uclass. It
670 names the bootflow and copies the partition number in from the iterator. Then it
671 calls the bootmeth device to check if it can support this device. This is
672 important since some bootmeths only work with network devices, for example. If
673 that check fails, it stops.
675 Assuming the bootmeth is happy, or at least indicates that it is willing to try
676 (by returning 0 from its `check()` method), the next step is to try the
677 partition. If that works it tries to detect a file system. If that works then it
678 calls the bootmeth device once more, this time to read the bootflow.
680 Note: At present a filesystem is needed for the bootmeth to be called on block
681 devices, simply because we don't have any examples where this is not the case.
682 This feature can be added as needed. Note that sandbox is a special case, since
683 in that case the host filesystem can be accessed even though the block device
686 If we take the example of the `bootmeth_extlinux` driver, this call ends up at
687 `extlinux_read_bootflow()`. It has the filesystem ready, so tries various
688 filenames to try to find the `extlinux.conf` file, reading it if possible. If
689 all goes well the bootflow ends up in the `BOOTFLOWST_READY` state.
691 At this point, we fall back from the bootmeth driver, to
692 `bootdev_find_in_blk()`, then back to `default_get_bootflow()`, then to
693 `bootdev_get_bootflow()`, then to `bootflow_check()` and finally to its caller,
694 either `bootflow_scan_first()` or `bootflow_scan_next()`. In either case,
695 the bootflow is returned as the result of this iteration, assuming it made it to
696 the `BOOTFLOWST_READY` state.
698 That is the basic operation of scanning for bootflows. The process of booting a
699 bootflow is handled by the bootmeth driver for that bootflow. In the case of
700 extlinux boot, this parses and processes the `extlinux.conf` file that was read.
701 See `extlinux_boot()` for how that works. The processing may involve reading
702 additional files, which is handled by the `read_file()` method, which is
703 `extlinux_read_file()` in this case. All bootmethds should support reading
704 files, since the bootflow is typically only the basic instructions and does not
705 include the operating system itself, ramdisk, device tree, etc.
707 The vast majority of the bootstd code is concerned with iterating through
708 partitions on bootdevs and using bootmethds to find bootflows.
710 How about bootdevs which are not block devices? They are handled by the same
711 methods as above, but with a different implementation. For example, the bootmeth
712 for PXE boot (over a network) uses `tftp` to read files rather than `fs_read()`.
713 But other than that it is very similar.
719 Tests are located in `test/boot` and cover the core functionality as well as
720 the commands. All tests use sandbox so can be run on a standard Linux computer
723 For testing, a DOS-formatted disk image is used with a FAT partition on it and
724 a second unused partition. This is created in `setup_bootflow_image()`, with a
725 canned one from the source tree used if it cannot be created (e.g. in CI).
731 The bootstd device holds a linked list of scanned bootflows as well as the
732 currently selected bootdev and bootflow (for use by commands). This is in
733 `struct bootstd_priv`.
735 Each bootdev device has its own `struct bootdev_uc_plat` which holds a
736 list of scanned bootflows just for that device.
738 The bootflow itself is documented in bootflow_h_. It includes various bits of
739 information about the bootflow and a buffer to hold the file.
745 Apart from the to-do items below, different types of bootflow files may be
746 implemented in future, e.g. Chromium OS support which is currently only
747 available as a script in chromebook_coral.
753 Some things that need to be done to completely replace the distro-boot scripts:
755 - add bootdev drivers for dhcp, sata, scsi, ide, virtio
757 - support for loading U-Boot scripts
761 - `bootflow prep` to load everything preparing for boot, so that `bootflow boot`
762 can just do the boot.
763 - automatically load kernel, FDT, etc. to suitable addresses so the board does
764 not need to specify things like `pxefile_addr_r`
767 .. _distro_bootcmd: https://github.com/u-boot/u-boot/blob/master/include/config_distro_bootcmd.h
768 .. _BootLoaderSpec: http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/
769 .. _distro_boot: https://github.com/u-boot/u-boot/blob/master/boot/distro.c
770 .. _bootflow_h: https://github.com/u-boot/u-boot/blob/master/include/bootflow.h