From d1b6b114432800a83aa12a2ff81d16e0d7a49e6f Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Fri, 23 Jun 2023 13:22:13 +0100 Subject: [PATCH] doc: Bring in the command-syntax extensions 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 --- .../cmd/bootm.rst} | 166 ++++++++++++--------- doc/usage/fit/index.rst | 1 + 2 files changed, 97 insertions(+), 70 deletions(-) rename doc/{uImage.FIT/command_syntax_extensions.txt => usage/cmd/bootm.rst} (57%) diff --git a/doc/uImage.FIT/command_syntax_extensions.txt b/doc/usage/cmd/bootm.rst similarity index 57% rename from doc/uImage.FIT/command_syntax_extensions.txt rename to doc/usage/cmd/bootm.rst index 6a99089..65b7891 100644 --- a/doc/uImage.FIT/command_syntax_extensions.txt +++ b/doc/usage/cmd/bootm.rst @@ -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 /* single image at */ -3. bootm /* multi-image at */ -4. bootm - /* multi-image at */ -5. bootm /* single image at */ -6. bootm /* single image at */ -7. bootm - /* single image at */ + 2. bootm /* single image at */ + 3. bootm /* multi-image at */ + 4. bootm - /* multi-image at */ + 5. bootm /* single image at */ + 6. bootm /* single image at */ + 7. bootm - /* single image at */ -New uImage: -8. bootm -9. bootm []: -10. bootm []#[#]: []: -12. bootm []: []: []: -13. bootm []: []: -14. bootm []: - []: -15. bootm []: - +New uImage:: + 8. bootm + 9. bootm []: + 10. bootm []#[#]: []: + 12. bootm []: []: []: + 13. bootm []: []: + 14. bootm []: - []: + 15. bootm []: - 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 . + - boot method: non-FDT Ad. 3. First and second components of the image at 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 , 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 with initrd loaded with ramdisk from the image at . + - boot method: non-FDT Ad. 6. is the address of a kernel image, is the address of a ramdisk image, and is the address of a FDT binary blob. Kernel is booted with initrd loaded with ramdisk from the image at . + - boot method: FDT Ad. 7. is the address of a kernel image and is the address of a FDT binary blob. Kernel is booted without initrd. + - boot method: FDT Ad. 8. Image at 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 from the image at address . + - boot method: non-FDT Ad. 10. Boot configuration from the image at . + - boot method: FDT or non-FDT, depending on whether the configuration given defines FDT Ad. 11. Equivalent to case 5: boot kernel stored in from the image at with initrd loaded with ramdisk from the image at . + - boot method: non-FDT Ad. 12. Equivalent to case 6: boot kernel stored in from the image at with initrd loaded with ramdisk from the image at , and pass FDT blob from the image at . + - boot method: FDT Ad. 13. Similar to case 12, the difference being that 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 from the image at , without initrd, and pass FDT blob from the image at . + - boot method: FDT Ad. 15. Similar to case 14, the difference being that 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 -: +new uImage sub-image specification + : -- new uImage configuration specification -# +new uImage configuration specification + # -- new uImage configuration specification with extra configuration components -#[#[#..]] +new uImage configuration specification with extra configuration components + #[#[#..]] 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 is omitted, then it is assumed that image at should be used. Similarly, when is omitted, it is assumed that image at should be used. If 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 bd25bd3..92998e7 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 -- 2.7.4