diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.korat | 51 | ||||
| -rw-r--r-- | doc/README.mips | 57 | ||||
| -rw-r--r-- | doc/README.sata | 68 | ||||
| -rw-r--r-- | doc/README.sh | 51 | ||||
| -rw-r--r-- | doc/uImage.FIT/command_syntax_extensions.txt | 191 | ||||
| -rw-r--r-- | doc/uImage.FIT/howto.txt | 297 | ||||
| -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 |
10 files changed, 1179 insertions, 4 deletions
diff --git a/doc/README.korat b/doc/README.korat new file mode 100644 index 0000000..0a59f40 --- /dev/null +++ b/doc/README.korat @@ -0,0 +1,51 @@ +The Korat board has two NOR flashes, FLASH0 and FLASH1, which are connected to +chip select 0 and 1, respectively. FLASH0 contains 16 MiB, and is mapped to +addresses 0xFF000000 - 0xFFFFFFFF as U-Boot Flash Bank #2. FLASH1 contains +from 16 to 128 MiB, and is mapped to 0xF?000000 - 0xF7FFFFFF as U-Boot Flash +Bank #1 (with the starting address depending on the flash size detected at +runtime). The write-enable pin on FLASH0 is disabled, so the contents of FLASH0 +cannot be modified in the field. This also prevents FLASH0 from executing +commands to return chip information, so its configuration is hard-coded in +U-Boot. + +There are two versions of U-Boot for Korat: "permanent" and "upgradable". The +permanent U-Boot is pre-programmed at the top of FLASH0, e.g., at addresses +0xFFFA0000 - 0xFFFFFFFF for the current 384 KiB size. The upgradable U-Boot is +located 256 KiB from the top of FLASH1, e.g. at addresses 0xF7F6000 - 0xF7FC0000 +for the current 384 KiB size. FLASH1 addresses 0xF7FE0000 - 0xF7FF0000 are +used for the U-Boot environmental parameters, and addresses 0xF7FC0000 - +0xF7FDFFFF are used for the redundant copy of the parameters. These locations +are used by both versions of U-Boot. + +On booting, the permanent U-Boot in FLASH0 begins executing. After performing +minimal setup, it monitors the state of the board's Reset switch (GPIO47). If +the switch is sensed as open before a timeout period, then U-Boot branches to +address 0xF7FBFFFC. This causes the upgradable U-Boot to execute from the +beginning. If the switch remains closed thoughout the timeout period, the +permanent U-Boot activates the on-board buzzer until the switch is sensed as +opened. It then continues to execute without branching to FLASH1. The effect +of this is that normally the Korat board boots its upgradable U-Boot, but, if +this has been corrupted, the user can boot the permanent U-Boot, which can then +be used to erase and reload FLASH1 as needed. + +Note that it is not necessary for the permanent U-Boot to have all the latest +features, but only that it have sufficient functionality (working "tftp", +"erase", "cp.b", etc.) to repair FLASH1. Also, the permanent U-Boot makes no +assumptions about the size of FLASH1 or the size of the upgradable U-Boot: it is +sufficient that the upgradable U-Boot can be started by a branch to 0xF7FBFFFC. + +The build sequence: + + make korat_config + make all perm=1 + +builds the permanent U-Boot by selecting loader file "u-boot.lds" and defining +preprocessor symbol "CONFIG_KORAT_PERMANENT". The default build: + + make korat_config + make all + +creates the upgradable U-Boot but selecting loader file "u-boot-F7FC.lds" and +leaving preprocessor symbol "CONFIG_KORAT_PERMANENT" undefined. + +2008-02-22, Larry Johnson <lrj@acm.org> diff --git a/doc/README.mips b/doc/README.mips new file mode 100644 index 0000000..85dea40 --- /dev/null +++ b/doc/README.mips @@ -0,0 +1,57 @@ + +Notes for the MIPS architecture port of U-Boot + +Toolchains +---------- + + http://www.denx.de/wiki/DULG/ELDK + ELDK < DULG < DENX + + http://www.emdebian.org/crosstools.html + Embedded Debian -- Cross-development toolchains + + http://buildroot.uclibc.org/ + Buildroot + +Known Issues +------------ + + * Little endian build problem + + If use non-ELDK toolchains, -EB will be set to CPPFLAGS. Therefore all + objects will be generated in big-endian format. + + * Cache incoherency issue caused by do_bootelf_exec() at cmd_elf.c + + Cache will be disabled before entering the loaded ELF image without + writing back and invalidating cache lines. This leads to cache + incoherency in most cases, unless the code gets loaded after U-Boot + re-initializes the cache. The more common uImage 'bootm' command does + not suffer this problem. + + [workaround] To avoid this cache incoherency, + 1) insert flush_cache(all) before calling dcache_disable(), or + 2) fix dcache_disable() to do both flushing and disabling cache. + + * Note that Linux users need to kill dcache_disable() in do_bootelf_exec() + or override do_bootelf_exec() not to disable I-/D-caches, because most + Linux/MIPS ports don't re-enable caches after entering kernel_entry. + +TODOs +----- + + * Probe CPU types, I-/D-cache and TLB size etc. automatically + + * Secondary cache support missing + + * Centralize the link directive files + + * Initialize TLB entries redardless of their use + + * R2000/R3000 class parts are not supported + + * Limited testing across different MIPS variants + + * Due to cache initialization issues, the DRAM on board must be + initialized in board specific assembler language before the cache init + code is run -- that is, initialize the DRAM in lowlevel_init(). diff --git a/doc/README.sata b/doc/README.sata new file mode 100644 index 0000000..d0ce667 --- /dev/null +++ b/doc/README.sata @@ -0,0 +1,68 @@ +1. SATA usage in U-boot + + There are two ways to operate the hard disk + + * Read/write raw blocks from/to SATA hard disk + * ext2load to read a file from ext2 file system + +1.0 How to read the SATA hard disk's information? + + => sata info + +SATA device 0: Model: ST3320620AS Firm: 3.AAD Ser#: 4QF01ZTN + Type: Hard Disk + Supports 48-bit addressing + Capacity: 305245.3 MB = 298.0 GB (625142448 x 512) + +1.1 How to raw write the kernel, file system, dtb to a SATA hard disk? + + Notes: Hard disk sectors are normally 512 bytes, so + 0x1000 sectors = 2 MBytes + + write kernel + => tftp 40000 /tftpboot/uImage.837x + => sata write 40000 0 2000 + + write ramdisk + => tftp 40000 /tftpboot/ramdisk.837x + => sata write 40000 2000 8000 + + write dtb + => tftp 40000 /tftpboot/mpc837xemds.dtb + => sata write 40000 a000 1000 + +1.2 How to raw read the kernel, file system, dtb from a SATA hard disk? + + load kernel + => sata read 200000 0 2000 + + load ramdisk + => sata read 1000000 2000 8000 + + load dtb + => sata read 2000000 a000 1000 + + boot + => bootm 200000 1000000 2000000 + +1.3 How to load an image from an ext2 file system in U-boot? + + U-boot doesn't support writing to an ext2 file system, so the + files must be written by other means (e.g. linux). + + => ext2ls sata 0:1 / + <DIR> 4096 . + <DIR> 4096 .. + <DIR> 16384 lost+found + 1352023 uImage.837x + 3646377 ramdisk.837x + 12288 mpc837xemds.dtb + 12 hello.txt + + => ext2load sata 0:1 200000 /uImage.837x + + => ext2load sata 0:1 1000000 /ramdisk.837x + + => ext2load sata 0:1 2000000 /mpc837xemds.dtb + + => bootm 200000 1000000 2000000 diff --git a/doc/README.sh b/doc/README.sh index 075d360..6baee08 100644 --- a/doc/README.sh +++ b/doc/README.sh @@ -1,6 +1,6 @@ U-Boot for Renesas SuperH - Last update 08/10/2007 by Nobuhiro Iwamatsu + Last update 01/18/2008 by Nobuhiro Iwamatsu ================================================================================ 0. What's this? @@ -18,7 +18,19 @@ U-Boot for Renesas SuperH 2. Supported CPUs 2.1. Renesas SH7750/SH7750R + This CPU has the SH4 core. + 2.2. Renesas SH7722 + This CPU has the SH4AL-DSP core. + + 2.3. Renesas SH7720 + This CPU has the SH3 core. + + 2.4. Renesas SH7710/SH7712 + This CPU has the SH3-DSP core and Ethernet controller. + + 2.5. Renesas SH7780 + This CPU has the SH4A core. ================================================================================ 3. Supported Boards @@ -26,10 +38,42 @@ U-Boot for Renesas SuperH 3.1. Hitachi UL MS7750SE01/MS7750RSE01 Board specific code is in board/ms7750se To use this board, type "make ms7750se_config". + Support devices are : + - SCIF + - SDRAM + - NOR Flash + - Marubun PCMCIA 3.2. Hitachi UL MS7722SE01 Board specific code is in board/ms7722se To use this board, type "make ms7722se_config". + Support devices are : + - SCIF + - SDRAM + - NOR Flash + - Marubun PCMCIA + - SMC91x ethernet + + 3.2. Hitachi UL MS7720ERP01 + Board specific code is in board/ms7720se + To use this board, type "make ms7720se_config". + Support devices are : + - SCIF + - SDRAM + - NOR Flash + - Marubun PCMCIA + + 3.3. Renesas R7780MP + Board specific code is in board/r7780mp + To use this board, type "make r7780mp_config". + Support devices are : + - SCIF + - DDR-SDRAM + - NOR Flash + - Compact Flash + - ASIX ethernet + - SH7780 PCI bridge + - RTL8110 ethernet ** README ** In SuperH, S-record and binary of made u-boot work on the memory. @@ -49,13 +93,12 @@ U-Boot for Renesas SuperH 5. Future I plan to support the following CPUs and boards. 5.1. CPUs - - SH7710/SH7712 (SH3) - - SH7780(SH4) + - SH7751R(SH4) - SH7785(SH4) 5.2. Boards - Many boards ;-) ================================================================================ -Copyright (c) 2007 +Copyright (c) 2007,2008 Nobuhiro Iwamatsu <iwamatsu@nigaur.org> diff --git a/doc/uImage.FIT/command_syntax_extensions.txt b/doc/uImage.FIT/command_syntax_extensions.txt new file mode 100644 index 0000000..6185cd8 --- /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 0000000..8065e9e --- /dev/null +++ b/doc/uImage.FIT/howto.txt @@ -0,0 +1,297 @@ +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 +doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is +in the current working directory; if desired, an alternative path can be +specified in the kernel.its file). Here's how to create the image and inspect +its contents: + +[on the host system] +$ mkimage -f kernel.its kernel.itb +DTC: dts->dtb on file "kernel.its" +$ +$ mkimage -l kernel.itb +FIT description: Simple image with single Linux kernel +Created: Tue Mar 11 17:26:15 2008 + Image 0 (kernel@1) + Description: Vanilla Linux kernel + Type: Kernel Image + Compression: gzip compressed + Data Size: 943347 Bytes = 921.24 kB = 0.90 MB + Architecture: PowerPC + OS: Linux + Load Address: 0x00000000 + Entry Point: 0x00000000 + Hash algo: crc32 + Hash value: 2ae2bb40 + Hash algo: sha1 + Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 + Default Configuration: 'config@1' + Configuration 0 (config@1) + Description: Boot Linux kernel + Kernel: kernel@1 + + +The resulting image file kernel.itb can be now transferred to the target, +inspected and booted (note that first three U-Boot commands below are shown +for completeness -- they are part of the standard booting procedure and not +specific to the new image format). + +[on the target system] +=> print nfsargs +nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath} +=> print addip +addip=setenv bootargs ${bootargs} ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:${netdev}:off panic=1 +=> run nfsargs addip +=> tftp 900000 /path/to/tftp/location/kernel.itb +Using FEC 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 doc/uImage.FIT/kernel_fdt.its like this +(note again, that both prerequisite data files are assumed to be present in +the current working directory -- image source file kernel_fdt.its can be +modified to take the files from some other location if needed): + +[on the host system] +$ mkimage -f kernel_fdt.its kernel_fdt.itb +DTC: dts->dtb on file "kernel_fdt.its" +$ +$ mkimage -l kernel_fdt.itb +FIT description: Simple image with single Linux kernel and FDT blob +Created: Tue Mar 11 16:29:22 2008 + Image 0 (kernel@1) + Description: Vanilla Linux kernel + Type: Kernel Image + Compression: gzip compressed + Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB + Architecture: PowerPC + OS: Linux + Load Address: 0x00000000 + Entry Point: 0x00000000 + Hash algo: crc32 + Hash value: 2c0cc807 + Hash algo: sha1 + Hash value: 264b59935470e42c418744f83935d44cdf59a3bb + Image 1 (fdt@1) + Description: Flattened Device Tree blob + Type: Flat Device Tree + Compression: uncompressed + Data Size: 16384 Bytes = 16.00 kB = 0.02 MB + Architecture: PowerPC + Hash algo: crc32 + Hash value: 0d655d71 + Hash algo: sha1 + Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def + Default Configuration: 'conf@1' + Configuration 0 (conf@1) + Description: Boot Linux kernel with FDT blob + Kernel: kernel@1 + FDT: fdt@1 + + +The resulting image file kernel_fdt.itb can be now transferred to the target, +inspected and booted: + +[on the target system] +=> tftp 900000 /path/to/tftp/location/kernel_fdt.itb +Using FEC 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 doc/uImage.FIT/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@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 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@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 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@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 0000000..c1244fb --- /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 doc/uImage.FIT/*.its for actual image source files. |