[PATCH 9/9] doc: Bring in the command-syntax extensions
Heinrich Schuchardt
xypron.glpk at gmx.de
Fri Jun 23 09:51:48 CEST 2023
On 6/22/23 22:21, Simon Glass wrote:
> Bring this file into the documentation.
>
> Signed-off-by: Simon Glass <sjg at chromium.org>
> ---
>
> .../fit/command_syntax_extensions.rst} | 166 ++++++++++--------
> doc/usage/fit/index.rst | 1 +
> 2 files changed, 97 insertions(+), 70 deletions(-)
> rename doc/{uImage.FIT/command_syntax_extensions.txt => usage/fit/command_syntax_extensions.rst} (57%)
>
> diff --git a/doc/uImage.FIT/command_syntax_extensions.txt b/doc/usage/fit/command_syntax_extensions.rst
> similarity index 57%
> rename from doc/uImage.FIT/command_syntax_extensions.txt
> rename to doc/usage/fit/command_syntax_extensions.rst
> index 6a99089ab557..65b7891c8a69 100644
> --- a/doc/uImage.FIT/command_syntax_extensions.txt
> +++ b/doc/usage/fit/command_syntax_extensions.rst
This is the wrong place for documenting a command.
Please, create doc/usage/cmd/bootm.rst instead adhering to the style of
the other man-pages.
Best regards
Heinrich
> @@ -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:
> + 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 |
> + ======================================================================
> + | 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::
> +
> + bootm 200000:kernel-1
> +
> +boot configuration "cfg-1" from a new uImage located at 200000::
> +
> + bootm 200000#cfg-1
> +
> +boot configuration "cfg-1" with extra "cfg-2" from a new uImage located
> +at 200000::
> +
> + bootm 200000#cfg-1#cfg-2
> +
> +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 configuration "cfg-1" from a new uImage located at 200000:
> -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::
>
> -- boot configuration "cfg-1" with extra "cfg-2" from a new uImage located
> - at 200000:
> -bootm 200000#cfg-1#cfg-2
> + bootm 200000:kernel-1 800000:ramdisk-1 800000: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 "kernel-2" with initrd "ramdisk-2", both stored in a new uImage
> +at address 200000, with a raw FDT blob stored at address 600000::
>
> -- 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
> + bootm 200000:kernel-2 200000:ramdisk-2 600000
>
> -- 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::
>
> -- 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
> + 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:
> -
> -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 :kernel-1 400000:ramdisk-1 :fdt-1
> -Last command is equivalent to:
> -bootm 200000:kernel-1 400000:ramdisk-1 400000:fdt-1
> +commands::
> +
> + 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 :kernel-1 400000:ramdisk-1 :fdt-1
> + Last command is equivalent to:
> + bootm 200000:kernel-1 400000:ramdisk-1 400000:fdt-1
> diff --git a/doc/usage/fit/index.rst b/doc/usage/fit/index.rst
> index bd25bd30b284..92998e724c28 100644
> --- a/doc/usage/fit/index.rst
> +++ b/doc/usage/fit/index.rst
> @@ -17,3 +17,4 @@ doc/uImage.FIT
> verified-boot
> beaglebone_vboot
> overlay-fdt-boot
> + command_syntax_extensions
More information about the U-Boot
mailing list