From 9dbd27a48aec4aaf235af91a3b7397725b644463 Mon Sep 17 00:00:00 2001 From: Michael Opdenacker Date: Fri, 23 Sep 2022 14:30:56 +0200 Subject: manuals: improve initramfs details MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 Signed-off-by: Richard Purdie --- documentation/dev-manual/common-tasks.rst | 114 +++++++------------- documentation/dev-manual/qemu.rst | 8 +- documentation/migration-guides/migration-2.4.rst | 2 +- documentation/migration-guides/migration-3.2.rst | 4 +- .../migration-guides/release-notes-3.4.rst | 4 +- .../migration-guides/release-notes-4.0.rst | 8 +- documentation/ref-manual/classes.rst | 6 +- documentation/ref-manual/images.rst | 6 +- documentation/ref-manual/tasks.rst | 6 +- documentation/ref-manual/variables.rst | 118 ++++++++++++++------- 10 files changed, 138 insertions(+), 138 deletions(-) diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst index 559709d6f3..883a1adea7 100644 --- a/documentation/dev-manual/common-tasks.rst +++ b/documentation/dev-manual/common-tasks.rst @@ -3882,99 +3882,59 @@ and have separate configuration files, BitBake places the artifacts for each build in the respective temporary build directories (i.e. :term:`TMPDIR`). -Building an Initial RAM Filesystem (initramfs) Image +Building an Initial RAM Filesystem (Initramfs) Image ---------------------------------------------------- -An initial RAM filesystem (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). +An initial RAM filesystem (:term:`Initramfs`) image provides a temporary root +filesystem used for early system initialization, typically providing tools and +loading modules needed to locate and mount the final root filesystem. -.. note:: - - The initramfs image is the successor of initial RAM disk (initrd). It - is a "copy in and out" (cpio) archive of the initial filesystem that - gets loaded into memory during the Linux startup process. Because - Linux uses the contents of the archive during initialization, the - initramfs image needs to contain all of the device drivers and tools - needed to mount the final root filesystem. - -Follow these steps to create an initramfs image: +Follow these steps to create an :term:`Initramfs` image: -1. *Create the initramfs Image Recipe:* You can reference the +1. *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. - -2. *Decide if You Need to Bundle the initramfs Image Into the Kernel - Image:* If you want the initramfs image that is built to be bundled - in with the kernel image, set the - :term:`INITRAMFS_IMAGE_BUNDLE` - variable to "1" in your ``local.conf`` configuration file and set the - :term:`INITRAMFS_IMAGE` - variable in the recipe that builds the kernel image. - - .. note:: + as an example from which to work. - It is recommended that you bundle the initramfs image with the - kernel image to avoid circular dependencies between the kernel - recipe and the initramfs recipe should the initramfs image include - kernel modules. +2. *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 + in with the kernel image, set the :term:`INITRAMFS_IMAGE_BUNDLE` + variable to ``"1"`` in your ``local.conf`` configuration file and set the + :term:`INITRAMFS_IMAGE` variable in the recipe that builds the kernel image. - Setting the :term:`INITRAMFS_IMAGE_BUNDLE` flag causes the initramfs + Setting the :term:`INITRAMFS_IMAGE_BUNDLE` flag causes the :term:`Initramfs` image to be unpacked into the ``${B}/usr/`` directory. The unpacked - initramfs image is then passed to the kernel's ``Makefile`` using the - :term:`CONFIG_INITRAMFS_SOURCE` - variable, allowing the initramfs image to be built into the kernel - normally. - - .. 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. - - .. note:: - - If you choose to not bundle the initramfs image with the kernel - image, you are essentially using an - `Initial RAM Disk (initrd) `__. - Creating an initrd is handled primarily through the :term:`INITRD_IMAGE`, - ``INITRD_LIVE``, and ``INITRD_IMAGE_LIVE`` variables. For more - information, see the :ref:`ref-classes-image-live` file. - -3. *Optionally Add Items to the initramfs Image Through the initramfs - Image Recipe:* If you add items to the initramfs image by way of its - recipe, you should use - :term:`PACKAGE_INSTALL` - rather than - :term:`IMAGE_INSTALL`. - :term:`PACKAGE_INSTALL` gives more direct control of what is added to the - image as compared to the defaults you might not necessarily want that - are set by the :ref:`image ` - or :ref:`core-image ` - classes. - -4. *Build the Kernel Image and the initramfs Image:* Build your kernel - image using BitBake. Because the initramfs image recipe is a - dependency of the kernel image, the initramfs image is built as well + :term:`Initramfs` image is then passed to the kernel's ``Makefile`` using the + :term:`CONFIG_INITRAMFS_SOURCE` variable, allowing the :term:`Initramfs` + image to be built into the kernel normally. + +3. *Optionally Add Items to the Initramfs Image Through the Initramfs + Image Recipe:* If you add items to the :term:`Initramfs` image by way of its + recipe, you should use :term:`PACKAGE_INSTALL` rather than + :term:`IMAGE_INSTALL`. :term:`PACKAGE_INSTALL` gives more direct control of + what is added to the image as compared to the defaults you might not + necessarily want that are set by the :ref:`image ` + or :ref:`core-image ` classes. + +4. *Build the Kernel Image and the Initramfs Image:* Build your kernel + image using BitBake. Because the :term:`Initramfs` image recipe is a + dependency of the kernel image, the :term:`Initramfs` image is built as well and bundled with the kernel image if you used the - :term:`INITRAMFS_IMAGE_BUNDLE` - variable described earlier. + :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 +There may be a case where we want to build an :term:`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 +our main image to use ``TCLIBC="glibc"``, but to use ``TCLIBC="musl"`` in our :term:`Initramfs` image to keep a smaller footprint. However, by performing the steps mentioned -above the initramfs image will inherit ``TCLIBC="glibc"`` without allowing us +above the :term:`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 +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:: @@ -3982,7 +3942,7 @@ To achieve this, you need to perform some additional steps: TMPDIR="${TOPDIR}/tmp-initramfscfg" TCLIBC="musl" -2. *Set additional initramfs variables on your main configuration:* +2. *Set additional Initramfs variables on your main configuration:* Additionally, on your main configuration (``local.conf``) you need to set the variables:: @@ -3997,7 +3957,7 @@ To achieve this, you need to perform some additional steps: 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 + instead, resulting in a musl based :term:`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` @@ -4171,7 +4131,7 @@ file:: Finally, you should consider exactly the type of root filesystem you need to meet your needs while also reducing its size. For example, consider ``cramfs``, ``squashfs``, ``ubifs``, ``ext2``, or an -``initramfs`` using ``initramfs``. Be aware that ``ext3`` requires a 1 +:term:`Initramfs` using ``initramfs``. Be aware that ``ext3`` requires a 1 Mbyte journal. If you are okay with running read-only, you do not need this journal. @@ -8802,7 +8762,7 @@ perform a one-time setup of your controller image by doing the following: - Installs normal linux utilities not BusyBox ones (e.g. ``bash``, ``coreutils``, ``tar``, ``gzip``, and ``kmod``). - - Uses a custom Initial RAM Disk (initramfs) image with a custom + - Uses a custom :term:`Initramfs` image with a custom installer. A normal image that you can install usually creates a single root filesystem partition. This image uses another installer that creates a specific partition layout. Not all Board Support diff --git a/documentation/dev-manual/qemu.rst b/documentation/dev-manual/qemu.rst index 88a63c1808..9f4bc264a3 100644 --- a/documentation/dev-manual/qemu.rst +++ b/documentation/dev-manual/qemu.rst @@ -123,9 +123,9 @@ available. Follow these general steps to run QEMU: $ runqemu qemux86-64 core-image-minimal ext4 - - This example specifies to boot an initial RAM disk image and to - enable audio in QEMU. For this case, ``runqemu`` set the internal - variable ``FSTYPE`` to "cpio.gz". Also, for audio to be enabled, + - This example specifies to boot an :term:`Initramfs` image and to + enable audio in QEMU. For this case, ``runqemu`` sets the internal + variable ``FSTYPE`` to ``cpio.gz``. Also, for audio to be enabled, an appropriate driver must be installed (see the previous description for the ``audio`` option for more information). :: @@ -394,7 +394,7 @@ command line: options are basically identical. If you do not provide a MACHINE option, ``runqemu`` tries to determine it based on other options. -- ``ramfs``: Indicates you are booting an initial RAM disk (initramfs) +- ``ramfs``: Indicates you are booting an :term:`Initramfs` image, which means the ``FSTYPE`` is ``cpio.gz``. - ``iso``: Indicates you are booting an ISO image, which means the diff --git a/documentation/migration-guides/migration-2.4.rst b/documentation/migration-guides/migration-2.4.rst index 964ed92937..8904495022 100644 --- a/documentation/migration-guides/migration-2.4.rst +++ b/documentation/migration-guides/migration-2.4.rst @@ -54,7 +54,7 @@ occurred: when "pam" is in :term:`DISTRO_FEATURES`. - The ``switch_root`` program is now packaged in a separate - "util-linux-switch-root" package for small initramfs images that + "util-linux-switch-root" package for small :term:`Initramfs` images that do not need the whole ``util-linux`` package or the busybox binary, which are both much larger than ``switch_root``. The main ``util-linux`` package has a recommended runtime dependency (i.e. diff --git a/documentation/migration-guides/migration-3.2.rst b/documentation/migration-guides/migration-3.2.rst index 92b7f91f2c..cc6f05322a 100644 --- a/documentation/migration-guides/migration-3.2.rst +++ b/documentation/migration-guides/migration-3.2.rst @@ -265,10 +265,10 @@ using the GL options. .. _migration-3.2-initramfs-suffix: -initramfs images now use a blank suffix +Initramfs images now use a blank suffix --------------------------------------- -The reference initramfs images (``core-image-minimal-initramfs``, +The reference :term:`Initramfs` images (``core-image-minimal-initramfs``, ``core-image-tiny-initramfs`` and ``core-image-testmaster-initramfs``) now set an empty string for :term:`IMAGE_NAME_SUFFIX`, which otherwise defaults to ``".rootfs"``. These images aren't root filesystems and thus the rootfs diff --git a/documentation/migration-guides/release-notes-3.4.rst b/documentation/migration-guides/release-notes-3.4.rst index 323e4df7ae..4319bf119d 100644 --- a/documentation/migration-guides/release-notes-3.4.rst +++ b/documentation/migration-guides/release-notes-3.4.rst @@ -36,7 +36,7 @@ New Features / Enhancements in 3.4 - Kernel-related enhancements: - - Support zstd-compressed modules and initramfs images + - Support zstd-compressed modules and :term:`Initramfs` images - Allow opt-out of split kernel modules - linux-yocto-dev: base AUTOREV on specified version - kernel-yocto: provide debug / summary information for metadata @@ -211,7 +211,7 @@ The following corrections have been made to the LICENSE values set by recipes: Other license-related notes: - When creating recipes for Python software, recipetool will now treat "BSD" as "BSD-3-Clause" for the purposes of setting LICENSE, as that is the most common understanding. -- Please be aware that an initramfs bundled with the kernel using :term:`INITRAMFS_IMAGE_BUNDLE` should only contain GPLv2-compatible software; this is now mentioned in the documentation. +- Please be aware that an :term:`Initramfs` bundled with the kernel using :term:`INITRAMFS_IMAGE_BUNDLE` should only contain GPLv2-compatible software; this is now mentioned in the documentation. Security Fixes in 3.4 ~~~~~~~~~~~~~~~~~~~~~ diff --git a/documentation/migration-guides/release-notes-4.0.rst b/documentation/migration-guides/release-notes-4.0.rst index b675cae217..a61ccc6913 100644 --- a/documentation/migration-guides/release-notes-4.0.rst +++ b/documentation/migration-guides/release-notes-4.0.rst @@ -30,7 +30,7 @@ New Features / Enhancements in 4.0 - New :ref:`overlayfs ` and :ref:`overlayfs-etc ` classes and - ``overlayroot`` support in the initramfs framework to make it easier to + ``overlayroot`` support in the :term:`Initramfs` framework to make it easier to overlay read-only filesystems (for example) with `OverlayFS `__. @@ -168,7 +168,7 @@ New Features / Enhancements in 4.0 - Kernel-related enhancements: - - Allow initramfs to be built from a separate multiconfig + - Allow :term:`Initramfs` to be built from a separate multiconfig - Make kernel-base recommend kernel-image, not depend (allowing images containing kernel modules without kernel image) - linux-yocto: split vtpm for more granular inclusion - linux-yocto: cfg/debug: add configs for kcsan @@ -182,7 +182,7 @@ New Features / Enhancements in 4.0 - FIT image related enhancements: - - New ``FIT_SUPPORTED_INITRAMFS_FSTYPES`` variable to allow extending initramfs image types to look for + - New ``FIT_SUPPORTED_INITRAMFS_FSTYPES`` variable to allow extending :term:`Initramfs` image types to look for - New ``FIT_CONF_PREFIX`` variable to allow overriding FIT configuration prefix - Use 'bbnote' for better logging @@ -276,7 +276,7 @@ New Features / Enhancements in 4.0 - volatile-binds: SELinux and overlayfs extensions in mount-copybind - gtk-icon-cache: Allow using gtk4 - kmod: Add an exclude directive to depmod -- os-release: add os-release-initrd package for use in systemd-based initramfs images +- os-release: add os-release-initrd package for use in systemd-based :term:`Initramfs` images - gstreamer1.0-plugins-base: add support for graphene - gpg-sign: Add parameters to gpg signature function - package_manager: sign DEB package feeds diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index 11e0d472e8..f402d090c9 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst @@ -1256,9 +1256,9 @@ package installs all packages with modules and various other kernel packages such as ``kernel-vmlinux``. The ``kernel`` class contains logic that allows you to embed an initial -RAM filesystem (initramfs) image when you build the kernel image. For -information on how to build an initramfs, see the -":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section in +RAM filesystem (:term:`Initramfs`) image when you build the kernel image. For +information on how to build 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. Various other classes are used by the ``kernel`` and ``module`` classes diff --git a/documentation/ref-manual/images.rst b/documentation/ref-manual/images.rst index 31fb567687..4b771d0601 100644 --- a/documentation/ref-manual/images.rst +++ b/documentation/ref-manual/images.rst @@ -78,11 +78,11 @@ Following is a list of supported recipes: libraries you can use in a host development environment. - ``core-image-minimal-initramfs``: A ``core-image-minimal`` image that - has the Minimal RAM-based Initial Root Filesystem (initramfs) as part + has the Minimal RAM-based Initial Root Filesystem (:term:`Initramfs`) as part of the kernel, which allows the system to find the first "init" program more efficiently. See the :term:`PACKAGE_INSTALL` variable for - additional information helpful when working with initramfs images. + additional information helpful when working with :term:`Initramfs` images. - ``core-image-minimal-mtdutils``: A ``core-image-minimal`` image that has support for the Minimal MTD Utilities, which let the user @@ -121,7 +121,7 @@ Following is a list of supported recipes: section in the Yocto Project Development Tasks Manual. - ``core-image-testmaster-initramfs``: A RAM-based Initial Root - Filesystem (initramfs) image tailored for use with the + Filesystem (:term:`Initramfs`) image tailored for use with the ``core-image-testmaster`` image. - ``core-image-weston``: A very basic Wayland image with a terminal. diff --git a/documentation/ref-manual/tasks.rst b/documentation/ref-manual/tasks.rst index cb08a75c90..2a692c1725 100644 --- a/documentation/ref-manual/tasks.rst +++ b/documentation/ref-manual/tasks.rst @@ -575,10 +575,8 @@ information on live image types. ``do_bundle_initramfs`` ----------------------- -Combines an initial RAM disk (initramfs) image and kernel together to -form a single image. The -:term:`CONFIG_INITRAMFS_SOURCE` variable -has some more information about these types of images. +Combines an :term:`Initramfs` image and kernel together to +form a single image. .. _ref-tasks-rootfs: 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 `__ archive which is extracted + by the Linux kernel into RAM in a special `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 ` 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 `__ 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 ` 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 ` - 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` -- cgit v1.2.3-54-g00ecf