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

[Quentin Schulz <quentin.schulz@cherry.de>]

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