mirror of
https://git.yoctoproject.org/poky
synced 2026-06-01 00:59:48 +00:00
manuals: improve initramfs details
- Create a new entry in the glossary - Add implementation details - Replace the mention of "init ramdisk" by "initramfs¨ whenever possible - Remove obsolete and duplicate information - Fix spacing issues in the Sphinx code (From yocto-docs rev: 952c7e6dee49532705b2c162f4728e635c38df3f) Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Michael Opdenacker
committed by
Richard Purdie
Richard Purdie
parent
c3c7344826
commit
9dbd27a48a
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user