Merge tag 'u-boot-stm32-20200528' of https://gitlab.denx.de/u-boot/custodians/u-boot-stm
[oweals/u-boot.git] / doc / uImage.FIT / source_file_format.txt
index 88663a161d34e9c1824144c6aa0fdce51f07307b..884a58456f760c6b2b9fc8bce78cf52ac46090af 100644 (file)
@@ -102,15 +102,15 @@ Root node of the uImage Tree should have the following layout:
     |
     o images
     | |
-    | o image@1 {...}
-    | o image@2 {...}
+    | o image-1 {...}
+    | o image-2 {...}
     | ...
     |
     o configurations
-      |- default = "conf@1"
+      |- default = "conf-1"
       |
-      o conf@1 {...}
-      o conf@2 {...}
+      o conf-1 {...}
+      o conf-2 {...}
       ...
 
 
@@ -142,7 +142,7 @@ Root node of the uImage Tree should have the following layout:
 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
+ o image-1
    |- description = "component sub-image description"
    |- data = /incbin/("path/to/data/file.bin")
    |- type = "sub-image type name"
@@ -152,8 +152,8 @@ the '/images' node should have the following layout:
    |- load = <00000000>
    |- entry = <00000000>
    |
-   o hash@1 {...}
-   o hash@2 {...}
+   o hash-1 {...}
+   o hash-2 {...}
    ...
 
   Mandatory properties:
@@ -164,7 +164,9 @@ the '/images' node should have the following layout:
   - 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".
+    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" and "ramdisk". Valid OS names
@@ -183,14 +185,14 @@ the '/images' node should have the following layout:
     property of the root node. Mandatory for types: "standalone" and "kernel".
 
   Optional nodes:
-  - hash@1 : Each hash sub-node represents separate hash or checksum
+  - 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
+o hash-1
   |- algo = "hash or checksum algorithm name"
   |- value = [hash or checksum value]
 
@@ -212,8 +214,8 @@ The 'configurations' node has has the following structure:
 o configurations
   |- default = "default configuration sub-node unit name"
   |
-  o config@1 {...}
-  o config@2 {...}
+  o config-1 {...}
+  o config-2 {...}
   ...
 
 
@@ -231,13 +233,14 @@ o configurations
 
 Each configuration has the following structure:
 
-o config@1
+o config-1
   |- description = "configuration description"
   |- kernel = "kernel sub-node unit name"
   |- ramdisk = "ramdisk sub-node unit name"
   |- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...]
   |- fpga = "fpga sub-node unit-name"
   |- loadables = "loadables sub-node unit-name"
+  |- compatible = "vendor,board-style device tree compatible string"
 
 
   Mandatory properties:
@@ -259,8 +262,14 @@ o config@1
   - 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 optionaly invoke additional post-processing steps on this binary based
+    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.
@@ -295,6 +304,11 @@ 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
 -----------