mirror of
https://github.com/AsahiLinux/u-boot
synced 2024-12-25 12:33:41 +00:00
5f65826b1b
The Device Tree Compiler (DTC) used to have its master
repository located on jdl.com. While it is still there,
its official, new, shiny location is on kernel.org here:
git://git.kernel.org/pub/scm/utils/dtc/dtc.git
Update a few references to point there instead.
Signed-off-by: Jon Loeliger <jdl@jdl.com>
Acked-by: Simon Glass <sjg@chromium.org>
300 lines
11 KiB
Text
300 lines
11 KiB
Text
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
|
|
|
|
git://git.kernel.org/pub/scm/utils/dtc/dtc.git
|
|
|
|
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/uImage.FIT/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 file(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
|
|
doc/uImage.FIT/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 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 doc/uImage.FIT/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 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 doc/uImage.FIT/multi.its for an image source file that allows more
|
|
sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs).
|