| U-Boot new uImage source file format (bindings definition) |
| ========================================================== |
| |
| Author: Marian Balakowicz <m8@semihalf.com> |
| External data additions, 25/1/16 Simon Glass <sjg@chromium.org> |
| |
| 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 - flattened 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 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 image-1 {...} |
| | o image-2 {...} |
| | ... |
| | |
| o configurations |
| |- default = "conf-1" |
| | |
| o conf-1 {...} |
| o conf-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 nodes: |
| - 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. |
| - 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", "kernel_noload", "ramdisk", "firmware", "script", |
| "filesystem", "flat_dt" and others (see uimage_type in common/image.c). |
| - 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". If the data is compressed but it should not be |
| uncompressed by U-Boot (e.g. compressed ramdisk), this should also be set |
| to "none". |
| |
| Conditionally mandatory property: |
| - os : OS name, mandatory for types "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", "unity", "integrity". |
| - 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", "microblaze", "nios2", "blackfin", "avr32", "st200", |
| "sandbox". |
| - entry : entry point address, address size is determined by |
| '#address-cells' property of the root node. |
| Mandatory for types: "firmware", and "kernel". |
| - load : load address, address size is determined by '#address-cells' |
| property of the root node. |
| Mandatory for types: "firmware", and "kernel". |
| - compatible : compatible method for loading image. |
| Mandatory for types: "fpga", and images that do not specify a load address. |
| Supported compatible methods: |
| "u-boot,fpga-legacy" - the generic fpga loading routine. |
| "u-boot,zynqmp-fpga-ddrauth" - signed non-encrypted FPGA bitstream for |
| Xilinx Zynq UltraScale+ (ZymqMP) device. |
| "u-boot,zynqmp-fpga-enc" - encrypted FPGA bitstream for Xilinx Zynq |
| UltraScale+ (ZynqMP) device. |
| |
| 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 creates 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" |
| |- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...] |
| |- loadables = "loadables sub-node unit-name" |
| |- compatible = "vendor,board-style device tree compatible string" |
| |
| |
| Mandatory properties: |
| - description : Textual configuration description. |
| - kernel or firmware: Unit name of the corresponding kernel or firmware |
| (u-boot, op-tee, etc) image. If both "kernel" and "firmware" are specified, |
| control is passed to the firmware image. |
| |
| Optional properties: |
| - fdt : Unit name of the corresponding fdt blob (component image node of a |
| "fdt type"). Additional fdt overlay nodes can be supplied which signify |
| that the resulting device tree blob is generated by the first base fdt |
| blob with all subsequent overlays applied. |
| - fpga : Unit name of the corresponding fpga bitstream blob |
| (component image node of a "fpga type"). |
| - loadables : Unit name containing a list of additional binaries to be |
| loaded at their given locations. "loadables" is a comma-separated list |
| of strings. U-Boot will load each binary at its given start-address and |
| may optionally invoke additional post-processing steps on this binary based |
| on its component image node type. |
| - compatible : The root compatible string of the U-Boot device tree that |
| this configuration shall automatically match when CONFIG_FIT_BEST_MATCH is |
| enabled. If this property is not provided, the compatible string will be |
| extracted from the fdt blob instead. This is only possible if the fdt is |
| not compressed, so images with compressed fdts that want to use compatible |
| string matching must always provide this property. |
| |
| 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) External data |
| ---------------- |
| |
| The above format shows a 'data' property which holds the data for each image. |
| It is also possible for this data to reside outside the FIT itself. This |
| allows the FIT to be quite small, so that it can be loaded and scanned |
| without loading a large amount of data. Then when an image is needed it can |
| be loaded from an external source. |
| |
| In this case the 'data' property is omitted. Instead you can use: |
| |
| - data-offset : offset of the data in a separate image store. The image |
| store is placed immediately after the last byte of the device tree binary, |
| aligned to a 4-byte boundary. |
| - data-size : size of the data in bytes |
| |
| The 'data-offset' property can be substituted with 'data-position', which |
| defines an absolute position or address as the offset. This is helpful when |
| booting U-Boot proper before performing relocation. Pass '-p [offset]' to |
| mkimage to enable 'data-position'. |
| |
| Normal kernel FIT image has data embedded within FIT structure. U-Boot image |
| for SPL boot has external data. Existence of 'data-offset' can be used to |
| identify which format is used. |
| |
| For FIT image with external data, it would be better to align each blob of data |
| to block(512 byte) for block device, so that we don't need to do the copy when |
| read the image data in SPL. Pass '-B 0x200' to mkimage to align the FIT |
| structure and data to 512 byte, other values available for other align size. |
| |
| 9) Examples |
| ----------- |
| |
| Please see doc/uImage.FIT/*.its for actual image source files. |