13310c549SMarian BalakowiczU-boot new uImage source file format (bindings definition) 23310c549SMarian Balakowicz========================================================== 33310c549SMarian Balakowicz 43310c549SMarian BalakowiczAuthor: Marian Balakowicz <m8@semihalf.com> 53310c549SMarian Balakowicz 63310c549SMarian Balakowicz1) Introduction 73310c549SMarian Balakowicz--------------- 83310c549SMarian Balakowicz 93310c549SMarian BalakowiczEvolution of the 2.6 Linux kernel for embedded PowerPC systems introduced new 103310c549SMarian Balakowiczbooting method which requires that hardware description is available to the 113310c549SMarian Balakowiczkernel in the form of Flattened Device Tree. 123310c549SMarian Balakowicz 133310c549SMarian BalakowiczBooting with a Flattened Device Tree is much more flexible and is intended to 143310c549SMarian Balakowiczreplace direct passing of 'struct bd_info' which was used to boot pre-FDT 153310c549SMarian Balakowiczkernels. 163310c549SMarian Balakowicz 173310c549SMarian BalakowiczHowever, U-boot needs to support both techniques to provide backward 183310c549SMarian Balakowiczcompatibility for platforms which are not FDT ready. Number of elements 193310c549SMarian Balakowiczplaying role in the booting process has increased and now includes the FDT 203310c549SMarian Balakowiczblob. Kernel image, FDT blob and possibly ramdisk image - all must be placed 213310c549SMarian Balakowiczin the system memory and passed to bootm as a arguments. Some of them may be 223310c549SMarian Balakowiczmissing: FDT is not present for legacy platforms, ramdisk is always optional. 233310c549SMarian BalakowiczAdditionally, old uImage format has been extended to support multi sub-images 243310c549SMarian Balakowiczbut the support is limited by simple format of the legacy uImage structure. 253310c549SMarian BalakowiczSingle binary header 'struct image_header' is not flexible enough to cover all 263310c549SMarian Balakowiczpossible scenarios. 273310c549SMarian Balakowicz 283310c549SMarian BalakowiczAll those factors combined clearly show that there is a need for new, more 293310c549SMarian Balakowiczflexible, multi component uImage format. 303310c549SMarian Balakowicz 313310c549SMarian Balakowicz 323310c549SMarian Balakowicz2) New uImage format assumptions 333310c549SMarian Balakowicz-------------------------------- 343310c549SMarian Balakowicz 353310c549SMarian Balakowicza) Implementation 363310c549SMarian Balakowicz 373310c549SMarian BalakowiczLibfdt has been selected for the new uImage format implementation as (1) it 383310c549SMarian Balakowiczprovides needed functionality, (2) is actively maintained and developed and 393310c549SMarian Balakowicz(3) increases code reuse as it is already part of the U-boot source tree. 403310c549SMarian Balakowicz 413310c549SMarian Balakowiczb) Terminology 423310c549SMarian Balakowicz 433310c549SMarian BalakowiczThis document defines new uImage structure by providing FDT bindings for new 443310c549SMarian BalakowiczuImage internals. Bindings are defined from U-boot perspective, i.e. describe 453310c549SMarian Balakowiczfinal form of the uImage at the moment when it reaches U-boot. User 463310c549SMarian Balakowiczperspective may be simpler, as some of the properties (like timestamps and 473310c549SMarian Balakowiczhashes) will need to be filled in automatically by the U-boot mkimage tool. 483310c549SMarian Balakowicz 493310c549SMarian BalakowiczTo avoid confusion with the kernel FDT the following naming convention is 503310c549SMarian Balakowiczproposed for the new uImage format related terms: 513310c549SMarian Balakowicz 523310c549SMarian BalakowiczFIT - Flattened uImage Tree 533310c549SMarian Balakowicz 543310c549SMarian BalakowiczFIT is formally a flattened device tree (in the libfdt meaning), which 553310c549SMarian Balakowiczconforms to bindings defined in this document. 563310c549SMarian Balakowicz 573310c549SMarian Balakowicz.its - image tree source 583310c549SMarian Balakowicz.itb - image tree blob 593310c549SMarian Balakowicz 603310c549SMarian Balakowiczc) Image building procedure 613310c549SMarian Balakowicz 623310c549SMarian BalakowiczThe following picture shows how the new uImage is prepared. Input consists of 633310c549SMarian Balakowiczimage source file (.its) and a set of data files. Image is created with the 643310c549SMarian Balakowiczhelp of standard U-boot mkimage tool which in turn uses dtc (device tree 65*61ffc17aSMasahiro Yamadacompiler) to produce image tree blob (.itb). Resulting .itb file is the 663310c549SMarian Balakowiczactual binary of a new uImage. 673310c549SMarian Balakowicz 683310c549SMarian Balakowicz 693310c549SMarian Balakowicztqm5200.its 703310c549SMarian Balakowicz+ 713310c549SMarian Balakowiczvmlinux.bin.gz mkimage + dtc xfer to target 723310c549SMarian Balakowiczeldk-4.2-ramdisk --------------> tqm5200.itb --------------> bootm 733310c549SMarian Balakowicztqm5200.dtb /|\ 743310c549SMarian Balakowicz... | 753310c549SMarian Balakowicz 'new uImage' 763310c549SMarian Balakowicz 773310c549SMarian Balakowicz - create .its file, automatically filled-in properties are omitted 783310c549SMarian Balakowicz - call mkimage tool on a .its file 793310c549SMarian Balakowicz - mkimage calls dtc to create .itb image and assures that 803310c549SMarian Balakowicz missing properties are added 813310c549SMarian Balakowicz - .itb (new uImage) is uploaded onto the target and used therein 823310c549SMarian Balakowicz 833310c549SMarian Balakowicz 843310c549SMarian Balakowiczd) Unique identifiers 853310c549SMarian Balakowicz 863310c549SMarian BalakowiczTo identify FIT sub-nodes representing images, hashes, configurations (which 873310c549SMarian Balakowiczare defined in the following sections), the "unit name" of the given sub-node 883310c549SMarian Balakowiczis used as it's identifier as it assures uniqueness without additional 893310c549SMarian Balakowiczchecking required. 903310c549SMarian Balakowicz 913310c549SMarian Balakowicz 923310c549SMarian Balakowicz3) Root node properties 933310c549SMarian Balakowicz----------------------- 943310c549SMarian Balakowicz 953310c549SMarian BalakowiczRoot node of the uImage Tree should have the following layout: 963310c549SMarian Balakowicz 973310c549SMarian Balakowicz/ o image-tree 983310c549SMarian Balakowicz |- description = "image description" 993310c549SMarian Balakowicz |- timestamp = <12399321> 1003310c549SMarian Balakowicz |- #address-cells = <1> 1013310c549SMarian Balakowicz | 1023310c549SMarian Balakowicz o images 1033310c549SMarian Balakowicz | | 1043310c549SMarian Balakowicz | o img@1 {...} 1053310c549SMarian Balakowicz | o img@2 {...} 1063310c549SMarian Balakowicz | ... 1073310c549SMarian Balakowicz | 1083310c549SMarian Balakowicz o configurations 1093310c549SMarian Balakowicz |- default = "cfg@1" 1103310c549SMarian Balakowicz | 1113310c549SMarian Balakowicz o cfg@1 {...} 1123310c549SMarian Balakowicz o cfg@2 {...} 1133310c549SMarian Balakowicz ... 1143310c549SMarian Balakowicz 1153310c549SMarian Balakowicz 1163310c549SMarian Balakowicz Optional property: 1173310c549SMarian Balakowicz - description : Textual description of the uImage 1183310c549SMarian Balakowicz 1193310c549SMarian Balakowicz Mandatory property: 1203310c549SMarian Balakowicz - timestamp : Last image modification time being counted in seconds since 1213310c549SMarian Balakowicz 1970-01-01 00:00:00 - to be automatically calculated by mkimage tool. 1223310c549SMarian Balakowicz 1233310c549SMarian Balakowicz Conditionally mandatory property: 1243310c549SMarian Balakowicz - #address-cells : Number of 32bit cells required to represent entry and 1253310c549SMarian Balakowicz load addresses supplied within sub-image nodes. May be omitted when no 1263310c549SMarian Balakowicz entry or load addresses are used. 1273310c549SMarian Balakowicz 1283310c549SMarian Balakowicz Mandatory node: 1293310c549SMarian Balakowicz - images : This node contains a set of sub-nodes, each of them representing 1303310c549SMarian Balakowicz single component sub-image (like kernel, ramdisk, etc.). At least one 1313310c549SMarian Balakowicz sub-image is required. 1323310c549SMarian Balakowicz 1333310c549SMarian Balakowicz Optional node: 1343310c549SMarian Balakowicz - configurations : Contains a set of available configuration nodes and 1353310c549SMarian Balakowicz defines a default configuration. 1363310c549SMarian Balakowicz 1373310c549SMarian Balakowicz 1383310c549SMarian Balakowicz4) '/images' node 1393310c549SMarian Balakowicz----------------- 1403310c549SMarian Balakowicz 1413310c549SMarian BalakowiczThis node is a container node for component sub-image nodes. Each sub-node of 1423310c549SMarian Balakowiczthe '/images' node should have the following layout: 1433310c549SMarian Balakowicz 1443310c549SMarian Balakowicz o image@1 1453310c549SMarian Balakowicz |- description = "component sub-image description" 1463310c549SMarian Balakowicz |- data = /incbin/("path/to/data/file.bin") 1473310c549SMarian Balakowicz |- type = "sub-image type name" 1483310c549SMarian Balakowicz |- arch = "ARCH name" 1493310c549SMarian Balakowicz |- os = "OS name" 1503310c549SMarian Balakowicz |- compression = "compression name" 1513310c549SMarian Balakowicz |- load = <00000000> 1523310c549SMarian Balakowicz |- entry = <00000000> 1533310c549SMarian Balakowicz | 1543310c549SMarian Balakowicz o hash@1 {...} 1553310c549SMarian Balakowicz o hash@2 {...} 1563310c549SMarian Balakowicz ... 1573310c549SMarian Balakowicz 1583310c549SMarian Balakowicz Mandatory properties: 1593310c549SMarian Balakowicz - description : Textual description of the component sub-image 1603310c549SMarian Balakowicz - type : Name of component sub-image type, supported types are: 1613310c549SMarian Balakowicz "standalone", "kernel", "ramdisk", "firmware", "script", "filesystem", 1623310c549SMarian Balakowicz "fdt". 1633310c549SMarian Balakowicz - data : Path to the external file which contains this node's binary data. 1643310c549SMarian Balakowicz - compression : Compression used by included data. Supported compressions 1653310c549SMarian Balakowicz are "gzip" and "bzip2". If no compression is used compression property 1663310c549SMarian Balakowicz should be set to "none". 1673310c549SMarian Balakowicz 1683310c549SMarian Balakowicz Conditionally mandatory property: 1693310c549SMarian Balakowicz - os : OS name, mandatory for type="kernel", valid OS names are: "openbsd", 1703310c549SMarian Balakowicz "netbsd", "freebsd", "4_4bsd", "linux", "svr4", "esix", "solaris", "irix", 1713310c549SMarian Balakowicz "sco", "dell", "ncr", "lynxos", "vxworks", "psos", "qnx", "u_boot", 172f5ed9e39SPeter Tyser "rtems", "unity", "integrity". 1733310c549SMarian Balakowicz - arch : Architecture name, mandatory for types: "standalone", "kernel", 1743310c549SMarian Balakowicz "firmware", "ramdisk" and "fdt". Valid architecture names are: "alpha", 1753310c549SMarian Balakowicz "arm", "i386", "ia64", "mips", "mips64", "ppc", "s390", "sh", "sparc", 1761117cbf2SThomas Chou "sparc64", "m68k", "microblaze", "nios2", "blackfin", "avr32", "st200". 1773310c549SMarian Balakowicz - entry : entry point address, address size is determined by 1783310c549SMarian Balakowicz '#address-cells' property of the root node. Mandatory for for types: 1793310c549SMarian Balakowicz "standalone" and "kernel". 1803310c549SMarian Balakowicz - load : load address, address size is determined by '#address-cells' 1813310c549SMarian Balakowicz property of the root node. Mandatory for types: "standalone" and "kernel". 1823310c549SMarian Balakowicz 1833310c549SMarian Balakowicz Optional nodes: 1843310c549SMarian Balakowicz - hash@1 : Each hash sub-node represents separate hash or checksum 1853310c549SMarian Balakowicz calculated for node's data according to specified algorithm. 1863310c549SMarian Balakowicz 1873310c549SMarian Balakowicz 1883310c549SMarian Balakowicz5) Hash nodes 1893310c549SMarian Balakowicz------------- 1903310c549SMarian Balakowicz 1913310c549SMarian Balakowiczo hash@1 1923310c549SMarian Balakowicz |- algo = "hash or checksum algorithm name" 1933310c549SMarian Balakowicz |- value = [hash or checksum value] 1943310c549SMarian Balakowicz 1953310c549SMarian Balakowicz Mandatory properties: 1963310c549SMarian Balakowicz - algo : Algorithm name, supported are "crc32", "md5" and "sha1". 1973310c549SMarian Balakowicz - value : Actual checksum or hash value, correspondingly 4, 16 or 20 bytes 1983310c549SMarian Balakowicz long. 1993310c549SMarian Balakowicz 2003310c549SMarian Balakowicz 2013310c549SMarian Balakowicz6) '/configurations' node 2023310c549SMarian Balakowicz------------------------- 2033310c549SMarian Balakowicz 2043310c549SMarian BalakowiczThe 'configurations' node is optional. If present, it allows to create a 2053310c549SMarian Balakowiczconvenient, labeled boot configurations, which combine together kernel images 2063310c549SMarian Balakowiczwith their ramdisks and fdt blobs. 2073310c549SMarian Balakowicz 2083310c549SMarian BalakowiczThe 'configurations' node has has the following structure: 2093310c549SMarian Balakowicz 2103310c549SMarian Balakowiczo configurations 2113310c549SMarian Balakowicz |- default = "default configuration sub-node unit name" 2123310c549SMarian Balakowicz | 2133310c549SMarian Balakowicz o config@1 {...} 2143310c549SMarian Balakowicz o config@2 {...} 2153310c549SMarian Balakowicz ... 2163310c549SMarian Balakowicz 2173310c549SMarian Balakowicz 2183310c549SMarian Balakowicz Optional property: 2193310c549SMarian Balakowicz - default : Selects one of the configuration sub-nodes as a default 2203310c549SMarian Balakowicz configuration. 2213310c549SMarian Balakowicz 2223310c549SMarian Balakowicz Mandatory nodes: 2233310c549SMarian Balakowicz - configuration-sub-node-unit-name : At least one of the configuration 2243310c549SMarian Balakowicz sub-nodes is required. 2253310c549SMarian Balakowicz 2263310c549SMarian Balakowicz 2273310c549SMarian Balakowicz7) Configuration nodes 2283310c549SMarian Balakowicz---------------------- 2293310c549SMarian Balakowicz 2303310c549SMarian BalakowiczEach configuration has the following structure: 2313310c549SMarian Balakowicz 2323310c549SMarian Balakowiczo config@1 2333310c549SMarian Balakowicz |- description = "configuration description" 2343310c549SMarian Balakowicz |- kernel = "kernel sub-node unit name" 2353310c549SMarian Balakowicz |- ramdisk = "ramdisk sub-node unit name" 2363310c549SMarian Balakowicz |- fdt = "fdt sub-node unit-name" 2373310c549SMarian Balakowicz 2383310c549SMarian Balakowicz 2393310c549SMarian Balakowicz Mandatory properties: 2403310c549SMarian Balakowicz - description : Textual configuration description. 2413310c549SMarian Balakowicz - kernel : Unit name of the corresponding kernel image (image sub-node of a 2423310c549SMarian Balakowicz "kernel" type). 2433310c549SMarian Balakowicz 2443310c549SMarian Balakowicz Optional properties: 2453310c549SMarian Balakowicz - ramdisk : Unit name of the corresponding ramdisk image (component image 2463310c549SMarian Balakowicz node of a "ramdisk" type). 2473310c549SMarian Balakowicz - fdt : Unit name of the corresponding fdt blob (component image node of a 2483310c549SMarian Balakowicz "fdt type"). 2493310c549SMarian Balakowicz 2503310c549SMarian BalakowiczThe FDT blob is required to properly boot FDT based kernel, so the minimal 2513310c549SMarian Balakowiczconfiguration for 2.6 FDT kernel is (kernel, fdt) pair. 2523310c549SMarian Balakowicz 2533310c549SMarian BalakowiczOlder, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases 2543310c549SMarian Balakowicz'struct bd_info' must be passed instead of FDT blob, thus fdt property *must 2553310c549SMarian Balakowicznot* be specified in a configuration node. 2563310c549SMarian Balakowicz 2573310c549SMarian Balakowicz 2583310c549SMarian Balakowicz8) Examples 2593310c549SMarian Balakowicz----------- 2603310c549SMarian Balakowicz 26143142e81SBartlomiej SiekaPlease see doc/uImage.FIT/*.its for actual image source files. 262