source_file_format.txt 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310
  1. U-Boot new uImage source file format (bindings definition)
  2. ==========================================================
  3. Author: Marian Balakowicz <m8@semihalf.com>
  4. External data additions, 25/1/16 Simon Glass <sjg@chromium.org>
  5. 1) Introduction
  6. ---------------
  7. Evolution of the 2.6 Linux kernel for embedded PowerPC systems introduced new
  8. booting method which requires that hardware description is available to the
  9. kernel in the form of Flattened Device Tree.
  10. Booting with a Flattened Device Tree is much more flexible and is intended to
  11. replace direct passing of 'struct bd_info' which was used to boot pre-FDT
  12. kernels.
  13. However, U-Boot needs to support both techniques to provide backward
  14. compatibility for platforms which are not FDT ready. Number of elements
  15. playing role in the booting process has increased and now includes the FDT
  16. blob. Kernel image, FDT blob and possibly ramdisk image - all must be placed
  17. in the system memory and passed to bootm as a arguments. Some of them may be
  18. missing: FDT is not present for legacy platforms, ramdisk is always optional.
  19. Additionally, old uImage format has been extended to support multi sub-images
  20. but the support is limited by simple format of the legacy uImage structure.
  21. Single binary header 'struct image_header' is not flexible enough to cover all
  22. possible scenarios.
  23. All those factors combined clearly show that there is a need for new, more
  24. flexible, multi component uImage format.
  25. 2) New uImage format assumptions
  26. --------------------------------
  27. a) Implementation
  28. Libfdt has been selected for the new uImage format implementation as (1) it
  29. provides needed functionality, (2) is actively maintained and developed and
  30. (3) increases code reuse as it is already part of the U-Boot source tree.
  31. b) Terminology
  32. This document defines new uImage structure by providing FDT bindings for new
  33. uImage internals. Bindings are defined from U-Boot perspective, i.e. describe
  34. final form of the uImage at the moment when it reaches U-Boot. User
  35. perspective may be simpler, as some of the properties (like timestamps and
  36. hashes) will need to be filled in automatically by the U-Boot mkimage tool.
  37. To avoid confusion with the kernel FDT the following naming convention is
  38. proposed for the new uImage format related terms:
  39. FIT - Flattened uImage Tree
  40. FIT is formally a flattened device tree (in the libfdt meaning), which
  41. conforms to bindings defined in this document.
  42. .its - image tree source
  43. .itb - flattened image tree blob
  44. c) Image building procedure
  45. The following picture shows how the new uImage is prepared. Input consists of
  46. image source file (.its) and a set of data files. Image is created with the
  47. help of standard U-Boot mkimage tool which in turn uses dtc (device tree
  48. compiler) to produce image tree blob (.itb). Resulting .itb file is the
  49. actual binary of a new uImage.
  50. tqm5200.its
  51. +
  52. vmlinux.bin.gz mkimage + dtc xfer to target
  53. eldk-4.2-ramdisk --------------> tqm5200.itb --------------> bootm
  54. tqm5200.dtb /|\
  55. ... |
  56. 'new uImage'
  57. - create .its file, automatically filled-in properties are omitted
  58. - call mkimage tool on a .its file
  59. - mkimage calls dtc to create .itb image and assures that
  60. missing properties are added
  61. - .itb (new uImage) is uploaded onto the target and used therein
  62. d) Unique identifiers
  63. To identify FIT sub-nodes representing images, hashes, configurations (which
  64. are defined in the following sections), the "unit name" of the given sub-node
  65. is used as it's identifier as it assures uniqueness without additional
  66. checking required.
  67. 3) Root node properties
  68. -----------------------
  69. Root node of the uImage Tree should have the following layout:
  70. / o image-tree
  71. |- description = "image description"
  72. |- timestamp = <12399321>
  73. |- #address-cells = <1>
  74. |
  75. o images
  76. | |
  77. | o image-1 {...}
  78. | o image-2 {...}
  79. | ...
  80. |
  81. o configurations
  82. |- default = "conf-1"
  83. |
  84. o conf-1 {...}
  85. o conf-2 {...}
  86. ...
  87. Optional property:
  88. - description : Textual description of the uImage
  89. Mandatory property:
  90. - timestamp : Last image modification time being counted in seconds since
  91. 1970-01-01 00:00:00 - to be automatically calculated by mkimage tool.
  92. Conditionally mandatory property:
  93. - #address-cells : Number of 32bit cells required to represent entry and
  94. load addresses supplied within sub-image nodes. May be omitted when no
  95. entry or load addresses are used.
  96. Mandatory node:
  97. - images : This node contains a set of sub-nodes, each of them representing
  98. single component sub-image (like kernel, ramdisk, etc.). At least one
  99. sub-image is required.
  100. Optional node:
  101. - configurations : Contains a set of available configuration nodes and
  102. defines a default configuration.
  103. 4) '/images' node
  104. -----------------
  105. This node is a container node for component sub-image nodes. Each sub-node of
  106. the '/images' node should have the following layout:
  107. o image-1
  108. |- description = "component sub-image description"
  109. |- data = /incbin/("path/to/data/file.bin")
  110. |- type = "sub-image type name"
  111. |- arch = "ARCH name"
  112. |- os = "OS name"
  113. |- compression = "compression name"
  114. |- load = <00000000>
  115. |- entry = <00000000>
  116. |
  117. o hash-1 {...}
  118. o hash-2 {...}
  119. ...
  120. Mandatory properties:
  121. - description : Textual description of the component sub-image
  122. - type : Name of component sub-image type, supported types are:
  123. "standalone", "kernel", "kernel_noload", "ramdisk", "firmware", "script",
  124. "filesystem", "flat_dt" and others (see uimage_type in common/image.c).
  125. - data : Path to the external file which contains this node's binary data.
  126. - compression : Compression used by included data. Supported compressions
  127. are "gzip" and "bzip2". If no compression is used compression property
  128. should be set to "none". If the data is compressed but it should not be
  129. uncompressed by U-Boot (e.g. compressed ramdisk), this should also be set
  130. to "none".
  131. Conditionally mandatory property:
  132. - os : OS name, mandatory for types "kernel" and "ramdisk". Valid OS names
  133. are: "openbsd", "netbsd", "freebsd", "4_4bsd", "linux", "svr4", "esix",
  134. "solaris", "irix", "sco", "dell", "ncr", "lynxos", "vxworks", "psos", "qnx",
  135. "u_boot", "rtems", "unity", "integrity".
  136. - arch : Architecture name, mandatory for types: "standalone", "kernel",
  137. "firmware", "ramdisk" and "fdt". Valid architecture names are: "alpha",
  138. "arm", "i386", "ia64", "mips", "mips64", "ppc", "s390", "sh", "sparc",
  139. "sparc64", "m68k", "microblaze", "nios2", "blackfin", "avr32", "st200",
  140. "sandbox".
  141. - entry : entry point address, address size is determined by
  142. '#address-cells' property of the root node. Mandatory for for types:
  143. "standalone" and "kernel".
  144. - load : load address, address size is determined by '#address-cells'
  145. property of the root node. Mandatory for types: "standalone" and "kernel".
  146. Optional nodes:
  147. - hash-1 : Each hash sub-node represents separate hash or checksum
  148. calculated for node's data according to specified algorithm.
  149. 5) Hash nodes
  150. -------------
  151. o hash-1
  152. |- algo = "hash or checksum algorithm name"
  153. |- value = [hash or checksum value]
  154. Mandatory properties:
  155. - algo : Algorithm name, supported are "crc32", "md5" and "sha1".
  156. - value : Actual checksum or hash value, correspondingly 4, 16 or 20 bytes
  157. long.
  158. 6) '/configurations' node
  159. -------------------------
  160. The 'configurations' node is optional. If present, it allows to create a
  161. convenient, labeled boot configurations, which combine together kernel images
  162. with their ramdisks and fdt blobs.
  163. The 'configurations' node has has the following structure:
  164. o configurations
  165. |- default = "default configuration sub-node unit name"
  166. |
  167. o config-1 {...}
  168. o config-2 {...}
  169. ...
  170. Optional property:
  171. - default : Selects one of the configuration sub-nodes as a default
  172. configuration.
  173. Mandatory nodes:
  174. - configuration-sub-node-unit-name : At least one of the configuration
  175. sub-nodes is required.
  176. 7) Configuration nodes
  177. ----------------------
  178. Each configuration has the following structure:
  179. o config-1
  180. |- description = "configuration description"
  181. |- kernel = "kernel sub-node unit name"
  182. |- ramdisk = "ramdisk sub-node unit name"
  183. |- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...]
  184. |- fpga = "fpga sub-node unit-name"
  185. |- loadables = "loadables sub-node unit-name"
  186. |- compatible = "vendor,board-style device tree compatible string"
  187. Mandatory properties:
  188. - description : Textual configuration description.
  189. - kernel : Unit name of the corresponding kernel image (image sub-node of a
  190. "kernel" type).
  191. Optional properties:
  192. - ramdisk : Unit name of the corresponding ramdisk image (component image
  193. node of a "ramdisk" type).
  194. - fdt : Unit name of the corresponding fdt blob (component image node of a
  195. "fdt type"). Additional fdt overlay nodes can be supplied which signify
  196. that the resulting device tree blob is generated by the first base fdt
  197. blob with all subsequent overlays applied.
  198. - setup : Unit name of the corresponding setup binary (used for booting
  199. an x86 kernel). This contains the setup.bin file built by the kernel.
  200. - fpga : Unit name of the corresponding fpga bitstream blob
  201. (component image node of a "fpga type").
  202. - loadables : Unit name containing a list of additional binaries to be
  203. loaded at their given locations. "loadables" is a comma-separated list
  204. of strings. U-Boot will load each binary at its given start-address and
  205. may optionally invoke additional post-processing steps on this binary based
  206. on its component image node type.
  207. - compatible : The root compatible string of the U-Boot device tree that
  208. this configuration shall automatically match when CONFIG_FIT_BEST_MATCH is
  209. enabled. If this property is not provided, the compatible string will be
  210. extracted from the fdt blob instead. This is only possible if the fdt is
  211. not compressed, so images with compressed fdts that want to use compatible
  212. string matching must always provide this property.
  213. The FDT blob is required to properly boot FDT based kernel, so the minimal
  214. configuration for 2.6 FDT kernel is (kernel, fdt) pair.
  215. Older, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases
  216. 'struct bd_info' must be passed instead of FDT blob, thus fdt property *must
  217. not* be specified in a configuration node.
  218. 8) External data
  219. ----------------
  220. The above format shows a 'data' property which holds the data for each image.
  221. It is also possible for this data to reside outside the FIT itself. This
  222. allows the FIT to be quite small, so that it can be loaded and scanned
  223. without loading a large amount of data. Then when an image is needed it can
  224. be loaded from an external source.
  225. In this case the 'data' property is omitted. Instead you can use:
  226. - data-offset : offset of the data in a separate image store. The image
  227. store is placed immediately after the last byte of the device tree binary,
  228. aligned to a 4-byte boundary.
  229. - data-size : size of the data in bytes
  230. The 'data-offset' property can be substituted with 'data-position', which
  231. defines an absolute position or address as the offset. This is helpful when
  232. booting U-Boot proper before performing relocation. Pass '-p [offset]' to
  233. mkimage to enable 'data-position'.
  234. Normal kernel FIT image has data embedded within FIT structure. U-Boot image
  235. for SPL boot has external data. Existence of 'data-offset' can be used to
  236. identify which format is used.
  237. 9) Examples
  238. -----------
  239. Please see doc/uImage.FIT/*.its for actual image source files.