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