From d1b6b114432800a83aa12a2ff81d16e0d7a49e6f Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Fri, 23 Jun 2023 13:22:13 +0100 Subject: 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 --- doc/uImage.FIT/command_syntax_extensions.txt | 201 ------------------------ doc/usage/cmd/bootm.rst | 227 +++++++++++++++++++++++++++ doc/usage/fit/index.rst | 1 + 3 files changed, 228 insertions(+), 201 deletions(-) delete mode 100644 doc/uImage.FIT/command_syntax_extensions.txt create mode 100644 doc/usage/cmd/bootm.rst diff --git a/doc/uImage.FIT/command_syntax_extensions.txt b/doc/uImage.FIT/command_syntax_extensions.txt deleted file mode 100644 index 6a99089ab55..00000000000 --- a/doc/uImage.FIT/command_syntax_extensions.txt +++ /dev/null @@ -1,201 +0,0 @@ -Command syntax extensions for the new uImage format -=================================================== - -Author: Bartlomiej Sieka - -With the introduction of the new uImage format, bootm command (and other -commands as well) have to understand new syntax of the arguments. This is -necessary in order to specify objects contained in the new uImage, on which -bootm has to operate. This note attempts to first summarize bootm usage -scenarios, and then introduces new argument syntax. - - -bootm usage scenarios ---------------------- - -Below is a summary of bootm usage scenarios, focused on booting a PowerPC -Linux kernel. The purpose of the following list is to document a complete list -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. - - -1. bootm boot image at the current address, equivalent to 2,3,8 - -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 */ - -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: - - | 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 - - -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 configuration specification -# - -- 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 -unit. - -Examples: - -- 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 "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 ------------------------------ - -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: - -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 diff --git a/doc/usage/cmd/bootm.rst b/doc/usage/cmd/bootm.rst new file mode 100644 index 00000000000..65b7891c8a6 --- /dev/null +++ b/doc/usage/cmd/bootm.rst @@ -0,0 +1,227 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Command syntax extensions for the new uImage format +=================================================== + +Author: Bartlomiej Sieka + +With the introduction of the new uImage format, bootm command (and other +commands as well) have to understand new syntax of the arguments. This is +necessary in order to specify objects contained in the new uImage, on which +bootm has to operate. This note attempts to first summarize bootm usage +scenarios, and then introduces new argument syntax. + + +bootm usage scenarios +--------------------- + +Below is a summary of bootm usage scenarios, focused on booting a PowerPC +Linux kernel. The purpose of the following list is to document a complete list +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:: + + 1. bootm boot image at the current address, equivalent to 2,3,8 + +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 */ + +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:: + + ====================================================================== + | 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 + + +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 configuration specification + # + +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 +unit. + +Examples: + +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 "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 +----------------------------- + +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:: + + 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 diff --git a/doc/usage/fit/index.rst b/doc/usage/fit/index.rst index bd25bd30b28..92998e724c2 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 -- cgit v1.2.3