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 <sjg@chromium.org>

3 files changed, 201 insertions, 128 deletions

diff --git a/doc/usage/cmd/bootm.rst b/doc/usage/cmd/bootm.rst
index 65b7891..a7e5f6c 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 <tur@semihalf.com>
+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]#<conf>[#extra-conf]
+    bootm [[fit_addr]:<os_subimg>] [[<fit_addr2>]:<rd_subimg2>] [[<fit_addr3>]:<fdt_subimg>]
 
-bootm usage scenarios
----------------------
+    bootm <addr1> [[<addr2> [<addr3>]]    # 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 <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> */
+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 <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>
+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 <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
+
+
+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 <addr1>.
+::
+
+    2.  bootm <addr1>            /* single image at <addr1> */
 
-- boot method: non-FDT
+Boot kernel image located at <addr1>.
 
-Ad. 3. First and second components of the image at <addr1> are assumed to be a
+Boot method: non-FDT
+
+::
+
+    3.  bootm <addr1>            /* multi-image at <addr1>  */
+
+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::
+Boot method: depends on the number of components at <addr1>, 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 <addr1> -            /* multi-image at <addr1>  */
 
-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 <addr1> with initrd loaded with ramdisk
+::
+
+    5.  bootm <addr1> <addr2>        /* single image at <addr1> */
+
+Boot kernel image located at <addr1> with initrd loaded with ramdisk
 from the image at <addr2>.
 
-- boot method: non-FDT
+Boot method: non-FDT
+
+::
 
-Ad. 6. <addr1> is the address of a kernel image, <addr2> is the address of a
+    6.  bootm <addr1> <addr2> <addr3>   /* single image at <addr1> */
+
+<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
+Boot method: FDT
+
+::
+
+    7.  bootm <addr1> -      <addr3>   /* single image at <addr1> */
 
-Ad. 7. <addr1> is the address of a kernel image and <addr3> is the address of
+<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
+Boot method: FDT
+
+FIT syntax
+~~~~~~~~~~
+
+::
+
+    8.  bootm <addr1>
 
-Ad. 8. Image at <addr1> is assumed to contain a default configuration, which
+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
+Boot method: FDT or non-FDT, depending on whether the default configuration
+defines FDT
+
+::
+
+    9.  bootm [<addr1>]:<subimg1>
 
-Ad. 9. Similar to case 2: boot kernel stored in <subimg1> from the image at
+Similar to case 2: boot kernel stored in <subimg1> from the image at
 address <addr1>.
 
-- boot method: non-FDT
+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
+    10. bootm [<addr1>]#<conf>[#<extra-conf[#...]]
+
+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
+    11. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2>
+
+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
+Boot method: non-FDT
 
-Ad. 12. Equivalent to case 6: boot kernel stored in <subimg1> from the image
+::
+
+    12. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> [<addr3>]:<subimg3>
+
+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
+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
+    13. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> <addr3>
 
-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>.
+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
+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
+    14. bootm [<addr1>]:<subimg1> -              [<addr3>]:<subimg3>
 
+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>.
 
-New uImage argument syntax
---------------------------
+Boot method: FDT
 
-New uImage support introduces two new forms for bootm arguments, with the
-following syntax:
+    15. bootm [<addr1>]:<subimg1> -              <addr3>
 
-new uImage sub-image specification
-    <addr>:<sub-image unit_name>
+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.
 
-new uImage configuration specification
-    <addr>#<configuration unit_name>
+Boot method: FDT
 
-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
-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 <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
+.. sectionauthor:: Bartlomiej Sieka <tur@semihalf.com>
+.. sectionauthor:: Simon Glass <sjg@chromium.org>
diff --git a/doc/usage/fit/index.rst b/doc/usage/fit/index.rst
index 92998e7..bd25bd3 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 04c959a..29ae8a1 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