[yocto-docs][PATCH] dev-manual/building: document the initramfs-framework recipe

[yocto-docs][PATCH] dev-manual/building: document the initramfs-framework recipe

[Antonin Godard]

[ 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 <alejandro@enedino.org>
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/dev-manual/building.rst | 74 ++++++++++++++++++++++++++++++++++-
 1 file changed, 73 insertions(+), 1 deletion(-)

diff --git a/documentation/dev-manual/building.rst b/documentation/dev-manual/building.rst
index fe502690ddc45694a9b0ae2d5e98894fe5153d74..fe720fcacc562c70bb886062153b587f5df11651 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 <dev-manual/building:Customizing an
+   Initramfs using \`\`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,76 @@ 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
+</openembedded-core/tree/meta/recipes-core/images>` uses the
+:oe_git:`initramfs-framework_1.0.bb
+</openembedded-core/tree/meta/recipes-core/initrdscripts/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
+</openembedded-core/tree/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. This package should always be installed if using any
+   of the additional modules below.
+-  ``initramfs-module-exec``: support for execution of applications.
+-  ``initramfs-module-mdev``: support for `mdev
+   <https://wiki.gentoo.org/wiki/Mdev>`__.
+-  ``initramfs-module-udev``: support for :wikipedia:`Udev <Udev>`.
+-  ``initramfs-module-e2fs``: support for :wikipedia:`ext4/ext3/ext2
+   <Extended_file_system>` filesystems.
+-  ``initramfs-module-nfsrootfs``: support for locating and mounting the root
+   partition via :wikipedia:`NFS <Network_File_System>`.
+-  ``initramfs-module-rootfs``: support for locating and mounting the root
+   partition.
+-  ``initramfs-module-debug``: dynamic debug support.
+-  ``initramfs-module-lvm``: :wikipedia:`LVM <Logical_volume_management>` 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 </openembedded-core/tree/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
+   <https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html>`__
+   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
+<dev-manual/layers:Appending Other Layers Metadata With Your Layer>` 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-<module name>``
+where ``<module name>`` is the name of the module. The recipe should set its
+variable :term:`RDEPENDS` to ``initramfs-framework-base`` and the packages on
+which the module depends on at runtime.
+
+The recipe must install shell initialization scripts in :term:`${D} <D>`\
+``/init.d`` and must follow the ``<number>-<script name>`` naming where:
+
+-  ``<number>`` is a two-digit number that affects the execution order of the
+   script compared to others. For example, the script ``80-setup-live`` would be
+   executed after ``01-udev`` because 80 is greater than 01.
+
+-  ``<script name>`` is the script name which can you can choose freely.
+
 Bundling an Initramfs Image From a Separate Multiconfig
 -------------------------------------------------------
 

---
base-commit: 3f3a9f53fea6c7d533b9e999dc959dcc3bed7745
change-id: 20250103-initramfs-framework-ab241fecf9c9

Best regards,
-- 
Antonin Godard <antonin.godard@bootlin.com>

Re: [docs] [yocto-docs][PATCH] dev-manual/building: document the initramfs-framework recipe

[Quentin Schulz]

Hi Antonin,

On 1/3/25 5:34 PM, Antonin Godard via lists.yoctoproject.org wrote:
> [ 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 <alejandro@enedino.org>
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/dev-manual/building.rst | 74 ++++++++++++++++++++++++++++++++++-
>   1 file changed, 73 insertions(+), 1 deletion(-)
> 
> diff --git a/documentation/dev-manual/building.rst b/documentation/dev-manual/building.rst
> index fe502690ddc45694a9b0ae2d5e98894fe5153d74..fe720fcacc562c70bb886062153b587f5df11651 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 <dev-manual/building:Customizing an
> +   Initramfs using \`\`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,76 @@ 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
> +</openembedded-core/tree/meta/recipes-core/images>` uses the
> +:oe_git:`initramfs-framework_1.0.bb
> +</openembedded-core/tree/meta/recipes-core/initrdscripts/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
> +</openembedded-core/tree/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. This package should always be installed if using any
> +   of the additional modules below.

Not sure the last sentence is necessary as it's listed in the RDEPENDS 
of each package, so the user doesn't need to do anything. I can suggest 
to either remove it or change it to something like "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."?

This package should be added as a runtime dependency of custom initramfs 
modules but that is specified at the end of the section, so I don't 
think we need to specify it here?

> +-  ``initramfs-module-exec``: support for execution of applications.
> +-  ``initramfs-module-mdev``: support for `mdev
> +   <https://wiki.gentoo.org/wiki/Mdev>`__.
> +-  ``initramfs-module-udev``: support for :wikipedia:`Udev <Udev>`.
> +-  ``initramfs-module-e2fs``: support for :wikipedia:`ext4/ext3/ext2
> +   <Extended_file_system>` filesystems.
> +-  ``initramfs-module-nfsrootfs``: support for locating and mounting the root
> +   partition via :wikipedia:`NFS <Network_File_System>`.
> +-  ``initramfs-module-rootfs``: support for locating and mounting the root
> +   partition.
> +-  ``initramfs-module-debug``: dynamic debug support.
> +-  ``initramfs-module-lvm``: :wikipedia:`LVM <Logical_volume_management>` 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 </openembedded-core/tree/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
> +   <https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html>`__
> +   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
> +<dev-manual/layers:Appending Other Layers Metadata With Your Layer>` 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-<module name>``
> +where ``<module name>`` is the name of the module. The recipe should set its
> +variable :term:`RDEPENDS` to ``initramfs-framework-base`` and the packages on

s/the packages/the other packages/ ?

> +which the module depends on at runtime.
> +

s/on// as it's duplicated by "on which"

So either,

the packages which the module depends on at runtime
or
the packages on which the module depends at runtime

> +The recipe must install shell initialization scripts in :term:`${D} <D>`\
> +``/init.d`` and must follow the ``<number>-<script name>`` naming where:

s/naming/naming scheme/ ? or "convention"?

> +
> +-  ``<number>`` is a two-digit number that affects the execution order of the

We should make it very clear that it needs to be a two-digit number, 
yes, even between 0 and 9 as it's sorted alphabetically, so 10-something 
would be called before 8-else (because 1 < 8), hence why it needs to be 
08-else instead.

> +   script compared to others. For example, the script ``80-setup-live`` would be
> +   executed after ``01-udev`` because 80 is greater than 01.
> +
> +-  ``<script name>`` is the script name which can you can choose freely.

-can

Yes, BUT, if there are more than one script using the same number, the 
order in which the scripts are run is the alphabetical order I believe.

Looks good to me otherwise,
Cheers,
Quentin