Add documentation for this feature, including the commands.
Signed-off-by: Simon Glass sjg@chromium.org ---
MAINTAINERS | 3 + doc/develop/bootflow.rst | 323 ++++++++++++++++++ doc/develop/index.rst | 1 + doc/device-tree-bindings/bootmethod.txt | 14 + doc/usage/bootflow.rst | 419 ++++++++++++++++++++++++ doc/usage/bootmethod.rst | 138 ++++++++ doc/usage/index.rst | 2 + 7 files changed, 900 insertions(+) create mode 100644 doc/develop/bootflow.rst create mode 100644 doc/device-tree-bindings/bootmethod.txt create mode 100644 doc/usage/bootflow.rst create mode 100644 doc/usage/bootmethod.rst
diff --git a/MAINTAINERS b/MAINTAINERS index 2f74f7dbb19..f472a589f61 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -637,6 +637,9 @@ F: boot/bootmethod.c F: boot/distro.c F: cmd/bootflow.c F: cmd/bootmethod.c +F: doc/develop/bootflow.rst +F: doc/usage/bootflow.rst +F: doc/usage/bootmethod.rst F: include/bootmethod.h F: include/distro.h F: test/boot/bootmethod.c diff --git a/doc/develop/bootflow.rst b/doc/develop/bootflow.rst new file mode 100644 index 00000000000..930952cf2c4 --- /dev/null +++ b/doc/develop/bootflow.rst @@ -0,0 +1,323 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +Bootmethod and Bootflow +======================= + +Introduction +------------ + +Bootmethod and bootflow provide a built-in way for U-Boot to automatically boot +an Operating System without custom scripting and other customisation: + + - bootmethod - a method to scan a device to find bootflows (owned by U-Boot) + - bootflow - a description of how to boot (owned 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 +disto_boodcmd_ 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. + +Bootmethod and bootflow together provide 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). + + +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 devicetree files. The details are described in disto_boodcmd_. + +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. + + +Bootmethod +---------- + +How does U-Boot find the bootflow files? That is the job of bootmethods. +A bootmethod is simply a device that locates bootflow files. For example, an +MMC bootmethod for distro boot would simply scan through the partitions on the +MMC to find valid filesystems, then search each filesystem for a file called +`extlinux/extlinux.conf`. Each of those files constitutes a bootflow, so the +MMC device may produce multiple bootflows. Of course that is under control of +the bootmethod. + + +Boot process +------------ + +U-Boot tries to use the 'lazy init' approach whereever possible and distro boot +is no exception. The algorithm is: + + while (get next bootmethod) + while (get next bootflow) + try to boot it + +So U-Boot works its way through the bootmethods, trying in turn the bootflows +provided by each, until it either boots or exhausts the available options. + +If you are familiar with the producer–consumer model, bootmethods are the +producers and bootflows are the items produced. The consumer is the 'booter' +which tries to boot each produced item. + +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, listing each find it finds (-l) and trying +to boot it (-b). + + +Bootmethod uclass +----------------- + +The bootmethod uclass provides an simple API call to obtain one or more +bootflows from a device:: + + int bootmethod_get_bootflow(struct udevice *dev, int seq, + struct bootflow *bflow); + +This takes a sequence number (0 for the first bootflow, 1 for the next) and +returnS a bootflow. This is the core of the bootmethod implementation. The +bootmethod drivers that implement this differ depending on the media they are +reading from, but each is responsible for returning a valid bootflow if +available. + + +Bootmethod drivers +------------------ + +A bootmethod driver is typically fairly simple. Here is one for mmc:: + + static int mmc_get_bootflow(struct udevice *dev, int seq, + struct bootflow *bflow) + { + struct udevice *mmc_dev = dev_get_parent(dev); + struct udevice *blk; + int ret; + + ret = mmc_get_blk(mmc_dev, &blk); + /* + * If there is no media, indicate that no more partitions should be + * checked + */ + if (ret == -EOPNOTSUPP) + ret = -ESHUTDOWN; + if (ret) + return log_msg_ret("blk", ret); + assert(blk); + ret = bootmethod_find_in_blk(dev, blk, seq, bflow); + if (ret) + return log_msg_ret("find", ret); + + return 0; + } + + struct bootmethod_ops mmc_bootmethod_ops = { + .get_bootflow = mmc_get_bootflow, + }; + + U_BOOT_DRIVER(mmc_bootmethod) = { + .name = "mmc_bootmethod", + .id = UCLASS_BOOTMETHOD, + .ops = &mmc_bootmethod_ops, + }; + +The implementation of the `get_bootflow` method is simply to obtain the +block device and call a bootmethod helper function to do the rest. The +implementation of `bootmethod_find_in_blk()` checks the partition table, and +attempts to read a file from a filesystem on the partition number given by the +@seq parameter. + + +Device hierarchy +---------------- + +A bootmethod device is a child of the media device. In this example, you can see +that the bootmethod 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 + bootmethod 0 [ ] mmc_bootmethod | | `-- mmc@7e202000.bootmethod + mmc 1 [ + ] sdhci-bcm2835 | |-- sdhci@7e300000 + blk 1 [ ] mmc_blk | | |-- sdhci@7e300000.blk + bootmethod 1 [ ] mmc_bootmethod | | `-- sdhci@7e300000.bootmethod + +The bootmethod device is typically created automatically in the media uclass' +`post_bind()` method. This is typically something like this:: + + ret = bootmethod_setup_for_dev(dev, "eth_bootmethod"); + if (ret) + return log_msg_ret("bootmethod", ret); + +Here, `eth_bootmethod` is the name of the Ethernet bootmethod driver and `dev` +is the ethernet device. This function is safe to call even if bootmethod is +not enabled, since it does nothing in that case. It can be added to all uclasses +which implement suitable media. + + +Using devicetree +---------------- + +If a bootmethod is complicated or needs configuration information, it can be +added to the devicetree as a child of the media device. For example, imagine a +bootmethod which reads a bootflow from SPI flash. The devicetree fragment might +look like this:: + + spi@0 { + flash@0 { + reg = <0>; + compatible = "spansion,m25p16", "jedec,spi-nor"; + spi-max-frequency = <40000000>; + + bootmethod { + compatible = "sf-bootmethod"; + offset = <0x2000>; + size = <0x1000>; + }; + }; + }; + +The `sf-bootmethod` 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 disto_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 +------------- + +The bootmethod/bootflow feature can be enabled with `CONFIG_BOOTMETHOD`. Each +type of bootflow has its own CONFIG option also. For example, +`CONFIG_BOOTMETHOD_DISTRO` enables support for distro boot. + + +Command interface +----------------- + +Two commands are available: + +`bootmethod` + Allows listing of available bootmethods, selecting a particular one and + getting information about it. See :doc:`../usage/bootmethod` + +`bootflow` + Allows scanning one or more bootmethods for bootflows, listing available + bootflows, selecting one, obtaining information about it and booting it. + See :doc:`../usage/bootflow` + + +.. _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. +loaded File was loaded and is ready for use. In this state the bootflow can + be booted. +======= ======================================================================= + + +Bootflow internals +------------------ + +The bootflow uclass holds a linked list of scanned bootflows as well as the +currently selected bootmethod and bootflow (for use by commands). This is in +`struct bootflow_state`. + +Each bootmethod device has its own `struct bootmethod_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. EFI support and Chromium OS support. + + +To do +----- + +Most of the following things will be completd as part of initial development, +before a final series is sent: + +- use `ready` instead of `loaded` for the state name? +- `bootflow prep` to load everything preparing for boot, so that `bootflow boot` + can just do the boot. +- check ordering of bootmethods (should it use aliases?) +- check ordering of bootflows within bootmethods (needed) +- implement boot_targets env var? +- quick way to boot from particular media - 'bootflow boot mmc1' ? +- add bootmethod drivers for dhcp, sata, scsi, ide, usb, virtio +- introduce an interface for disto_getfile() and disto_net_getfile() provided + by the bootmethod +- better name for this feature? It is clearly not auto-boot or distro-boot, + but perhaps standard boot? + +Other ideas: + +- rename bootflow to flow, bootmethod to method (since this is a bootloader + after all) +- bootmethod flags for speed (e.g. network and USB are slow) +- should the means of scanning for particular files on a bootmethod device be + moved into a driver architecture, so we have drivers for distro boot, + Chromium OS, etc.? +- automatically load kernel, FDT, etc. to suitable addresses so the board does + not need to specific things like `pxefile_addr_r` + + +.. _disto_boodcmd: 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 diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 1fb0f06f6e8..e87bac0185b 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -9,6 +9,7 @@ Implementation .. toctree:: :maxdepth: 1
+ bootflow ci_testing commands devicetree/index diff --git a/doc/device-tree-bindings/bootmethod.txt b/doc/device-tree-bindings/bootmethod.txt new file mode 100644 index 00000000000..ef2545cab68 --- /dev/null +++ b/doc/device-tree-bindings/bootmethod.txt @@ -0,0 +1,14 @@ +U-Boot Bootmethod +================= + +A bootmethod provides a way to obtain a bootflow file from a device. It is a +child of the media device (UCLASS_MMC, UCLASS_SPI_FLASH, etc.) + +The bootmethod driver is provided by the media devices. The bindings for each +are described in this file. + + +MMC bootmethod +-------------- + +Optional properties: diff --git a/doc/usage/bootflow.rst b/doc/usage/bootflow.rst new file mode 100644 index 00000000000..39cae8beed9 --- /dev/null +++ b/doc/usage/bootflow.rst @@ -0,0 +1,419 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +bootflow command +================ + +Synopis +------- + +:: + + bootflow scan [-abel] + bootflow list [-e] + bootflow select [<num|name>] + bootflow info [-d] + bootflow boot + + +Description +----------- + +The `bootflow` command is used to manage bootflows. It can scan bootmethods to +locate bootflows, list them and boot them. + +See :doc:`../develop/bootflow` for more information. + + +bootflow scan +~~~~~~~~~~~~~ + +Scans for available bootflows, optionally booting the first valid one it finds. +This operates in two modes: + +- If no bootmethod is selected (see `bootmethod select`) it scans bootflows one + by one, extracting all the bootmethods from each +- If a bootmethod is selected, it just scans that one bootflow + +Flags are: + +-a + Collect all bootflows, even those that cannot be loaded. Normally if a file + is not where it is expected, then the bootflow fails and so is dropped + during the scan. With this option you can see why each bootflow would be + dropped. + +-b + Boot each valid bootflow as it is scanned. Typically only the first bootflow + matters, since by then the system boots in the OS and U-Boot is no-longer + running. `bootflow scan -b` is a quick way to boot the first available OS. + A valid bootflow is one that made it all the way to the `loaded` state. + +-e + Used with -l to also show errors for each bootflow. The shows detailed error + information for each bootflow that failed to make it to the `loaded` state. + +-l + List bootflows while scanning. This is helpful when you want to see what + is happening during scanning. Use it with the `-b` flag to see which + bootmethod and bootflows are being tried. + + +bootflow list +~~~~~~~~~~~~~ + +Lists the previously scanned bootflows. You must use `bootflow scan` before this +to see anything. + +If you scanned with -a and have bootflows with errors, -e can be used to show +those errors. + +The list looks something like this: + +=== =========== ====== ======== ==== =============================== ================ +Seq Type State Uclass Part Name Filename +=== =========== ====== ======== ==== =============================== ================ + 0 distro-boot loaded mmc 2 mmc@7e202000.bootmethod.part_2 extlinux/extlinux.conf + 1 distro-boot loaded ethernet 0 smsc95xx_eth.bootmethod.0 rpi.pxe/extlinux/extlinux.conf +=== =========== ====== ======== ==== =============================== ================ + +The fields are as follows: + +Seq: + Sequence number in the scan, used to reference the bootflow later + +Type: + Type of the bootflow. Currently this is always 'distro-boot', indicating + that it is an extlinux.conf file. + +State: + Current state of the bootflow, indicating how far the bootmethod got in + obtaining a valid one. See :ref:`BootflowStates` for a list of states. + +Uclass: + Name of the media device's Uclass. This indicates the type of the parent + device (e.g. MMC, Ethernet). + +Part: + Partition number being accesseed, numbered from 1. Normally a device will + have a partition table with a small number of partitions. For devices + without partition tables (e.g. network) this field is 0. + +Name: + Name of the bootflow. This is generated from the bootmethod appended with + the partition information + +Filename: + Name of the bootflow file. This indicates where the file is on the + filesystem or network device. + + +bootflow select +~~~~~~~~~~~~~~~ + +Use this to select a particular bootflow. You can select it by the sequence +number or name, as shown in `bootflow list`. + +Once a bootflow is selected, you can use `bootflow info` and `bootflow boot`. + +If no bootflow name or number is provided, then any existing bootflow is +unselected. + + +bootflow info +~~~~~~~~~~~~~ + +This shows information on the current bootflow, with the format looking like +this: + +========= =============================== +Name mmc@7e202000.bootmethod.part_2 +Device mmc@7e202000.bootmethod +Block dev mmc@7e202000.blk +Sequence 1 +Type distro-boot +State loaded +Partition 2 +Subdir (none) +Filename extlinux/extlinux.conf +Buffer 3db7ad48 +Size 232 (562 bytes) +Error 0 +========= =============================== + +Most of the information is the same as `bootflow list` above. The new fields +are: + +Device + Name of the bootmethod + +Block dev + Name of the block device, if any. Network devices don't have a block device. + +Subdir + Subdirectory used for retrieving files. For network bootmethods this is the + directory of the 'bootfile' parameter passed from DHCP. All file retrievals + when booting are relative to this. + +Buffer + Buffer containing the bootflow file. You can use the :doc:`md` to look at + it, or dump it with `bootflow info -d`. + +Size + Size of the bootflow file + +Error + Error number returned from scanning for the bootflow. This is 0 if the + bootflow is in the 'loaded' state, or a negative error value on error. You + can look up Linux error codes to find the meaning of the number. + +Use the `-d` flag to dump out the contents of the bootfile file. + + +bootflow boot +~~~~~~~~~~~~~ + +This boots the current bootflow. + + +Example +------- + +Here is an example of scanning for bootflows, then listing them:: + + U-Boot> bootflow scan -l + Scanning for bootflows in all bootmethods + Seq Type State Uclass Part Name Filename + --- ----------- ------ -------- ---- ------------------------ ---------------- + Scanning bootmethod 'mmc@7e202000.bootmethod': + 0 distro-boot loaded mmc 2 mmc@7e202000.bootmethod.p extlinux/extlinux.conf + Scanning bootmethod 'sdhci@7e300000.bootmethod': + Card did not respond to voltage select! : -110 + Scanning bootmethod 'smsc95xx_eth.bootmethod': + Waiting for Ethernet connection... done. + BOOTP broadcast 1 + DHCP client bound to address 192.168.4.30 (4 ms) + Using smsc95xx_eth device + TFTP from server 192.168.4.1; our IP address is 192.168.4.30 + Filename 'rpi.pxe/'. + Load address: 0x200000 + Loading: * + TFTP error: 'Is a directory' (0) + Starting again + + missing environment variable: pxeuuid + Retrieving file: rpi.pxe/pxelinux.cfg/01-b8-27-eb-a6-61-e1 + Waiting for Ethernet connection... done. + Using smsc95xx_eth device + TFTP from server 192.168.4.1; our IP address is 192.168.4.30 + Filename 'rpi.pxe/pxelinux.cfg/01-b8-27-eb-a6-61-e1'. + Load address: 0x2500000 + Loading: ################################################## 566 Bytes + 45.9 KiB/s + done + Bytes transferred = 566 (236 hex) + 1 distro-boot loaded ethernet 0 smsc95xx_eth.bootmethod.0 rpi.pxe/extlinux/extlinux.conf + No more bootmethods + --- ----------- ------ -------- ---- ------------------------ ---------------- + (2 bootflows, 2 valid) + U-Boot> bootflow l + Showing all bootflows + Seq Type State Uclass Part Name Filename + --- ----------- ------ -------- ---- ------------------------ ---------------- + 0 distro-boot loaded mmc 2 mmc@7e202000.bootmethod.p extlinux/extlinux.conf + 1 distro-boot loaded ethernet 0 smsc95xx_eth.bootmethod.0 rpi.pxe/extlinux/extlinux.conf + --- ----------- ------ -------- ---- ------------------------ ---------------- + (2 bootflows, 2 valid) + + +The second one is then selected by name (we could instead use `bootflow sel 0`), +displayed and booted:: + + U-Boot> bootflow info + No bootflow selected + U-Boot> bootflow sel mmc@7e202000.bootmethod.part_2 + U-Boot> bootflow info + Name: mmc@7e202000.bootmethod.part_2 + Device: mmc@7e202000.bootmethod + Block dev: mmc@7e202000.blk + Sequence: 1 + Type: distro-boot + State: loaded + Partition: 2 + Subdir: (none) + Filename: extlinux/extlinux.conf + Buffer: 3db7ae88 + Size: 232 (562 bytes) + Error: 0 + U-Boot> bootflow boot + ** Booting bootflow 'smsc95xx_eth.bootmethod.0' + Ignoring unknown command: ui + Ignoring malformed menu command: autoboot + Ignoring malformed menu command: hidden + Ignoring unknown command: totaltimeout + 1: Fedora-Workstation-armhfp-31-1.9 (5.3.7-301.fc31.armv7hl) + Retrieving file: rpi.pxe/initramfs-5.3.7-301.fc31.armv7hl.img + get 2700000 rpi.pxe/initramfs-5.3.7-301.fc31.armv7hl.img + Waiting for Ethernet connection... done. + Using smsc95xx_eth device + TFTP from server 192.168.4.1; our IP address is 192.168.4.30 + Filename 'rpi.pxe/initramfs-5.3.7-301.fc31.armv7hl.img'. + Load address: 0x2700000 + Loading: ###################################T ############### 57.7 MiB + 1.9 MiB/s + done + Bytes transferred = 60498594 (39b22a2 hex) + Retrieving file: rpi.pxe//vmlinuz-5.3.7-301.fc31.armv7hl + get 80000 rpi.pxe//vmlinuz-5.3.7-301.fc31.armv7hl + Waiting for Ethernet connection... done. + Using smsc95xx_eth device + TFTP from server 192.168.4.1; our IP address is 192.168.4.30 + Filename 'rpi.pxe//vmlinuz-5.3.7-301.fc31.armv7hl'. + Load address: 0x80000 + Loading: ################################################## 7.2 MiB + 2.3 MiB/s + done + Bytes transferred = 7508480 (729200 hex) + append: ro root=UUID=9732b35b-4cd5-458b-9b91-80f7047e0b8a rhgb quiet LANG=en_US.UTF-8 cma=192MB cma=256MB + Retrieving file: rpi.pxe//dtb-5.3.7-301.fc31.armv7hl/bcm2837-rpi-3-b.dtb + get 2600000 rpi.pxe//dtb-5.3.7-301.fc31.armv7hl/bcm2837-rpi-3-b.dtb + Waiting for Ethernet connection... done. + Using smsc95xx_eth device + TFTP from server 192.168.4.1; our IP address is 192.168.4.30 + Filename 'rpi.pxe//dtb-5.3.7-301.fc31.armv7hl/bcm2837-rpi-3-b.dtb'. + Load address: 0x2600000 + Loading: ################################################## 13.8 KiB + 764.6 KiB/s + done + Bytes transferred = 14102 (3716 hex) + Kernel image @ 0x080000 [ 0x000000 - 0x729200 ] + ## Flattened Device Tree blob at 02600000 + Booting using the fdt blob at 0x2600000 + Using Device Tree in place at 02600000, end 02606715 + + Starting kernel ... + + [ OK ] Started Show Plymouth Boot Screen. + [ OK ] Started Forward Password R…s to Plymouth Directory Watch. + [ OK ] Reached target Local Encrypted Volumes. + [ OK ] Reached target Paths. + .... + + +Here we scan for bootflows and boot the first one found:: + + U-Boot> bootflow scan -bl + Scanning for bootflows in all bootmethods + Seq Type State Uclass Part Name Filename + --- ----------- ------ -------- ---- ------------------------ ---------------- + Scanning bootmethod 'mmc@7e202000.bootmethod': + 0 distro-boot loaded mmc 2 mmc@7e202000.bootmethod.p extlinux/extlinux.conf + ** Booting bootflow 'mmc@7e202000.bootmethod.part_2' + Ignoring unknown command: ui + Ignoring malformed menu command: autoboot + Ignoring malformed menu command: hidden + Ignoring unknown command: totaltimeout + 1: Fedora-KDE-armhfp-31-1.9 (5.3.7-301.fc31.armv7hl) + Retrieving file: /initramfs-5.3.7-301.fc31.armv7hl.img + getfile 2700000 /initramfs-5.3.7-301.fc31.armv7hl.img + Retrieving file: /vmlinuz-5.3.7-301.fc31.armv7hl + getfile 80000 /vmlinuz-5.3.7-301.fc31.armv7hl + append: ro root=UUID=b8781f09-e2dd-4cb8-979b-7df5eeaaabea rhgb LANG=en_US.UTF-8 cma=192MB console=tty0 console=ttyS1,115200 + Retrieving file: /dtb-5.3.7-301.fc31.armv7hl/bcm2837-rpi-3-b.dtb + getfile 2600000 /dtb-5.3.7-301.fc31.armv7hl/bcm2837-rpi-3-b.dtb + Kernel image @ 0x080000 [ 0x000000 - 0x729200 ] + ## Flattened Device Tree blob at 02600000 + Booting using the fdt blob at 0x2600000 + Using Device Tree in place at 02600000, end 02606715 + + Starting kernel ... + + [ 0.000000] Booting Linux on physical CPU 0x0 + + +Here is am example using the -e flag to see all errors:: + + U-Boot> bootflow scan -a + Card did not respond to voltage select! : -110 + Waiting for Ethernet connection... done. + BOOTP broadcast 1 + DHCP client bound to address 192.168.4.30 (4 ms) + Using smsc95xx_eth device + TFTP from server 192.168.4.1; our IP address is 192.168.4.30 + Filename 'rpi.pxe/'. + Load address: 0x200000 + Loading: * + TFTP error: 'Is a directory' (0) + Starting again + + missing environment variable: pxeuuid + Retrieving file: rpi.pxe/pxelinux.cfg/01-b8-27-eb-a6-61-e1 + Waiting for Ethernet connection... done. + Using smsc95xx_eth device + TFTP from server 192.168.4.1; our IP address is 192.168.4.30 + Filename 'rpi.pxe/pxelinux.cfg/01-b8-27-eb-a6-61-e1'. + Load address: 0x2500000 + Loading: ################################################## 566 Bytes + 49.8 KiB/s + done + Bytes transferred = 566 (236 hex) + U-Boot> bootflow l -e + Showing all bootflows + Seq Type State Uclass Part Name Filename + --- ----------- ------ -------- ---- ------------------------ ---------------- + 0 distro-boot fs mmc 1 mmc@7e202000.bootmethod.p extlinux/extlinux.conf + ** File not found, err=-2 + 1 distro-boot loaded mmc 2 mmc@7e202000.bootmethod.p extlinux/extlinux.conf + 2 distro-boot fs mmc 3 mmc@7e202000.bootmethod.p extlinux/extlinux.conf + ** File not found, err=-1 + 3 distro-boot media mmc 0 mmc@7e202000.bootmethod.p <NULL> + ** No partition found, err=-2 + 4 distro-boot media mmc 0 mmc@7e202000.bootmethod.p <NULL> + ** No partition found, err=-2 + 5 distro-boot media mmc 0 mmc@7e202000.bootmethod.p <NULL> + ** No partition found, err=-2 + 6 distro-boot media mmc 0 mmc@7e202000.bootmethod.p <NULL> + ** No partition found, err=-2 + 7 distro-boot media mmc 0 mmc@7e202000.bootmethod.p <NULL> + ** No partition found, err=-2 + 8 distro-boot media mmc 0 mmc@7e202000.bootmethod.p <NULL> + ** No partition found, err=-2 + 9 distro-boot media mmc 0 mmc@7e202000.bootmethod.p <NULL> + ** No partition found, err=-2 + a distro-boot media mmc 0 mmc@7e202000.bootmethod.p <NULL> + ** No partition found, err=-2 + b distro-boot media mmc 0 mmc@7e202000.bootmethod.p <NULL> + ** No partition found, err=-2 + c distro-boot media mmc 0 mmc@7e202000.bootmethod.p <NULL> + ** No partition found, err=-2 + d distro-boot media mmc 0 mmc@7e202000.bootmethod.p <NULL> + ** No partition found, err=-2 + e distro-boot media mmc 0 mmc@7e202000.bootmethod.p <NULL> + ** No partition found, err=-2 + f distro-boot media mmc 0 mmc@7e202000.bootmethod.p <NULL> + ** No partition found, err=-2 + 10 distro-boot media mmc 0 mmc@7e202000.bootmethod.p <NULL> + ** No partition found, err=-2 + 11 distro-boot media mmc 0 mmc@7e202000.bootmethod.p <NULL> + ** No partition found, err=-2 + 12 distro-boot media mmc 0 mmc@7e202000.bootmethod.p <NULL> + ** No partition found, err=-2 + 13 distro-boot media mmc 0 mmc@7e202000.bootmethod.p <NULL> + ** No partition found, err=-2 + 14 distro-boot loaded ethernet 0 smsc95xx_eth.bootmethod.0 rpi.pxe/extlinux/extlinux.conf + --- ----------- ------ -------- ---- ------------------------ ---------------- + (21 bootflows, 2 valid) + U-Boot> + + +Return value +------------ + +On success `bootflow boot` normally boots into the Operating System and does not +return to U-Boot. If something about the U-Boot processing fails, then the +return value $? is 1. If the boot succeeds but for some reason the Operating +System returns, then $? is 0, indicating success. + +For other subcommands, the return value $? is always 0 (true). + + +.. BootflowStates_: diff --git a/doc/usage/bootmethod.rst b/doc/usage/bootmethod.rst new file mode 100644 index 00000000000..28afe09f06f --- /dev/null +++ b/doc/usage/bootmethod.rst @@ -0,0 +1,138 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +bootmethod command +================== + +Synopis +------- + +:: + + bootmethod list [-p] - list all available bootmethods (-p to probe)\n" + bootmethod select <bm> - select a bootmethod by name\n" + bootmethod info [-p] - show information about a bootmethod"; + +Description +----------- + +The `` command is used to manage bootmethods. It can list available +bootmethods, select one and obtain information about it. + +See :doc:`../develop/bootflow` for more information about bootmethods in +general. + + +bootmethod list +~~~~~~~~~~~~~~~ + +This lists available bootmethods + +Scanning with -p causes the bootmethods to be probed. This happens automatically +when they are used. + +The list looks something like this: + +=== ====== ====== ======== ========================= +Seq Probed Status Uclass Name +=== ====== ====== ======== ========================= + 0 [ + ] OK mmc mmc@7e202000.bootmethod + 1 [ ] OK mmc sdhci@7e300000.bootmethod + 2 [ ] OK ethernet smsc95xx_eth.bootmethod +=== ====== ====== ======== ========================= + + +The fields are as follows: + +Seq: + Sequence number in the scan, used to reference the bootflow later + +Probed: + Shows a plus (+) if the device is probed, empty if not. + +Status: + Shows the status of the device. Typically this is `OK` meaning that there is + no error. If you use -p and an error occurs when probing, then this shows + the error number. You can look up Linux error codes to find the meaning of + the number. + +Uclass: + Name of the media device's Uclass. This indicates the type of the parent + device (e.g. MMC, Ethernet). + +Name: + Name of the bootmethod. This is generated from the media device appended + with `.bootmethod` + + +bootmethod select +~~~~~~~~~~~~~~~~~ + +Use this to select a particular bootmethod. You can select it by the sequence +number or name, as shown in `bootmethod list`. + +Once a bootmethod is selected, you can use `bootmethod info` to look at it or +`bootflow scan` to scan it. + +If no bootmethod name or number is provided, then any existing bootmethod is +unselected. + + +bootmethod info +~~~~~~~~~~~~~~~ + +This shows information on the current bootmethod, with the format looking like +this: + +========= ======================= +Name mmc@7e202000.bootmethod +Sequence 0 +Status Probed +Uclass mmc +Bootflows 1 (1 valid) +========= ======================= + +Most of the information is the same as `bootmethod list` above. The new fields +are: + +Device + Name of the bootmethod + +Status + Shows `Probed` if the device is probed, `OK` if not. If -p is used and the + device fails to probe, an error code is shown. + +Bootflows + Indicates the number of bootflows attached to the bootmethod. This is 0 + unless you have used 'bootflow scan' on the bootflow, or on all bootflows. + + +Example +------- + +This example shows listing available bootmethod and getting information about +one of them:: + + U-Boot> bootmethod list + Seq Probed Status Uclass Name + --- ------ ------ -------- ------------------ + 0 [ + ] OK mmc mmc@7e202000.bootmethod + 1 [ ] OK mmc sdhci@7e300000.bootmethod + 2 [ ] OK ethernet smsc95xx_eth.bootmethod + --- ------ ------ -------- ------------------ + (3 devices) + U-Boot> bootmethod sel 0 + U-Boot> bootflow scan + U-Boot> bootmethod info + Name: mmc@7e202000.bootmethod + Sequence: 0 + Status: Probed + Uclass: mmc + Bootflows: 1 (1 valid) + + +Return value +------------ + +The return value $? is always 0 (true). + + diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 356f2a56181..0abfad26e8e 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -21,8 +21,10 @@ Shell commands askenv base bootefi + bootflow booti bootmenu + bootmethod button x86/cbsysinfo conitrace