From c684db989e86cc041da30114c4d7f8d549260875 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:30:52 +0100 Subject: doc: Move bootstd into its own directory Before adding more files, move the bootstd docs into a new directory, with an index. Signed-off-by: Simon Glass Reviewed-by: Quentin Schulz Reviewed-by: Mattijs Korpershoek --- doc/develop/board_best_practices.rst | 2 +- doc/develop/bootstd.rst | 808 ----------------------------------- doc/develop/bootstd/index.rst | 9 + doc/develop/bootstd/overview.rst | 808 +++++++++++++++++++++++++++++++++++ doc/develop/index.rst | 2 +- 5 files changed, 819 insertions(+), 810 deletions(-) delete mode 100644 doc/develop/bootstd.rst create mode 100644 doc/develop/bootstd/index.rst create mode 100644 doc/develop/bootstd/overview.rst (limited to 'doc/develop') 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.rst b/doc/develop/bootstd.rst deleted file mode 100644 index bdda90fae3f..00000000000 --- a/doc/develop/bootstd.rst +++ /dev/null @@ -1,808 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0+: - -U-Boot Standard Boot -==================== - -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. - - -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. - - -Available bootmeth drivers --------------------------- - -Bootmeth drivers are provided for: - - - extlinux / syslinux boot from a disk - - extlinux boot from a network (PXE) - - U-Boot scripts from disk, network or SPI flash - - EFI boot using bootefi from disk - - VBE - - EFI boot using boot manager - - Android bootflow (boot image v4) - - -Command interface ------------------ - -Three 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 and setting the order in which they - are tried. See :doc:`../usage/cmd/bootmeth` - -.. _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/ diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst new file mode 100644 index 00000000000..f4f87c7787c --- /dev/null +++ b/doc/develop/bootstd/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +Standard Boot +============= + +.. toctree:: + :maxdepth: 2 + + overview diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst new file mode 100644 index 00000000000..aa38ad9a0ea --- /dev/null +++ b/doc/develop/bootstd/overview.rst @@ -0,0 +1,808 @@ +.. 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. + + +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. + + +Available bootmeth drivers +-------------------------- + +Bootmeth drivers are provided for: + + - extlinux / syslinux boot from a disk + - extlinux boot from a network (PXE) + - U-Boot scripts from disk, network or SPI flash + - EFI boot using bootefi from disk + - VBE + - EFI boot using boot manager + - Android bootflow (boot image v4) + + +Command interface +----------------- + +Three 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 and setting the order in which they + are tried. See :doc:`/usage/cmd/bootmeth` + +.. _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/ 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 -- cgit v1.2.3 From 1426f672d254a92202c1e50ad21b7dd4c8e9641a Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:30:53 +0100 Subject: doc: Mention automatic binding of bootmeths Add a note about how bootmeth drivers are instantiated. Signed-off-by: Simon Glass Reviewed-by: Mattijs Korpershoek Suggested-by: Heinrich Schuchardt --- doc/develop/bootstd/overview.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'doc/develop') diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index aa38ad9a0ea..e04c683fb11 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -424,6 +424,9 @@ Bootmeth drivers are provided for: - EFI boot using boot manager - Android bootflow (boot image v4) +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 ----------------- -- cgit v1.2.3 From b1bb34fecd84a1754e0e187aa2735ecfd2910ffd Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:30:54 +0100 Subject: doc: Add a description for bootmeth_extlinux Add documentation for the extlinux bootmeth. Signed-off-by: Simon Glass Reviewed-by: Quentin Schulz Reviewed-by: Mattijs Korpershoek --- doc/develop/bootstd/extlinux.rst | 28 ++++++++++++++++++++++++++++ doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 4 ++-- 3 files changed, 31 insertions(+), 2 deletions(-) create mode 100644 doc/develop/bootstd/extlinux.rst (limited to 'doc/develop') diff --git a/doc/develop/bootstd/extlinux.rst b/doc/develop/bootstd/extlinux.rst new file mode 100644 index 00000000000..46e9ad9eea1 --- /dev/null +++ b/doc/develop/bootstd/extlinux.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +Extlinux Bootmeth +================= + +`Extlinux `_ +(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 PXE bootmeth 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 index f4f87c7787c..5bbb3d633a3 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -7,3 +7,4 @@ Standard Boot :maxdepth: 2 overview + extlinux diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index e04c683fb11..26b798596c5 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -414,9 +414,9 @@ a good selection of boot options is available. Available bootmeth drivers -------------------------- -Bootmeth drivers are provided for: +Bootmeth drivers are provided for booting from various media: - - extlinux / syslinux boot from a disk + - :doc:`extlinux / syslinux ` boot from a storage device - extlinux boot from a network (PXE) - U-Boot scripts from disk, network or SPI flash - EFI boot using bootefi from disk -- cgit v1.2.3 From 64a1446bd09ec58ab259c9ec2b3160ac604b734f Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:30:55 +0100 Subject: doc: Add a description for bootmeth_pxe Add documentation for the pxe bootmeth. Signed-off-by: Simon Glass Reviewed-by: Quentin Schulz Reviewed-by: Mattijs Korpershoek --- doc/develop/bootstd/extlinux.rst | 3 ++- doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 2 +- doc/develop/bootstd/pxelinux.rst | 27 +++++++++++++++++++++++++++ 4 files changed, 31 insertions(+), 2 deletions(-) create mode 100644 doc/develop/bootstd/pxelinux.rst (limited to 'doc/develop') diff --git a/doc/develop/bootstd/extlinux.rst b/doc/develop/bootstd/extlinux.rst index 46e9ad9eea1..bf27dc57aaa 100644 --- a/doc/develop/bootstd/extlinux.rst +++ b/doc/develop/bootstd/extlinux.rst @@ -14,7 +14,8 @@ 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 PXE bootmeth uses the same file format, but in a network context. +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. diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index 5bbb3d633a3..5052afe448f 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -8,3 +8,4 @@ Standard Boot overview extlinux + pxelinux diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index 26b798596c5..6afa1c29615 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -417,7 +417,7 @@ Available bootmeth drivers Bootmeth drivers are provided for booting from various media: - :doc:`extlinux / syslinux ` boot from a storage device - - extlinux boot from a network (PXE) + - :doc:`extlinux / syslinux ` boot from a network (PXE) - U-Boot scripts from disk, network or SPI flash - EFI boot using bootefi from disk - VBE 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 `_. +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 `_ 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. -- cgit v1.2.3 From 70a4982d4fd83d18cd1951b2be9f3e7538b8c499 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:30:56 +0100 Subject: doc: Add a description for bootmeth_qfw Add documentation for the qfw bootmeth. Fix up the compatible string to drop the 'extlinux' part, which is not relevant to this bootmeth. Signed-off-by: Simon Glass Reviewed-by: Quentin Schulz Reviewed-by: Mattijs Korpershoek --- doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 1 + doc/develop/bootstd/qfw.rst | 20 ++++++++++++++++++++ 3 files changed, 22 insertions(+) create mode 100644 doc/develop/bootstd/qfw.rst (limited to 'doc/develop') diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index 5052afe448f..f8fce7207ce 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -9,3 +9,4 @@ Standard Boot overview extlinux pxelinux + qfw diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index 6afa1c29615..ef878963c9e 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -423,6 +423,7 @@ Bootmeth drivers are provided for booting from various media: - VBE - EFI boot using boot manager - Android bootflow (boot image v4) + - :doc:`QFW `: QEMU firmware interface Each driver is controlled by a Kconfig option. If no bootmeth driver is selected by a compatible string in the devicetree, all available bootmeth 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 `_ 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. -- cgit v1.2.3 From 56418511e9fd5ca34c38c896a364ea0249c53610 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:30:57 +0100 Subject: doc: Add a description for bootmeth_cros Add documentation for the cros bootmeth. Signed-off-by: Simon Glass Reviewed-by: Quentin Schulz Reviewed-by: Mattijs Korpershoek --- doc/develop/bootstd/cros.rst | 33 +++++++++++++++++++++++++++++++++ doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 1 + 3 files changed, 35 insertions(+) create mode 100644 doc/develop/bootstd/cros.rst (limited to 'doc/develop') 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 `_. + +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/index.rst b/doc/develop/bootstd/index.rst index f8fce7207ce..69fd3c2d2eb 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -10,3 +10,4 @@ Standard Boot extlinux pxelinux qfw + cros diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index ef878963c9e..de15fa41a1d 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -421,6 +421,7 @@ Bootmeth drivers are provided for booting from various media: - U-Boot scripts from disk, network or SPI flash - EFI boot using bootefi from disk - VBE + - :doc:`ChromiumOS ` ChromiumOS boot from a disk - EFI boot using boot manager - Android bootflow (boot image v4) - :doc:`QFW `: QEMU firmware interface -- cgit v1.2.3 From 95403023cfa890b4e5e7ce7040227e518b2da288 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:30:58 +0100 Subject: doc: Add a description for bootmeth_sandbox Add documentation for the sandbox bootmeth. Fix up the compatible string to drop the 'extlinux' part, which is not relevant to this bootmeth. Signed-off-by: Simon Glass Reviewed-by: Quentin Schulz Reviewed-by: Mattijs Korpershoek --- doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 1 + doc/develop/bootstd/sandbox.rst | 17 +++++++++++++++++ 3 files changed, 19 insertions(+) create mode 100644 doc/develop/bootstd/sandbox.rst (limited to 'doc/develop') diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index 69fd3c2d2eb..2c5d2d3fade 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -11,3 +11,4 @@ Standard Boot pxelinux qfw cros + sandbox diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index de15fa41a1d..20c5d56aad2 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -425,6 +425,7 @@ Bootmeth drivers are provided for booting from various media: - EFI boot using boot manager - Android bootflow (boot image v4) - :doc:`QFW `: QEMU firmware interface + - :doc:`sandbox ` used only for testing Each driver is controlled by a Kconfig option. If no bootmeth driver is selected by a compatible string in the devicetree, all available bootmeth 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. -- cgit v1.2.3 From 87d00856df35f7e269dfa1f343035cff33dfea58 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:31:01 +0100 Subject: doc: Add a description for bootmeth_script Add documentation for the script bootmeth. Signed-off-by: Simon Glass Reviewed-by: Quentin Schulz Reviewed-by: Mattijs Korpershoek --- doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 2 +- doc/develop/bootstd/script.rst | 52 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 54 insertions(+), 1 deletion(-) create mode 100644 doc/develop/bootstd/script.rst (limited to 'doc/develop') diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index 2c5d2d3fade..9d35b567d55 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -11,4 +11,5 @@ Standard Boot pxelinux qfw cros + script sandbox diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index 20c5d56aad2..bc7e4b39704 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -418,7 +418,7 @@ Bootmeth drivers are provided for booting from various media: - :doc:`extlinux / syslinux ` boot from a storage device - :doc:`extlinux / syslinux ` boot from a network (PXE) - - U-Boot scripts from disk, network or SPI flash + - :doc:`U-Boot scripts