command_syntax_extensions.txt 7.2 KB

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