howto.txt 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297
  1. How to use images in the new image format
  2. =========================================
  3. Author: Bartlomiej Sieka <tur@semihalf.com>
  4. Overview
  5. --------
  6. The new uImage format allows more flexibility in handling images of various
  7. types (kernel, ramdisk, etc.), it also enhances integrity protection of images
  8. with sha1 and md5 checksums.
  9. Two auxiliary tools are needed on the development host system in order to
  10. create an uImage in the new format: mkimage and dtc, although only one
  11. (mkimage) is invoked directly. dtc is called from within mkimage and operates
  12. behind the scenes, but needs to be present in the $PATH nevertheless. It is
  13. important that the dtc used has support for binary includes -- refer to
  14. www.jdl.com for its latest version. mkimage (together with dtc) takes as input
  15. an image source file, which describes the contents of the image and defines
  16. its various properties used during booting. By convention, image source file
  17. has the ".its" extension, also, the details of its format are given in
  18. doc/source_file_format.txt. The actual data that is to be included in the
  19. uImage (kernel, ramdisk, etc.) is specified in the image source file in the
  20. form of paths to appropriate data files. The outcome of the image creation
  21. process is a binary file (by convention with the ".itb" extension) that
  22. contains all the referenced data (kernel, ramdisk, etc.) and other information
  23. needed by U-Boot to handle the uImage properly. The uImage file is then
  24. transferred to the target (e.g., via tftp) and booted using the bootm command.
  25. To summarize the prerequisites needed for new uImage creation:
  26. - mkimage
  27. - dtc (with support for binary includes)
  28. - image source file (*.its)
  29. - image data file(s)
  30. Here's a graphical overview of the image creation and booting process:
  31. image source file mkimage + dtc transfer to target
  32. + ---------------> image file --------------------> bootm
  33. image data files(s)
  34. Example 1 -- old-style (non-FDT) kernel booting
  35. -----------------------------------------------
  36. Consider a simple scenario, where a PPC Linux kernel built from sources on the
  37. development host is to be booted old-style (non-FDT) by U-Boot on an embedded
  38. target. Assume that the outcome of the build is vmlinux.bin.gz, a file which
  39. contains a gzip-compressed PPC Linux kernel (the only data file in this case).
  40. The uImage can be produced using the image source file
  41. doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is
  42. in the current working directory; if desired, an alternative path can be
  43. specified in the kernel.its file). Here's how to create the image and inspect
  44. its contents:
  45. [on the host system]
  46. $ mkimage -f kernel.its kernel.itb
  47. DTC: dts->dtb on file "kernel.its"
  48. $
  49. $ mkimage -l kernel.itb
  50. FIT description: Simple image with single Linux kernel
  51. Created: Tue Mar 11 17:26:15 2008
  52. Image 0 (kernel@1)
  53. Description: Vanilla Linux kernel
  54. Type: Kernel Image
  55. Compression: gzip compressed
  56. Data Size: 943347 Bytes = 921.24 kB = 0.90 MB
  57. Architecture: PowerPC
  58. OS: Linux
  59. Load Address: 0x00000000
  60. Entry Point: 0x00000000
  61. Hash algo: crc32
  62. Hash value: 2ae2bb40
  63. Hash algo: sha1
  64. Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
  65. Default Configuration: 'config@1'
  66. Configuration 0 (config@1)
  67. Description: Boot Linux kernel
  68. Kernel: kernel@1
  69. The resulting image file kernel.itb can be now transferred to the target,
  70. inspected and booted (note that first three U-Boot commands below are shown
  71. for completeness -- they are part of the standard booting procedure and not
  72. specific to the new image format).
  73. [on the target system]
  74. => print nfsargs
  75. nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath}
  76. => print addip
  77. addip=setenv bootargs ${bootargs} ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:${netdev}:off panic=1
  78. => run nfsargs addip
  79. => tftp 900000 /path/to/tftp/location/kernel.itb
  80. Using FEC ETHERNET device
  81. TFTP from server 192.168.1.1; our IP address is 192.168.160.5
  82. Filename '/path/to/tftp/location/kernel.itb'.
  83. Load address: 0x900000
  84. Loading: #################################################################
  85. done
  86. Bytes transferred = 944464 (e6950 hex)
  87. => iminfo
  88. ## Checking Image at 00900000 ...
  89. FIT image found
  90. FIT description: Simple image with single Linux kernel
  91. Created: 2008-03-11 16:26:15 UTC
  92. Image 0 (kernel@1)
  93. Description: Vanilla Linux kernel
  94. Type: Kernel Image
  95. Compression: gzip compressed
  96. Data Start: 0x009000e0
  97. Data Size: 943347 Bytes = 921.2 kB
  98. Architecture: PowerPC
  99. OS: Linux
  100. Load Address: 0x00000000
  101. Entry Point: 0x00000000
  102. Hash algo: crc32
  103. Hash value: 2ae2bb40
  104. Hash algo: sha1
  105. Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
  106. Default Configuration: 'config@1'
  107. Configuration 0 (config@1)
  108. Description: Boot Linux kernel
  109. Kernel: kernel@1
  110. => bootm
  111. ## Booting kernel from FIT Image at 00900000 ...
  112. Using 'config@1' configuration
  113. Trying 'kernel@1' kernel subimage
  114. Description: Vanilla Linux kernel
  115. Type: Kernel Image
  116. Compression: gzip compressed
  117. Data Start: 0x009000e0
  118. Data Size: 943347 Bytes = 921.2 kB
  119. Architecture: PowerPC
  120. OS: Linux
  121. Load Address: 0x00000000
  122. Entry Point: 0x00000000
  123. Hash algo: crc32
  124. Hash value: 2ae2bb40
  125. Hash algo: sha1
  126. Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
  127. Verifying Hash Integrity ... crc32+ sha1+ OK
  128. Uncompressing Kernel Image ... OK
  129. Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb
  130. Linux version 2.4.25 (m8@hekate) (gcc version 4.0.0 (DENX ELDK 4.0 4.0.0)) #2 czw lip 5 17:56:18 CEST 2007
  131. On node 0 totalpages: 65536
  132. zone(0): 65536 pages.
  133. zone(1): 0 pages.
  134. zone(2): 0 pages.
  135. Kernel command line: root=/dev/nfs rw nfsroot=192.168.1.1:/opt/eldk-4.1/ppc_6xx ip=192.168.160.5:192.168.1.1::255.255.0.0:lite5200b:eth0:off panic=1
  136. Calibrating delay loop... 307.20 BogoMIPS
  137. Example 2 -- new-style (FDT) kernel booting
  138. -------------------------------------------
  139. Consider another simple scenario, where a PPC Linux kernel is to be booted
  140. new-style, i.e., with a FDT blob. In this case there are two prerequisite data
  141. files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can
  142. be produced using image source file doc/uImage.FIT/kernel_fdt.its like this
  143. (note again, that both prerequisite data files are assumed to be present in
  144. the current working directory -- image source file kernel_fdt.its can be
  145. modified to take the files from some other location if needed):
  146. [on the host system]
  147. $ mkimage -f kernel_fdt.its kernel_fdt.itb
  148. DTC: dts->dtb on file "kernel_fdt.its"
  149. $
  150. $ mkimage -l kernel_fdt.itb
  151. FIT description: Simple image with single Linux kernel and FDT blob
  152. Created: Tue Mar 11 16:29:22 2008
  153. Image 0 (kernel@1)
  154. Description: Vanilla Linux kernel
  155. Type: Kernel Image
  156. Compression: gzip compressed
  157. Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB
  158. Architecture: PowerPC
  159. OS: Linux
  160. Load Address: 0x00000000
  161. Entry Point: 0x00000000
  162. Hash algo: crc32
  163. Hash value: 2c0cc807
  164. Hash algo: sha1
  165. Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
  166. Image 1 (fdt@1)
  167. Description: Flattened Device Tree blob
  168. Type: Flat Device Tree
  169. Compression: uncompressed
  170. Data Size: 16384 Bytes = 16.00 kB = 0.02 MB
  171. Architecture: PowerPC
  172. Hash algo: crc32
  173. Hash value: 0d655d71
  174. Hash algo: sha1
  175. Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
  176. Default Configuration: 'conf@1'
  177. Configuration 0 (conf@1)
  178. Description: Boot Linux kernel with FDT blob
  179. Kernel: kernel@1
  180. FDT: fdt@1
  181. The resulting image file kernel_fdt.itb can be now transferred to the target,
  182. inspected and booted:
  183. [on the target system]
  184. => tftp 900000 /path/to/tftp/location/kernel_fdt.itb
  185. Using FEC ETHERNET device
  186. TFTP from server 192.168.1.1; our IP address is 192.168.160.5
  187. Filename '/path/to/tftp/location/kernel_fdt.itb'.
  188. Load address: 0x900000
  189. Loading: #################################################################
  190. ###########
  191. done
  192. Bytes transferred = 1109776 (10ef10 hex)
  193. => iminfo
  194. ## Checking Image at 00900000 ...
  195. FIT image found
  196. FIT description: Simple image with single Linux kernel and FDT blob
  197. Created: 2008-03-11 15:29:22 UTC
  198. Image 0 (kernel@1)
  199. Description: Vanilla Linux kernel
  200. Type: Kernel Image
  201. Compression: gzip compressed
  202. Data Start: 0x009000ec
  203. Data Size: 1092037 Bytes = 1 MB
  204. Architecture: PowerPC
  205. OS: Linux
  206. Load Address: 0x00000000
  207. Entry Point: 0x00000000
  208. Hash algo: crc32
  209. Hash value: 2c0cc807
  210. Hash algo: sha1
  211. Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
  212. Image 1 (fdt@1)
  213. Description: Flattened Device Tree blob
  214. Type: Flat Device Tree
  215. Compression: uncompressed
  216. Data Start: 0x00a0abdc
  217. Data Size: 16384 Bytes = 16 kB
  218. Architecture: PowerPC
  219. Hash algo: crc32
  220. Hash value: 0d655d71
  221. Hash algo: sha1
  222. Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
  223. Default Configuration: 'conf@1'
  224. Configuration 0 (conf@1)
  225. Description: Boot Linux kernel with FDT blob
  226. Kernel: kernel@1
  227. FDT: fdt@1
  228. => bootm
  229. ## Booting kernel from FIT Image at 00900000 ...
  230. Using 'conf@1' configuration
  231. Trying 'kernel@1' kernel subimage
  232. Description: Vanilla Linux kernel
  233. Type: Kernel Image
  234. Compression: gzip compressed
  235. Data Start: 0x009000ec
  236. Data Size: 1092037 Bytes = 1 MB
  237. Architecture: PowerPC
  238. OS: Linux
  239. Load Address: 0x00000000
  240. Entry Point: 0x00000000
  241. Hash algo: crc32
  242. Hash value: 2c0cc807
  243. Hash algo: sha1
  244. Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
  245. Verifying Hash Integrity ... crc32+ sha1+ OK
  246. Uncompressing Kernel Image ... OK
  247. ## Flattened Device Tree from FIT Image at 00900000
  248. Using 'conf@1' configuration
  249. Trying 'fdt@1' FDT blob subimage
  250. Description: Flattened Device Tree blob
  251. Type: Flat Device Tree
  252. Compression: uncompressed
  253. Data Start: 0x00a0abdc
  254. Data Size: 16384 Bytes = 16 kB
  255. Architecture: PowerPC
  256. Hash algo: crc32
  257. Hash value: 0d655d71
  258. Hash algo: sha1
  259. Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
  260. Verifying Hash Integrity ... crc32+ sha1+ OK
  261. Booting using the fdt blob at 0xa0abdc
  262. Loading Device Tree to 007fc000, end 007fffff ... OK
  263. [ 0.000000] Using lite5200 machine description
  264. [ 0.000000] Linux version 2.6.24-rc6-gaebecdfc (m8@hekate) (gcc version 4.0.0 (DENX ELDK 4.1 4.0.0)) #1 Sat Jan 12 15:38:48 CET 2008
  265. Example 3 -- advanced booting
  266. -----------------------------
  267. Refer to doc/uImage.FIT/multi.its for an image source file that allows more
  268. sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs).