<p>Philipp Deppenwiese <strong>merged</strong> this change.</p><p><a href="https://review.coreboot.org/27253">View Change</a></p><div style="white-space:pre-wrap">Approvals:
build bot (Jenkins): Verified
Philipp Deppenwiese: Looks good to me, approved
</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">Documentation: Add FIT payload documentation<br><br>Describe the new uImage.FIT loader.<br><br>Change-Id: I8b2060f2a63406669196bcbc190cc1511ae9fe94<br>Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com><br>Reviewed-on: https://review.coreboot.org/27253<br>Tested-by: build bot (Jenkins) <no-reply@coreboot.org><br>Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com><br>---<br>M Documentation/index.md<br>A Documentation/lib/payloads/fit.md<br>A Documentation/lib/payloads/index.md<br>3 files changed, 168 insertions(+), 0 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/Documentation/index.md b/Documentation/index.md</span><br><span>index a75edde..b20eedc 100644</span><br><span>--- a/Documentation/index.md</span><br><span>+++ b/Documentation/index.md</span><br><span>@@ -18,6 +18,7 @@</span><br><span> * [Northbridge-specific documentation](northbridge/index.md)</span><br><span> * [System on Chip-specific documentation](soc/index.md)</span><br><span> * [Mainboard-specific documentation](mainboard/index.md)</span><br><span style="color: hsl(120, 100%, 40%);">+* [Payload-specific documentation](lib/payloads/index.md)</span><br><span> * [SuperIO-specific documentation](superio/index.md)</span><br><span> * [Vendorcode-specific documentation](vendorcode/index.md)</span><br><span> * [Utilities](util.md)</span><br><span>diff --git a/Documentation/lib/payloads/fit.md b/Documentation/lib/payloads/fit.md</span><br><span>new file mode 100644</span><br><span>index 0000000..22a50db</span><br><span>--- /dev/null</span><br><span>+++ b/Documentation/lib/payloads/fit.md</span><br><span>@@ -0,0 +1,156 @@</span><br><span style="color: hsl(120, 100%, 40%);">+# Flattened uImage Tree documentation</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[uImage.FIT] is the new format used for uImage payloads developed by</span><br><span style="color: hsl(120, 100%, 40%);">+[U-boot].</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Supported architectures</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* aarch64</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Supported FIT sections</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The FIT can contain multiple sections, each holding a unique</span><br><span style="color: hsl(120, 100%, 40%);">+kernel, initrd or config. Out of the sections one kernel and</span><br><span style="color: hsl(120, 100%, 40%);">+one initrd is chosen, depending on the matching config.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The config is selected depending on the compat string.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The section must be named in order to be found by the FIT parser:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* kernel</span><br><span style="color: hsl(120, 100%, 40%);">+* fdt</span><br><span style="color: hsl(120, 100%, 40%);">+* ramdisk</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Architecture specifics</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The FIT parser needs architecure support.</span><br><span style="color: hsl(120, 100%, 40%);">+### aarch64</span><br><span style="color: hsl(120, 100%, 40%);">+The source code can be found in ''src/arch/arm64/fit.c''.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+On aarch64 the kernel (a section named 'kernel') must be in **Image**</span><br><span style="color: hsl(120, 100%, 40%);">+format and it needs a devicetree (a section named 'fdt') to boot.</span><br><span style="color: hsl(120, 100%, 40%);">+The kernel will be placed close to "*DRAMSTART*".</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Other</span><br><span style="color: hsl(120, 100%, 40%);">+Other architectures aren't supported.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Supported compression</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The FIT image has to be included uncompressed into the CBFS. The sections</span><br><span style="color: hsl(120, 100%, 40%);">+inside the FIT image can use different compression schemes.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Supported compression algorithms:</span><br><span style="color: hsl(120, 100%, 40%);">+* LZMA</span><br><span style="color: hsl(120, 100%, 40%);">+* LZ4</span><br><span style="color: hsl(120, 100%, 40%);">+* none</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Compat string</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The config entries contain a compatible string, that is used to find a</span><br><span style="color: hsl(120, 100%, 40%);">+matching config.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The following mainboard specific funtions provide the BOARDID and SKUID:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```c</span><br><span style="color: hsl(120, 100%, 40%);">+uint32_t board_id(void);</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```c</span><br><span style="color: hsl(120, 100%, 40%);">+uint32_t sku_id(void);</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+By default the following compat strings are added:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* *CONFIG_MAINBOARD_VENDOR*,*CONFIG_MAINBOARD_PART_NUMBER*</span><br><span style="color: hsl(120, 100%, 40%);">+* *CONFIG_MAINBOARD_VENDOR*,*CONFIG_MAINBOARD_PART_NUMBER*-rev*BOARDID*</span><br><span style="color: hsl(120, 100%, 40%);">+* *CONFIG_MAINBOARD_VENDOR*,*CONFIG_MAINBOARD_PART_NUMBER*-rev*BOARDID*-sku*SKUID*</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Example:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+cavium,cn8100_sff_evb</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If *board_id()* or *sku_id()* return invalid, the single comapt string isn't added.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+You can add custom compat strings by calling:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```c</span><br><span style="color: hsl(120, 100%, 40%);">+fit_add_compat_string(const char *str);</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If no matching compat string is found, the default config is chosen.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Building FIT image</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The FIT image has to be built by calling ''mkimage''. You can use</span><br><span style="color: hsl(120, 100%, 40%);">+the following example configuration:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+/*</span><br><span style="color: hsl(120, 100%, 40%);">+ * Simple U-Boot uImage source file containing a single kernel and FDT blob</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/dts-v1/;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/ {</span><br><span style="color: hsl(120, 100%, 40%);">+ description = "Simple image with single Linux kernel and FDT blob";</span><br><span style="color: hsl(120, 100%, 40%);">+ #address-cells = <1>;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ images {</span><br><span style="color: hsl(120, 100%, 40%);">+ kernel {</span><br><span style="color: hsl(120, 100%, 40%);">+ description = "Vanilla Linux kernel";</span><br><span style="color: hsl(120, 100%, 40%);">+ data = /incbin/("Image.lzma");</span><br><span style="color: hsl(120, 100%, 40%);">+ type = "kernel";</span><br><span style="color: hsl(120, 100%, 40%);">+ arch = "arm64";</span><br><span style="color: hsl(120, 100%, 40%);">+ os = "linux";</span><br><span style="color: hsl(120, 100%, 40%);">+ compression = "lzma";</span><br><span style="color: hsl(120, 100%, 40%);">+ load = <0x80000>;</span><br><span style="color: hsl(120, 100%, 40%);">+ entry = <0x80000>;</span><br><span style="color: hsl(120, 100%, 40%);">+ hash-1 {</span><br><span style="color: hsl(120, 100%, 40%);">+ algo = "crc32";</span><br><span style="color: hsl(120, 100%, 40%);">+ };</span><br><span style="color: hsl(120, 100%, 40%);">+ };</span><br><span style="color: hsl(120, 100%, 40%);">+ fdt-1 {</span><br><span style="color: hsl(120, 100%, 40%);">+ description = "Flattened Device Tree blob";</span><br><span style="color: hsl(120, 100%, 40%);">+ data = /incbin/("target.dtb");</span><br><span style="color: hsl(120, 100%, 40%);">+ type = "flat_dt";</span><br><span style="color: hsl(120, 100%, 40%);">+ arch = "arm64";</span><br><span style="color: hsl(120, 100%, 40%);">+ compression = "none";</span><br><span style="color: hsl(120, 100%, 40%);">+ hash-1 {</span><br><span style="color: hsl(120, 100%, 40%);">+ algo = "crc32";</span><br><span style="color: hsl(120, 100%, 40%);">+ };</span><br><span style="color: hsl(120, 100%, 40%);">+ };</span><br><span style="color: hsl(120, 100%, 40%);">+ ramdisk-1 {</span><br><span style="color: hsl(120, 100%, 40%);">+ description = "Compressed Initramfs";</span><br><span style="color: hsl(120, 100%, 40%);">+ data = /incbin/("initramfs.cpio.xz");</span><br><span style="color: hsl(120, 100%, 40%);">+ type = "ramdisk";</span><br><span style="color: hsl(120, 100%, 40%);">+ arch = "arm64";</span><br><span style="color: hsl(120, 100%, 40%);">+ os = "linux";</span><br><span style="color: hsl(120, 100%, 40%);">+ compression = "none";</span><br><span style="color: hsl(120, 100%, 40%);">+ load = <00000000>;</span><br><span style="color: hsl(120, 100%, 40%);">+ entry = <00000000>;</span><br><span style="color: hsl(120, 100%, 40%);">+ hash-1 {</span><br><span style="color: hsl(120, 100%, 40%);">+ algo = "sha1";</span><br><span style="color: hsl(120, 100%, 40%);">+ };</span><br><span style="color: hsl(120, 100%, 40%);">+ };</span><br><span style="color: hsl(120, 100%, 40%);">+ };</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ configurations {</span><br><span style="color: hsl(120, 100%, 40%);">+ default = "conf-1";</span><br><span style="color: hsl(120, 100%, 40%);">+ conf-1 {</span><br><span style="color: hsl(120, 100%, 40%);">+ description = "Boot Linux kernel with FDT blob";</span><br><span style="color: hsl(120, 100%, 40%);">+ kernel = "kernel";</span><br><span style="color: hsl(120, 100%, 40%);">+ fdt = "fdt-1";</span><br><span style="color: hsl(120, 100%, 40%);">+ ramdisk = "ramdisk-1";</span><br><span style="color: hsl(120, 100%, 40%);">+ };</span><br><span style="color: hsl(120, 100%, 40%);">+ };</span><br><span style="color: hsl(120, 100%, 40%);">+};</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+It includes a compressed initrd **initramfs.cpio.xz**, which will be</span><br><span style="color: hsl(120, 100%, 40%);">+decompressed by the Linux kernel, a compressed kernel **Image.lzma**, which will</span><br><span style="color: hsl(120, 100%, 40%);">+be decompressed by the FIT loader and an uncompressed devicetree blob.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[uImage.FIT]: https://raw.githubusercontent.com/u-boot/u-boot/master/doc/uImage.FIT/howto.txt</span><br><span style="color: hsl(120, 100%, 40%);">+[U-Boot]: https://www.denx.de/wiki/U-Boot</span><br><span>diff --git a/Documentation/lib/payloads/index.md b/Documentation/lib/payloads/index.md</span><br><span>new file mode 100644</span><br><span>index 0000000..44daef1</span><br><span>--- /dev/null</span><br><span>+++ b/Documentation/lib/payloads/index.md</span><br><span>@@ -0,0 +1,11 @@</span><br><span style="color: hsl(120, 100%, 40%);">+# Payload-specific documentation</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This section contains documentation about coreboot on specific payloads.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Payloads are run after coreboot has initialized the hardware.</span><br><span style="color: hsl(120, 100%, 40%);">+coreboot supports multiple payloads, depending on the architecture of the</span><br><span style="color: hsl(120, 100%, 40%);">+selected mainboard.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## FIT</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+- [uImage.FIT support](fit.md)</span><br><span></span><br></pre><p>To view, visit <a href="https://review.coreboot.org/27253">change 27253</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://review.coreboot.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://review.coreboot.org/27253"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: coreboot </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-MessageType: merged </div>
<div style="display:none"> Gerrit-Change-Id: I8b2060f2a63406669196bcbc190cc1511ae9fe94 </div>
<div style="display:none"> Gerrit-Change-Number: 27253 </div>
<div style="display:none"> Gerrit-PatchSet: 3 </div>
<div style="display:none"> Gerrit-Owner: Patrick Rudolph <patrick.rudolph@9elements.com> </div>
<div style="display:none"> Gerrit-Reviewer: David Hendricks <david.hendricks@gmail.com> </div>
<div style="display:none"> Gerrit-Reviewer: Patrick Rudolph <patrick.rudolph@9elements.com> </div>
<div style="display:none"> Gerrit-Reviewer: Paul Menzel <paulepanter@users.sourceforge.net> </div>
<div style="display:none"> Gerrit-Reviewer: Philipp Deppenwiese <zaolin.daisuki@gmail.com> </div>
<div style="display:none"> Gerrit-Reviewer: T.Michael Turney <tturne@codeaurora.org> </div>
<div style="display:none"> Gerrit-Reviewer: Tristan Hsieh <tristan.shieh@mediatek.com> </div>
<div style="display:none"> Gerrit-Reviewer: build bot (Jenkins) <no-reply@coreboot.org> </div>