← Back to branch summary

~ubuntu-branches/ubuntu/maverick/u-boot-omap3/maverick

« back to all changes in this revision

Viewing changes to doc/uImage.FIT/source_file_format.txt

  • Committer: Bazaar Package Importer
  • Author(s): Oliver Grawert
  • Date: 2010-03-22 15:06:23 UTC
  • Revision ID: james.westby@ubuntu.com-20100322150623-i21g8rgiyl5dohag
Tags: upstream-2010.3git20100315
Import upstream version 2010.3git20100315

Show diffs side-by-side

added added

removed removed

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