Mirrors/u-boot
2
0
Fork 0
mirror of https://github.com/AsahiLinux/u-boot synced 2024-11-24 21:54:01 +00:00
Code Issues Projects Releases Packages Wiki Activity

[new uImage] Add new uImage format documentation and examples

Browse source 
Create doc/uImage.FIT documentation directory with the following files:
- command_syntax_extensions.txt : extended command syntax description
- howto.txt                     : short usage howto
- source_file_format.txt        : internal new uImage format description

Add example image source files:
- kernel.its
- kernel_fdt.its
- multi.its

Update README appropriately.

Signed-off-by: Marian Balakowicz <m8@semihalf.com>
Signed-off-by: Bartlomiej Sieka <tur@semihalf.com>
This commit is contained in:
Marian Balakowicz 2008-03-12 12:13:13 +01:00
parent 1ec73761d2
commit 3310c549a7
7 changed files with 981 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
README
View file

@ -2684,6 +2684,14 @@ Some configuration options can be set using Environment Variables:
configuration from the BOOTP server, but not try to
load any image using TFTP
autoscript - if set to "yes" commands like "loadb", "loady",
"bootp", "tftpb", "rarpboot" and "nfs" will attempt
to automatically run script images (by internally
calling "autoscript").
autoscript_uname - if script image is in a format (FIT) this
variable is used to get script subimage unit name.
autostart - if set to "yes", an image loaded using the "bootp",
"rarpboot", "tftpboot" or "diskboot" commands will
be automatically started (by internally calling
@ -2898,10 +2906,24 @@ o If neither SROM nor the environment contain a MAC address, an error
Image Formats:
==============
The "boot" commands of this monitor operate on "image" files which
can be basicly anything, preceeded by a special header; see the
definitions in include/image.h for details; basicly, the header
defines the following image properties:
U-Boot is capable of booting (and performing other auxiliary operations on)
images in two formats:
New uImage format (FIT)
-----------------------
Flexible and powerful format based on Flattened Image Tree -- FIT (similar
to Flattened Device Tree). It allows the use of images with multiple
components (several kernels, ramdisks, etc.), with contents protected by
SHA1, MD5 or CRC32. More details are found in the doc/uImage.FIT directory.
Old uImage format
-----------------
Old image format is based on binary files which can be basically anything,
preceded by a special header; see the definitions in include/image.h for
details; basically, the header defines the following image properties:
* Target Operating System (Provisions for OpenBSD, NetBSD, FreeBSD,
4.4BSD, Linux, SVR4, Esix, Solaris, Irix, SCO, Dell, NCR, VxWorks,

191
doc/uImage.FIT/command_syntax_extensions.txt Normal file
View file

@ -0,0 +1,191 @@
Command syntax extensions for the new uImage format
===================================================
Author: Bartlomiej Sieka <tur@semihalf.com>
With the introduction of the new uImage format, bootm command (and other
commands as well) have to understand new syntax of the arguments. This is
necessary in order to specify objects contained in the new uImage, on which
bootm has to operate. This note attempts to first summarize bootm usage
scenarios, and then introduces new argument syntax.
bootm usage scenarios
---------------------
Below is a summary of bootm usage scenarios, focused on booting a PowerPC
Linux kernel. The purpose of the following list is to document a complete list
of supported bootm usages.
Note: U-Boot supports two methods of booting a PowerPC Linux kernel: old way,
i.e., without passing the Flattened Device Tree (FDT), and new way, where the
kernel is passed a pointer to the FDT. The boot method is indicated for each
scenario.
1. bootm boot image at the current address, equivalent to 2,3,8
Old uImage:
2. bootm <addr1> /* single image at <addr1> */
3. bootm <addr1> /* multi-image at <addr1> */
4. bootm <addr1> - /* multi-image at <addr1> */
5. bootm <addr1> <addr2> /* single image at <addr1> */
6. bootm <addr1> <addr2> <addr3> /* single image at <addr1> */
7. bootm <addr1> - <addr3> /* single image at <addr1> */
New uImage:
8. bootm <addr1>
9. bootm [<addr1>]:<subimg1>
10. bootm [<addr1>]#<conf>
11. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2>
12. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> [<addr3>]:<subimg3>
13. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> <addr3>
14. bootm [<addr1>]:<subimg1> - [<addr3>]:<subimg3>
15. bootm [<addr1>]:<subimg1> - <addr3>
Ad. 1. This is equivalent to cases 2,3,8, depending on the type of image at
the current image address.
- boot method: see cases 2,3,8
Ad. 2. Boot kernel image located at <addr1>.
- boot method: non-FDT
Ad. 3. First and second components of the image at <addr1> are assumed to be a
kernel and a ramdisk, respectively. The kernel is booted with initrd loaded
with the ramdisk from the image.
- boot method: depends on the number of components at <addr1>, and on whether
U-Boot is compiled with OF support:
| 2 components | 3 components |
| (kernel, initrd) | (kernel, initrd, fdt) |
---------------------------------------------------------------------
#ifdef CONFIG_OF_* | non-FDT | FDT |
#ifndef CONFIG_OF_* | non-FDT | non-FDT |
Ad. 4. Similar to case 3, but the kernel is booted without initrd. Second
component of the multi-image is irrelevant (it can be a dummy, 1-byte file).
- boot method: see case 3
Ad. 5. Boot kernel image located at <addr1> with initrd loaded with ramdisk
from the image at <addr2>.
- boot method: non-FDT
Ad. 6. <addr1> is the address of a kernel image, <addr2> is the address of a
ramdisk image, and <addr3> is the address of a FDT binary blob. Kernel is
booted with initrd loaded with ramdisk from the image at <addr2>.
- boot method: FDT
Ad. 7. <addr1> is the address of a kernel image and <addr3> is the address of
a FDT binary blob. Kernel is booted without initrd.
- boot method: FDT
Ad. 8. Image at <addr1> is assumed to contain a default configuration, which
is booted.
- boot method: FDT or non-FDT, depending on whether the default configuration
defines FDT
Ad. 9. Similar to case 2: boot kernel stored in <subimg1> from the image at
address <addr1>.
- boot method: non-FDT
Ad. 10. Boot configuration <conf> from the image at <addr1>.
- boot method: FDT or non-FDT, depending on whether the configuration given
defines FDT
Ad. 11. Equivalent to case 5: boot kernel stored in <subimg1> from the image
at <addr1> with initrd loaded with ramdisk <subimg2> from the image at
<addr2>.
- boot method: non-FDT
Ad. 12. Equivalent to case 6: boot kernel stored in <subimg1> from the image
at <addr1> with initrd loaded with ramdisk <subimg2> from the image at
<addr2>, and pass FDT blob <subimg3> from the image at <addr3>.
- boot method: FDT
Ad. 13. Similar to case 12, the difference being that <addr3> is the address
of FDT binary blob that is to be passed to the kernel.
- boot method: FDT
Ad. 14. Equivalent to case 7: boot kernel stored in <subimg1> from the image
at <addr1>, without initrd, and pass FDT blob <subimg3> from the image at
<addr3>.
- boot method: FDT
Ad. 15. Similar to case 14, the difference being that <addr3> is the address
of the FDT binary blob that is to be passed to the kernel.
- boot method: FDT
New uImage argument syntax
--------------------------
New uImage support introduces two new forms for bootm arguments, with the
following syntax:
- new uImage sub-image specification
<addr>:<sub-image unit_name>
- new uImage configuration specification
<addr>#<configuration unit_name>
Examples:
- boot kernel "kernel@1" stored in a new uImage located at 200000:
bootm 200000:kernel@1
- boot configuration "cfg@1" from a new uImage located at 200000:
bootm 200000#cfg@1
- boot "kernel@1" from a new uImage at 200000 with initrd "ramdisk@2" found in
some other new uImage stored at address 800000:
bootm 200000:kernel@1 800000:ramdisk@2
- boot "kernel@2" from a new uImage at 200000, with initrd "ramdisk@1" and FDT
"fdt@1", both stored in some other new uImage located at 800000:
bootm 200000:kernel@1 800000:ramdisk@1 800000:fdt@1
- boot kernel "kernel@2" with initrd "ramdisk@2", both stored in a new uImage
at address 200000, with a raw FDT blob stored at address 600000:
bootm 200000:kernel@2 200000:ramdisk@2 600000
- boot kernel "kernel@2" from new uImage at 200000 with FDT "fdt@1" from the
same new uImage:
bootm 200000:kernel@2 - 200000:fdt@1
Note on current image address
-----------------------------
When bootm is called without arguments, the image at current image address is
booted. The current image address is the address set most recently by a load
command, etc, and is by default equal to CFG_LOAD_ADDR. For example, consider
the following commands:
tftp 200000 /tftpboot/kernel
bootm
Last command is equivalent to:
bootm 200000
In case of the new uImage argument syntax, the address portion of any argument
can be omitted. If <addr3> is omitted, then it is assumed that image at
<addr2> should be used. Similarly, when <addr2> is omitted, is is assumed that
image at <addr1> should be used. If <addr1> is omitted, it is assumed that the
current image address is to be used. For example, consider the following
commands:
tftp 200000 /tftpboot/uImage
bootm :kernel@1
Last command is equivalent to:
bootm 200000:kernel@1
tftp 200000 /tftpboot/uImage
bootm 400000:kernel@1 :ramdisk@1
Last command is equivalent to:
bootm 400000:kernel@1 400000:ramdisk@1
tftp 200000 /tftpboot/uImage
bootm :kernel@1 400000:ramdisk@1 :fdt@1
Last command is equivalent to:
bootm 200000:kernel@1 400000:ramdisk@1 400000:fdt@1

296
doc/uImage.FIT/howto.txt Normal file
View file

@ -0,0 +1,296 @@
How to use images in the new image format
=========================================
Author: Bartlomiej Sieka <tur@semihalf.com>
Overview
--------
The new uImage format allows more flexibility in handling images of various
types (kernel, ramdisk, etc.), it also enhances integrity protection of images
with sha1 and md5 checksums.
Two auxiliary tools are needed on the development host system in order to
create an uImage in the new format: mkimage and dtc, although only one
(mkimage) is invoked directly. dtc is called from within mkimage and operates
behind the scenes, but needs to be present in the $PATH nevertheless. It is
important that the dtc used has support for binary includes -- refer to
www.jdl.com for its latest version. mkimage (together with dtc) takes as input
an image source file, which describes the contents of the image and defines
its various properties used during booting. By convention, image source file
has the ".its" extension, also, the details of its format are given in
doc/source_file_format.txt. The actual data that is to be included in the
uImage (kernel, ramdisk, etc.) is specified in the image source file in the
form of paths to appropriate data files. The outcome of the image creation
process is a binary file (by convention with the ".itb" extension) that
contains all the referenced data (kernel, ramdisk, etc.) and other information
needed by U-Boot to handle the uImage properly. The uImage file is then
transferred to the target (e.g., via tftp) and booted using the bootm command.
To summarize the prerequisites needed for new uImage creation:
- mkimage
- dtc (with support for binary includes)
- image source file (*.its)
- image data file(s)
Here's a graphical overview of the image creation and booting process:
image source file mkimage + dtc transfer to target
+ ---------------> image file --------------------> bootm
image data files(s)
Example 1 -- old-style (non-FDT) kernel booting
-----------------------------------------------
Consider a simple scenario, where a PPC Linux kernel built from sources on the
development host is to be booted old-style (non-FDT) by U-Boot on an embedded
target. Assume that the outcome of the build is vmlinux.bin.gz, a file which
contains a gzip-compressed PPC Linux kernel (the only data file in this case).
The uImage can be produced using the image source file examples/kernel.its
(note that kernel.its assumes that vmlinux.bin.gz is in the current working
directory; if desired, an alternative path can be specified in the kernel.its
file). Here's how to create the image and inspect its contents:
[on the host system]
$ mkimage -f kernel.its kernel.itb
DTC: dts->dtb on file "kernel.its"
$
$ mkimage -l kernel.itb
FIT description: Simple image with single Linux kernel
Created: Tue Mar 11 17:26:15 2008
Image 0 (kernel@1)
Description: Vanilla Linux kernel
Type: Kernel Image
Compression: gzip compressed
Data Size: 943347 Bytes = 921.24 kB = 0.90 MB
Architecture: PowerPC
OS: Linux
Load Address: 0x00000000
Entry Point: 0x00000000
Hash algo: crc32
Hash value: 2ae2bb40
Hash algo: sha1
Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
Default Configuration: 'config@1'
Configuration 0 (config@1)
Description: Boot Linux kernel
Kernel: kernel@1
The resulting image file kernel.itb can be now transferred to the target,
inspected and booted (note that first three U-Boot commands below are shown
for completeness -- they are part of the standard booting procedure and not
specific to the new image format).
[on the target system]
=> print nfsargs
nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath}
=> print addip
addip=setenv bootargs ${bootargs} ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:${netdev}:off panic=1
=> run nfsargs addip
=> tftp 900000 /path/to/tftp/location/kernel.itb
Using FEC ETHERNET device
TFTP from server 192.168.1.1; our IP address is 192.168.160.5
Filename '/path/to/tftp/location/kernel.itb'.
Load address: 0x900000
Loading: #################################################################
done
Bytes transferred = 944464 (e6950 hex)
=> iminfo
## Checking Image at 00900000 ...
FIT image found
FIT description: Simple image with single Linux kernel
Created: 2008-03-11 16:26:15 UTC
Image 0 (kernel@1)
Description: Vanilla Linux kernel
Type: Kernel Image
Compression: gzip compressed
Data Start: 0x009000e0
Data Size: 943347 Bytes = 921.2 kB
Architecture: PowerPC
OS: Linux
Load Address: 0x00000000
Entry Point: 0x00000000
Hash algo: crc32
Hash value: 2ae2bb40
Hash algo: sha1
Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
Default Configuration: 'config@1'
Configuration 0 (config@1)
Description: Boot Linux kernel
Kernel: kernel@1
=> bootm
## Booting kernel from FIT Image at 00900000 ...
Using 'config@1' configuration
Trying 'kernel@1' kernel subimage
Description: Vanilla Linux kernel
Type: Kernel Image
Compression: gzip compressed
Data Start: 0x009000e0
Data Size: 943347 Bytes = 921.2 kB
Architecture: PowerPC
OS: Linux
Load Address: 0x00000000
Entry Point: 0x00000000
Hash algo: crc32
Hash value: 2ae2bb40
Hash algo: sha1
Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
Verifying Hash Integrity ... crc32+ sha1+ OK
Uncompressing Kernel Image ... OK
Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb
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
On node 0 totalpages: 65536
zone(0): 65536 pages.
zone(1): 0 pages.
zone(2): 0 pages.
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
Calibrating delay loop... 307.20 BogoMIPS
Example 2 -- new-style (FDT) kernel booting
-------------------------------------------
Consider another simple scenario, where a PPC Linux kernel is to be booted
new-style, i.e., with a FDT blob. In this case there are two prerequisite data
files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can
be produced using image source file examples/kernel_fdt.its like this (note
again, that both prerequisite data files are assumed to be present in the
current working directory -- image source file kernel_fdt.its can be modified
to take the files from some other location if needed):
[on the host system]
$ mkimage -f kernel_fdt.its kernel_fdt.itb
DTC: dts->dtb on file "kernel_fdt.its"
$
$ mkimage -l kernel_fdt.itb
FIT description: Simple image with single Linux kernel and FDT blob
Created: Tue Mar 11 16:29:22 2008
Image 0 (kernel@1)
Description: Vanilla Linux kernel
Type: Kernel Image
Compression: gzip compressed
Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB
Architecture: PowerPC
OS: Linux
Load Address: 0x00000000
Entry Point: 0x00000000
Hash algo: crc32
Hash value: 2c0cc807
Hash algo: sha1
Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
Image 1 (fdt@1)
Description: Flattened Device Tree blob
Type: Flat Device Tree
Compression: uncompressed
Data Size: 16384 Bytes = 16.00 kB = 0.02 MB
Architecture: PowerPC
Hash algo: crc32
Hash value: 0d655d71
Hash algo: sha1
Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
Default Configuration: 'conf@1'
Configuration 0 (conf@1)
Description: Boot Linux kernel with FDT blob
Kernel: kernel@1
FDT: fdt@1
The resulting image file kernel_fdt.itb can be now transferred to the target,
inspected and booted:
[on the target system]
=> tftp 900000 /path/to/tftp/location/kernel_fdt.itb
Using FEC ETHERNET device
TFTP from server 192.168.1.1; our IP address is 192.168.160.5
Filename '/path/to/tftp/location/kernel_fdt.itb'.
Load address: 0x900000
Loading: #################################################################
###########
done
Bytes transferred = 1109776 (10ef10 hex)
=> iminfo
## Checking Image at 00900000 ...
FIT image found
FIT description: Simple image with single Linux kernel and FDT blob
Created: 2008-03-11 15:29:22 UTC
Image 0 (kernel@1)
Description: Vanilla Linux kernel
Type: Kernel Image
Compression: gzip compressed
Data Start: 0x009000ec
Data Size: 1092037 Bytes = 1 MB
Architecture: PowerPC
OS: Linux
Load Address: 0x00000000
Entry Point: 0x00000000
Hash algo: crc32
Hash value: 2c0cc807
Hash algo: sha1
Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
Image 1 (fdt@1)
Description: Flattened Device Tree blob
Type: Flat Device Tree
Compression: uncompressed
Data Start: 0x00a0abdc
Data Size: 16384 Bytes = 16 kB
Architecture: PowerPC
Hash algo: crc32
Hash value: 0d655d71
Hash algo: sha1
Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
Default Configuration: 'conf@1'
Configuration 0 (conf@1)
Description: Boot Linux kernel with FDT blob
Kernel: kernel@1
FDT: fdt@1
=> bootm
## Booting kernel from FIT Image at 00900000 ...
Using 'conf@1' configuration
Trying 'kernel@1' kernel subimage
Description: Vanilla Linux kernel
Type: Kernel Image
Compression: gzip compressed
Data Start: 0x009000ec
Data Size: 1092037 Bytes = 1 MB
Architecture: PowerPC
OS: Linux
Load Address: 0x00000000
Entry Point: 0x00000000
Hash algo: crc32
Hash value: 2c0cc807
Hash algo: sha1
Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
Verifying Hash Integrity ... crc32+ sha1+ OK
Uncompressing Kernel Image ... OK
## Flattened Device Tree from FIT Image at 00900000
Using 'conf@1' configuration
Trying 'fdt@1' FDT blob subimage
Description: Flattened Device Tree blob
Type: Flat Device Tree
Compression: uncompressed
Data Start: 0x00a0abdc
Data Size: 16384 Bytes = 16 kB
Architecture: PowerPC
Hash algo: crc32
Hash value: 0d655d71
Hash algo: sha1
Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
Verifying Hash Integrity ... crc32+ sha1+ OK
Booting using the fdt blob at 0xa0abdc
Loading Device Tree to 007fc000, end 007fffff ... OK
[ 0.000000] Using lite5200 machine description
[ 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
Example 3 -- advanced booting
-----------------------------
Refer to examples/multi.its for an image source file that allows more
sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs).

34
doc/uImage.FIT/kernel.its Normal file
View file

@ -0,0 +1,34 @@
/*
* Simple U-boot uImage source file containing a single kernel
*/
/ {
description = "Simple image with single Linux kernel";
#address-cells = <1>;
images {
kernel@1 {
description = "Vanilla Linux kernel";
data = /incbin/("./vmlinux.bin.gz");
type = "kernel";
arch = "ppc";
os = "linux";
compression = "gzip";
load = <00000000>;
entry = <00000000>;
hash@1 {
algo = "crc32";
};
hash@2 {
algo = "sha1";
};
};
};
configurations {
default = "config@1";
config@1 {
description = "Boot Linux kernel";
kernel = "kernel@1";
};
};
};

48
doc/uImage.FIT/kernel_fdt.its Normal file
View file

@ -0,0 +1,48 @@
/*
* Simple U-boot uImage source file containing a single kernel and FDT blob
*/
/ {
description = "Simple image with single Linux kernel and FDT blob";
#address-cells = <1>;
images {
kernel@1 {
description = "Vanilla Linux kernel";
data = /incbin/("./vmlinux.bin.gz");
type = "kernel";
arch = "ppc";
os = "linux";
compression = "gzip";
load = <00000000>;
entry = <00000000>;
hash@1 {
algo = "crc32";
};
hash@2 {
algo = "sha1";
};
};
fdt@1 {
description = "Flattened Device Tree blob";
data = /incbin/("./target.dtb");
type = "flat_dt";
arch = "ppc";
compression = "none";
hash@1 {
algo = "crc32";
};
hash@2 {
algo = "sha1";
};
};
};
configurations {
default = "conf@1";
conf@1 {
description = "Boot Linux kernel with FDT blob";
kernel = "kernel@1";
fdt = "fdt@1";
};
};
};

124
doc/uImage.FIT/multi.its Normal file
View file

@ -0,0 +1,124 @@
/*
* U-boot uImage source file with multiple kernels, ramdisks and FDT blobs
*/
/ {
description = "Various kernels, ramdisks and FDT blobs";
#address-cells = <1>;
images {
kernel@1 {
description = "vanilla-2.6.23";
data = /incbin/("./vmlinux.bin.gz");
type = "kernel";
arch = "ppc";
os = "linux";
compression = "gzip";
load = <00000000>;
entry = <00000000>;
hash@1 {
algo = "md5";
};
hash@2 {
algo = "sha1";
};
};
kernel@2 {
description = "2.6.23-denx";
data = /incbin/("./2.6.23-denx.bin.gz");
type = "kernel";
arch = "ppc";
os = "linux";
compression = "gzip";
load = <00000000>;
entry = <00000000>;
hash@1 {
algo = "sha1";
};
};
kernel@3 {
description = "2.4.25-denx";
data = /incbin/("./2.4.25-denx.bin.gz");
type = "kernel";
arch = "ppc";
os = "linux";
compression = "gzip";
load = <00000000>;
entry = <00000000>;
hash@1 {
algo = "md5";
};
};
ramdisk@1 {
description = "eldk-4.2-ramdisk";
data = /incbin/("./eldk-4.2-ramdisk");
type = "ramdisk";
arch = "ppc";
compression = "gzip";
hash@1 {
algo = "sha1";
};
};
ramdisk@2 {
description = "eldk-3.1-ramdisk";
data = /incbin/("./eldk-3.1-ramdisk");
type = "ramdisk";
arch = "ppc";
compression = "gzip";
hash@1 {
algo = "crc32";
};
};
fdt@1 {
description = "tqm5200-fdt";
data = /incbin/("./tqm5200.dtb");
type = "flat_dt";
arch = "ppc";
compression = "none";
hash@1 {
algo = "crc32";
};
};
fdt@2 {
description = "tqm5200s-fdt";
data = /incbin/("./tqm5200s.dtb");
type = "flat_dt";
arch = "ppc";
compression = "none";
load = <00700000>;
hash@1 {
algo = "sha1";
};
};
};
configurations {
default = "config@1";
config@1 {
description = "tqm5200 vanilla-2.6.23 configuration";
kernel = "kernel@1";
ramdisk = "ramdisk@1";
fdt = "fdt@1";
};
config@2 {
description = "tqm5200s denx-2.6.23 configuration";
kernel = "kernel@2";
ramdisk = "ramdisk@1";
fdt = "fdt@2";
};
config@3 {
description = "tqm5200s denx-2.4.25 configuration";
kernel = "kernel@3";
ramdisk = "ramdisk@2";
};
};
};

262
doc/uImage.FIT/source_file_format.txt Normal file
View file

@ -0,0 +1,262 @@
U-boot new uImage source file format (bindings definition)
==========================================================
Author: Marian Balakowicz <m8@semihalf.com>
1) Introduction
---------------
Evolution of the 2.6 Linux kernel for embedded PowerPC systems introduced new
booting method which requires that hardware description is available to the
kernel in the form of Flattened Device Tree.
Booting with a Flattened Device Tree is much more flexible and is intended to
replace direct passing of 'struct bd_info' which was used to boot pre-FDT
kernels.
However, U-boot needs to support both techniques to provide backward
compatibility for platforms which are not FDT ready. Number of elements
playing role in the booting process has increased and now includes the FDT
blob. Kernel image, FDT blob and possibly ramdisk image - all must be placed
in the system memory and passed to bootm as a arguments. Some of them may be
missing: FDT is not present for legacy platforms, ramdisk is always optional.
Additionally, old uImage format has been extended to support multi sub-images
but the support is limited by simple format of the legacy uImage structure.
Single binary header 'struct image_header' is not flexible enough to cover all
possible scenarios.
All those factors combined clearly show that there is a need for new, more
flexible, multi component uImage format.
2) New uImage format assumptions
--------------------------------
a) Implementation
Libfdt has been selected for the new uImage format implementation as (1) it
provides needed functionality, (2) is actively maintained and developed and
(3) increases code reuse as it is already part of the U-boot source tree.
b) Terminology
This document defines new uImage structure by providing FDT bindings for new
uImage internals. Bindings are defined from U-boot perspective, i.e. describe
final form of the uImage at the moment when it reaches U-boot. User
perspective may be simpler, as some of the properties (like timestamps and
hashes) will need to be filled in automatically by the U-boot mkimage tool.
To avoid confusion with the kernel FDT the following naming convention is
proposed for the new uImage format related terms:
FIT - Flattened uImage Tree
FIT is formally a flattened device tree (in the libfdt meaning), which
conforms to bindings defined in this document.
.its - image tree source
.itb - image tree blob
c) Image building procedure
The following picture shows how the new uImage is prepared. Input consists of
image source file (.its) and a set of data files. Image is created with the
help of standard U-boot mkimage tool which in turn uses dtc (device tree
compiler) to produce image tree blob (.itb). Resulting .itb file is is the
actual binary of a new uImage.
tqm5200.its
+
vmlinux.bin.gz mkimage + dtc xfer to target
eldk-4.2-ramdisk --------------> tqm5200.itb --------------> bootm
tqm5200.dtb /|\
... |
'new uImage'
- create .its file, automatically filled-in properties are omitted
- call mkimage tool on a .its file
- mkimage calls dtc to create .itb image and assures that
missing properties are added
- .itb (new uImage) is uploaded onto the target and used therein
d) Unique identifiers
To identify FIT sub-nodes representing images, hashes, configurations (which
are defined in the following sections), the "unit name" of the given sub-node
is used as it's identifier as it assures uniqueness without additional
checking required.
3) Root node properties
-----------------------
Root node of the uImage Tree should have the following layout:
/ o image-tree
|- description = "image description"
|- timestamp = <12399321>
|- #address-cells = <1>
|
o images
| |
| o img@1 {...}
| o img@2 {...}
| ...
|
o configurations
|- default = "cfg@1"
|
o cfg@1 {...}
o cfg@2 {...}
...
Optional property:
- description : Textual description of the uImage
Mandatory property:
- timestamp : Last image modification time being counted in seconds since
1970-01-01 00:00:00 - to be automatically calculated by mkimage tool.
Conditionally mandatory property:
- #address-cells : Number of 32bit cells required to represent entry and
load addresses supplied within sub-image nodes. May be omitted when no
entry or load addresses are used.
Mandatory node:
- images : This node contains a set of sub-nodes, each of them representing
single component sub-image (like kernel, ramdisk, etc.). At least one
sub-image is required.
Optional node:
- configurations : Contains a set of available configuration nodes and
defines a default configuration.
4) '/images' node
-----------------
This node is a container node for component sub-image nodes. Each sub-node of
the '/images' node should have the following layout:
o image@1
|- description = "component sub-image description"
|- data = /incbin/("path/to/data/file.bin")
|- type = "sub-image type name"
|- arch = "ARCH name"
|- os = "OS name"
|- compression = "compression name"
|- load = <00000000>
|- entry = <00000000>
|
o hash@1 {...}
o hash@2 {...}
...
Mandatory properties:
- description : Textual description of the component sub-image
- type : Name of component sub-image type, supported types are:
"standalone", "kernel", "ramdisk", "firmware", "script", "filesystem",
"fdt".
- data : Path to the external file which contains this node's binary data.
- compression : Compression used by included data. Supported compressions
are "gzip" and "bzip2". If no compression is used compression property
should be set to "none".
Conditionally mandatory property:
- os : OS name, mandatory for type="kernel", valid OS names are: "openbsd",
"netbsd", "freebsd", "4_4bsd", "linux", "svr4", "esix", "solaris", "irix",
"sco", "dell", "ncr", "lynxos", "vxworks", "psos", "qnx", "u_boot",
"rtems", "artos", "unity".
- arch : Architecture name, mandatory for types: "standalone", "kernel",
"firmware", "ramdisk" and "fdt". Valid architecture names are: "alpha",
"arm", "i386", "ia64", "mips", "mips64", "ppc", "s390", "sh", "sparc",
"sparc64", "m68k", "nios", "microblaze", "nios2", "blackfin", "avr32",
"st200".
- entry : entry point address, address size is determined by
'#address-cells' property of the root node. Mandatory for for types:
"standalone" and "kernel".
- load : load address, address size is determined by '#address-cells'
property of the root node. Mandatory for types: "standalone" and "kernel".
Optional nodes:
- hash@1 : Each hash sub-node represents separate hash or checksum
calculated for node's data according to specified algorithm.
5) Hash nodes
-------------
o hash@1
|- algo = "hash or checksum algorithm name"
|- value = [hash or checksum value]
Mandatory properties:
- algo : Algorithm name, supported are "crc32", "md5" and "sha1".
- value : Actual checksum or hash value, correspondingly 4, 16 or 20 bytes
long.
6) '/configurations' node
-------------------------
The 'configurations' node is optional. If present, it allows to create a
convenient, labeled boot configurations, which combine together kernel images
with their ramdisks and fdt blobs.
The 'configurations' node has has the following structure:
o configurations
|- default = "default configuration sub-node unit name"
|
o config@1 {...}
o config@2 {...}
...
Optional property:
- default : Selects one of the configuration sub-nodes as a default
configuration.
Mandatory nodes:
- configuration-sub-node-unit-name : At least one of the configuration
sub-nodes is required.
7) Configuration nodes
----------------------
Each configuration has the following structure:
o config@1
|- description = "configuration description"
|- kernel = "kernel sub-node unit name"
|- ramdisk = "ramdisk sub-node unit name"
|- fdt = "fdt sub-node unit-name"
Mandatory properties:
- description : Textual configuration description.
- kernel : Unit name of the corresponding kernel image (image sub-node of a
"kernel" type).
Optional properties:
- ramdisk : Unit name of the corresponding ramdisk image (component image
node of a "ramdisk" type).
- fdt : Unit name of the corresponding fdt blob (component image node of a
"fdt type").
The FDT blob is required to properly boot FDT based kernel, so the minimal
configuration for 2.6 FDT kernel is (kernel, fdt) pair.
Older, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases
'struct bd_info' must be passed instead of FDT blob, thus fdt property *must
not* be specified in a configuration node.
8) Examples
-----------
Please see examples/*.its for actual image source files.