From 35ed599f430bcba2fd2bc14e52e6cb450cd9a10c Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Fri, 23 Jun 2023 13:22:14 +0100 Subject: [PATCH] doc: Improve documentation for the bootm command Reformat and rewrite the documentation for this command. This is a complicated command, so further improvements are welcome. Signed-off-by: Simon Glass --- doc/usage/cmd/bootm.rst | 327 ++++++++++++++++++++++++---------------- doc/usage/fit/index.rst | 1 - doc/usage/index.rst | 1 + 3 files changed, 201 insertions(+), 128 deletions(-) diff --git a/doc/usage/cmd/bootm.rst b/doc/usage/cmd/bootm.rst index 65b7891c8a..a7e5f6ce69 100644 --- a/doc/usage/cmd/bootm.rst +++ b/doc/usage/cmd/bootm.rst @@ -1,161 +1,267 @@ .. SPDX-License-Identifier: GPL-2.0+ -Command syntax extensions for the new uImage format -=================================================== +bootm command +============= -Author: Bartlomiej Sieka +Synopsis +-------- -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 [fit_addr]#[#extra-conf] + bootm [[fit_addr]:] [[]:] [[]:] -bootm usage scenarios ---------------------- + bootm [[ []] # Legacy boot -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. +Description +----------- -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:: +The *bootm* command is used to boot an Operating System. It has a large number +of options depending on what needs to be booted. - 1. bootm boot image at the current address, equivalent to 2,3,8 +Note that the second form supports the first and/or second arguments to be +omitted by using a hyphen '-' instead. -Old uImage:: +fit_addr / fit_addr2 / fit_addr3 + address of FIT to boot, defaults to CONFIG_SYS_LOAD_ADDR. See notes below. - 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 */ +conf + configuration unit to boot (must be preceded by hash '#') -New uImage:: +extra-conf + extra configuration to boot. This is supported only for additional + devicetree overlays to apply on the base device tree supplied by the first + configuration unit. - 8. bootm - 9. bootm []: - 10. bootm []#[#]: []: - 12. bootm []: []: []: - 13. bootm []: []: - 14. bootm []: - []: - 15. bootm []: - +os_subimg + OS sub-image to boot (must be preceded by colon ':') + +rd_subimg + ramdisk sub-image to boot. Use a hyphen '-' if there is no ramdisk but an + FDT is needed. + +fdt_subimg + FDT sub-image to boot + +See below for legacy boot. Booting using :doc:`../fit/index` is recommended. + +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 + +As shown above, with FIT 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 + + +Legacy boot +----------- + +U-Boot supports a legacy image format, enabled by `CONFIG_LEGACY_IMAGE_FORMAT`. +This is not recommended as it is quite limited and insecure. Use +:doc:`../fit/index` instead. It is documented here for old boards which still +use it. + +Arguments are: + +addr1 + address of legacy image to boot. If the image includes a second component + (ramdisk) it is used as well, unless the second parameter is hyphen '-'. + +addr2 + address of legacy image to use as ramdisk -Ad. 1. This is equivalent to cases 2,3,8, depending on the type of image at +addr3 + address of legacy image to use as FDT + + +Example syntax +-------------- + +This section provides various examples of possible usage:: + + 1. bootm /* boot image at the current address, equivalent to 2,3,8 */ + +This is equivalent to cases 2, 3 or 8, depending on the type of image at the current image address. -- boot method: see cases 2,3,8 +Boot method: see cases 2,3,8 + +Legacy uImage syntax +~~~~~~~~~~~~~~~~~~~~ -Ad. 2. Boot kernel image located at . +:: + + 2. bootm /* single image at */ -- boot method: non-FDT +Boot kernel image located at . -Ad. 3. First and second components of the image at are assumed to be a +Boot method: non-FDT + +:: + + 3. bootm /* multi-image at */ + +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:: +Boot method: depends on the number of components at , and on whether +U-Boot is compiled with OF support, which it should be. - ====================================================================== - | 2 components | 3 components| - | (kernel, initrd) | (kernel, initrd, fdt) | - ====================================================================== - #ifdef CONFIG_OF_* | non-FDT | FDT | - #ifndef CONFIG_OF_* | non-FDT | non-FDT | - ====================================================================== + ==================== ======================== ======================== + Configuration 2 components 3 components + (kernel, initrd) (kernel, initrd, fdt) + ==================== ======================== ======================== + #ifdef CONFIG_OF_* non-FDT FDT + #ifndef CONFIG_OF_* non-FDT non-FDT + ==================== ======================== ======================== + +:: + + 4. bootm - /* multi-image at */ -Ad. 4. Similar to case 3, but the kernel is booted without initrd. Second +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 +Boot method: see case 3 -Ad. 5. Boot kernel image located at with initrd loaded with ramdisk +:: + + 5. bootm /* single image at */ + +Boot kernel image located at with initrd loaded with ramdisk from the image at . -- boot method: non-FDT +Boot method: non-FDT + +:: -Ad. 6. is the address of a kernel image, is the address of a + 6. bootm /* single image at */ + + 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 +Boot method: FDT + +:: + + 7. bootm - /* single image at */ -Ad. 7. is the address of a kernel image and is the address of + is the address of a kernel image and is the address of a FDT binary blob. Kernel is booted without initrd. -- boot method: FDT +Boot method: FDT + +FIT syntax +~~~~~~~~~~ + +:: + + 8. bootm -Ad. 8. Image at is assumed to contain a default configuration, which +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 +Boot method: FDT or non-FDT, depending on whether the default configuration +defines FDT + +:: + + 9. bootm []: -Ad. 9. Similar to case 2: boot kernel stored in from the image at +Similar to case 2: boot kernel stored in from the image at address . -- boot method: non-FDT +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 + 10. bootm []#[# 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 + 11. bootm []: []: + +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 +Boot method: non-FDT -Ad. 12. Equivalent to case 6: boot kernel stored in from the image +:: + + 12. bootm []: []: []: + +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 +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 + 13. bootm []: []: -Ad. 14. Equivalent to case 7: boot kernel stored in from the image -at , without initrd, and pass FDT blob from the image at -. +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 +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 + 14. bootm []: - []: +Equivalent to case 7: boot kernel stored in from the image +at , without initrd, and pass FDT blob from the image at +. -New uImage argument syntax --------------------------- +Boot method: FDT -New uImage support introduces two new forms for bootm arguments, with the -following syntax: + 15. bootm []: - -new uImage sub-image specification - : +Similar to case 14, the difference being that is the address +of the FDT binary blob that is to be passed to the kernel. -new uImage configuration specification - # +Boot method: FDT -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: +Example +------- boot kernel "kernel-1" stored in a new uImage located at 200000:: @@ -190,38 +296,5 @@ 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 +.. sectionauthor:: Bartlomiej Sieka +.. sectionauthor:: Simon Glass diff --git a/doc/usage/fit/index.rst b/doc/usage/fit/index.rst index 92998e724c..bd25bd30b2 100644 --- a/doc/usage/fit/index.rst +++ b/doc/usage/fit/index.rst @@ -17,4 +17,3 @@ doc/uImage.FIT verified-boot beaglebone_vboot overlay-fdt-boot - command_syntax_extensions diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 04c959af93..29ae8a176e 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -32,6 +32,7 @@ Shell commands cmd/bootefi cmd/bootflow cmd/booti + cmd/bootm cmd/bootmenu cmd/bootmeth cmd/button -- 2.39.5