diff options
Diffstat (limited to 'doc/uImage.FIT/source_file_format.txt')
| -rw-r--r-- | doc/uImage.FIT/source_file_format.txt | 322 |
1 files changed, 0 insertions, 322 deletions
diff --git a/doc/uImage.FIT/source_file_format.txt b/doc/uImage.FIT/source_file_format.txt deleted file mode 100644 index 269e1fa0b58..00000000000 --- a/doc/uImage.FIT/source_file_format.txt +++ /dev/null @@ -1,322 +0,0 @@ -U-Boot new uImage source file format (bindings definition) -========================================================== - -Author: Marian Balakowicz <[email protected]> -External data additions, 25/1/16 Simon Glass <[email protected]> - -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 legacy_img_hdr' 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. - - phase : U-Boot phase for which the image is intended. - "spl" - image is an SPL image - "u-boot" - image is a U-Boot image - - 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" - |- script = " - |- 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. - - script : The image to use when loading a U-Boot script (for use with the - source command). - - 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. |