1 files changed, 80 insertions, 38 deletions

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 2971654531..2e2e16574c 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -1242,24 +1242,24 @@ system and gives an overview of their function and contents.
          :term:`Source Directory`.
 
    :term:`CONFIG_INITRAMFS_SOURCE`
-      Identifies the initial RAM filesystem (initramfs) source files. The
+      Identifies the initial RAM filesystem (:term:`Initramfs`) source files. The
       OpenEmbedded build system receives and uses this kernel Kconfig
       variable as an environment variable. By default, the variable is set
       to null ("").
 
       The :term:`CONFIG_INITRAMFS_SOURCE` can be either a single cpio archive
       with a ``.cpio`` suffix or a space-separated list of directories and
-      files for building the initramfs image. A cpio archive should contain
-      a filesystem archive to be used as an initramfs image. Directories
-      should contain a filesystem layout to be included in the initramfs
+      files for building the :term:`Initramfs` image. A cpio archive should contain
+      a filesystem archive to be used as an :term:`Initramfs` image. Directories
+      should contain a filesystem layout to be included in the :term:`Initramfs`
       image. Files should contain entries according to the format described
       by the ``usr/gen_init_cpio`` program in the kernel tree.
 
-      If you specify multiple directories and files, the initramfs image
+      If you specify multiple directories and files, the :term:`Initramfs` image
       will be the aggregate of all of them.
 
-      For information on creating an initramfs, see the
-      ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section
+      For information on creating an :term:`Initramfs`, see the
+      ":ref:`dev-manual/common-tasks:building an initial ram filesystem (Initramfs) image`" section
       in the Yocto Project Development Tasks Manual.
 
    :term:`CONFIG_SITE`
@@ -3182,10 +3182,10 @@ system and gives an overview of their function and contents.
             image, do not use the :term:`IMAGE_INSTALL` variable to specify
             packages for installation. Instead, use the
             :term:`PACKAGE_INSTALL` variable, which
-            allows the initial RAM filesystem (initramfs) recipe to use a
+            allows the initial RAM filesystem (:term:`Initramfs`) recipe to use a
             fixed set of packages and not be affected by :term:`IMAGE_INSTALL`.
-            For information on creating an initramfs, see the
-            ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`"
+            For information on creating an :term:`Initramfs`, see the
+            ":ref:`dev-manual/common-tasks:building an initial ram filesystem (Initramfs) image`"
             section in the Yocto Project Development Tasks Manual.
 
          -  Using :term:`IMAGE_INSTALL` with the
@@ -3265,7 +3265,7 @@ system and gives an overview of their function and contents.
       to distinguish the image file from other files created during image
       building; however if this suffix is redundant or not desired you can
       clear the value of this variable (set the value to ""). For example,
-      this is typically cleared in initramfs image recipes.
+      this is typically cleared in :term:`Initramfs` image recipes.
 
    :term:`IMAGE_OVERHEAD_FACTOR`
       Defines a multiplier that the build system applies to the initial
@@ -3632,37 +3632,79 @@ 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`
+      An Initial RAM Filesystem (:term:`Initramfs`) is an optionally compressed
+      `cpio <https://en.wikipedia.org/wiki/Cpio>`__ archive which is extracted
+      by the Linux kernel into RAM in a special `tmpfs <https://en.wikipedia.org/wiki/Tmpfs>`__
+      instance, used as the initial root filesystem.
+
+      This is a replacement for the legacy init RAM disk ("initrd")
+      technique, booting on an emulated block device in RAM, but being less
+      efficient because of the overhead of going through a filesystem and
+      having to duplicate accessed file contents in the file cache in RAM,
+      as for any block device.
+
+      .. note:
+
+         As far as bootloaders are concerned, :term:`Initramfs` and "initrd"
+         images are still copied to RAM in the same way. That's why most
+         most bootloaders refer to :term:`Initramfs` images as "initrd"
+         or "init RAM disk".
+
+      This kind of mechanism is typically used for two reasons:
+
+      -  For booting the same kernel binary on multiple systems requiring
+         different device drivers. The Initramfs image is then customized
+         for each type of system, to include the specific  kernel modules
+         necessary to access the final root filesystem. This technique
+         is used on all GNU / Linux distributions for desktops and servers.
+
+      -  For booting faster. As the root filesystem is extracted into RAM,
+         accessing the first user-space applications is very fast, compared
+         to having to initialize a block device, to access multiple blocks
+         from it, and to go through a filesystem having its own overhead.
+         For example, this allows to display a splashscreen very early,
+         and to later take care of mounting the final root filesystem and
+         loading less time-critical kernel drivers.
+
+      This cpio archive can either be loaded to RAM by the bootloader,
+      or be included in the kernel binary.
+
+      For information on creating and using an :term:`Initramfs`, see the
+      ":ref:`dev-manual/common-tasks:building an initial ram filesystem (Initramfs) image`"
+      section in the Yocto Project Development Tasks Manual.
+
    :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`.
+      when building an :term:`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
+      (:term:`Initramfs`), which is used during boot. Supported formats are the
       same as those supported by the
       :term:`IMAGE_FSTYPES` variable.
 
       The default value of this variable, which is set in the
       ``meta/conf/bitbake.conf`` configuration file in the
       :term:`Source Directory`, is "cpio.gz". The Linux kernel's
