1# Flattened uImage Tree documentation 2 3[uImage.FIT] is the new format used for uImage payloads developed by 4[U-boot]. 5 6## Supported architectures 7 8* aarch32 9* aarch64 10* riscv 11 12## Supported FIT sections 13 14The FIT can contain multiple sections, each holding a unique 15kernel, initrd or config. Out of the sections one kernel and 16one initrd is chosen, depending on the matching config. 17 18The config is selected depending on the compat string. 19 20The section must be named in order to be found by the FIT parser: 21 22* kernel 23* fdt 24* ramdisk 25 26## Architecture specifics 27 28The FIT parser needs architecture support. 29 30### aarch32 31The source code can be found in `src/arch/arm/fit_payload.c`. 32 33On aarch32 the kernel (a section named 'kernel') must be in **Image** 34format and it needs a devicetree (a section named 'fdt') to boot. 35The kernel will be placed close to "*DRAMSTART*". 36 37### aarch64 38The source code can be found in `src/arch/arm64/fit_payload.c`. 39 40On aarch64 the kernel (a section named 'kernel') must be in **Image** 41format and it needs a devicetree (a section named 'fdt') to boot. 42The kernel will be placed close to "*DRAMSTART*". 43 44### RISC-V 45The source code can be found in `src/arch/riscv/fit_payload.c`. 46 47On RISC-V the kernel (a section named 'kernel') must be in **Image** 48format and it needs a devicetree (a section named 'fdt') to boot. 49The kernel will be placed close to "*DRAMSTART*". 50 51### Other 52Other architectures aren't supported. 53 54## Supported compression 55 56The FIT image has to be included uncompressed into the CBFS. The sections 57inside the FIT image can use different compression schemes. 58 59Supported compression algorithms: 60* LZMA 61* LZ4 62* none 63 64## Compat string 65 66The config entries contain a compatible string, that is used to find a 67matching config. 68 69The following mainboard specific functions provide the BOARDID and SKUID: 70 71```c 72uint32_t board_id(void); 73``` 74 75```c 76uint32_t sku_id(void); 77``` 78 79By default the following compat strings are added: 80 81* *CONFIG_MAINBOARD_VENDOR*,*CONFIG_MAINBOARD_PART_NUMBER* 82* *CONFIG_MAINBOARD_VENDOR*,*CONFIG_MAINBOARD_PART_NUMBER*-rev*BOARDID* 83* *CONFIG_MAINBOARD_VENDOR*,*CONFIG_MAINBOARD_PART_NUMBER*-rev*BOARDID*-sku*SKUID* 84 85Example: 86 87``` 88cavium,cn8100_sff_evb 89``` 90 91If *board_id()* or *sku_id()* return invalid, the single comapt string isn't added. 92 93You can add custom compat strings by calling: 94 95```c 96fit_add_compat_string(const char *str); 97``` 98 99If no matching compat string is found, the default config is chosen. 100 101## Building FIT image 102 103The FIT image has to be built by calling `mkimage`. You can use 104the following example configuration: 105 106``` 107/* 108 * Simple U-Boot uImage source file containing a single kernel and FDT blob 109 */ 110 111/dts-v1/; 112 113/ { 114 description = "Simple image with single Linux kernel and FDT blob"; 115 #address-cells = <1>; 116 117 images { 118 kernel { 119 description = "Vanilla Linux kernel"; 120 data = /incbin/("Image.lzma"); 121 type = "kernel"; 122 arch = "arm64"; 123 os = "linux"; 124 compression = "lzma"; 125 load = <0x80000>; 126 entry = <0x80000>; 127 hash-1 { 128 algo = "crc32"; 129 }; 130 }; 131 fdt-1 { 132 description = "Flattened Device Tree blob"; 133 data = /incbin/("target.dtb"); 134 type = "flat_dt"; 135 arch = "arm64"; 136 compression = "none"; 137 hash-1 { 138 algo = "crc32"; 139 }; 140 }; 141 ramdisk-1 { 142 description = "Compressed Initramfs"; 143 data = /incbin/("initramfs.cpio.xz"); 144 type = "ramdisk"; 145 arch = "arm64"; 146 os = "linux"; 147 compression = "none"; 148 load = <00000000>; 149 entry = <00000000>; 150 hash-1 { 151 algo = "sha1"; 152 }; 153 }; 154 }; 155 156 configurations { 157 default = "conf-1"; 158 conf-1 { 159 description = "Boot Linux kernel with FDT blob"; 160 kernel = "kernel"; 161 fdt = "fdt-1"; 162 ramdisk = "ramdisk-1"; 163 }; 164 }; 165}; 166``` 167 168Save it as ITS file `config.its` along with the other files defined here: 169* target.dtb 170* initramfs.cpio.xz 171* Image.lzma 172 173Generate the `uImage` that will be included into the CBFS by calling 174 175```bash 176mkimage -f config.its uImage 177``` 178 179The generated file includes a compressed initrd **initramfs.cpio.xz**, which 180will be decompressed by the Linux kernel, a compressed kernel **Image.lzma**, 181which will be decompressed by the FIT loader and an uncompressed devicetree blob. 182 183[uImage.FIT]: https://github.com/u-boot/u-boot/blob/master/doc/usage/fit/howto.rst 184[U-Boot]: https://www.denx.de/wiki/U-Boot 185