1.. SPDX-License-Identifier: GPL-2.0+ 2 3Flattened Image Tree (FIT) Format 4================================= 5 6Introduction 7------------ 8 9The number of elements playing a role in the kernel booting process has 10increased over time and now typically includes the devicetree, kernel image and 11possibly a ramdisk image. Generally, all must be placed in the system memory and 12booted together. 13 14For firmware images a similar process has taken place, with various binaries 15loaded at different addresses, such as ARM's ATF, OpenSBI, FPGA and U-Boot 16itself. 17 18FIT provides a flexible and extensible format to deal with this complexity. It 19provides support for multiple components. It also supports multiple 20configurations, so that the same FIT can be used to boot multiple boards, with 21some components in common (e.g. kernel) and some specific to that board (e.g. 22devicetree). 23 24Terminology 25~~~~~~~~~~~ 26 27This document defines FIT by providing FDT (Flat Device Tree) bindings. These 28describe the final form of the FIT at the moment when it is used. The user 29perspective may be simpler, as some of the properties (like timestamps and 30hashes) are filled in automatically by the U-Boot mkimage tool. 31 32To avoid confusion with the kernel FDT the following naming convention is used: 33 34FIT 35 Flattened Image Tree 36 37FIT is formally a flattened devicetree (in the libfdt meaning), which conforms 38to bindings defined in this document. 39 40.its 41 image tree source 42 43.itb 44 flattened image tree blob 45 46Image-building procedure 47~~~~~~~~~~~~~~~~~~~~~~~~ 48 49The following picture shows how the FIT is prepared. Input consists of 50image source file (.its) and a set of data files. Image is created with the 51help of standard U-Boot mkimage tool which in turn uses dtc (device tree 52compiler) to produce image tree blob (.itb). The resulting .itb file is the 53actual binary of a new FIT:: 54 55 tqm5200.its 56 + 57 vmlinux.bin.gz mkimage + dtc xfer to target 58 eldk-4.2-ramdisk --------------> tqm5200.itb --------------> boot 59 tqm5200.dtb /|\ 60 | 61 'new FIT' 62 63Steps: 64 65#. Create .its file, automatically filled-in properties are omitted 66 67#. Call mkimage tool on a .its file 68 69#. mkimage calls dtc to create .itb image and assures that 70 missing properties are added 71 72#. .itb (new FIT) is uploaded onto the target and used therein 73 74 75Unique identifiers 76~~~~~~~~~~~~~~~~~~ 77 78To identify FIT sub-nodes representing images, hashes, configurations (which 79are defined in the following sections), the "unit name" of the given sub-node 80is used as it's identifier as it assures uniqueness without additional 81checking required. 82 83 84External data 85~~~~~~~~~~~~~ 86 87FIT is normally built initially with image data in the 'data' property of each 88image node. It is also possible for this data to reside outside the FIT itself. 89This allows the 'FDT' part of the FIT to be quite small, so that it can be 90loaded and scanned without loading a large amount of data. Then when an image is 91needed it can be loaded from an external source. 92 93External FITs use 'data-offset' or 'data-position' instead of 'data'. 94 95The mkimage tool can convert a FIT to use external data using the `-E` argument, 96optionally using `-p` to specific a fixed position. 97 98It is often desirable to align each image to a block size or cache-line size 99(e.g. 512 bytes), so that there is no need to copy it to an aligned address when 100reading the image data. The mkimage tool provides a `-B` argument to support 101this. 102 103Root-node properties 104-------------------- 105 106The root node of the FIT should have the following layout:: 107 108 / o image-tree 109 |- description = "image description" 110 |- timestamp = <12399321> 111 |- #address-cells = <1> 112 | 113 o images 114 | | 115 | o image-1 {...} 116 | o image-2 {...} 117 | ... 118 | 119 o configurations 120 |- default = "conf-1" 121 | 122 o conf-1 {...} 123 o conf-2 {...} 124 ... 125 126Optional property 127~~~~~~~~~~~~~~~~~ 128 129description 130 Textual description of the FIT 131 132Mandatory property 133~~~~~~~~~~~~~~~~~~ 134 135timestamp 136 Last image modification time being counted in seconds since 137 1970-01-01 00:00:00 - to be automatically calculated by mkimage tool. 138 139Conditionally mandatory property 140~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 141 142#address-cells 143 Number of 32bit cells required to represent entry and 144 load addresses supplied within sub-image nodes. May be omitted when no 145 entry or load addresses are used. 146 147Mandatory nodes 148~~~~~~~~~~~~~~~ 149 150images 151 This node contains a set of sub-nodes, each of them representing 152 single component sub-image (like kernel, ramdisk, etc.). At least one 153 sub-image is required. 154 155configurations 156 Contains a set of available configuration nodes and 157 defines a default configuration. 158 159 160'/images' node 161-------------- 162 163This node is a container node for component sub-image nodes. Each sub-node of 164the '/images' node should have the following layout:: 165 166 o image-1 167 |- description = "component sub-image description" 168 |- data = /incbin/("path/to/data/file.bin") 169 |- type = "sub-image type name" 170 |- arch = "ARCH name" 171 |- os = "OS name" 172 |- compression = "compression name" 173 |- load = <00000000> 174 |- entry = <00000000> 175 | 176 o hash-1 {...} 177 o hash-2 {...} 178 ... 179 180Mandatory properties 181~~~~~~~~~~~~~~~~~~~~ 182 183description 184 Textual description of the component sub-image 185 186type 187 Name of component sub-image type. Supported types are: 188 189 ==================== ================== 190 Sub-image type Meaning 191 ==================== ================== 192 invalid Invalid Image 193 aisimage Davinci AIS image 194 atmelimage ATMEL ROM-Boot Image 195 copro Coprocessor Image} 196 fdt_legacy legacy Image with Flat Device Tree 197 filesystem Filesystem Image 198 firmware Firmware 199 firmware_ivt Firmware with HABv4 IVT } 200 flat_dt Flat Device Tree 201 fpga FPGA Image } 202 gpimage TI Keystone SPL Image 203 imx8image NXP i.MX8 Boot Image 204 imx8mimage NXP i.MX8M Boot Image 205 imximage Freescale i.MX Boot Image 206 kernel Kernel Image 207 kernel_noload Kernel Image (no loading done) 208 kwbimage Kirkwood Boot Image 209 lpc32xximage LPC32XX Boot Image 210 mtk_image MediaTek BootROM loadable Image } 211 multi Multi-File Image 212 mxsimage Freescale MXS Boot Image 213 omapimage TI OMAP SPL With GP CH 214 pblimage Freescale PBL Boot Image 215 pmmc TI Power Management Micro-Controller Firmware 216 ramdisk RAMDisk Image 217 rkimage Rockchip Boot Image } 218 rksd Rockchip SD Boot Image } 219 rkspi Rockchip SPI Boot Image } 220 script Script 221 socfpgaimage Altera SoCFPGA CV/AV preloader 222 socfpgaimage_v1 Altera SoCFPGA A10 preloader 223 spkgimage Renesas SPKG Image } 224 standalone Standalone Program 225 stm32image STMicroelectronics STM32 Image } 226 sunxi_egon Allwinner eGON Boot Image } 227 sunxi_toc0 Allwinner TOC0 Boot Image } 228 tee Trusted Execution Environment Image 229 ublimage Davinci UBL image 230 vybridimage Vybrid Boot Image 231 x86_setup x86 setup.bin 232 zynqimage Xilinx Zynq Boot Image } 233 zynqmpbif Xilinx ZynqMP Boot Image (bif) } 234 zynqmpimage Xilinx ZynqMP Boot Image } 235 ==================== ================== 236 237compression 238 Compression used by included data. If no compression is used, the 239 compression property should be set to "none". If the data is compressed but 240 it should not be uncompressed by the loader (e.g. compressed ramdisk), this 241 should also be set to "none". 242 243 Supported compression types are: 244 245 ==================== ================== 246 Compression type Meaning 247 ==================== ================== 248 none uncompressed 249 bzip2 bzip2 compressed 250 gzip gzip compressed 251 lz4 lz4 compressed 252 lzma lzma compressed 253 lzo lzo compressed 254 zstd zstd compressed 255 ==================== ================== 256 257data-size 258 size of the data in bytes 259 260 261Conditionally mandatory property 262~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 263 264data 265 Path to the external file which contains this node's binary data. Within 266 the FIT this is the contents of the file. This is mandatory unless 267 external data is used. 268 269data-offset 270 Offset of the data in a separate image store. The image store is placed 271 immediately after the last byte of the device tree binary, aligned to a 272 4-byte boundary. This is mandatory if external data is used, with an offset. 273 274data-position 275 Machine address at which the data is to be found. This is a fixed address 276 not relative to the loading of the FIT. This is mandatory if external data 277 used with a fixed address. 278 279os 280 OS name, mandatory for types "kernel". Valid OS names are: 281 282 ==================== ================== 283 OS name Meaning 284 ==================== ================== 285 invalid Invalid OS 286 4_4bsd 4_4BSD 287 arm-trusted-firmware ARM Trusted Firmware 288 dell Dell 289 efi EFI Firmware 290 esix Esix 291 freebsd FreeBSD 292 integrity INTEGRITY 293 irix Irix 294 linux Linux 295 ncr NCR 296 netbsd NetBSD 297 openbsd OpenBSD 298 openrtos OpenRTOS 299 opensbi RISC-V OpenSBI 300 ose Enea OSE 301 plan9 Plan 9 302 psos pSOS 303 qnx QNX 304 rtems RTEMS 305 sco SCO 306 solaris Solaris 307 svr4 SVR4 308 tee Trusted Execution Environment 309 u-boot U-Boot 310 vxworks VxWorks 311 ==================== ================== 312 313arch 314 Architecture name, mandatory for types: "standalone", "kernel", 315 "firmware", "ramdisk" and "fdt". Valid architecture names are: 316 317 ==================== ================== 318 Architecture type Meaning 319 ==================== ================== 320 invalid Invalid ARCH 321 alpha Alpha 322 arc ARC 323 arm64 AArch64 324 arm ARM 325 avr32 AVR32 326 blackfin Blackfin 327 ia64 IA64 328 m68k M68K 329 microblaze MicroBlaze 330 mips64 MIPS 64 Bit 331 mips MIPS 332 nds32 NDS32 333 nios2 NIOS II 334 or1k OpenRISC 1000 335 powerpc PowerPC 336 ppc PowerPC 337 riscv RISC-V 338 s390 IBM S390 339 sandbox Sandbox 340 sh SuperH 341 sparc64 SPARC 64 Bit 342 sparc SPARC 343 x86_64 AMD x86_64 344 x86 Intel x86 345 xtensa Xtensa 346 ==================== ================== 347 348entry 349 entry point address, address size is determined by 350 '#address-cells' property of the root node. 351 Mandatory for types: "firmware", and "kernel". 352 353load 354 load address, address size is determined by '#address-cells' 355 property of the root node. 356 Mandatory for types: "firmware", and "kernel". 357 358compatible 359 compatible method for loading image. 360 Mandatory for types: "fpga", and images that do not specify a load address. 361 Supported compatible methods: 362 363 ========================== ========================================= 364 Compatible string Meaning 365 ========================== ========================================= 366 u-boot,fpga-legacy Generic fpga loading routine. 367 u-boot,zynqmp-fpga-ddrauth Signed non-encrypted FPGA bitstream for 368 Xilinx Zynq UltraScale+ (ZymqMP) device. 369 u-boot,zynqmp-fpga-enc Encrypted FPGA bitstream for Xilinx Zynq 370 UltraScale+ (ZynqMP) device. 371 ========================== ========================================= 372 373phase 374 U-Boot phase for which the image is intended. 375 376 "spl" 377 image is an SPL image 378 379 "u-boot" 380 image is a U-Boot image 381 382Optional nodes: 383 384hash-1 385 Each hash sub-node represents separate hash or checksum 386 calculated for node's data according to specified algorithm. 387 388signature-1 389 Each signature sub-node represents separate signature 390 calculated for node's data according to specified algorithm. 391 392 393Hash nodes 394---------- 395 396:: 397 398 o hash-1 399 |- algo = "hash or checksum algorithm name" 400 |- value = [hash or checksum value] 401 402Mandatory properties 403~~~~~~~~~~~~~~~~~~~~ 404 405algo 406 Algorithm name. Supported algoriths and their value sizes are: 407 408 ==================== ============ ========================================= 409 Sub-image type Size (bytes) Meaning 410 ==================== ============ ========================================= 411 crc16-ccitt 2 Cyclic Redundancy Check 16-bit 412 (Consultative Committee for International 413 Telegraphy and Telephony) 414 crc32 4 Cyclic Redundancy Check 32-bit 415 md5 16 Message Digest 5 (MD5) 416 sha1 20 Secure Hash Algorithm 1 (SHA1) 417 sha256 32 Secure Hash Algorithm 2 (SHA256) 418 sha384 48 Secure Hash Algorithm 2 (SHA384) 419 sha512 64 Secure Hash Algorithm 2 (SHA512) 420 ==================== ============ ========================================= 421 422value 423 Actual checksum or hash value. 424 425Image-signature nodes 426--------------------- 427 428:: 429 430 o signature-1 431 |- algo = "algorithm name" 432 |- key-name-hint = "key name" 433 |- value = [hash or checksum value] 434 435 436Mandatory properties 437~~~~~~~~~~~~~~~~~~~~ 438 439_`FIT Algorithm`: 440 441algo 442 Algorithm name. Supported algoriths and their value sizes are shown below. 443 Note that the hash is specified separately from the signing algorithm, so 444 it is possible to mix and match any SHA algorithm with any signing 445 algorithm. The size of the signature relates to the signing algorithm, not 446 the hash, since it is the hash that is signed. 447 448 ==================== ============ ========================================= 449 Sub-image type Size (bytes) Meaning 450 ==================== ============ ========================================= 451 sha1,rsa2048 256 SHA1 hash signed with 2048-bit 452 Rivest–Shamir–Adleman algorithm 453 sha1,rsa3072 384 SHA1 hash signed with 2048-bit RSA 454 sha1,rsa4096 512 SHA1 hash signed with 2048-bit RSA 455 sha1,ecdsa256 32 SHA1 hash signed with 256-bit Elliptic 456 Curve Digital Signature Algorithm 457 sha256,... 458 sha384,... 459 sha512,... 460 ==================== ============ ========================================= 461 462key-name-hint 463 Name of key to use for signing. The keys will normally be in 464 a single directory (parameter -k to mkimage). For a given key <name>, its 465 private key is stored in <name>.key and the certificate is stored in 466 <name>.crt. 467 468sign-images 469 A list of images to sign, each being a property of the conf 470 node that contains then. The default is "kernel,fdt" which means that these 471 two images will be looked up in the config and signed if present. This is 472 used by mkimage to determine which images to sign. 473 474The following properies are added as part of signing, and are mandatory: 475 476value 477 Actual signature value. This is added by mkimage. 478 479hashed-nodes 480 A list of nodes which were hashed by the signer. Each is 481 a string - the full path to node. A typical value might be:: 482 483 hashed-nodes = "/", "/configurations/conf-1", "/images/kernel", 484 "/images/kernel/hash-1", "/images/fdt-1", 485 "/images/fdt-1/hash-1"; 486 487hashed-strings 488 The start and size of the string region of the FIT that was hashed. The 489 start is normally 0, indicating the first byte of the string table. The size 490 indicates the number of bytes hashed as part of signing. 491 492The following properies are added as part of signing, and are optional: 493 494timestamp 495 Time when image was signed (standard Unix time_t format) 496 497signer-name 498 Name of the signer (e.g. "mkimage") 499 500signer-version 501 Version string of the signer (e.g. "2013.01") 502 503comment 504 Additional information about the signer or image 505 506padding 507 The padding algorithm, it may be pkcs-1.5 or pss, 508 if no value is provided we assume pkcs-1.5 509 510 511'/configurations' node 512---------------------- 513 514The 'configurations' node creates convenient, labeled boot configurations, 515which combine together kernel images with their ramdisks and fdt blobs. 516 517The 'configurations' node has the following structure:: 518 519 o configurations 520 |- default = "default configuration sub-node unit name" 521 | 522 o config-1 {...} 523 o config-2 {...} 524 ... 525 526 527Optional property 528~~~~~~~~~~~~~~~~~ 529 530default 531 Selects one of the configuration sub-nodes as a default configuration. 532 533Mandatory nodes 534~~~~~~~~~~~~~~~ 535 536configuration-sub-node-unit-name 537 At least one of the configuration sub-nodes is required. 538 539Optional nodes 540~~~~~~~~~~~~~~ 541 542signature-1 543 Each signature sub-node represents separate signature 544 calculated for the configuration according to specified algorithm. 545 546 547Configuration nodes 548------------------- 549 550Each configuration has the following structure:: 551 552 o config-1 553 |- description = "configuration description" 554 |- kernel = "kernel sub-node unit name" 555 |- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...] 556 |- loadables = "loadables sub-node unit-name" 557 |- script = " 558 |- compatible = "vendor,board-style device tree compatible string" 559 o signature-1 {...} 560 561Mandatory properties 562~~~~~~~~~~~~~~~~~~~~ 563 564description 565 Textual configuration description. 566 567kernel or firmware 568 Unit name of the corresponding kernel or firmware 569 (u-boot, op-tee, etc) image. If both "kernel" and "firmware" are specified, 570 control is passed to the firmware image. 571 572Optional properties 573~~~~~~~~~~~~~~~~~~~ 574 575fdt 576 Unit name of the corresponding fdt blob (component image node of a 577 "fdt type"). Additional fdt overlay nodes can be supplied which signify 578 that the resulting device tree blob is generated by the first base fdt 579 blob with all subsequent overlays applied. 580 581fpga 582 Unit name of the corresponding fpga bitstream blob 583 (component image node of a "fpga type"). 584 585loadables 586 Unit name containing a list of additional binaries to be 587 loaded at their given locations. "loadables" is a comma-separated list 588 of strings. U-Boot will load each binary at its given start-address and 589 may optionally invoke additional post-processing steps on this binary based 590 on its component image node type. 591 592script 593 The image to use when loading a U-Boot script (for use with the 594 source command). 595 596compatible 597 The root compatible string of the U-Boot device tree that 598 this configuration shall automatically match when CONFIG_FIT_BEST_MATCH is 599 enabled. If this property is not provided, the compatible string will be 600 extracted from the fdt blob instead. This is only possible if the fdt is 601 not compressed, so images with compressed fdts that want to use compatible 602 string matching must always provide this property. 603 604The FDT blob is required to properly boot FDT based kernel, so the minimal 605configuration for 2.6 FDT kernel is (kernel, fdt) pair. 606 607Older, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases 608'struct bd_info' must be passed instead of FDT blob, thus fdt property *must 609not* be specified in a configuration node. 610 611Configuration-signature nodes 612----------------------------- 613 614:: 615 616 o signature-1 617 |- algo = "algorithm name" 618 |- key-name-hint = "key name" 619 |- sign-images = "path1", "path2"; 620 |- value = [hash or checksum value] 621 |- hashed-strings = <0 len> 622 623 624Mandatory properties 625~~~~~~~~~~~~~~~~~~~~ 626 627algo 628 See `FIT Algorithm`_. 629 630key-name-hint 631 Name of key to use for signing. The keys will normally be in 632 a single directory (parameter -k to mkimage). For a given key <name>, its 633 private key is stored in <name>.key and the certificate is stored in 634 <name>.crt. 635 636The following properies are added as part of signing, and are mandatory: 637 638value 639 Actual signature value. This is added by mkimage. 640 641The following properies are added as part of signing, and are optional: 642 643timestamp 644 Time when image was signed (standard Unix time_t format) 645 646signer-name 647 Name of the signer (e.g. "mkimage") 648 649signer-version 650 Version string of the signer (e.g. "2013.01") 651 652comment 653 Additional information about the signer or image 654 655padding 656 The padding algorithm, it may be pkcs-1.5 or pss, 657 if no value is provided we assume pkcs-1.5 658 659 660 661Examples 662-------- 663 664Some example files are available here, showing various scenarios 665 666.. toctree:: 667 :maxdepth: 1 668 669 kernel 670 kernel_fdt 671 kernel_fdts_compressed 672 multi 673 multi_spl 674 multi-with-fpga 675 multi-with-loadables 676 sec_firmware_ppa 677 sign-configs 678 sign-images 679 uefi 680 update3 681 update_uboot 682 683.. sectionauthor:: Marian Balakowicz <m8@semihalf.com> 684.. sectionauthor:: External data additions, 25/1/16 Simon Glass <sjg@chromium.org> 685