[coreboot-gerrit] Change in coreboot[master]: Documentation: Add FIT payload documentation
Patrick Rudolph (Code Review)
gerrit at coreboot.org
Wed Jun 27 13:11:53 CEST 2018
Patrick Rudolph has uploaded this change for review. ( https://review.coreboot.org/27253
Change subject: Documentation: Add FIT payload documentation
......................................................................
Documentation: Add FIT payload documentation
Describe the new uImage.FIT loader.
Change-Id: I8b2060f2a63406669196bcbc190cc1511ae9fe94
Signed-off-by: Patrick Rudolph <patrick.rudolph at 9elements.com>
---
M Documentation/index.md
A Documentation/lib/payloads/fit.md
A Documentation/lib/payloads/index.md
3 files changed, 167 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/53/27253/1
diff --git a/Documentation/index.md b/Documentation/index.md
index cf22dca..48eee25 100644
--- a/Documentation/index.md
+++ b/Documentation/index.md
@@ -17,6 +17,7 @@
* [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)
* [Release notes for past releases](releases/index.md)
diff --git a/Documentation/lib/payloads/fit.md b/Documentation/lib/payloads/fit.md
new file mode 100644
index 0000000..a2cb8f8
--- /dev/null
+++ b/Documentation/lib/payloads/fit.md
@@ -0,0 +1,155 @@
+# FIT documentation
+
+[uImage.FIT] is the new format used for uImage payloads developed by
+uboot.
+
+## 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 choosen, 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 specific
+
+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 an devicetree (a section named 'fdt') to boot.
+The kernel will be placed close to *DRAM_START*.
+
+### 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 contains 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()* returns 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 choosen.
+
+## Building FIT image
+
+The FIT image has to be build 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
diff --git a/Documentation/lib/payloads/index.md b/Documentation/lib/payloads/index.md
new file mode 100644
index 0000000..44daef1
--- /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)
--
To view, visit https://review.coreboot.org/27253
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings
Gerrit-Project: coreboot
Gerrit-Branch: master
Gerrit-MessageType: newchange
Gerrit-Change-Id: I8b2060f2a63406669196bcbc190cc1511ae9fe94
Gerrit-Change-Number: 27253
Gerrit-PatchSet: 1
Gerrit-Owner: Patrick Rudolph <patrick.rudolph at 9elements.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.coreboot.org/pipermail/coreboot-gerrit/attachments/20180627/9f32eb87/attachment-0001.html>
More information about the coreboot-gerrit
mailing list