Documentation: Add FIT payload documentation
Describe the new uImage.FIT loader. Change-Id: I8b2060f2a63406669196bcbc190cc1511ae9fe94 Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com> Reviewed-on: https://review.coreboot.org/27253 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com>
This commit is contained in:
parent
8346a44dd1
commit
486df4612d
|
@ -18,6 +18,7 @@ Contents:
|
|||
* [Northbridge-specific documentation](northbridge/index.md)
|
||||
* [System on Chip-specific documentation](soc/index.md)
|
||||
* [Mainboard-specific documentation](mainboard/index.md)
|
||||
* [Payload-specific documentation](lib/payloads/index.md)
|
||||
* [SuperIO-specific documentation](superio/index.md)
|
||||
* [Vendorcode-specific documentation](vendorcode/index.md)
|
||||
* [Utilities](util.md)
|
||||
|
|
|
@ -0,0 +1,156 @@
|
|||
# Flattened uImage Tree documentation
|
||||
|
||||
[uImage.FIT] is the new format used for uImage payloads developed by
|
||||
[U-boot].
|
||||
|
||||
## Supported architectures
|
||||
|
||||
* aarch64
|
||||
|
||||
## Supported FIT sections
|
||||
|
||||
The FIT can contain multiple sections, each holding a unique
|
||||
kernel, initrd or config. Out of the sections one kernel and
|
||||
one initrd is chosen, depending on the matching config.
|
||||
|
||||
The config is selected depending on the compat string.
|
||||
|
||||
The section must be named in order to be found by the FIT parser:
|
||||
|
||||
* kernel
|
||||
* fdt
|
||||
* ramdisk
|
||||
|
||||
## Architecture specifics
|
||||
|
||||
The FIT parser needs architecure support.
|
||||
### aarch64
|
||||
The source code can be found in ''src/arch/arm64/fit.c''.
|
||||
|
||||
On aarch64 the kernel (a section named 'kernel') must be in **Image**
|
||||
format and it needs a devicetree (a section named 'fdt') to boot.
|
||||
The kernel will be placed close to "*DRAMSTART*".
|
||||
|
||||
### Other
|
||||
Other architectures aren't supported.
|
||||
|
||||
## Supported compression
|
||||
|
||||
The FIT image has to be included uncompressed into the CBFS. The sections
|
||||
inside the FIT image can use different compression schemes.
|
||||
|
||||
Supported compression algorithms:
|
||||
* LZMA
|
||||
* LZ4
|
||||
* none
|
||||
|
||||
## Compat string
|
||||
|
||||
The config entries contain a compatible string, that is used to find a
|
||||
matching config.
|
||||
|
||||
The following mainboard specific funtions provide the BOARDID and SKUID:
|
||||
|
||||
```c
|
||||
uint32_t board_id(void);
|
||||
```
|
||||
|
||||
```c
|
||||
uint32_t sku_id(void);
|
||||
```
|
||||
|
||||
By default the following compat strings are added:
|
||||
|
||||
* *CONFIG_MAINBOARD_VENDOR*,*CONFIG_MAINBOARD_PART_NUMBER*
|
||||
* *CONFIG_MAINBOARD_VENDOR*,*CONFIG_MAINBOARD_PART_NUMBER*-rev*BOARDID*
|
||||
* *CONFIG_MAINBOARD_VENDOR*,*CONFIG_MAINBOARD_PART_NUMBER*-rev*BOARDID*-sku*SKUID*
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
cavium,cn8100_sff_evb
|
||||
```
|
||||
|
||||
If *board_id()* or *sku_id()* return invalid, the single comapt string isn't added.
|
||||
|
||||
You can add custom compat strings by calling:
|
||||
|
||||
```c
|
||||
fit_add_compat_string(const char *str);
|
||||
```
|
||||
|
||||
If no matching compat string is found, the default config is chosen.
|
||||
|
||||
## Building FIT image
|
||||
|
||||
The FIT image has to be built by calling ''mkimage''. You can use
|
||||
the following example configuration:
|
||||
|
||||
```
|
||||
/*
|
||||
* Simple U-Boot uImage source file containing a single kernel and FDT blob
|
||||
*/
|
||||
|
||||
/dts-v1/;
|
||||
|
||||
/ {
|
||||
description = "Simple image with single Linux kernel and FDT blob";
|
||||
#address-cells = <1>;
|
||||
|
||||
images {
|
||||
kernel {
|
||||
description = "Vanilla Linux kernel";
|
||||
data = /incbin/("Image.lzma");
|
||||
type = "kernel";
|
||||
arch = "arm64";
|
||||
os = "linux";
|
||||
compression = "lzma";
|
||||
load = <0x80000>;
|
||||
entry = <0x80000>;
|
||||
hash-1 {
|
||||
algo = "crc32";
|
||||
};
|
||||
};
|
||||
fdt-1 {
|
||||
description = "Flattened Device Tree blob";
|
||||
data = /incbin/("target.dtb");
|
||||
type = "flat_dt";
|
||||
arch = "arm64";
|
||||
compression = "none";
|
||||
hash-1 {
|
||||
algo = "crc32";
|
||||
};
|
||||
};
|
||||
ramdisk-1 {
|
||||
description = "Compressed Initramfs";
|
||||
data = /incbin/("initramfs.cpio.xz");
|
||||
type = "ramdisk";
|
||||
arch = "arm64";
|
||||
os = "linux";
|
||||
compression = "none";
|
||||
load = <00000000>;
|
||||
entry = <00000000>;
|
||||
hash-1 {
|
||||
algo = "sha1";
|
||||
};
|
||||
};
|
||||
};
|
||||
|
||||
configurations {
|
||||
default = "conf-1";
|
||||
conf-1 {
|
||||
description = "Boot Linux kernel with FDT blob";
|
||||
kernel = "kernel";
|
||||
fdt = "fdt-1";
|
||||
ramdisk = "ramdisk-1";
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
It includes a compressed initrd **initramfs.cpio.xz**, which will be
|
||||
decompressed by the Linux kernel, a compressed kernel **Image.lzma**, which will
|
||||
be decompressed by the FIT loader and an uncompressed devicetree blob.
|
||||
|
||||
[uImage.FIT]: https://raw.githubusercontent.com/u-boot/u-boot/master/doc/uImage.FIT/howto.txt
|
||||
[U-Boot]: https://www.denx.de/wiki/U-Boot
|
|
@ -0,0 +1,11 @@
|
|||
# Payload-specific documentation
|
||||
|
||||
This section contains documentation about coreboot on specific payloads.
|
||||
|
||||
Payloads are run after coreboot has initialized the hardware.
|
||||
coreboot supports multiple payloads, depending on the architecture of the
|
||||
selected mainboard.
|
||||
|
||||
## FIT
|
||||
|
||||
- [uImage.FIT support](fit.md)
|
Loading…
Reference in New Issue