-      initramfs mechanism, as opposed to the initial RAM filesystem
+      :term:`Initramfs` mechanism, as opposed to the initial RAM filesystem
       `initrd <https://en.wikipedia.org/wiki/Initrd>`__ mechanism, expects
       an optionally compressed cpio archive.
 
    :term:`INITRAMFS_IMAGE`
       Specifies the :term:`PROVIDES` name of an image
-      recipe that is used to build an initial RAM filesystem (initramfs)
+      recipe that is used to build an initial RAM filesystem (:term:`Initramfs`)
       image. In other words, the :term:`INITRAMFS_IMAGE` variable causes an
       additional recipe to be built as a dependency to whatever root
       filesystem recipe you might be using (e.g. ``core-image-sato``). The
-      initramfs image recipe you provide should set
+      :term:`Initramfs` image recipe you provide should set
       :term:`IMAGE_FSTYPES` to
       :term:`INITRAMFS_FSTYPES`.
 
-      An initramfs image provides a temporary root filesystem used for
+      An :term:`Initramfs` image provides a temporary root filesystem used for
       early system initialization (e.g. loading of modules needed to locate
       and mount the "real" root filesystem).
 
@@ -3670,8 +3712,8 @@ system and gives an overview of their function and contents.
 
          See the ``meta/recipes-core/images/core-image-minimal-initramfs.bb``
          recipe in the :term:`Source Directory`
-         for an example initramfs recipe. To select this sample recipe as
-         the one built to provide the initramfs image, set :term:`INITRAMFS_IMAGE`
+         for an example :term:`Initramfs` recipe. To select this sample recipe as
+         the one built to provide the :term:`Initramfs` image, set :term:`INITRAMFS_IMAGE`
          to "core-image-minimal-initramfs".
 
       You can also find more information by referencing the
@@ -3681,13 +3723,13 @@ system and gives an overview of their function and contents.
       class to see how to use the :term:`INITRAMFS_IMAGE` variable.
 
       If :term:`INITRAMFS_IMAGE` is empty, which is the default, then no
-      initramfs image is built.
+      :term:`Initramfs` image is built.
 
       For more information, you can also see the
       :term:`INITRAMFS_IMAGE_BUNDLE`
       variable, which allows the generated image to be bundled inside the
