1a187559eSBin MengU-Boot new uImage source file format (bindings definition) 23310c549SMarian Balakowicz========================================================== 33310c549SMarian Balakowicz 43310c549SMarian BalakowiczAuthor: Marian Balakowicz <m8@semihalf.com> 5722ebc8fSSimon GlassExternal data additions, 25/1/16 Simon Glass <sjg@chromium.org> 63310c549SMarian Balakowicz 73310c549SMarian Balakowicz1) Introduction 83310c549SMarian Balakowicz--------------- 93310c549SMarian Balakowicz 103310c549SMarian BalakowiczEvolution of the 2.6 Linux kernel for embedded PowerPC systems introduced new 113310c549SMarian Balakowiczbooting method which requires that hardware description is available to the 123310c549SMarian Balakowiczkernel in the form of Flattened Device Tree. 133310c549SMarian Balakowicz 143310c549SMarian BalakowiczBooting with a Flattened Device Tree is much more flexible and is intended to 153310c549SMarian Balakowiczreplace direct passing of 'struct bd_info' which was used to boot pre-FDT 163310c549SMarian Balakowiczkernels. 173310c549SMarian Balakowicz 18a187559eSBin MengHowever, U-Boot needs to support both techniques to provide backward 193310c549SMarian Balakowiczcompatibility for platforms which are not FDT ready. Number of elements 203310c549SMarian Balakowiczplaying role in the booting process has increased and now includes the FDT 213310c549SMarian Balakowiczblob. Kernel image, FDT blob and possibly ramdisk image - all must be placed 223310c549SMarian Balakowiczin the system memory and passed to bootm as a arguments. Some of them may be 233310c549SMarian Balakowiczmissing: FDT is not present for legacy platforms, ramdisk is always optional. 243310c549SMarian BalakowiczAdditionally, old uImage format has been extended to support multi sub-images 253310c549SMarian Balakowiczbut the support is limited by simple format of the legacy uImage structure. 263310c549SMarian BalakowiczSingle binary header 'struct image_header' is not flexible enough to cover all 273310c549SMarian Balakowiczpossible scenarios. 283310c549SMarian Balakowicz 293310c549SMarian BalakowiczAll those factors combined clearly show that there is a need for new, more 303310c549SMarian Balakowiczflexible, multi component uImage format. 313310c549SMarian Balakowicz 323310c549SMarian Balakowicz 333310c549SMarian Balakowicz2) New uImage format assumptions 343310c549SMarian Balakowicz-------------------------------- 353310c549SMarian Balakowicz 363310c549SMarian Balakowicza) Implementation 373310c549SMarian Balakowicz 383310c549SMarian BalakowiczLibfdt has been selected for the new uImage format implementation as (1) it 393310c549SMarian Balakowiczprovides needed functionality, (2) is actively maintained and developed and 40a187559eSBin Meng(3) increases code reuse as it is already part of the U-Boot source tree. 413310c549SMarian Balakowicz 423310c549SMarian Balakowiczb) Terminology 433310c549SMarian Balakowicz 443310c549SMarian BalakowiczThis document defines new uImage structure by providing FDT bindings for new 45a187559eSBin MenguImage internals. Bindings are defined from U-Boot perspective, i.e. describe 46a187559eSBin Mengfinal form of the uImage at the moment when it reaches U-Boot. User 473310c549SMarian Balakowiczperspective may be simpler, as some of the properties (like timestamps and 48a187559eSBin Menghashes) will need to be filled in automatically by the U-Boot mkimage tool. 493310c549SMarian Balakowicz 503310c549SMarian BalakowiczTo avoid confusion with the kernel FDT the following naming convention is 513310c549SMarian Balakowiczproposed for the new uImage format related terms: 523310c549SMarian Balakowicz 533310c549SMarian BalakowiczFIT - Flattened uImage Tree 543310c549SMarian Balakowicz 553310c549SMarian BalakowiczFIT is formally a flattened device tree (in the libfdt meaning), which 563310c549SMarian Balakowiczconforms to bindings defined in this document. 573310c549SMarian Balakowicz 583310c549SMarian Balakowicz.its - image tree source 59486c39c2SAndreas Dannenberg.itb - flattened image tree blob 603310c549SMarian Balakowicz 613310c549SMarian Balakowiczc) Image building procedure 623310c549SMarian Balakowicz 633310c549SMarian BalakowiczThe following picture shows how the new uImage is prepared. Input consists of 643310c549SMarian Balakowiczimage source file (.its) and a set of data files. Image is created with the 65a187559eSBin Menghelp of standard U-Boot mkimage tool which in turn uses dtc (device tree 6661ffc17aSMasahiro Yamadacompiler) to produce image tree blob (.itb). Resulting .itb file is the 673310c549SMarian Balakowiczactual binary of a new uImage. 683310c549SMarian Balakowicz 693310c549SMarian Balakowicz 703310c549SMarian Balakowicztqm5200.its 713310c549SMarian Balakowicz+ 723310c549SMarian Balakowiczvmlinux.bin.gz mkimage + dtc xfer to target 733310c549SMarian Balakowiczeldk-4.2-ramdisk --------------> tqm5200.itb --------------> bootm 743310c549SMarian Balakowicztqm5200.dtb /|\ 753310c549SMarian Balakowicz... | 763310c549SMarian Balakowicz 'new uImage' 773310c549SMarian Balakowicz 783310c549SMarian Balakowicz - create .its file, automatically filled-in properties are omitted 793310c549SMarian Balakowicz - call mkimage tool on a .its file 803310c549SMarian Balakowicz - mkimage calls dtc to create .itb image and assures that 813310c549SMarian Balakowicz missing properties are added 823310c549SMarian Balakowicz - .itb (new uImage) is uploaded onto the target and used therein 833310c549SMarian Balakowicz 843310c549SMarian Balakowicz 853310c549SMarian Balakowiczd) Unique identifiers 863310c549SMarian Balakowicz 873310c549SMarian BalakowiczTo identify FIT sub-nodes representing images, hashes, configurations (which 883310c549SMarian Balakowiczare defined in the following sections), the "unit name" of the given sub-node 893310c549SMarian Balakowiczis used as it's identifier as it assures uniqueness without additional 903310c549SMarian Balakowiczchecking required. 913310c549SMarian Balakowicz 923310c549SMarian Balakowicz 933310c549SMarian Balakowicz3) Root node properties 943310c549SMarian Balakowicz----------------------- 953310c549SMarian Balakowicz 963310c549SMarian BalakowiczRoot node of the uImage Tree should have the following layout: 973310c549SMarian Balakowicz 983310c549SMarian Balakowicz/ o image-tree 993310c549SMarian Balakowicz |- description = "image description" 1003310c549SMarian Balakowicz |- timestamp = <12399321> 1013310c549SMarian Balakowicz |- #address-cells = <1> 1023310c549SMarian Balakowicz | 1033310c549SMarian Balakowicz o images 1043310c549SMarian Balakowicz | | 10583840405SAndre Przywara | o image-1 {...} 10683840405SAndre Przywara | o image-2 {...} 1073310c549SMarian Balakowicz | ... 1083310c549SMarian Balakowicz | 1093310c549SMarian Balakowicz o configurations 11083840405SAndre Przywara |- default = "conf-1" 1113310c549SMarian Balakowicz | 11283840405SAndre Przywara o conf-1 {...} 11383840405SAndre Przywara o conf-2 {...} 1143310c549SMarian Balakowicz ... 1153310c549SMarian Balakowicz 1163310c549SMarian Balakowicz 1173310c549SMarian Balakowicz Optional property: 1183310c549SMarian Balakowicz - description : Textual description of the uImage 1193310c549SMarian Balakowicz 1203310c549SMarian Balakowicz Mandatory property: 1213310c549SMarian Balakowicz - timestamp : Last image modification time being counted in seconds since 1223310c549SMarian Balakowicz 1970-01-01 00:00:00 - to be automatically calculated by mkimage tool. 1233310c549SMarian Balakowicz 1243310c549SMarian Balakowicz Conditionally mandatory property: 1253310c549SMarian Balakowicz - #address-cells : Number of 32bit cells required to represent entry and 1263310c549SMarian Balakowicz load addresses supplied within sub-image nodes. May be omitted when no 1273310c549SMarian Balakowicz entry or load addresses are used. 1283310c549SMarian Balakowicz 1293310c549SMarian Balakowicz Mandatory node: 1303310c549SMarian Balakowicz - images : This node contains a set of sub-nodes, each of them representing 1313310c549SMarian Balakowicz single component sub-image (like kernel, ramdisk, etc.). At least one 1323310c549SMarian Balakowicz sub-image is required. 1333310c549SMarian Balakowicz 1343310c549SMarian Balakowicz Optional node: 1353310c549SMarian Balakowicz - configurations : Contains a set of available configuration nodes and 1363310c549SMarian Balakowicz defines a default configuration. 1373310c549SMarian Balakowicz 1383310c549SMarian Balakowicz 1393310c549SMarian Balakowicz4) '/images' node 1403310c549SMarian Balakowicz----------------- 1413310c549SMarian Balakowicz 1423310c549SMarian BalakowiczThis node is a container node for component sub-image nodes. Each sub-node of 1433310c549SMarian Balakowiczthe '/images' node should have the following layout: 1443310c549SMarian Balakowicz 14583840405SAndre Przywara o image-1 1463310c549SMarian Balakowicz |- description = "component sub-image description" 1473310c549SMarian Balakowicz |- data = /incbin/("path/to/data/file.bin") 1483310c549SMarian Balakowicz |- type = "sub-image type name" 1493310c549SMarian Balakowicz |- arch = "ARCH name" 1503310c549SMarian Balakowicz |- os = "OS name" 1513310c549SMarian Balakowicz |- compression = "compression name" 1523310c549SMarian Balakowicz |- load = <00000000> 1533310c549SMarian Balakowicz |- entry = <00000000> 1543310c549SMarian Balakowicz | 15583840405SAndre Przywara o hash-1 {...} 15683840405SAndre Przywara o hash-2 {...} 1573310c549SMarian Balakowicz ... 1583310c549SMarian Balakowicz 1593310c549SMarian Balakowicz Mandatory properties: 1603310c549SMarian Balakowicz - description : Textual description of the component sub-image 1613310c549SMarian Balakowicz - type : Name of component sub-image type, supported types are: 16225fa0b93STom Rini "standalone", "kernel", "kernel_noload", "ramdisk", "firmware", "script", 16325fa0b93STom Rini "filesystem", "flat_dt" and others (see uimage_type in common/image.c). 1643310c549SMarian Balakowicz - data : Path to the external file which contains this node's binary data. 1653310c549SMarian Balakowicz - compression : Compression used by included data. Supported compressions 1663310c549SMarian Balakowicz are "gzip" and "bzip2". If no compression is used compression property 167*fd15a9e2SSimon Goldschmidt should be set to "none". If the data is compressed but it should not be 168*fd15a9e2SSimon Goldschmidt uncompressed by U-Boot (e.g. compressed ramdisk), this should also be set 169*fd15a9e2SSimon Goldschmidt to "none". 1703310c549SMarian Balakowicz 1713310c549SMarian Balakowicz Conditionally mandatory property: 1725cde9d8eSGuilherme Maciel Ferreira - os : OS name, mandatory for types "kernel" and "ramdisk". Valid OS names 1735cde9d8eSGuilherme Maciel Ferreira are: "openbsd", "netbsd", "freebsd", "4_4bsd", "linux", "svr4", "esix", 1745cde9d8eSGuilherme Maciel Ferreira "solaris", "irix", "sco", "dell", "ncr", "lynxos", "vxworks", "psos", "qnx", 1755cde9d8eSGuilherme Maciel Ferreira "u_boot", "rtems", "unity", "integrity". 1763310c549SMarian Balakowicz - arch : Architecture name, mandatory for types: "standalone", "kernel", 1773310c549SMarian Balakowicz "firmware", "ramdisk" and "fdt". Valid architecture names are: "alpha", 1783310c549SMarian Balakowicz "arm", "i386", "ia64", "mips", "mips64", "ppc", "s390", "sh", "sparc", 17938119778SSimon Glass "sparc64", "m68k", "microblaze", "nios2", "blackfin", "avr32", "st200", 18038119778SSimon Glass "sandbox". 1813310c549SMarian Balakowicz - entry : entry point address, address size is determined by 1823310c549SMarian Balakowicz '#address-cells' property of the root node. Mandatory for for types: 1833310c549SMarian Balakowicz "standalone" and "kernel". 1843310c549SMarian Balakowicz - load : load address, address size is determined by '#address-cells' 1853310c549SMarian Balakowicz property of the root node. Mandatory for types: "standalone" and "kernel". 1863310c549SMarian Balakowicz 1873310c549SMarian Balakowicz Optional nodes: 18883840405SAndre Przywara - hash-1 : Each hash sub-node represents separate hash or checksum 1893310c549SMarian Balakowicz calculated for node's data according to specified algorithm. 1903310c549SMarian Balakowicz 1913310c549SMarian Balakowicz 1923310c549SMarian Balakowicz5) Hash nodes 1933310c549SMarian Balakowicz------------- 1943310c549SMarian Balakowicz 19583840405SAndre Przywarao hash-1 1963310c549SMarian Balakowicz |- algo = "hash or checksum algorithm name" 1973310c549SMarian Balakowicz |- value = [hash or checksum value] 1983310c549SMarian Balakowicz 1993310c549SMarian Balakowicz Mandatory properties: 2003310c549SMarian Balakowicz - algo : Algorithm name, supported are "crc32", "md5" and "sha1". 2013310c549SMarian Balakowicz - value : Actual checksum or hash value, correspondingly 4, 16 or 20 bytes 2023310c549SMarian Balakowicz long. 2033310c549SMarian Balakowicz 2043310c549SMarian Balakowicz 2053310c549SMarian Balakowicz6) '/configurations' node 2063310c549SMarian Balakowicz------------------------- 2073310c549SMarian Balakowicz 2083310c549SMarian BalakowiczThe 'configurations' node is optional. If present, it allows to create a 2093310c549SMarian Balakowiczconvenient, labeled boot configurations, which combine together kernel images 2103310c549SMarian Balakowiczwith their ramdisks and fdt blobs. 2113310c549SMarian Balakowicz 2123310c549SMarian BalakowiczThe 'configurations' node has has the following structure: 2133310c549SMarian Balakowicz 2143310c549SMarian Balakowiczo configurations 2153310c549SMarian Balakowicz |- default = "default configuration sub-node unit name" 2163310c549SMarian Balakowicz | 21783840405SAndre Przywara o config-1 {...} 21883840405SAndre Przywara o config-2 {...} 2193310c549SMarian Balakowicz ... 2203310c549SMarian Balakowicz 2213310c549SMarian Balakowicz 2223310c549SMarian Balakowicz Optional property: 2233310c549SMarian Balakowicz - default : Selects one of the configuration sub-nodes as a default 2243310c549SMarian Balakowicz configuration. 2253310c549SMarian Balakowicz 2263310c549SMarian Balakowicz Mandatory nodes: 2273310c549SMarian Balakowicz - configuration-sub-node-unit-name : At least one of the configuration 2283310c549SMarian Balakowicz sub-nodes is required. 2293310c549SMarian Balakowicz 2303310c549SMarian Balakowicz 2313310c549SMarian Balakowicz7) Configuration nodes 2323310c549SMarian Balakowicz---------------------- 2333310c549SMarian Balakowicz 2343310c549SMarian BalakowiczEach configuration has the following structure: 2353310c549SMarian Balakowicz 23683840405SAndre Przywarao config-1 2373310c549SMarian Balakowicz |- description = "configuration description" 2383310c549SMarian Balakowicz |- kernel = "kernel sub-node unit name" 2393310c549SMarian Balakowicz |- ramdisk = "ramdisk sub-node unit name" 2406b54e50bSPantelis Antoniou |- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...] 241ed0cea7cSMichal Simek |- fpga = "fpga sub-node unit-name" 242ecf8cd65SKarl Apsite |- loadables = "loadables sub-node unit-name" 2433310c549SMarian Balakowicz 2443310c549SMarian Balakowicz 2453310c549SMarian Balakowicz Mandatory properties: 2463310c549SMarian Balakowicz - description : Textual configuration description. 2473310c549SMarian Balakowicz - kernel : Unit name of the corresponding kernel image (image sub-node of a 2483310c549SMarian Balakowicz "kernel" type). 2493310c549SMarian Balakowicz 2503310c549SMarian Balakowicz Optional properties: 2513310c549SMarian Balakowicz - ramdisk : Unit name of the corresponding ramdisk image (component image 2523310c549SMarian Balakowicz node of a "ramdisk" type). 2533310c549SMarian Balakowicz - fdt : Unit name of the corresponding fdt blob (component image node of a 2546b54e50bSPantelis Antoniou "fdt type"). Additional fdt overlay nodes can be supplied which signify 2556b54e50bSPantelis Antoniou that the resulting device tree blob is generated by the first base fdt 2566b54e50bSPantelis Antoniou blob with all subsequent overlays applied. 25790268b87SSimon Glass - setup : Unit name of the corresponding setup binary (used for booting 25890268b87SSimon Glass an x86 kernel). This contains the setup.bin file built by the kernel. 259ed0cea7cSMichal Simek - fpga : Unit name of the corresponding fpga bitstream blob 260ed0cea7cSMichal Simek (component image node of a "fpga type"). 261ecf8cd65SKarl Apsite - loadables : Unit name containing a list of additional binaries to be 262ecf8cd65SKarl Apsite loaded at their given locations. "loadables" is a comma-separated list 263d7be5092SAndrew F. Davis of strings. U-Boot will load each binary at its given start-address and 264d7be5092SAndrew F. Davis may optionaly invoke additional post-processing steps on this binary based 265d7be5092SAndrew F. Davis on its component image node type. 2663310c549SMarian Balakowicz 2673310c549SMarian BalakowiczThe FDT blob is required to properly boot FDT based kernel, so the minimal 2683310c549SMarian Balakowiczconfiguration for 2.6 FDT kernel is (kernel, fdt) pair. 2693310c549SMarian Balakowicz 2703310c549SMarian BalakowiczOlder, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases 2713310c549SMarian Balakowicz'struct bd_info' must be passed instead of FDT blob, thus fdt property *must 2723310c549SMarian Balakowicznot* be specified in a configuration node. 2733310c549SMarian Balakowicz 2743310c549SMarian Balakowicz 275722ebc8fSSimon Glass8) External data 276722ebc8fSSimon Glass---------------- 277722ebc8fSSimon Glass 278722ebc8fSSimon GlassThe above format shows a 'data' property which holds the data for each image. 279722ebc8fSSimon GlassIt is also possible for this data to reside outside the FIT itself. This 280722ebc8fSSimon Glassallows the FIT to be quite small, so that it can be loaded and scanned 281722ebc8fSSimon Glasswithout loading a large amount of data. Then when an image is needed it can 282722ebc8fSSimon Glassbe loaded from an external source. 283722ebc8fSSimon Glass 284722ebc8fSSimon GlassIn this case the 'data' property is omitted. Instead you can use: 285722ebc8fSSimon Glass 286722ebc8fSSimon Glass - data-offset : offset of the data in a separate image store. The image 287722ebc8fSSimon Glass store is placed immediately after the last byte of the device tree binary, 288722ebc8fSSimon Glass aligned to a 4-byte boundary. 289722ebc8fSSimon Glass - data-size : size of the data in bytes 290722ebc8fSSimon Glass 291f8f9107dSTeddy ReedThe 'data-offset' property can be substituted with 'data-position', which 292f8f9107dSTeddy Reeddefines an absolute position or address as the offset. This is helpful when 293a1be94b6SPeng Fanbooting U-Boot proper before performing relocation. Pass '-p [offset]' to 294a1be94b6SPeng Fanmkimage to enable 'data-position'. 295722ebc8fSSimon Glass 2965fd13d97SYork SunNormal kernel FIT image has data embedded within FIT structure. U-Boot image 2975fd13d97SYork Sunfor SPL boot has external data. Existence of 'data-offset' can be used to 2985fd13d97SYork Sunidentify which format is used. 2995fd13d97SYork Sun 300722ebc8fSSimon Glass9) Examples 3013310c549SMarian Balakowicz----------- 3023310c549SMarian Balakowicz 30343142e81SBartlomiej SiekaPlease see doc/uImage.FIT/*.its for actual image source files. 304