(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
+
+ 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/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
+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
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)
+image source file mkimage + dtc transfer to target
+ + ---------------> image file --------------------> bootm
+image data file(s)
+
+SPL usage
+---------
+
+The SPL can make use of the new image format as well, this traditionally
+is used to ship multiple device tree files within one image. Code in the SPL
+will choose the one matching the current board and append this to the
+U-Boot proper binary to be automatically used up by it.
+Aside from U-Boot proper and one device tree blob the SPL can load multiple,
+arbitrary image files as well. These binaries should be specified in their
+own subnode under the /images node, which should then be referenced from one or
+multiple /configurations subnodes. The required images must be enumerated in
+the "loadables" property as a list of strings.
+If a platform specific image source file (.its) is shipped with the U-Boot
+source, it can be specified using the CONFIG_SPL_FIT_SOURCE Kconfig symbol.
+In this case it will be automatically used by U-Boot's Makefile to generate
+the image.
+If a static source file is not flexible enough, CONFIG_SPL_FIT_GENERATOR
+can point to a script which generates this image source file during
+the build process. It gets passed a list of device tree files (taken from the
+CONFIG_OF_LIST symbol).
Example 1 -- old-style (non-FDT) kernel booting
-----------------------------------------------
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:
+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
$
$ 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
+Created: Tue Mar 11 17:26:15 2008
+ Image 0 (kernel)
+ Description: Vanilla Linux kernel
+ Type: Kernel Image
+ Compression: gzip compressed
+ Data Size: 943347 Bytes = 921.24 kB = 0.90 MB
Architecture: PowerPC
- OS: Linux
+ 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
+ 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
The resulting image file kernel.itb can be now transferred to the target,
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
+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
## 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)
+ Created: 2008-03-11 16:26:15 UTC
+ Image 0 (kernel)
Description: Vanilla Linux kernel
- Type: Kernel Image
+ Type: Kernel Image
Compression: gzip compressed
Data Start: 0x009000e0
Data Size: 943347 Bytes = 921.2 kB
Architecture: PowerPC
- OS: Linux
+ 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)
+ Default Configuration: 'config-1'
+ Configuration 0 (config-1)
Description: Boot Linux kernel
- Kernel: kernel@1
+ Kernel: kernel
=> bootm
## Booting kernel from FIT Image at 00900000 ...
- Using 'config@1' configuration
- Trying 'kernel@1' kernel subimage
+ Using 'config-1' configuration
+ Trying 'kernel' kernel subimage
Description: Vanilla Linux kernel
- Type: Kernel Image
+ Type: Kernel Image
Compression: gzip compressed
Data Start: 0x009000e0
Data Size: 943347 Bytes = 921.2 kB
Architecture: PowerPC
- OS: Linux
+ OS: Linux
Load Address: 0x00000000
Entry Point: 0x00000000
Hash algo: crc32
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):
+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
$
$ 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
+Created: Tue Mar 11 16:29:22 2008
+ Image 0 (kernel)
+ Description: Vanilla Linux kernel
+ Type: Kernel Image
+ Compression: gzip compressed
+ Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB
Architecture: PowerPC
- OS: Linux
+ 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
+ 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
+ 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
+ FDT: fdt-1
The resulting image file kernel_fdt.itb can be now transferred to the target,
[on the target system]
=> tftp 900000 /path/to/tftp/location/kernel_fdt.itb
-Using FEC ETHERNET device
+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)
+ Created: 2008-03-11 15:29:22 UTC
+ Image 0 (kernel)
Description: Vanilla Linux kernel
- Type: Kernel Image
+ Type: Kernel Image
Compression: gzip compressed
Data Start: 0x009000ec
Data Size: 1092037 Bytes = 1 MB
Architecture: PowerPC
- OS: Linux
+ OS: Linux
Load Address: 0x00000000
Entry Point: 0x00000000
Hash algo: crc32
Hash value: 2c0cc807
Hash algo: sha1
Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
- Image 1 (fdt@1)
+ Image 1 (fdt-1)
Description: Flattened Device Tree blob
- Type: Flat Device Tree
+ Type: Flat Device Tree
Compression: uncompressed
Data Start: 0x00a0abdc
Data Size: 16384 Bytes = 16 kB
Hash value: 0d655d71
Hash algo: sha1
Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
- Default Configuration: 'conf@1'
- Configuration 0 (conf@1)
+ Default Configuration: 'conf-1'
+ Configuration 0 (conf-1)
Description: Boot Linux kernel with FDT blob
- Kernel: kernel@1
- FDT: fdt@1
+ Kernel: kernel
+ FDT: fdt-1
=> bootm
## Booting kernel from FIT Image at 00900000 ...
- Using 'conf@1' configuration
- Trying 'kernel@1' kernel subimage
+ Using 'conf-1' configuration
+ Trying 'kernel' kernel subimage
Description: Vanilla Linux kernel
- Type: Kernel Image
+ Type: Kernel Image
Compression: gzip compressed
Data Start: 0x009000ec
Data Size: 1092037 Bytes = 1 MB
Architecture: PowerPC
- OS: Linux
+ OS: Linux
Load Address: 0x00000000
Entry Point: 0x00000000
Hash algo: crc32
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
+ Using 'conf-1' configuration
+ Trying 'fdt-1' FDT blob subimage
Description: Flattened Device Tree blob
- Type: Flat Device Tree
+ Type: Flat Device Tree
Compression: uncompressed
Data Start: 0x00a0abdc
Data Size: 16384 Bytes = 16 kB
Example 3 -- advanced booting
-----------------------------
-Refer to examples/multi.its for an image source file that allows more
+Refer to doc/uImage.FIT/multi.its for an image source file that allows more
sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs).
projects / oweals / u-boot.git / blobdiff