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