[U-Boot-Users] [PATCH 20/20] [new uImage] Add new uImage format documentation and examples
Bartlomiej Sieka
tur at semihalf.com
Wed Mar 12 21:12:31 CET 2008
From: Marian Balakowicz <m8 at semihalf.com>
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 at semihalf.com>
Signed-off-by: Bartlomiej Sieka <tur at semihalf.com>
---
README | 30 ++-
doc/uImage.FIT/command_syntax_extensions.txt | 191 +++++++++++++++++
doc/uImage.FIT/howto.txt | 296 ++++++++++++++++++++++++++
doc/uImage.FIT/kernel.its | 34 +++
doc/uImage.FIT/kernel_fdt.its | 48 ++++
doc/uImage.FIT/multi.its | 124 +++++++++++
doc/uImage.FIT/source_file_format.txt | 262 +++++++++++++++++++++++
7 files changed, 981 insertions(+), 4 deletions(-)
create mode 100644 doc/uImage.FIT/command_syntax_extensions.txt
create mode 100644 doc/uImage.FIT/howto.txt
create mode 100644 doc/uImage.FIT/kernel.its
create mode 100644 doc/uImage.FIT/kernel_fdt.its
create mode 100644 doc/uImage.FIT/multi.its
create mode 100644 doc/uImage.FIT/source_file_format.txt
diff --git a/README b/README
index 0ed47f0..26bd0cf 100644
--- a/README
+++ b/README
@@ -2684,6 +2684,14 @@ Some configuration options can be set using Environment Variables:
configuration from the BOOTP server, but not try to
load any image using TFTP
+ autoscript - if set to "yes" commands like "loadb", "loady",
+ "bootp", "tftpb", "rarpboot" and "nfs" will attempt
+ to automatically run script images (by internally
+ calling "autoscript").
+
+ autoscript_uname - if script image is in a format (FIT) this
+ variable is used to get script subimage unit name.
+
autostart - if set to "yes", an image loaded using the "bootp",
"rarpboot", "tftpboot" or "diskboot" commands will
be automatically started (by internally calling
@@ -2898,10 +2906,24 @@ o If neither SROM nor the environment contain a MAC address, an error
Image Formats:
==============
-The "boot" commands of this monitor operate on "image" files which
-can be basicly anything, preceeded by a special header; see the
-definitions in include/image.h for details; basicly, the header
-defines the following image properties:
+U-Boot is capable of booting (and performing other auxiliary operations on)
+images in two formats:
+
+New uImage format (FIT)
+-----------------------
+
+Flexible and powerful format based on Flattened Image Tree -- FIT (similar
+to Flattened Device Tree). It allows the use of images with multiple
+components (several kernels, ramdisks, etc.), with contents protected by
+SHA1, MD5 or CRC32. More details are found in the doc/uImage.FIT directory.
+
+
+Old uImage format
+-----------------
+
+Old image format is based on binary files which can be basically anything,
+preceded by a special header; see the definitions in include/image.h for
+details; basically, the header defines the following image properties:
* Target Operating System (Provisions for OpenBSD, NetBSD, FreeBSD,
4.4BSD, Linux, SVR4, Esix, Solaris, Irix, SCO, Dell, NCR, VxWorks,
diff --git a/doc/uImage.FIT/command_syntax_extensions.txt b/doc/uImage.FIT/command_syntax_extensions.txt
new file mode 100644
index 0000000..b8b50ff
--- /dev/null
+++ b/doc/uImage.FIT/command_syntax_extensions.txt
@@ -0,0 +1,191 @@
+Command syntax extensions for the new uImage format
+===================================================
+
+Author: Bartlomiej Sieka <tur at 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 at 1" stored in a new uImage located at 200000:
+bootm 200000:kernel at 1
+
+- boot configuration "cfg at 1" from a new uImage located at 200000:
+bootm 200000#cfg at 1
+
+- boot "kernel at 1" from a new uImage at 200000 with initrd "ramdisk at 2" found in
+ some other new uImage stored at address 800000:
+bootm 200000:kernel at 1 800000:ramdisk at 2
+
+- boot "kernel at 2" from a new uImage at 200000, with initrd "ramdisk at 1" and FDT
+ "fdt at 1", both stored in some other new uImage located at 800000:
+bootm 200000:kernel at 1 800000:ramdisk at 1 800000:fdt at 1
+
+- boot kernel "kernel at 2" with initrd "ramdisk at 2", both stored in a new uImage
+ at address 200000, with a raw FDT blob stored at address 600000:
+bootm 200000:kernel at 2 200000:ramdisk at 2 600000
+
+- boot kernel "kernel at 2" from new uImage at 200000 with FDT "fdt at 1" from the
+ same new uImage:
+bootm 200000:kernel at 2 - 200000:fdt at 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 at 1
+Last command is equivalent to:
+bootm 200000:kernel at 1
+
+tftp 200000 /tftpboot/uImage
+bootm 400000:kernel at 1 :ramdisk at 1
+Last command is equivalent to:
+bootm 400000:kernel at 1 400000:ramdisk at 1
+
+tftp 200000 /tftpboot/uImage
+bootm :kernel at 1 400000:ramdisk at 1 :fdt at 1
+Last command is equivalent to:
+bootm 200000:kernel at 1 400000:ramdisk at 1 400000:fdt at 1
diff --git a/doc/uImage.FIT/howto.txt b/doc/uImage.FIT/howto.txt
new file mode 100644
index 0000000..35ab97d
--- /dev/null
+++ b/doc/uImage.FIT/howto.txt
@@ -0,0 +1,296 @@
+How to use images in the new image format
+=========================================
+
+Author: Bartlomiej Sieka <tur at 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 at 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 at 1'
+ Configuration 0 (config at 1)
+ Description: Boot Linux kernel
+ Kernel: kernel at 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 at 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 at 1'
+ Configuration 0 (config at 1)
+ Description: Boot Linux kernel
+ Kernel: kernel at 1
+
+=> bootm
+## Booting kernel from FIT Image at 00900000 ...
+ Using 'config at 1' configuration
+ Trying 'kernel at 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 at 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 at 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 at 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 at 1'
+ Configuration 0 (conf at 1)
+ Description: Boot Linux kernel with FDT blob
+ Kernel: kernel at 1
+ FDT: fdt at 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 at 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 at 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 at 1'
+ Configuration 0 (conf at 1)
+ Description: Boot Linux kernel with FDT blob
+ Kernel: kernel at 1
+ FDT: fdt at 1
+=> bootm
+## Booting kernel from FIT Image at 00900000 ...
+ Using 'conf at 1' configuration
+ Trying 'kernel at 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 at 1' configuration
+ Trying 'fdt at 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 at 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).
diff --git a/doc/uImage.FIT/kernel.its b/doc/uImage.FIT/kernel.its
new file mode 100644
index 0000000..d1a5939
--- /dev/null
+++ b/doc/uImage.FIT/kernel.its
@@ -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 at 1 {
+ description = "Vanilla Linux kernel";
+ data = /incbin/("./vmlinux.bin.gz");
+ type = "kernel";
+ arch = "ppc";
+ os = "linux";
+ compression = "gzip";
+ load = <00000000>;
+ entry = <00000000>;
+ hash at 1 {
+ algo = "crc32";
+ };
+ hash at 2 {
+ algo = "sha1";
+ };
+ };
+ };
+
+ configurations {
+ default = "config at 1";
+ config at 1 {
+ description = "Boot Linux kernel";
+ kernel = "kernel at 1";
+ };
+ };
+};
diff --git a/doc/uImage.FIT/kernel_fdt.its b/doc/uImage.FIT/kernel_fdt.its
new file mode 100644
index 0000000..fd6dee2
--- /dev/null
+++ b/doc/uImage.FIT/kernel_fdt.its
@@ -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 at 1 {
+ description = "Vanilla Linux kernel";
+ data = /incbin/("./vmlinux.bin.gz");
+ type = "kernel";
+ arch = "ppc";
+ os = "linux";
+ compression = "gzip";
+ load = <00000000>;
+ entry = <00000000>;
+ hash at 1 {
+ algo = "crc32";
+ };
+ hash at 2 {
+ algo = "sha1";
+ };
+ };
+ fdt at 1 {
+ description = "Flattened Device Tree blob";
+ data = /incbin/("./target.dtb");
+ type = "flat_dt";
+ arch = "ppc";
+ compression = "none";
+ hash at 1 {
+ algo = "crc32";
+ };
+ hash at 2 {
+ algo = "sha1";
+ };
+ };
+ };
+
+ configurations {
+ default = "conf at 1";
+ conf at 1 {
+ description = "Boot Linux kernel with FDT blob";
+ kernel = "kernel at 1";
+ fdt = "fdt at 1";
+ };
+ };
+};
diff --git a/doc/uImage.FIT/multi.its b/doc/uImage.FIT/multi.its
new file mode 100644
index 0000000..b992962
--- /dev/null
+++ b/doc/uImage.FIT/multi.its
@@ -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 at 1 {
+ description = "vanilla-2.6.23";
+ data = /incbin/("./vmlinux.bin.gz");
+ type = "kernel";
+ arch = "ppc";
+ os = "linux";
+ compression = "gzip";
+ load = <00000000>;
+ entry = <00000000>;
+ hash at 1 {
+ algo = "md5";
+ };
+ hash at 2 {
+ algo = "sha1";
+ };
+ };
+
+ kernel at 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 at 1 {
+ algo = "sha1";
+ };
+ };
+
+ kernel at 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 at 1 {
+ algo = "md5";
+ };
+ };
+
+ ramdisk at 1 {
+ description = "eldk-4.2-ramdisk";
+ data = /incbin/("./eldk-4.2-ramdisk");
+ type = "ramdisk";
+ arch = "ppc";
+ compression = "gzip";
+ hash at 1 {
+ algo = "sha1";
+ };
+ };
+
+ ramdisk at 2 {
+ description = "eldk-3.1-ramdisk";
+ data = /incbin/("./eldk-3.1-ramdisk");
+ type = "ramdisk";
+ arch = "ppc";
+ compression = "gzip";
+ hash at 1 {
+ algo = "crc32";
+ };
+ };
+
+ fdt at 1 {
+ description = "tqm5200-fdt";
+ data = /incbin/("./tqm5200.dtb");
+ type = "flat_dt";
+ arch = "ppc";
+ compression = "none";
+ hash at 1 {
+ algo = "crc32";
+ };
+ };
+
+ fdt at 2 {
+ description = "tqm5200s-fdt";
+ data = /incbin/("./tqm5200s.dtb");
+ type = "flat_dt";
+ arch = "ppc";
+ compression = "none";
+ load = <00700000>;
+ hash at 1 {
+ algo = "sha1";
+ };
+ };
+
+ };
+
+ configurations {
+ default = "config at 1";
+
+ config at 1 {
+ description = "tqm5200 vanilla-2.6.23 configuration";
+ kernel = "kernel at 1";
+ ramdisk = "ramdisk at 1";
+ fdt = "fdt at 1";
+ };
+
+ config at 2 {
+ description = "tqm5200s denx-2.6.23 configuration";
+ kernel = "kernel at 2";
+ ramdisk = "ramdisk at 1";
+ fdt = "fdt at 2";
+ };
+
+ config at 3 {
+ description = "tqm5200s denx-2.4.25 configuration";
+ kernel = "kernel at 3";
+ ramdisk = "ramdisk at 2";
+ };
+ };
+};
diff --git a/doc/uImage.FIT/source_file_format.txt b/doc/uImage.FIT/source_file_format.txt
new file mode 100644
index 0000000..3f7104f
--- /dev/null
+++ b/doc/uImage.FIT/source_file_format.txt
@@ -0,0 +1,262 @@
+U-boot new uImage source file format (bindings definition)
+==========================================================
+
+Author: Marian Balakowicz <m8 at 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 at 1 {...}
+ | o img at 2 {...}
+ | ...
+ |
+ o configurations
+ |- default = "cfg at 1"
+ |
+ o cfg at 1 {...}
+ o cfg at 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 at 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 at 1 {...}
+ o hash at 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 at 1 : Each hash sub-node represents separate hash or checksum
+ calculated for node's data according to specified algorithm.
+
+
+5) Hash nodes
+-------------
+
+o hash at 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 at 1 {...}
+ o config at 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 at 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.
More information about the U-Boot
mailing list