ref-manual/ref-classes: update kernel-fitimage with Initramfs bundle and boot script

Submitted by abdellatif.elkhlifi@arm.com on Oct. 13, 2020, 12:09 p.m. | Patch ID: 177190

Details

Message ID 20201013120937.10453-1-abdellatif.elkhlifi@arm.com
State New
Headers show

Commit Message

abdellatif.elkhlifi@arm.com Oct. 13, 2020, 12:09 p.m.
From: Abdellatif El Khlifi <abdellatif.elkhlifi@arm.com>

This commit adds the description of the Initramfs bundle and boot script
new features implemented in the kernel-fitimage class.

Change-Id: Ifffa6b850308aa7ceadc4f117806cffad0137137
Signed-off-by: Abdellatif El Khlifi <abdellatif.elkhlifi@arm.com>
---
 documentation/ref-manual/ref-classes.rst | 32 ++++++++++++++++++++----
 1 file changed, 27 insertions(+), 5 deletions(-)

Patch hide | download patch | download mbox

diff --git a/documentation/ref-manual/ref-classes.rst b/documentation/ref-manual/ref-classes.rst
index 756df2a60f..0e5342340a 100644
--- a/documentation/ref-manual/ref-classes.rst
+++ b/documentation/ref-manual/ref-classes.rst
@@ -1375,11 +1375,13 @@  generation.
 ===========================
 
 The ``kernel-fitimage`` class provides support to pack a kernel Image,
-device trees and a RAM disk into a single FIT image. In theory, a FIT
-image can support any number of kernels, RAM disks and device-trees.
+device trees, a U-boot script, a Initramfs bundle and a RAM disk
+into a single FIT image. In theory, a FIT image can support any number
+of kernels, U-boot scripts, Initramfs bundles, RAM disks and device-trees.
 However, ``kernel-fitimage`` currently only supports
-limited usescases: just one kernel image, an optional RAM disk, and
-any number of device tree.
+limited usescases: just one kernel image, an optional U-boot script,
+an optional Initramfs bundle, an optional RAM disk, and any number of
+device tree.
 
 To create a FIT image, it is required that :term:`KERNEL_CLASSES`
 is set to "kernel-fitimage" and :term:`KERNEL_IMAGETYPE`
@@ -1406,7 +1408,27 @@  Only a single RAM disk can be added to the FIT image created by
 The address where the RAM disk image is to be loaded by U-boot
 is specified by :term:`UBOOT_RD_LOADADDRESS` and the entrypoint by
 :term:`UBOOT_RD_ENTRYPOINT`. The ramdisk is added to FIT image when
-:term:`INITRAMFS_IMAGE` is specified.
+:term:`INITRAMFS_IMAGE` is specified and that :term:`INITRAMFS_IMAGE_BUNDLE`
+is set to 0.
+
+Only a single Initramfs bundle can be added to the FIT image created by
+``kernel-fitimage`` and the Initramfs bundle in FIT is optional.
+In case of Initramfs, the kernel is configured to be bundled with the rootfs
+in the same binary (example: zImage-initramfs-:term:`MACHINE`.bin).
+When the kernel is copied to RAM and executed, it unpacks the Initramfs rootfs.
+The Initramfs bundle can be enabled when :term:`INITRAMFS_IMAGE`
+is specified and that :term:`INITRAMFS_IMAGE_BUNDLE` is set to 1.
+The address where the Initramfs bundle is to be loaded by U-boot is specified
+by :term:`UBOOT_LOADADDRESS` and the entrypoint by :term:`UBOOT_ENTRYPOINT`.
+
+Only a single U-boot boot script can be added to the FIT image created by
+``kernel-fitimage`` and the boot script is optional.
+The boot script is specified in the ITS file as a text file containing
+U-boot commands. When using a boot script the user should configure the
+U-boot ``do_install`` task to copy the script to sysroot.
+So the script can be included in the the FIT image by the ``kernel-fitimage``
+class. At run-time, U-boot CONFIG_BOOTCOMMAND define can be configured to
+load the boot script from the FIT image and executes it.
 
 The FIT image generated by ``kernel-fitimage`` class is signed when the
 variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`,