1.. SPDX-License-Identifier: GPL-2.0+:
2
3bootflow command
4================
5
6Synopis
7-------
8
9::
10
11    bootflow scan [-abelGH] [bootdev]
12    bootflow list [-e]
13    bootflow select [<num|name>]
14    bootflow info [-d]
15    bootflow boot
16
17
18Description
19-----------
20
21The `bootflow` command is used to manage bootflows. It can scan bootdevs to
22locate bootflows, list them and boot them.
23
24See :doc:`../../develop/bootstd` for more information.
25
26
27bootflow scan
28~~~~~~~~~~~~~
29
30Scans for available bootflows, optionally booting the first valid one it finds.
31This operates in two modes:
32
33- If no bootdev is selected (see `bootdev select`) it scans bootflows one
34  by one, extracting all the bootdevs from each
35- If a bootdev is selected, it just scans that one bootflow
36
37Flags are:
38
39-a
40    Collect all bootflows, even those that cannot be loaded. Normally if a file
41    is not where it is expected, then the bootflow fails and so is dropped
42    during the scan. With this option you can see why each bootflow would be
43    dropped.
44
45-b
46    Boot each valid bootflow as it is scanned. Typically only the first bootflow
47    matters, since by then the system boots in the OS and U-Boot is no-longer
48    running. `bootflow scan -b` is a quick way to boot the first available OS.
49    A valid bootflow is one that made it all the way to the `loaded` state.
50
51-e
52    Used with -l to also show errors for each bootflow. The shows detailed error
53    information for each bootflow that failed to make it to the `loaded` state.
54
55-l
56    List bootflows while scanning. This is helpful when you want to see what
57    is happening during scanning. Use it with the `-b` flag to see which
58    bootdev and bootflows are being tried.
59
60-G
61    Skip global bootmeths when scanning. By default these are tried first, but
62    this flag disables them.
63
64-H
65    Don't use bootdev hunters. By default these are used before each boot
66    priority or label is tried, to see if more bootdevs can be discovered, but
67    this flag disables that process.
68
69
70The optional argument specifies a particular bootdev to scan. This can either be
71the name of a bootdev or its sequence number (both shown with `bootdev list`).
72Alternatively a convenience label can be used, like `mmc0`, which is the type of
73device and an optional sequence number. Specifically, the label is the uclass of
74the bootdev's parent followed by the sequence number of that parent. Sequence
75numbers are typically set by aliases, so if you have 'mmc0' in your devicetree
76alias section, then `mmc0` refers to the bootdev attached to that device.
77
78
79bootflow list
80~~~~~~~~~~~~~
81
82Lists the previously scanned bootflows. You must use `bootflow scan` before this
83to see anything.
84
85If you scanned with -a and have bootflows with errors, -e can be used to show
86those errors.
87
88The list looks something like this:
89
90===  ======  ======  ========  ====  ===============================   ================
91Seq  Method  State   Uclass    Part  Name                              Filename
92===  ======  ======  ========  ====  ===============================   ================
93  0  distro  ready   mmc          2  mmc\@7e202000.bootdev.part_2      /boot/extlinux/extlinux.conf
94  1  pxe     ready   ethernet     0  smsc95xx_eth.bootdev.0            rpi.pxe/extlinux/extlinux.conf
95===  ======  ======  ========  ====  ===============================   ================
96
97The fields are as follows:
98
99Seq:
100    Sequence number in the scan, used to reference the bootflow later
101
102Method:
103    The boot method (bootmeth) used to find the bootflow. Several methods are
104    included in U-Boot.
105
106State:
107    Current state of the bootflow, indicating how far the bootdev got in
108    obtaining a valid one. See :ref:`BootflowStates` for a list of states.
109
110Uclass:
111    Name of the media device's Uclass. This indicates the type of the parent
112    device (e.g. MMC, Ethernet).
113
114Part:
115    Partition number being accesseed, numbered from 1. Normally a device will
116    have a partition table with a small number of partitions. For devices
117    without partition tables (e.g. network) this field is 0.
118
119Name:
120    Name of the bootflow. This is generated from the bootdev appended with
121    the partition information
122
123Filename:
124    Name of the bootflow file. This indicates where the file is on the
125    filesystem or network device.
126
127
128bootflow select
129~~~~~~~~~~~~~~~
130
131Use this to select a particular bootflow. You can select it by the sequence
132number or name, as shown in `bootflow list`.
133
134Once a bootflow is selected, you can use `bootflow info` and `bootflow boot`.
135
136If no bootflow name or number is provided, then any existing bootflow is
137unselected.
138
139
140bootflow info
141~~~~~~~~~~~~~
142
143This shows information on the current bootflow, with the format looking like
144this:
145
146=========  ===============================
147Name       mmc\@7e202000.bootdev.part_2
148Device     mmc\@7e202000.bootdev
149Block dev  mmc\@7e202000.blk
150Type       distro
151Method:    extlinux
152State      ready
153Partition  2
154Subdir     (none)
155Filename   /extlinux/extlinux.conf
156Buffer     3db7ad48
157Size       232 (562 bytes)
158FDT:       <NULL>
159Error      0
160=========  ===============================
161
162Most of the information is the same as `bootflow list` above. The new fields
163are:
164
165Device
166    Name of the bootdev
167
168Block dev
169    Name of the block device, if any. Network devices don't have a block device.
170
171Subdir
172    Subdirectory used for retrieving files. For network bootdevs this is the
173    directory of the 'bootfile' parameter passed from DHCP. All file retrievals
174    when booting are relative to this.
175
176Buffer
177    Buffer containing the bootflow file. You can use the :doc:`md` to look at
178    it, or dump it with `bootflow info -d`.
179
180Size
181    Size of the bootflow file
182
183FDT:
184    Filename of the device tree, if supported. The EFI bootmeth uses this to
185    remember the filename to load. If `<NULL>` then there is none.
186
187Error
188    Error number returned from scanning for the bootflow. This is 0 if the
189    bootflow is in the 'loaded' state, or a negative error value on error. You
190    can look up Linux error codes to find the meaning of the number.
191
192Use the `-d` flag to dump out the contents of the bootfile file.
193
194
195bootflow boot
196~~~~~~~~~~~~~
197
198This boots the current bootflow.
199
200
201Example
202-------
203
204Here is an example of scanning for bootflows, then listing them::
205
206    U-Boot> bootflow scan -l
207    Scanning for bootflows in all bootdevs
208    Seq  Type         State   Uclass    Part  Name                      Filename
209    ---  -----------  ------  --------  ----  ------------------------  ----------------
210    Scanning bootdev 'mmc@7e202000.bootdev':
211      0  distro       ready   mmc          2  mmc@7e202000.bootdev.p    /extlinux/extlinux.conf
212    Scanning bootdev 'sdhci@7e300000.bootdev':
213    Card did not respond to voltage select! : -110
214    Scanning bootdev 'smsc95xx_eth.bootdev':
215    Waiting for Ethernet connection... done.
216    BOOTP broadcast 1
217    DHCP client bound to address 192.168.4.30 (4 ms)
218    Using smsc95xx_eth device
219    TFTP from server 192.168.4.1; our IP address is 192.168.4.30
220    Filename 'rpi.pxe/'.
221    Load address: 0x200000
222    Loading: *
223    TFTP error: 'Is a directory' (0)
224    Starting again
225
226    missing environment variable: pxeuuid
227    Retrieving file: rpi.pxe/pxelinux.cfg/01-b8-27-eb-a6-61-e1
228    Waiting for Ethernet connection... done.
229    Using smsc95xx_eth device
230    TFTP from server 192.168.4.1; our IP address is 192.168.4.30
231    Filename 'rpi.pxe/pxelinux.cfg/01-b8-27-eb-a6-61-e1'.
232    Load address: 0x2500000
233    Loading: ##################################################  566 Bytes
234    	 45.9 KiB/s
235    done
236    Bytes transferred = 566 (236 hex)
237      1  distro       ready   ethernet     0  smsc95xx_eth.bootdev.0 rpi.pxe/extlinux/extlinux.conf
238    No more bootdevs
239    ---  -----------  ------  --------  ----  ------------------------  ----------------
240    (2 bootflows, 2 valid)
241    U-Boot> bootflow l
242    Showing all bootflows
243    Seq  Type         State   Uclass    Part  Name                      Filename
244    ---  -----------  ------  --------  ----  ------------------------  ----------------
245      0  distro       ready   mmc          2  mmc@7e202000.bootdev.p    /extlinux/extlinux.conf
246      1  pxe          ready   ethernet     0  smsc95xx_eth.bootdev.0     rpi.pxe/extlinux/extlinux.conf
247    ---  -----------  ------  --------  ----  ------------------------  ----------------
248    (2 bootflows, 2 valid)
249
250
251The second one is then selected by name (we could instead use `bootflow sel 0`),
252displayed and booted::
253
254    U-Boot> bootflow info
255    No bootflow selected
256    U-Boot> bootflow sel mmc@7e202000.bootdev.part_2
257    U-Boot> bootflow info
258    Name:      mmc@7e202000.bootdev.part_2
259    Device:    mmc@7e202000.bootdev
260    Block dev: mmc@7e202000.blk
261    Sequence:  1
262    Method:    distro
263    State:     ready
264    Partition: 2
265    Subdir:    (none)
266    Filename:  extlinux/extlinux.conf
267    Buffer:    3db7ae88
268    Size:      232 (562 bytes)
269    Error:     0
270    U-Boot> bootflow boot
271    ** Booting bootflow 'smsc95xx_eth.bootdev.0'
272    Ignoring unknown command: ui
273    Ignoring malformed menu command:  autoboot
274    Ignoring malformed menu command:  hidden
275    Ignoring unknown command: totaltimeout
276    1:	Fedora-Workstation-armhfp-31-1.9 (5.3.7-301.fc31.armv7hl)
277    Retrieving file: rpi.pxe/initramfs-5.3.7-301.fc31.armv7hl.img
278    get 2700000 rpi.pxe/initramfs-5.3.7-301.fc31.armv7hl.img
279    Waiting for Ethernet connection... done.
280    Using smsc95xx_eth device
281    TFTP from server 192.168.4.1; our IP address is 192.168.4.30
282    Filename 'rpi.pxe/initramfs-5.3.7-301.fc31.armv7hl.img'.
283    Load address: 0x2700000
284    Loading: ###################################T ###############  57.7 MiB
285    	 1.9 MiB/s
286    done
287    Bytes transferred = 60498594 (39b22a2 hex)
288    Retrieving file: rpi.pxe//vmlinuz-5.3.7-301.fc31.armv7hl
289    get 80000 rpi.pxe//vmlinuz-5.3.7-301.fc31.armv7hl
290    Waiting for Ethernet connection... done.
291    Using smsc95xx_eth device
292    TFTP from server 192.168.4.1; our IP address is 192.168.4.30
293    Filename 'rpi.pxe//vmlinuz-5.3.7-301.fc31.armv7hl'.
294    Load address: 0x80000
295    Loading: ##################################################  7.2 MiB
296    	 2.3 MiB/s
297    done
298    Bytes transferred = 7508480 (729200 hex)
299    append: ro root=UUID=9732b35b-4cd5-458b-9b91-80f7047e0b8a rhgb quiet LANG=en_US.UTF-8 cma=192MB cma=256MB
300    Retrieving file: rpi.pxe//dtb-5.3.7-301.fc31.armv7hl/bcm2837-rpi-3-b.dtb
301    get 2600000 rpi.pxe//dtb-5.3.7-301.fc31.armv7hl/bcm2837-rpi-3-b.dtb
302    Waiting for Ethernet connection... done.
303    Using smsc95xx_eth device
304    TFTP from server 192.168.4.1; our IP address is 192.168.4.30
305    Filename 'rpi.pxe//dtb-5.3.7-301.fc31.armv7hl/bcm2837-rpi-3-b.dtb'.
306    Load address: 0x2600000
307    Loading: ##################################################  13.8 KiB
308    	 764.6 KiB/s
309    done
310    Bytes transferred = 14102 (3716 hex)
311    Kernel image @ 0x080000 [ 0x000000 - 0x729200 ]
312    ## Flattened Device Tree blob at 02600000
313       Booting using the fdt blob at 0x2600000
314       Using Device Tree in place at 02600000, end 02606715
315
316    Starting kernel ...
317
318    [  OK  ] Started Show Plymouth Boot Screen.
319    [  OK  ] Started Forward Password R…s to Plymouth Directory Watch.
320    [  OK  ] Reached target Local Encrypted Volumes.
321    [  OK  ] Reached target Paths.
322    ....
323
324
325Here we scan for bootflows and boot the first one found::
326
327    U-Boot> bootflow scan -bl
328    Scanning for bootflows in all bootdevs
329    Seq  Method       State   Uclass    Part  Name                    Filename
330    ---  -----------  ------  --------  ----  ----------------------  ----------------
331    Scanning bootdev 'mmc@7e202000.bootdev':
332      0  distro       ready   mmc          2  mmc@7e202000.bootdev.p  /extlinux/extlinux.conf
333    ** Booting bootflow 'mmc@7e202000.bootdev.part_2'
334    Ignoring unknown command: ui
335    Ignoring malformed menu command:  autoboot
336    Ignoring malformed menu command:  hidden
337    Ignoring unknown command: totaltimeout
338    1:	Fedora-KDE-armhfp-31-1.9 (5.3.7-301.fc31.armv7hl)
339    Retrieving file: /initramfs-5.3.7-301.fc31.armv7hl.img
340    getfile 2700000 /initramfs-5.3.7-301.fc31.armv7hl.img
341    Retrieving file: /vmlinuz-5.3.7-301.fc31.armv7hl
342    getfile 80000 /vmlinuz-5.3.7-301.fc31.armv7hl
343    append: ro root=UUID=b8781f09-e2dd-4cb8-979b-7df5eeaaabea rhgb LANG=en_US.UTF-8 cma=192MB console=tty0 console=ttyS1,115200
344    Retrieving file: /dtb-5.3.7-301.fc31.armv7hl/bcm2837-rpi-3-b.dtb
345    getfile 2600000 /dtb-5.3.7-301.fc31.armv7hl/bcm2837-rpi-3-b.dtb
346    Kernel image @ 0x080000 [ 0x000000 - 0x729200 ]
347    ## Flattened Device Tree blob at 02600000
348       Booting using the fdt blob at 0x2600000
349       Using Device Tree in place at 02600000, end 02606715
350
351    Starting kernel ...
352
353    [    0.000000] Booting Linux on physical CPU 0x0
354
355
356Here is am example using the -e flag to see all errors::
357
358    U-Boot> bootflow scan -a
359    Card did not respond to voltage select! : -110
360    Waiting for Ethernet connection... done.
361    BOOTP broadcast 1
362    DHCP client bound to address 192.168.4.30 (4 ms)
363    Using smsc95xx_eth device
364    TFTP from server 192.168.4.1; our IP address is 192.168.4.30
365    Filename 'rpi.pxe/'.
366    Load address: 0x200000
367    Loading: *
368    TFTP error: 'Is a directory' (0)
369    Starting again
370
371    missing environment variable: pxeuuid
372    Retrieving file: rpi.pxe/pxelinux.cfg/01-b8-27-eb-a6-61-e1
373    Waiting for Ethernet connection... done.
374    Using smsc95xx_eth device
375    TFTP from server 192.168.4.1; our IP address is 192.168.4.30
376    Filename 'rpi.pxe/pxelinux.cfg/01-b8-27-eb-a6-61-e1'.
377    Load address: 0x2500000
378    Loading: ##################################################  566 Bytes
379    	 49.8 KiB/s
380    done
381    Bytes transferred = 566 (236 hex)
382    U-Boot> bootflow l -e
383    Showing all bootflows
384    Seq  Type         State   Uclass    Part  Name                   Filename
385    ---  -----------  ------  --------  ----  ---------------------  ----------------
386      0  distro       fs      mmc          1  mmc@7e202000.bootdev.p /extlinux/extlinux.conf
387         ** File not found, err=-2
388      1  distro       ready   mmc          2  mmc@7e202000.bootdev.p /extlinux/extlinux.conf
389      2  distro       fs      mmc          3  mmc@7e202000.bootdev.p /extlinux/extlinux.conf
390         ** File not found, err=-1
391      3  distro       media   mmc          0  mmc@7e202000.bootdev.p <NULL>
392         ** No partition found, err=-2
393      4  distro       media   mmc          0  mmc@7e202000.bootdev.p <NULL>
394         ** No partition found, err=-2
395      5  distro       media   mmc          0  mmc@7e202000.bootdev.p <NULL>
396         ** No partition found, err=-2
397      6  distro       media   mmc          0  mmc@7e202000.bootdev.p <NULL>
398         ** No partition found, err=-2
399      7  distro       media   mmc          0  mmc@7e202000.bootdev.p <NULL>
400         ** No partition found, err=-2
401      8  distro       media   mmc          0  mmc@7e202000.bootdev.p <NULL>
402         ** No partition found, err=-2
403      9  distro       media   mmc          0  mmc@7e202000.bootdev.p <NULL>
404         ** No partition found, err=-2
405      a  distro       media   mmc          0  mmc@7e202000.bootdev.p <NULL>
406         ** No partition found, err=-2
407      b  distro       media   mmc          0  mmc@7e202000.bootdev.p <NULL>
408         ** No partition found, err=-2
409      c  distro       media   mmc          0  mmc@7e202000.bootdev.p <NULL>
410         ** No partition found, err=-2
411      d  distro       media   mmc          0  mmc@7e202000.bootdev.p <NULL>
412         ** No partition found, err=-2
413      e  distro       media   mmc          0  mmc@7e202000.bootdev.p <NULL>
414         ** No partition found, err=-2
415      f  distro       media   mmc          0  mmc@7e202000.bootdev.p <NULL>
416         ** No partition found, err=-2
417     10  distro       media   mmc          0  mmc@7e202000.bootdev.p <NULL>
418         ** No partition found, err=-2
419     11  distro       media   mmc          0  mmc@7e202000.bootdev.p <NULL>
420         ** No partition found, err=-2
421     12  distro       media   mmc          0  mmc@7e202000.bootdev.p <NULL>
422         ** No partition found, err=-2
423     13  distro       media   mmc          0  mmc@7e202000.bootdev.p <NULL>
424         ** No partition found, err=-2
425     14  distro       ready   ethernet     0  smsc95xx_eth.bootdev.0 rpi.pxe/extlinux/extlinux.conf
426    ---  -----------  ------  --------  ----  ---------------------  ----------------
427    (21 bootflows, 2 valid)
428    U-Boot>
429
430
431Return value
432------------
433
434On success `bootflow boot` normally boots into the Operating System and does not
435return to U-Boot. If something about the U-Boot processing fails, then the
436return value $? is 1. If the boot succeeds but for some reason the Operating
437System returns, then $? is 0, indicating success.
438
439For other subcommands, the return value $? is always 0 (true).
440
441
442.. BootflowStates_:
443