diff options
| -rw-r--r-- | README | 30 | ||||
| -rw-r--r-- | doc/uImage.FIT/command_syntax_extensions.txt | 191 | ||||
| -rw-r--r-- | doc/uImage.FIT/howto.txt | 296 | ||||
| -rw-r--r-- | doc/uImage.FIT/kernel.its | 34 | ||||
| -rw-r--r-- | doc/uImage.FIT/kernel_fdt.its | 48 | ||||
| -rw-r--r-- | doc/uImage.FIT/multi.its | 124 | ||||
| -rw-r--r-- | doc/uImage.FIT/source_file_format.txt | 262 |
7 files changed, 981 insertions, 4 deletions
@@ -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 0000000000..b8b50ffae9 --- /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@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 diff --git a/doc/uImage.FIT/howto.txt b/doc/uImage.FIT/howto.txt new file mode 100644 index 0000000000..35ab97d32e --- /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). diff --git a/doc/uImage.FIT/kernel.its b/doc/uImage.FIT/kernel.its new file mode 100644 index 0000000000..d1a5939115 --- /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@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"; + }; + }; +}; diff --git a/doc/uImage.FIT/kernel_fdt.its b/doc/uImage.FIT/kernel_fdt.its new file mode 100644 index 0000000000..fd6dee2571 --- /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@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"; + }; + }; +}; diff --git a/doc/uImage.FIT/multi.its b/doc/uImage.FIT/multi.its new file mode 100644 index 0000000000..b9929623b4 --- /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@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"; + }; + }; +}; diff --git a/doc/uImage.FIT/source_file_format.txt b/doc/uImage.FIT/source_file_format.txt new file mode 100644 index 0000000000..3f7104f958 --- /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@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. |