[new uImage] Add new uImage format documentation and examples

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>

1 files changed, 296 insertions, 0 deletions

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@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).