2 files changed, 59 insertions, 0 deletions

diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
index 1856d4c3ad..fd394c3ae2 100644
--- a/documentation/dev-manual/common-tasks.rst
+++ b/documentation/dev-manual/common-tasks.rst
@@ -3919,6 +3919,48 @@ Follow these steps to create an initramfs image:
    :term:`INITRAMFS_IMAGE_BUNDLE`
    variable described earlier.
 
+Bundling an Initramfs Image From a Separate Multiconfig
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There may be a case where we want to build an initramfs image which does not
+inherit the same distro policy as our main image, for example, we may want
+our main image to use ``TCLIBC="glibc"``, but to use ``TCLIBC="musl"`` in our initramfs
+image to keep a smaller footprint. However, by performing the steps mentioned
+above the initramfs image will inherit ``TCLIBC="glibc"`` without allowing us
+to override it.
+
+To achieve this, you need to perform some additional steps:
+
+1. *Create a multiconfig for your initramfs image:* You can perform the steps
+   on ":ref:`dev-manual/common-tasks:building images for multiple targets using multiple configurations`" to create a separate multiconfig.
+   For the sake of simplicity let's assume such multiconfig is called: ``initramfscfg.conf`` and
+   contains the variables::
+
+      TMPDIR="${TOPDIR}/tmp-initramfscfg"
+      TCLIBC="musl"
+
+2. *Set additional initramfs variables on your main configuration:*
+   Additionally, on your main configuration (``local.conf``) you need to set the
+   variables::
+
+     INITRAMFS_MULTICONFIG = "initramfscfg"
+     INITRAMFS_DEPLOY_DIR_IMAGE = "${TOPDIR}/tmp-initramfscfg/deploy/images/${MACHINE}"
+
+   The variables :term:`INITRAMFS_MULTICONFIG` and :term:`INITRAMFS_DEPLOY_DIR_IMAGE`
+   are used to create a multiconfig dependency from the kernel to the :term:`INITRAMFS_IMAGE`
+   to be built coming from the ``initramfscfg`` multiconfig, and to let the
+   buildsystem know where the :term:`INITRAMFS_IMAGE` will be located.
+
+   Building a system with such configuration will build the kernel using the
+   main configuration but the ``do_bundle_initramfs`` task will grab the
+   selected :term:`INITRAMFS_IMAGE` from :term:`INITRAMFS_DEPLOY_DIR_IMAGE`
+   instead, resulting in a musl based initramfs image bundled in the kernel
+   but a glibc based main image.
+
+   The same is applicable to avoid inheriting :term:`DISTRO_FEATURES` on :term:`INITRAMFS_IMAGE`
+   or to build a different :term:`DISTRO` for it such as ``poky-tiny``.
+
+
 Building a Tiny System
 ----------------------
 
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index d4f40b6929..caa9713935 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -3554,6 +3554,13 @@ system and gives an overview of their function and contents.
          even if the toolchain's binaries are strippable, there are other files
          needed for the build that are not strippable.
 
+   :term:`INITRAMFS_DEPLOY_DIR_IMAGE`
+      Indicates the deploy directory used by ``do_bundle_initramfs`` where the
+      :term:`INITRAMFS_IMAGE` will be fetched from.
+      This variable is set by default to ``${DEPLOY_DIR_IMAGE}`` in the
+      :ref:`kernel <ref-classes-kernel>` class and it's only meant to be changed
+      when building an initramfs image from a separate multiconfig via :term:`INITRAMFS_MULTICONFIG`.
+
    :term:`INITRAMFS_FSTYPES`
       Defines the format for the output image of an initial RAM filesystem
       (initramfs), which is used during boot. Supported formats are the
@@ -3673,6 +3680,16 @@ system and gives an overview of their function and contents.
       See the :term:`MACHINE` variable for additional
       information.
 
+   :term:`INITRAMFS_MULTICONFIG`
+      Defines the multiconfig to create a multiconfig dependency to be used by the :ref:`kernel <ref-classes-kernel>` class.
+
+      This allows the kernel to bundle an :term:`INITRAMFS_IMAGE` coming from
+      a separate multiconfig, this is meant to be used in addition to :term:`INITRAMFS_DEPLOY_DIR_IMAGE`.
+
+      For more information on how to bundle an initramfs image from a separate
+      multiconfig see the ":ref:`dev-manual/common-tasks:Bundling an Initramfs Image From a Separate Multiconfig`"
+      section in the Yocto Project Development Tasks Manual.
+
    :term:`INITRAMFS_NAME`
       The base name of the initial RAM filesystem image. This variable is
       set in the ``meta/classes/kernel-artifact-names.bbclass`` file as