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

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 6a99089ab5575d08284257f08830cb753377463d..65b7891c8a69ad8eb1ad66efe71b6af02ace38d0 100644 (file)
--- 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 <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 bd25bd30b2840390e240c1ed4e9ba3982f6af639..92998e724c28f2221762a9d7a8b82040eefbb858 100644 (file)
--- 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