From 486df4612d18cf74e7bbcaa009d37e33199cd8fc Mon Sep 17 00:00:00 2001 From: Patrick Rudolph Date: Wed, 27 Jun 2018 13:09:49 +0200 Subject: Documentation: Add FIT payload documentation Describe the new uImage.FIT loader. Change-Id: I8b2060f2a63406669196bcbc190cc1511ae9fe94 Signed-off-by: Patrick Rudolph Reviewed-on: https://review.coreboot.org/27253 Tested-by: build bot (Jenkins) Reviewed-by: Philipp Deppenwiese --- Documentation/index.md | 1 + Documentation/lib/payloads/fit.md | 156 ++++++++++++++++++++++++++++++++++++ Documentation/lib/payloads/index.md | 11 +++ 3 files changed, 168 insertions(+) create mode 100644 Documentation/lib/payloads/fit.md create mode 100644 Documentation/lib/payloads/index.md diff --git a/Documentation/index.md b/Documentation/index.md index a75edde2b1..b20eedc10f 100644 --- a/Documentation/index.md +++ b/Documentation/index.md @@ -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) diff --git a/Documentation/lib/payloads/fit.md b/Documentation/lib/payloads/fit.md new file mode 100644 index 0000000000..22a50dbe1a --- /dev/null +++ b/Documentation/lib/payloads/fit.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 diff --git a/Documentation/lib/payloads/index.md b/Documentation/lib/payloads/index.md new file mode 100644 index 0000000000..44daef18b4 --- /dev/null +++ b/Documentation/lib/payloads/index.md @@ -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) -- cgit v1.2.3