[coreboot-gerrit] Change in coreboot[master]: Documentation: Add FIT payload documentation
Philipp Deppenwiese (Code Review)
gerrit at coreboot.org
Thu Aug 9 01:49:44 CEST 2018
Philipp Deppenwiese has submitted this change and it was merged. ( 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>
Reviewed-on: https://review.coreboot.org/27253
Tested-by: build bot (Jenkins) <no-reply at coreboot.org>
Reviewed-by: Philipp Deppenwiese <zaolin.daisuki at gmail.com>
---
M Documentation/index.md
A Documentation/lib/payloads/fit.md
A Documentation/lib/payloads/index.md
3 files changed, 168 insertions(+), 0 deletions(-)
Approvals:
build bot (Jenkins): Verified
Philipp Deppenwiese: Looks good to me, approved
diff --git a/Documentation/index.md b/Documentation/index.md
index a75edde..b20eedc 100644
--- a/Documentation/index.md
+++ b/Documentation/index.md
@@ -18,6 +18,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)
* [Utilities](util.md)
diff --git a/Documentation/lib/payloads/fit.md b/Documentation/lib/payloads/fit.md
new file mode 100644
index 0000000..22a50db
--- /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 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: merged
Gerrit-Change-Id: I8b2060f2a63406669196bcbc190cc1511ae9fe94
Gerrit-Change-Number: 27253
Gerrit-PatchSet: 3
Gerrit-Owner: Patrick Rudolph <patrick.rudolph at 9elements.com>
Gerrit-Reviewer: David Hendricks <david.hendricks at gmail.com>
Gerrit-Reviewer: Patrick Rudolph <patrick.rudolph at 9elements.com>
Gerrit-Reviewer: Paul Menzel <paulepanter at users.sourceforge.net>
Gerrit-Reviewer: Philipp Deppenwiese <zaolin.daisuki at gmail.com>
Gerrit-Reviewer: T.Michael Turney <tturne at codeaurora.org>
Gerrit-Reviewer: Tristan Hsieh <tristan.shieh at mediatek.com>
Gerrit-Reviewer: build bot (Jenkins) <no-reply at coreboot.org>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.coreboot.org/pipermail/coreboot-gerrit/attachments/20180808/a1447f75/attachment.html>
More information about the coreboot-gerrit
mailing list