-      kernel image. Additionally, for information on creating an initramfs
-      image, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section
+      kernel image. Additionally, for information on creating an :term:`Initramfs`
+      image, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (Initramfs) image`" section
       in the Yocto Project Development Tasks Manual.
 
    :term:`INITRAMFS_IMAGE_BUNDLE`
@@ -3696,32 +3738,32 @@ system and gives an overview of their function and contents.
       extra pass
       (:ref:`ref-tasks-bundle_initramfs`) during
       kernel compilation in order to build a single binary that contains
-      both the kernel image and the initial RAM filesystem (initramfs)
+      both the kernel image and the initial RAM filesystem (:term:`Initramfs`)
       image. This makes use of the
       :term:`CONFIG_INITRAMFS_SOURCE` kernel
       feature.
 
       .. note::
 
-         Bundling the initramfs with the kernel conflates the code in the
-         initramfs with the GPLv2 licensed Linux kernel binary. Thus only GPLv2
-         compatible software may be part of a bundled initramfs.
+         Bundling the :term:`Initramfs` with the kernel conflates the code in the
+         :term:`Initramfs` with the GPLv2 licensed Linux kernel binary. Thus only GPLv2
+         compatible software may be part of a bundled :term:`Initramfs`.
 
       .. note::
 
-         Using an extra compilation pass to bundle the initramfs avoids a
-         circular dependency between the kernel recipe and the initramfs
-         recipe should the initramfs include kernel modules. Should that be
-         the case, the initramfs recipe depends on the kernel for the
-         kernel modules, and the kernel depends on the initramfs recipe
-         since the initramfs is bundled inside the kernel image.
+         Using an extra compilation pass to bundle the :term:`Initramfs` avoids a
+         circular dependency between the kernel recipe and the :term:`Initramfs`
+         recipe should the :term:`Initramfs` include kernel modules. Should that be
+         the case, the :term:`Initramfs` recipe depends on the kernel for the
+         kernel modules, and the kernel depends on the :term:`Initramfs` recipe
+         since the :term:`Initramfs` is bundled inside the kernel image.
 
       The combined binary is deposited into the ``tmp/deploy`` directory,
       which is part of the :term:`Build Directory`.
 
       Setting the variable to "1" in a configuration file causes the
       OpenEmbedded build system to generate a kernel image with the
-      initramfs specified in :term:`INITRAMFS_IMAGE` bundled within::
+      :term:`Initramfs` specified in :term:`INITRAMFS_IMAGE` bundled within::
 
          INITRAMFS_IMAGE_BUNDLE = "1"
 
@@ -3739,7 +3781,7 @@ system and gives an overview of their function and contents.
       See the
       :yocto_git:`local.conf.sample.extended </poky/tree/meta-poky/conf/templates/default/local.conf.sample.extended>`
       file for additional information. Also, for information on creating an
-      initramfs, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section
+      :term:`Initramfs`, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (Initramfs) image`" section
       in the Yocto Project Development Tasks Manual.
 
    :term:`INITRAMFS_LINK_NAME`
@@ -3764,7 +3806,7 @@ system and gives an overview of their function and contents.
       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
+      For more information on how to bundle an :term:`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.
 
@@ -4240,7 +4282,7 @@ system and gives an overview of their function and contents.
       :term:`KERNELDEPMODDEPEND` does not control whether or not that data
       exists, but simply whether or not it is used. If you do not need to
       use the data, set the :term:`KERNELDEPMODDEPEND` variable in your
-      ``initramfs`` recipe. Setting the variable there when the data is not
+      :term:`Initramfs` recipe. Setting the variable there when the data is not
       needed avoids a potential dependency loop.
 
    :term:`KFEATURE_DESCRIPTION`
@@ -5395,9 +5437,9 @@ system and gives an overview of their function and contents.
       :term:`IMAGE_INSTALL` variable to specify
       packages for installation. The exception to this is when working with
       the :ref:`core-image-minimal-initramfs <ref-manual/images:images>`
-      image. When working with an initial RAM filesystem (initramfs) image,
+      image. When working with an initial RAM filesystem (:term:`Initramfs`) image,
       use the :term:`PACKAGE_INSTALL` variable. For information on creating an
-      initramfs, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section
+      :term:`Initramfs`, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (Initramfs) image`" section
       in the Yocto Project Development Tasks Manual.
 
    :term:`PACKAGE_INSTALL_ATTEMPTONLY`