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>master
parent
1ec73761d2
commit
3310c549a7
@ -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 |
@ -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). |
@ -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"; |
||||
}; |
||||
}; |
||||
}; |
@ -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"; |
||||
}; |
||||
}; |
||||
}; |
@ -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"; |
||||
}; |
||||
}; |
||||
}; |
@ -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. |
Loading…
Reference in new issue