Mirrors/u-boot
2
0
Fork 0
mirror of https://github.com/AsahiLinux/u-boot synced 2025-02-18 06:58:54 +00:00
Code Issues Projects Releases Packages Wiki Activity

doc: Bring in the command-syntax extensions

Browse source 
Bring this file into the documentation. For now it is not in the correct
format for a command, but it is valid rST. Futher work will improve this.

Signed-off-by: Simon Glass <sjg@chromium.org>
This commit is contained in:
Simon Glass 2023-06-23 13:22:13 +01:00 • committed by Heinrich Schuchardt
parent 3790b18444
commit d1b6b11443
2 changed files with 95 additions and 68 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

162
doc/uImage.FIT/command_syntax_extensions.txt → doc/usage/cmd/bootm.rst
View file

@ -1,3 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0+
Command syntax extensions for the new uImage format
===================================================
@ -20,100 +22,117 @@ of supported bootm usages.
Note: U-Boot supports two methods of booting a PowerPC Linux kernel: old way,
i.e., without passing the Flattened Device Tree (FDT), and new way, where the
kernel is passed a pointer to the FDT. The boot method is indicated for each
scenario.
scenario::
1. bootm boot image at the current address, equivalent to 2,3,8
1. bootm boot image at the current address, equivalent to 2,3,8
Old uImage::
Old uImage:
2. bootm <addr1> /* single image at <addr1> */
3. bootm <addr1> /* multi-image at <addr1> */
4. bootm <addr1> - /* multi-image at <addr1> */
5. bootm <addr1> <addr2> /* single image at <addr1> */
6. bootm <addr1> <addr2> <addr3> /* single image at <addr1> */
7. bootm <addr1> - <addr3> /* single image at <addr1> */
2. bootm <addr1> /* single image at <addr1> */
3. bootm <addr1> /* multi-image at <addr1> */
4. bootm <addr1> - /* multi-image at <addr1> */
5. bootm <addr1> <addr2> /* single image at <addr1> */
6. bootm <addr1> <addr2> <addr3> /* single image at <addr1> */
7. bootm <addr1> - <addr3> /* single image at <addr1> */
New uImage:
8. bootm <addr1>
9. bootm [<addr1>]:<subimg1>
10. bootm [<addr1>]#<conf>[#<extra-conf[#...]]
11. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2>
12. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> [<addr3>]:<subimg3>
13. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> <addr3>
14. bootm [<addr1>]:<subimg1> - [<addr3>]:<subimg3>
15. bootm [<addr1>]:<subimg1> - <addr3>
New uImage::
8. bootm <addr1>
9. bootm [<addr1>]:<subimg1>
10. bootm [<addr1>]#<conf>[#<extra-conf[#...]]
11. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2>
12. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> [<addr3>]:<subimg3>
13. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> <addr3>
14. bootm [<addr1>]:<subimg1> - [<addr3>]:<subimg3>
15. bootm [<addr1>]:<subimg1> - <addr3>
Ad. 1. This is equivalent to cases 2,3,8, depending on the type of image at
the current image address.
- boot method: see cases 2,3,8
Ad. 2. Boot kernel image located at <addr1>.
- boot method: non-FDT
Ad. 3. First and second components of the image at <addr1> are assumed to be a
kernel and a ramdisk, respectively. The kernel is booted with initrd loaded
with the ramdisk from the image.
- boot method: depends on the number of components at <addr1>, and on whether
U-Boot is compiled with OF support:
| 2 components | 3 components |
| (kernel, initrd) | (kernel, initrd, fdt) |
---------------------------------------------------------------------
#ifdef CONFIG_OF_* | non-FDT | FDT |
#ifndef CONFIG_OF_* | non-FDT | non-FDT |
- boot method: depends on the number of components at <addr1>, and on whether
U-Boot is compiled with OF support::
======================================================================
| 2 components | 3 components|
| (kernel, initrd) | (kernel, initrd, fdt) |
======================================================================
#ifdef CONFIG_OF_* | non-FDT | FDT |
#ifndef CONFIG_OF_* | non-FDT | non-FDT |
======================================================================
Ad. 4. Similar to case 3, but the kernel is booted without initrd. Second
component of the multi-image is irrelevant (it can be a dummy, 1-byte file).
- boot method: see case 3
Ad. 5. Boot kernel image located at <addr1> with initrd loaded with ramdisk
from the image at <addr2>.
- boot method: non-FDT
Ad. 6. <addr1> is the address of a kernel image, <addr2> is the address of a
ramdisk image, and <addr3> is the address of a FDT binary blob. Kernel is
booted with initrd loaded with ramdisk from the image at <addr2>.
- boot method: FDT
Ad. 7. <addr1> is the address of a kernel image and <addr3> is the address of
a FDT binary blob. Kernel is booted without initrd.
- boot method: FDT
Ad. 8. Image at <addr1> is assumed to contain a default configuration, which
is booted.
- boot method: FDT or non-FDT, depending on whether the default configuration
defines FDT
Ad. 9. Similar to case 2: boot kernel stored in <subimg1> from the image at
address <addr1>.
- boot method: non-FDT
Ad. 10. Boot configuration <conf> from the image at <addr1>.
- boot method: FDT or non-FDT, depending on whether the configuration given
defines FDT
Ad. 11. Equivalent to case 5: boot kernel stored in <subimg1> from the image
at <addr1> with initrd loaded with ramdisk <subimg2> from the image at
<addr2>.
- boot method: non-FDT
Ad. 12. Equivalent to case 6: boot kernel stored in <subimg1> from the image
at <addr1> with initrd loaded with ramdisk <subimg2> from the image at
<addr2>, and pass FDT blob <subimg3> from the image at <addr3>.
- boot method: FDT
Ad. 13. Similar to case 12, the difference being that <addr3> is the address
of FDT binary blob that is to be passed to the kernel.
- boot method: FDT
Ad. 14. Equivalent to case 7: boot kernel stored in <subimg1> from the image
at <addr1>, without initrd, and pass FDT blob <subimg3> from the image at
<addr3>.
- boot method: FDT
Ad. 15. Similar to case 14, the difference being that <addr3> is the address
of the FDT binary blob that is to be passed to the kernel.
- boot method: FDT
@ -123,14 +142,14 @@ New uImage argument syntax
New uImage support introduces two new forms for bootm arguments, with the
following syntax:
- new uImage sub-image specification
<addr>:<sub-image unit_name>
new uImage sub-image specification
<addr>:<sub-image unit_name>
- new uImage configuration specification
<addr>#<configuration unit_name>
new uImage configuration specification
<addr>#<configuration unit_name>
- new uImage configuration specification with extra configuration components
<addr>#<configuration unit_name>[#<extra configuration unit_name>[#..]]
new uImage configuration specification with extra configuration components
<addr>#<configuration unit_name>[#<extra configuration unit_name>[#..]]
The extra configuration currently is supported only for additional device tree
overlays to apply on the base device tree supplied by the first configuration
@ -138,31 +157,38 @@ unit.
Examples:
- boot kernel "kernel-1" stored in a new uImage located at 200000:
bootm 200000:kernel-1
boot kernel "kernel-1" stored in a new uImage located at 200000::
- boot configuration "cfg-1" from a new uImage located at 200000:
bootm 200000#cfg-1
bootm 200000:kernel-1
- boot configuration "cfg-1" with extra "cfg-2" from a new uImage located
at 200000:
bootm 200000#cfg-1#cfg-2
boot configuration "cfg-1" from a new uImage located at 200000::
- boot "kernel-1" from a new uImage at 200000 with initrd "ramdisk-2" found in
some other new uImage stored at address 800000:
bootm 200000:kernel-1 800000:ramdisk-2
bootm 200000#cfg-1
- boot "kernel-2" from a new uImage at 200000, with initrd "ramdisk-1" and FDT
"fdt-1", both stored in some other new uImage located at 800000:
bootm 200000:kernel-1 800000:ramdisk-1 800000:fdt-1
boot configuration "cfg-1" with extra "cfg-2" from a new uImage located
at 200000::
- boot kernel "kernel-2" with initrd "ramdisk-2", both stored in a new uImage
at address 200000, with a raw FDT blob stored at address 600000:
bootm 200000:kernel-2 200000:ramdisk-2 600000
bootm 200000#cfg-1#cfg-2
- boot kernel "kernel-2" from new uImage at 200000 with FDT "fdt-1" from the
same new uImage:
bootm 200000:kernel-2 - 200000:fdt-1
boot "kernel-1" from a new uImage at 200000 with initrd "ramdisk-2" found in
some other new uImage stored at address 800000::
bootm 200000:kernel-1 800000:ramdisk-2
boot "kernel-2" from a new uImage at 200000, with initrd "ramdisk-1" and FDT
"fdt-1", both stored in some other new uImage located at 800000::
bootm 200000:kernel-1 800000:ramdisk-1 800000:fdt-1
boot kernel "kernel-2" with initrd "ramdisk-2", both stored in a new uImage
at address 200000, with a raw FDT blob stored at address 600000::
bootm 200000:kernel-2 200000:ramdisk-2 600000
boot kernel "kernel-2" from new uImage at 200000 with FDT "fdt-1" from the
same new uImage::
bootm 200000:kernel-2 - 200000:fdt-1
Note on current image address
@ -171,31 +197,31 @@ Note on current image address
When bootm is called without arguments, the image at current image address is
booted. The current image address is the address set most recently by a load
command, etc, and is by default equal to CONFIG_SYS_LOAD_ADDR. For example, consider
the following commands:
the following commands::
tftp 200000 /tftpboot/kernel
bootm
Last command is equivalent to:
bootm 200000
tftp 200000 /tftpboot/kernel
bootm
Last command is equivalent to:
bootm 200000
In case of the new uImage argument syntax, the address portion of any argument
can be omitted. If <addr3> is omitted, then it is assumed that image at
<addr2> should be used. Similarly, when <addr2> is omitted, it is assumed that
image at <addr1> should be used. If <addr1> is omitted, it is assumed that the
current image address is to be used. For example, consider the following
commands:
commands::
tftp 200000 /tftpboot/uImage
bootm :kernel-1
Last command is equivalent to:
bootm 200000:kernel-1
tftp 200000 /tftpboot/uImage
bootm :kernel-1
Last command is equivalent to:
bootm 200000:kernel-1
tftp 200000 /tftpboot/uImage
bootm 400000:kernel-1 :ramdisk-1
Last command is equivalent to:
bootm 400000:kernel-1 400000:ramdisk-1
tftp 200000 /tftpboot/uImage
bootm 400000:kernel-1 :ramdisk-1
Last command is equivalent to:
bootm 400000:kernel-1 400000:ramdisk-1
tftp 200000 /tftpboot/uImage
bootm :kernel-1 400000:ramdisk-1 :fdt-1
Last command is equivalent to:
bootm 200000:kernel-1 400000:ramdisk-1 400000:fdt-1
tftp 200000 /tftpboot/uImage
bootm :kernel-1 400000:ramdisk-1 :fdt-1
Last command is equivalent to:
bootm 200000:kernel-1 400000:ramdisk-1 400000:fdt-1

1
doc/usage/fit/index.rst
View file

@ -17,3 +17,4 @@ doc/uImage.FIT
verified-boot
beaglebone_vboot
overlay-fdt-boot
command_syntax_extensions