doc/uImage.FIT/command_syntax_extensions.txt

   1 Command syntax extensions for the new uImage format
   2 ===================================================
   3
   4 Author: Bartlomiej Sieka <tur@semihalf.com>
   5
   6 With the introduction of the new uImage format, bootm command (and other
   7 commands as well) have to understand new syntax of the arguments. This is
   8 necessary in order to specify objects contained in the new uImage, on which
   9 bootm has to operate. This note attempts to first summarize bootm usage
  10 scenarios, and then introduces new argument syntax.
  11
  12
  13 bootm usage scenarios
  14 ---------------------
  15
  16 Below is a summary of bootm usage scenarios, focused on booting a PowerPC
  17 Linux kernel. The purpose of the following list is to document a complete list
  18 of supported bootm usages.
  19
  20 Note: U-Boot supports two methods of booting a PowerPC Linux kernel: old way,
  21 i.e., without passing the Flattened Device Tree (FDT), and new way, where the
  22 kernel is passed a pointer to the FDT. The boot method is indicated for each
  23 scenario.
  24
  25
  26 1.  bootm               boot image at the current address, equivalent to 2,3,8
  27
  28 Old uImage:
  29 2.  bootm <addr1>                   /* single image at <addr1> */
  30 3.  bootm <addr1>                   /* multi-image at <addr1>  */
  31 4.  bootm <addr1> -                 /* multi-image at <addr1>  */
  32 5.  bootm <addr1> <addr2>           /* single image at <addr1> */
  33 6.  bootm <addr1> <addr2> <addr3>   /* single image at <addr1> */
  34 7.  bootm <addr1> -       <addr3>   /* single image at <addr1> */
  35
  36 New uImage:
  37 8.  bootm <addr1>
  38 9.  bootm [<addr1>]:<subimg1>
  39 10. bootm [<addr1>]#<conf>[#<extra-conf[#...]]
  40 11. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2>
  41 12. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> [<addr3>]:<subimg3>
  42 13. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> <addr3>
  43 14. bootm [<addr1>]:<subimg1> -                   [<addr3>]:<subimg3>
  44 15. bootm [<addr1>]:<subimg1> -                   <addr3>
  45
  46
  47 Ad. 1. This is equivalent to cases 2,3,8, depending on the type of image at
  48 the current image address.
  49 - boot method: see cases 2,3,8
  50
  51 Ad. 2. Boot kernel image located at <addr1>.
  52 - boot method: non-FDT
  53
  54 Ad. 3. First and second components of the image at <addr1> are assumed to be a
  55 kernel and a ramdisk, respectively. The kernel is booted with initrd loaded
  56 with the ramdisk from the image.
  57 - boot method: depends on the number of components at <addr1>, and on whether
  58   U-Boot is compiled with OF support:
  59
  60                     |          2 components |          3 components |
  61                     |      (kernel, initrd) | (kernel, initrd, fdt) |
  62 ---------------------------------------------------------------------
  63 #ifdef CONFIG_OF_*  |               non-FDT |                   FDT |
  64 #ifndef CONFIG_OF_* |               non-FDT |               non-FDT |
  65
  66 Ad. 4. Similar to case 3, but the kernel is booted without initrd.  Second
  67 component of the multi-image is irrelevant (it can be a dummy, 1-byte file).
  68 - boot method: see case 3
  69
  70 Ad. 5. Boot kernel image located at <addr1> with initrd loaded with ramdisk
  71 from the image at <addr2>.
  72 - boot method: non-FDT
  73
  74 Ad. 6. <addr1> is the address of a kernel image, <addr2> is the address of a
  75 ramdisk image, and <addr3> is the address of a FDT binary blob.  Kernel is
  76 booted with initrd loaded with ramdisk from the image at <addr2>.
  77 - boot method: FDT
  78
  79 Ad. 7. <addr1> is the address of a kernel image and <addr3> is the address of
  80 a FDT binary blob. Kernel is booted without initrd.
  81 - boot method: FDT
  82
  83 Ad. 8. Image at <addr1> is assumed to contain a default configuration, which
  84 is booted.
  85 - boot method: FDT or non-FDT, depending on whether the default configuration
  86   defines FDT
  87
  88 Ad. 9. Similar to case 2: boot kernel stored in <subimg1> from the image at
  89 address <addr1>.
  90 - boot method: non-FDT
  91
  92 Ad. 10. Boot configuration <conf> from the image at <addr1>.
  93 - boot method: FDT or non-FDT, depending on whether the configuration given
  94   defines FDT
  95
  96 Ad. 11. Equivalent to case 5: boot kernel stored in <subimg1> from the image
  97 at <addr1> with initrd loaded with ramdisk <subimg2> from the image at
  98 <addr2>.
  99 - boot method: non-FDT
 100
 101 Ad. 12. Equivalent to case 6: boot kernel stored in <subimg1> from the image
 102 at <addr1> with initrd loaded with ramdisk <subimg2> from the image at
 103 <addr2>, and pass FDT blob <subimg3> from the image at <addr3>.
 104 - boot method: FDT
 105
 106 Ad. 13. Similar to case 12, the difference being that <addr3> is the address
 107 of FDT binary blob that is to be passed to the kernel.
 108 - boot method: FDT
 109
 110 Ad. 14. Equivalent to case 7: boot kernel stored in <subimg1> from the image
 111 at <addr1>, without initrd, and pass FDT blob <subimg3> from the image at
 112 <addr3>.
 113 - boot method: FDT
 114
 115 Ad. 15. Similar to case 14, the difference being that <addr3> is the address
 116 of the FDT binary blob that is to be passed to the kernel.
 117 - boot method: FDT
 118
 119
 120 New uImage argument syntax
 121 --------------------------
 122
 123 New uImage support introduces two new forms for bootm arguments, with the
 124 following syntax:
 125
 126 - new uImage sub-image specification
 127 <addr>:<sub-image unit_name>
 128
 129 - new uImage configuration specification
 130 <addr>#<configuration unit_name>
 131
 132 - new uImage configuration specification with extra configuration components
 133 <addr>#<configuration unit_name>[#<extra configuration unit_name>[#..]]
 134
 135 The extra configuration currently is supported only for additional device tree
 136 overlays to apply on the base device tree supplied by the first configuration
 137 unit.
 138
 139 Examples:
 140
 141 - boot kernel "kernel-1" stored in a new uImage located at 200000:
 142 bootm 200000:kernel-1
 143
 144 - boot configuration "cfg-1" from a new uImage located at 200000:
 145 bootm 200000#cfg-1
 146
 147 - boot configuration "cfg-1" with extra "cfg-2" from a new uImage located
 148   at 200000:
 149 bootm 200000#cfg-1#cfg-2
 150
 151 - boot "kernel-1" from a new uImage at 200000 with initrd "ramdisk-2" found in
 152   some other new uImage stored at address 800000:
 153 bootm 200000:kernel-1 800000:ramdisk-2
 154
 155 - boot "kernel-2" from a new uImage at 200000, with initrd "ramdisk-1" and FDT
 156   "fdt-1", both stored in some other new uImage located at 800000:
 157 bootm 200000:kernel-1 800000:ramdisk-1 800000:fdt-1
 158
 159 - boot kernel "kernel-2" with initrd "ramdisk-2", both stored in a new uImage
 160   at address 200000, with a raw FDT blob stored at address 600000:
 161 bootm 200000:kernel-2 200000:ramdisk-2 600000
 162
 163 - boot kernel "kernel-2" from new uImage at 200000 with FDT "fdt-1" from the
 164   same new uImage:
 165 bootm 200000:kernel-2 - 200000:fdt-1
 166
 167
 168 Note on current image address
 169 -----------------------------
 170
 171 When bootm is called without arguments, the image at current image address is
 172 booted. The current image address is the address set most recently by a load
 173 command, etc, and is by default equal to CONFIG_SYS_LOAD_ADDR. For example, consider
 174 the following commands:
 175
 176 tftp 200000 /tftpboot/kernel
 177 bootm
 178 Last command is equivalent to:
 179 bootm 200000
 180
 181 In case of the new uImage argument syntax, the address portion of any argument
 182 can be omitted. If <addr3> is omitted, then it is assumed that image at
 183 <addr2> should be used. Similarly, when <addr2> is omitted, it is assumed that
 184 image at <addr1> should be used. If <addr1> is omitted, it is assumed that the
 185 current image address is to be used. For example, consider the following
 186 commands:
 187
 188 tftp 200000 /tftpboot/uImage
 189 bootm :kernel-1
 190 Last command is equivalent to:
 191 bootm 200000:kernel-1
 192
 193 tftp 200000 /tftpboot/uImage
 194 bootm 400000:kernel-1 :ramdisk-1
 195 Last command is equivalent to:
 196 bootm 400000:kernel-1 400000:ramdisk-1
 197
 198 tftp 200000 /tftpboot/uImage
 199 bootm :kernel-1 400000:ramdisk-1 :fdt-1
 200 Last command is equivalent to:
 201 bootm 200000:kernel-1 400000:ramdisk-1 400000:fdt-1