From edd3b0224fb2d39dcb319f5a115fd5968cc72619 Mon Sep 17 00:00:00 2001 From: Antonin Godard Date: Mon, 27 Jan 2025 10:18:12 +0100 Subject: [PATCH] dev-manual/building: document the initramfs-framework recipe [ YOCTO #14747 ] Adding a initramfs is a common task, and the way oe-core offers to do so is by using the initramfs-framework recipe and companion modules. There was already documentation on adding an initramfs but the documentation was lacking details on this framework. Add it before the multiconfig section because it is a bit more important IMO. Reported-by: Alejandro Reviewed-by: Quentin Schulz (From yocto-docs rev: caedbca4eced4cf5bc74aaae64e4ad2887c2fc65) Signed-off-by: Antonin Godard Signed-off-by: Richard Purdie --- documentation/dev-manual/building.rst | 84 ++++++++++++++++++++++++++- 1 file changed, 83 insertions(+), 1 deletion(-) diff --git a/documentation/dev-manual/building.rst b/documentation/dev-manual/building.rst index fe502690dd..4770a5a184 100644 --- a/documentation/dev-manual/building.rst +++ b/documentation/dev-manual/building.rst @@ -280,7 +280,9 @@ Follow these steps to create an :term:`Initramfs` image: #. *Create the Initramfs Image Recipe:* You can reference the ``core-image-minimal-initramfs.bb`` recipe found in the ``meta/recipes-core`` directory of the :term:`Source Directory` - as an example from which to work. + as an example from which to work. The ``core-image-minimal-initramfs`` recipe + is based on the :ref:`initramfs-framework ` recipe described below. #. *Decide if You Need to Bundle the Initramfs Image Into the Kernel Image:* If you want the :term:`Initramfs` image that is built to be bundled @@ -308,6 +310,86 @@ Follow these steps to create an :term:`Initramfs` image: and bundled with the kernel image if you used the :term:`INITRAMFS_IMAGE_BUNDLE` variable described earlier. +Customizing an Initramfs using ``initramfs-framework`` +------------------------------------------------------ + +The ``core-image-minimal-initramfs.bb`` recipe found in +:oe_git:`meta/recipes-core/images +` uses the +:oe_git:`initramfs-framework_1.0.bb +` +recipe as its base component. The goal of the ``initramfs-framework`` recipe is +to provide the building blocks to build a customized :term:`Initramfs`. + +The ``initramfs-framework`` recipe relies on shell initialization scripts +defined in :oe_git:`meta/recipes-core/initrdscripts/initramfs-framework +`. Since some of +these scripts do not apply for all use cases, the ``initramfs-framework`` recipe +defines different packages: + +- ``initramfs-framework-base``: this package installs the basic components of + an :term:`Initramfs`, such as the ``init`` script or the ``/dev/console`` + character special file. As this package is a runtime dependency of all + modules listed below, it is automatically pulled in when one of the modules + is installed in the image. +- ``initramfs-module-exec``: support for execution of applications. +- ``initramfs-module-mdev``: support for `mdev + `__. +- ``initramfs-module-udev``: support for :wikipedia:`Udev `. +- ``initramfs-module-e2fs``: support for :wikipedia:`ext4/ext3/ext2 + ` filesystems. +- ``initramfs-module-nfsrootfs``: support for locating and mounting the root + partition via :wikipedia:`NFS `. +- ``initramfs-module-rootfs``: support for locating and mounting the root + partition. +- ``initramfs-module-debug``: dynamic debug support. +- ``initramfs-module-lvm``: :wikipedia:`LVM ` rootfs support. +- ``initramfs-module-overlayroot``: support for mounting a read-write overlay + on top of a read-only root filesystem. + +In addition to the packages defined by the ``initramfs-framework`` recipe +itself, the following packages are defined by the recipes present in +:oe_git:`meta/recipes-core/initrdscripts `: + +- ``initramfs-module-install``: module to create and install a partition layout + on a selected block device. +- ``initramfs-module-install-efi``: module to create and install an EFI + partition layout on a selected block device. +- ``initramfs-module-setup-live``: module to start a shell in the + :term:`Initramfs` if ``root=/dev/ram0`` in passed in the `Kernel command-line + `__ + or the ``root=`` parameter was not passed. + +To customize the :term:`Initramfs`, you can add or remove packages listed +earlier from the :term:`PACKAGE_INSTALL` variable with a :ref:`bbappend +` on the +``core-image-minimal-initramfs`` recipe, or create a custom recipe for the +:term:`Initramfs` taking ``core-image-minimal-initramfs`` as example. + +Custom scripts can be added to the :term:`Initramfs` by writing your own +recipes. The recipes are conventionally named ``initramfs-module-`` +where ```` is the name of the module. The recipe should set its +:term:`RDEPENDS` package-specific variables to include +``initramfs-framework-base`` and the other packages on which the module depends +at runtime. + +The recipe must install shell initialization scripts in :term:`${D} `\ +``/init.d`` and must follow the ``-