13310c549SMarian BalakowiczCommand syntax extensions for the new uImage format 23310c549SMarian Balakowicz=================================================== 33310c549SMarian Balakowicz 43310c549SMarian BalakowiczAuthor: Bartlomiej Sieka <tur@semihalf.com> 53310c549SMarian Balakowicz 63310c549SMarian BalakowiczWith the introduction of the new uImage format, bootm command (and other 73310c549SMarian Balakowiczcommands as well) have to understand new syntax of the arguments. This is 83310c549SMarian Balakowicznecessary in order to specify objects contained in the new uImage, on which 93310c549SMarian Balakowiczbootm has to operate. This note attempts to first summarize bootm usage 103310c549SMarian Balakowiczscenarios, and then introduces new argument syntax. 113310c549SMarian Balakowicz 123310c549SMarian Balakowicz 133310c549SMarian Balakowiczbootm usage scenarios 143310c549SMarian Balakowicz--------------------- 153310c549SMarian Balakowicz 163310c549SMarian BalakowiczBelow is a summary of bootm usage scenarios, focused on booting a PowerPC 173310c549SMarian BalakowiczLinux kernel. The purpose of the following list is to document a complete list 183310c549SMarian Balakowiczof supported bootm usages. 193310c549SMarian Balakowicz 203310c549SMarian BalakowiczNote: U-Boot supports two methods of booting a PowerPC Linux kernel: old way, 213310c549SMarian Balakowiczi.e., without passing the Flattened Device Tree (FDT), and new way, where the 223310c549SMarian Balakowiczkernel is passed a pointer to the FDT. The boot method is indicated for each 233310c549SMarian Balakowiczscenario. 243310c549SMarian Balakowicz 253310c549SMarian Balakowicz 263310c549SMarian Balakowicz1. bootm boot image at the current address, equivalent to 2,3,8 273310c549SMarian Balakowicz 283310c549SMarian BalakowiczOld uImage: 293310c549SMarian Balakowicz2. bootm <addr1> /* single image at <addr1> */ 303310c549SMarian Balakowicz3. bootm <addr1> /* multi-image at <addr1> */ 313310c549SMarian Balakowicz4. bootm <addr1> - /* multi-image at <addr1> */ 323310c549SMarian Balakowicz5. bootm <addr1> <addr2> /* single image at <addr1> */ 333310c549SMarian Balakowicz6. bootm <addr1> <addr2> <addr3> /* single image at <addr1> */ 343310c549SMarian Balakowicz7. bootm <addr1> - <addr3> /* single image at <addr1> */ 353310c549SMarian Balakowicz 363310c549SMarian BalakowiczNew uImage: 373310c549SMarian Balakowicz8. bootm <addr1> 383310c549SMarian Balakowicz9. bootm [<addr1>]:<subimg1> 39*6b54e50bSPantelis Antoniou10. bootm [<addr1>]#<conf>[#<extra-conf[#...]] 403310c549SMarian Balakowicz11. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> 413310c549SMarian Balakowicz12. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> [<addr3>]:<subimg3> 423310c549SMarian Balakowicz13. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> <addr3> 433310c549SMarian Balakowicz14. bootm [<addr1>]:<subimg1> - [<addr3>]:<subimg3> 443310c549SMarian Balakowicz15. bootm [<addr1>]:<subimg1> - <addr3> 453310c549SMarian Balakowicz 463310c549SMarian Balakowicz 473310c549SMarian BalakowiczAd. 1. This is equivalent to cases 2,3,8, depending on the type of image at 483310c549SMarian Balakowiczthe current image address. 493310c549SMarian Balakowicz- boot method: see cases 2,3,8 503310c549SMarian Balakowicz 513310c549SMarian BalakowiczAd. 2. Boot kernel image located at <addr1>. 523310c549SMarian Balakowicz- boot method: non-FDT 533310c549SMarian Balakowicz 543310c549SMarian BalakowiczAd. 3. First and second components of the image at <addr1> are assumed to be a 553310c549SMarian Balakowiczkernel and a ramdisk, respectively. The kernel is booted with initrd loaded 563310c549SMarian Balakowiczwith the ramdisk from the image. 573310c549SMarian Balakowicz- boot method: depends on the number of components at <addr1>, and on whether 583310c549SMarian Balakowicz U-Boot is compiled with OF support: 593310c549SMarian Balakowicz 603310c549SMarian Balakowicz | 2 components | 3 components | 613310c549SMarian Balakowicz | (kernel, initrd) | (kernel, initrd, fdt) | 623310c549SMarian Balakowicz--------------------------------------------------------------------- 633310c549SMarian Balakowicz#ifdef CONFIG_OF_* | non-FDT | FDT | 643310c549SMarian Balakowicz#ifndef CONFIG_OF_* | non-FDT | non-FDT | 653310c549SMarian Balakowicz 663310c549SMarian BalakowiczAd. 4. Similar to case 3, but the kernel is booted without initrd. Second 673310c549SMarian Balakowiczcomponent of the multi-image is irrelevant (it can be a dummy, 1-byte file). 683310c549SMarian Balakowicz- boot method: see case 3 693310c549SMarian Balakowicz 703310c549SMarian BalakowiczAd. 5. Boot kernel image located at <addr1> with initrd loaded with ramdisk 713310c549SMarian Balakowiczfrom the image at <addr2>. 723310c549SMarian Balakowicz- boot method: non-FDT 733310c549SMarian Balakowicz 743310c549SMarian BalakowiczAd. 6. <addr1> is the address of a kernel image, <addr2> is the address of a 753310c549SMarian Balakowiczramdisk image, and <addr3> is the address of a FDT binary blob. Kernel is 763310c549SMarian Balakowiczbooted with initrd loaded with ramdisk from the image at <addr2>. 773310c549SMarian Balakowicz- boot method: FDT 783310c549SMarian Balakowicz 793310c549SMarian BalakowiczAd. 7. <addr1> is the address of a kernel image and <addr3> is the address of 803310c549SMarian Balakowicza FDT binary blob. Kernel is booted without initrd. 813310c549SMarian Balakowicz- boot method: FDT 823310c549SMarian Balakowicz 833310c549SMarian BalakowiczAd. 8. Image at <addr1> is assumed to contain a default configuration, which 843310c549SMarian Balakowiczis booted. 853310c549SMarian Balakowicz- boot method: FDT or non-FDT, depending on whether the default configuration 863310c549SMarian Balakowicz defines FDT 873310c549SMarian Balakowicz 883310c549SMarian BalakowiczAd. 9. Similar to case 2: boot kernel stored in <subimg1> from the image at 893310c549SMarian Balakowiczaddress <addr1>. 903310c549SMarian Balakowicz- boot method: non-FDT 913310c549SMarian Balakowicz 923310c549SMarian BalakowiczAd. 10. Boot configuration <conf> from the image at <addr1>. 933310c549SMarian Balakowicz- boot method: FDT or non-FDT, depending on whether the configuration given 943310c549SMarian Balakowicz defines FDT 953310c549SMarian Balakowicz 963310c549SMarian BalakowiczAd. 11. Equivalent to case 5: boot kernel stored in <subimg1> from the image 973310c549SMarian Balakowiczat <addr1> with initrd loaded with ramdisk <subimg2> from the image at 983310c549SMarian Balakowicz<addr2>. 993310c549SMarian Balakowicz- boot method: non-FDT 1003310c549SMarian Balakowicz 1013310c549SMarian BalakowiczAd. 12. Equivalent to case 6: boot kernel stored in <subimg1> from the image 1023310c549SMarian Balakowiczat <addr1> with initrd loaded with ramdisk <subimg2> from the image at 1033310c549SMarian Balakowicz<addr2>, and pass FDT blob <subimg3> from the image at <addr3>. 1043310c549SMarian Balakowicz- boot method: FDT 1053310c549SMarian Balakowicz 1063310c549SMarian BalakowiczAd. 13. Similar to case 12, the difference being that <addr3> is the address 1073310c549SMarian Balakowiczof FDT binary blob that is to be passed to the kernel. 1083310c549SMarian Balakowicz- boot method: FDT 1093310c549SMarian Balakowicz 1103310c549SMarian BalakowiczAd. 14. Equivalent to case 7: boot kernel stored in <subimg1> from the image 1113310c549SMarian Balakowiczat <addr1>, without initrd, and pass FDT blob <subimg3> from the image at 1123310c549SMarian Balakowicz<addr3>. 1133310c549SMarian Balakowicz- boot method: FDT 1143310c549SMarian Balakowicz 1153310c549SMarian BalakowiczAd. 15. Similar to case 14, the difference being that <addr3> is the address 1163310c549SMarian Balakowiczof the FDT binary blob that is to be passed to the kernel. 1173310c549SMarian Balakowicz- boot method: FDT 1183310c549SMarian Balakowicz 1193310c549SMarian Balakowicz 1203310c549SMarian BalakowiczNew uImage argument syntax 1213310c549SMarian Balakowicz-------------------------- 1223310c549SMarian Balakowicz 1233310c549SMarian BalakowiczNew uImage support introduces two new forms for bootm arguments, with the 1243310c549SMarian Balakowiczfollowing syntax: 1253310c549SMarian Balakowicz 1263310c549SMarian Balakowicz- new uImage sub-image specification 1273310c549SMarian Balakowicz<addr>:<sub-image unit_name> 1283310c549SMarian Balakowicz 1293310c549SMarian Balakowicz- new uImage configuration specification 1303310c549SMarian Balakowicz<addr>#<configuration unit_name> 1313310c549SMarian Balakowicz 132*6b54e50bSPantelis Antoniou- new uImage configuration specification with extra configuration components 133*6b54e50bSPantelis Antoniou<addr>#<configuration unit_name>[#<extra configuration unit_name>[#..]] 134*6b54e50bSPantelis Antoniou 135*6b54e50bSPantelis AntoniouThe extra configuration currently is supported only for additional device tree 136*6b54e50bSPantelis Antoniouoverlays to apply on the base device tree supplied by the first configuration 137*6b54e50bSPantelis Antoniouunit. 1383310c549SMarian Balakowicz 1393310c549SMarian BalakowiczExamples: 1403310c549SMarian Balakowicz 1413310c549SMarian Balakowicz- boot kernel "kernel@1" stored in a new uImage located at 200000: 1423310c549SMarian Balakowiczbootm 200000:kernel@1 1433310c549SMarian Balakowicz 1443310c549SMarian Balakowicz- boot configuration "cfg@1" from a new uImage located at 200000: 1453310c549SMarian Balakowiczbootm 200000#cfg@1 1463310c549SMarian Balakowicz 147*6b54e50bSPantelis Antoniou- boot configuration "cfg@1" with extra "cfg@2" from a new uImage located 148*6b54e50bSPantelis Antoniou at 200000: 149*6b54e50bSPantelis Antonioubootm 200000#cfg@1#cfg@2 150*6b54e50bSPantelis Antoniou 1513310c549SMarian Balakowicz- boot "kernel@1" from a new uImage at 200000 with initrd "ramdisk@2" found in 1523310c549SMarian Balakowicz some other new uImage stored at address 800000: 1533310c549SMarian Balakowiczbootm 200000:kernel@1 800000:ramdisk@2 1543310c549SMarian Balakowicz 1553310c549SMarian Balakowicz- boot "kernel@2" from a new uImage at 200000, with initrd "ramdisk@1" and FDT 1563310c549SMarian Balakowicz "fdt@1", both stored in some other new uImage located at 800000: 1573310c549SMarian Balakowiczbootm 200000:kernel@1 800000:ramdisk@1 800000:fdt@1 1583310c549SMarian Balakowicz 1593310c549SMarian Balakowicz- boot kernel "kernel@2" with initrd "ramdisk@2", both stored in a new uImage 1603310c549SMarian Balakowicz at address 200000, with a raw FDT blob stored at address 600000: 1613310c549SMarian Balakowiczbootm 200000:kernel@2 200000:ramdisk@2 600000 1623310c549SMarian Balakowicz 1633310c549SMarian Balakowicz- boot kernel "kernel@2" from new uImage at 200000 with FDT "fdt@1" from the 1643310c549SMarian Balakowicz same new uImage: 1653310c549SMarian Balakowiczbootm 200000:kernel@2 - 200000:fdt@1 1663310c549SMarian Balakowicz 1673310c549SMarian Balakowicz 1683310c549SMarian BalakowiczNote on current image address 1693310c549SMarian Balakowicz----------------------------- 1703310c549SMarian Balakowicz 1713310c549SMarian BalakowiczWhen bootm is called without arguments, the image at current image address is 1723310c549SMarian Balakowiczbooted. The current image address is the address set most recently by a load 1736d0f6bcfSJean-Christophe PLAGNIOL-VILLARDcommand, etc, and is by default equal to CONFIG_SYS_LOAD_ADDR. For example, consider 1743310c549SMarian Balakowiczthe following commands: 1753310c549SMarian Balakowicz 1763310c549SMarian Balakowicztftp 200000 /tftpboot/kernel 1773310c549SMarian Balakowiczbootm 1783310c549SMarian BalakowiczLast command is equivalent to: 1793310c549SMarian Balakowiczbootm 200000 1803310c549SMarian Balakowicz 1813310c549SMarian BalakowiczIn case of the new uImage argument syntax, the address portion of any argument 1823310c549SMarian Balakowiczcan be omitted. If <addr3> is omitted, then it is assumed that image at 18361ffc17aSMasahiro Yamada<addr2> should be used. Similarly, when <addr2> is omitted, it is assumed that 1843310c549SMarian Balakowiczimage at <addr1> should be used. If <addr1> is omitted, it is assumed that the 1853310c549SMarian Balakowiczcurrent image address is to be used. For example, consider the following 1863310c549SMarian Balakowiczcommands: 1873310c549SMarian Balakowicz 1883310c549SMarian Balakowicztftp 200000 /tftpboot/uImage 1893310c549SMarian Balakowiczbootm :kernel@1 1903310c549SMarian BalakowiczLast command is equivalent to: 1913310c549SMarian Balakowiczbootm 200000:kernel@1 1923310c549SMarian Balakowicz 1933310c549SMarian Balakowicztftp 200000 /tftpboot/uImage 1943310c549SMarian Balakowiczbootm 400000:kernel@1 :ramdisk@1 1953310c549SMarian BalakowiczLast command is equivalent to: 1963310c549SMarian Balakowiczbootm 400000:kernel@1 400000:ramdisk@1 1973310c549SMarian Balakowicz 1983310c549SMarian Balakowicztftp 200000 /tftpboot/uImage 1993310c549SMarian Balakowiczbootm :kernel@1 400000:ramdisk@1 :fdt@1 2003310c549SMarian BalakowiczLast command is equivalent to: 2013310c549SMarian Balakowiczbootm 200000:kernel@1 400000:ramdisk@1 400000:fdt@1 202