source_file_format.txt 8.6 KB

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