1Command syntax extensions for the new uImage format 2=================================================== 3 4Author: Bartlomiej Sieka <tur@semihalf.com> 5 6With the introduction of the new uImage format, bootm command (and other 7commands as well) have to understand new syntax of the arguments. This is 8necessary in order to specify objects contained in the new uImage, on which 9bootm has to operate. This note attempts to first summarize bootm usage 10scenarios, and then introduces new argument syntax. 11 12 13bootm usage scenarios 14--------------------- 15 16Below is a summary of bootm usage scenarios, focused on booting a PowerPC 17Linux kernel. The purpose of the following list is to document a complete list 18of supported bootm usages. 19 20Note: U-Boot supports two methods of booting a PowerPC Linux kernel: old way, 21i.e., without passing the Flattened Device Tree (FDT), and new way, where the 22kernel is passed a pointer to the FDT. The boot method is indicated for each 23scenario. 24 25 261. bootm boot image at the current address, equivalent to 2,3,8 27 28Old uImage: 292. bootm <addr1> /* single image at <addr1> */ 303. bootm <addr1> /* multi-image at <addr1> */ 314. bootm <addr1> - /* multi-image at <addr1> */ 325. bootm <addr1> <addr2> /* single image at <addr1> */ 336. bootm <addr1> <addr2> <addr3> /* single image at <addr1> */ 347. bootm <addr1> - <addr3> /* single image at <addr1> */ 35 36New uImage: 378. bootm <addr1> 389. bootm [<addr1>]:<subimg1> 3910. bootm [<addr1>]#<conf>[#<extra-conf[#...]] 4011. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> 4112. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> [<addr3>]:<subimg3> 4213. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> <addr3> 4314. bootm [<addr1>]:<subimg1> - [<addr3>]:<subimg3> 4415. bootm [<addr1>]:<subimg1> - <addr3> 45 46 47Ad. 1. This is equivalent to cases 2,3,8, depending on the type of image at 48the current image address. 49- boot method: see cases 2,3,8 50 51Ad. 2. Boot kernel image located at <addr1>. 52- boot method: non-FDT 53 54Ad. 3. First and second components of the image at <addr1> are assumed to be a 55kernel and a ramdisk, respectively. The kernel is booted with initrd loaded 56with 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 66Ad. 4. Similar to case 3, but the kernel is booted without initrd. Second 67component of the multi-image is irrelevant (it can be a dummy, 1-byte file). 68- boot method: see case 3 69 70Ad. 5. Boot kernel image located at <addr1> with initrd loaded with ramdisk 71from the image at <addr2>. 72- boot method: non-FDT 73 74Ad. 6. <addr1> is the address of a kernel image, <addr2> is the address of a 75ramdisk image, and <addr3> is the address of a FDT binary blob. Kernel is 76booted with initrd loaded with ramdisk from the image at <addr2>. 77- boot method: FDT 78 79Ad. 7. <addr1> is the address of a kernel image and <addr3> is the address of 80a FDT binary blob. Kernel is booted without initrd. 81- boot method: FDT 82 83Ad. 8. Image at <addr1> is assumed to contain a default configuration, which 84is booted. 85- boot method: FDT or non-FDT, depending on whether the default configuration 86 defines FDT 87 88Ad. 9. Similar to case 2: boot kernel stored in <subimg1> from the image at 89address <addr1>. 90- boot method: non-FDT 91 92Ad. 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 96Ad. 11. Equivalent to case 5: boot kernel stored in <subimg1> from the image 97at <addr1> with initrd loaded with ramdisk <subimg2> from the image at 98<addr2>. 99- boot method: non-FDT 100 101Ad. 12. Equivalent to case 6: boot kernel stored in <subimg1> from the image 102at <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 106Ad. 13. Similar to case 12, the difference being that <addr3> is the address 107of FDT binary blob that is to be passed to the kernel. 108- boot method: FDT 109 110Ad. 14. Equivalent to case 7: boot kernel stored in <subimg1> from the image 111at <addr1>, without initrd, and pass FDT blob <subimg3> from the image at 112<addr3>. 113- boot method: FDT 114 115Ad. 15. Similar to case 14, the difference being that <addr3> is the address 116of the FDT binary blob that is to be passed to the kernel. 117- boot method: FDT 118 119 120New uImage argument syntax 121-------------------------- 122 123New uImage support introduces two new forms for bootm arguments, with the 124following 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 135The extra configuration currently is supported only for additional device tree 136overlays to apply on the base device tree supplied by the first configuration 137unit. 138 139Examples: 140 141- boot kernel "kernel-1" stored in a new uImage located at 200000: 142bootm 200000:kernel-1 143 144- boot configuration "cfg-1" from a new uImage located at 200000: 145bootm 200000#cfg-1 146 147- boot configuration "cfg-1" with extra "cfg-2" from a new uImage located 148 at 200000: 149bootm 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: 153bootm 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: 157bootm 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: 161bootm 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: 165bootm 200000:kernel-2 - 200000:fdt-1 166 167 168Note on current image address 169----------------------------- 170 171When bootm is called without arguments, the image at current image address is 172booted. The current image address is the address set most recently by a load 173command, etc, and is by default equal to CONFIG_SYS_LOAD_ADDR. For example, consider 174the following commands: 175 176tftp 200000 /tftpboot/kernel 177bootm 178Last command is equivalent to: 179bootm 200000 180 181In case of the new uImage argument syntax, the address portion of any argument 182can 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 184image at <addr1> should be used. If <addr1> is omitted, it is assumed that the 185current image address is to be used. For example, consider the following 186commands: 187 188tftp 200000 /tftpboot/uImage 189bootm :kernel-1 190Last command is equivalent to: 191bootm 200000:kernel-1 192 193tftp 200000 /tftpboot/uImage 194bootm 400000:kernel-1 :ramdisk-1 195Last command is equivalent to: 196bootm 400000:kernel-1 400000:ramdisk-1 197 198tftp 200000 /tftpboot/uImage 199bootm :kernel-1 400000:ramdisk-1 :fdt-1 200Last command is equivalent to: 201bootm 200000:kernel-1 400000:ramdisk-1 400000:fdt-1 202