mirror of
https://github.com/AsahiLinux/u-boot
synced 2024-12-05 02:51:00 +00:00
e7b2ce191e
Add documentation for this feature, including the commands and full devicetree bindings. Signed-off-by: Simon Glass <sjg@chromium.org>
427 lines
16 KiB
ReStructuredText
427 lines
16 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0+:
|
|
|
|
bootflow command
|
|
================
|
|
|
|
Synopis
|
|
-------
|
|
|
|
::
|
|
|
|
bootflow scan [-abel] [bootdev]
|
|
bootflow list [-e]
|
|
bootflow select [<num|name>]
|
|
bootflow info [-d]
|
|
bootflow boot
|
|
|
|
|
|
Description
|
|
-----------
|
|
|
|
The `bootflow` command is used to manage bootflows. It can scan bootdevs to
|
|
locate bootflows, list them and boot them.
|
|
|
|
See :doc:`../../develop/bootstd` for more information.
|
|
|
|
|
|
bootflow scan
|
|
~~~~~~~~~~~~~
|
|
|
|
Scans for available bootflows, optionally booting the first valid one it finds.
|
|
This operates in two modes:
|
|
|
|
- If no bootdev is selected (see `bootdev select`) it scans bootflows one
|
|
by one, extracting all the bootdevs from each
|
|
- If a bootdev 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
|
|
bootdev and bootflows are being tried.
|
|
|
|
The optional argument specifies a particular bootdev to scan. This can either be
|
|
the name of a bootdev or its sequence number (both shown with `bootdev list`).
|
|
Alternatively a convenience label can be used, like `mmc0`, which is the type of
|
|
device and an optional sequence number. Specifically, the label is the uclass of
|
|
the bootdev's parent followed by the sequence number of that parent. Sequence
|
|
numbers are typically set by aliases, so if you have 'mmc0' in your devicetree
|
|
alias section, then `mmc0` refers to the bootdev attached to that device.
|
|
|
|
|
|
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 Method State Uclass Part Name Filename
|
|
=== ====== ====== ======== ==== =============================== ================
|
|
0 distro ready mmc 2 mmc\@7e202000.bootdev.part_2 /boot/extlinux/extlinux.conf
|
|
1 pxe ready ethernet 0 smsc95xx_eth.bootdev.0 rpi.pxe/extlinux/extlinux.conf
|
|
=== ====== ====== ======== ==== =============================== ================
|
|
|
|
The fields are as follows:
|
|
|
|
Seq:
|
|
Sequence number in the scan, used to reference the bootflow later
|
|
|
|
Method:
|
|
The boot method (bootmeth) used to find the bootflow. Several methods are
|
|
included in U-Boot.
|
|
|
|
State:
|
|
Current state of the bootflow, indicating how far the bootdev 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 bootdev 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.bootdev.part_2
|
|
Device mmc\@7e202000.bootdev
|
|
Block dev mmc\@7e202000.blk
|
|
Type distro
|
|
Method: syslinux
|
|
State ready
|
|
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 bootdev
|
|
|
|
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 bootdevs 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 bootdevs
|
|
Seq Type State Uclass Part Name Filename
|
|
--- ----------- ------ -------- ---- ------------------------ ----------------
|
|
Scanning bootdev 'mmc@7e202000.bootdev':
|
|
0 distro ready mmc 2 mmc@7e202000.bootdev.p /extlinux/extlinux.conf
|
|
Scanning bootdev 'sdhci@7e300000.bootdev':
|
|
Card did not respond to voltage select! : -110
|
|
Scanning bootdev 'smsc95xx_eth.bootdev':
|
|
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 ready ethernet 0 smsc95xx_eth.bootdev.0 rpi.pxe/extlinux/extlinux.conf
|
|
No more bootdevs
|
|
--- ----------- ------ -------- ---- ------------------------ ----------------
|
|
(2 bootflows, 2 valid)
|
|
U-Boot> bootflow l
|
|
Showing all bootflows
|
|
Seq Type State Uclass Part Name Filename
|
|
--- ----------- ------ -------- ---- ------------------------ ----------------
|
|
0 distro ready mmc 2 mmc@7e202000.bootdev.p /extlinux/extlinux.conf
|
|
1 pxe ready ethernet 0 smsc95xx_eth.bootdev.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.bootdev.part_2
|
|
U-Boot> bootflow info
|
|
Name: mmc@7e202000.bootdev.part_2
|
|
Device: mmc@7e202000.bootdev
|
|
Block dev: mmc@7e202000.blk
|
|
Sequence: 1
|
|
Method: distro
|
|
State: ready
|
|
Partition: 2
|
|
Subdir: (none)
|
|
Filename: extlinux/extlinux.conf
|
|
Buffer: 3db7ae88
|
|
Size: 232 (562 bytes)
|
|
Error: 0
|
|
U-Boot> bootflow boot
|
|
** Booting bootflow 'smsc95xx_eth.bootdev.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 bootdevs
|
|
Seq Method State Uclass Part Name Filename
|
|
--- ----------- ------ -------- ---- ---------------------- ----------------
|
|
Scanning bootdev 'mmc@7e202000.bootdev':
|
|
0 distro ready mmc 2 mmc@7e202000.bootdev.p /extlinux/extlinux.conf
|
|
** Booting bootflow 'mmc@7e202000.bootdev.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 fs mmc 1 mmc@7e202000.bootdev.p /extlinux/extlinux.conf
|
|
** File not found, err=-2
|
|
1 distro ready mmc 2 mmc@7e202000.bootdev.p /extlinux/extlinux.conf
|
|
2 distro fs mmc 3 mmc@7e202000.bootdev.p /extlinux/extlinux.conf
|
|
** File not found, err=-1
|
|
3 distro media mmc 0 mmc@7e202000.bootdev.p <NULL>
|
|
** No partition found, err=-2
|
|
4 distro media mmc 0 mmc@7e202000.bootdev.p <NULL>
|
|
** No partition found, err=-2
|
|
5 distro media mmc 0 mmc@7e202000.bootdev.p <NULL>
|
|
** No partition found, err=-2
|
|
6 distro media mmc 0 mmc@7e202000.bootdev.p <NULL>
|
|
** No partition found, err=-2
|
|
7 distro media mmc 0 mmc@7e202000.bootdev.p <NULL>
|
|
** No partition found, err=-2
|
|
8 distro media mmc 0 mmc@7e202000.bootdev.p <NULL>
|
|
** No partition found, err=-2
|
|
9 distro media mmc 0 mmc@7e202000.bootdev.p <NULL>
|
|
** No partition found, err=-2
|
|
a distro media mmc 0 mmc@7e202000.bootdev.p <NULL>
|
|
** No partition found, err=-2
|
|
b distro media mmc 0 mmc@7e202000.bootdev.p <NULL>
|
|
** No partition found, err=-2
|
|
c distro media mmc 0 mmc@7e202000.bootdev.p <NULL>
|
|
** No partition found, err=-2
|
|
d distro media mmc 0 mmc@7e202000.bootdev.p <NULL>
|
|
** No partition found, err=-2
|
|
e distro media mmc 0 mmc@7e202000.bootdev.p <NULL>
|
|
** No partition found, err=-2
|
|
f distro media mmc 0 mmc@7e202000.bootdev.p <NULL>
|
|
** No partition found, err=-2
|
|
10 distro media mmc 0 mmc@7e202000.bootdev.p <NULL>
|
|
** No partition found, err=-2
|
|
11 distro media mmc 0 mmc@7e202000.bootdev.p <NULL>
|
|
** No partition found, err=-2
|
|
12 distro media mmc 0 mmc@7e202000.bootdev.p <NULL>
|
|
** No partition found, err=-2
|
|
13 distro media mmc 0 mmc@7e202000.bootdev.p <NULL>
|
|
** No partition found, err=-2
|
|
14 distro ready ethernet 0 smsc95xx_eth.bootdev.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_:
|