diff options
author | Michael Opdenacker <michael.opdenacker@bootlin.com> | 2022-09-23 14:30:56 +0200 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2022-10-07 10:54:25 +0100 |
commit | 9dbd27a48aec4aaf235af91a3b7397725b644463 (patch) | |
tree | 59eceecd9bc147f56af607431082264807ea0068 /documentation/dev-manual | |
parent | c3c7344826231d1b2c009dbb317d2373bbdf9ff3 (diff) | |
download | poky-9dbd27a48aec4aaf235af91a3b7397725b644463.tar.gz |
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>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r-- | documentation/dev-manual/common-tasks.rst | 114 | ||||
-rw-r--r-- | documentation/dev-manual/qemu.rst | 8 |
2 files changed, 41 insertions, 81 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 | |||
3882 | each build in the respective temporary build directories (i.e. | 3882 | each build in the respective temporary build directories (i.e. |
3883 | :term:`TMPDIR`). | 3883 | :term:`TMPDIR`). |
3884 | 3884 | ||
3885 | Building an Initial RAM Filesystem (initramfs) Image | 3885 | Building an Initial RAM Filesystem (Initramfs) Image |
3886 | ---------------------------------------------------- | 3886 | ---------------------------------------------------- |
3887 | 3887 | ||
3888 | An initial RAM filesystem (initramfs) image provides a temporary root | 3888 | An initial RAM filesystem (:term:`Initramfs`) image provides a temporary root |
3889 | filesystem used for early system initialization (e.g. loading of modules | 3889 | filesystem used for early system initialization, typically providing tools and |
3890 | needed to locate and mount the "real" root filesystem). | 3890 | loading modules needed to locate and mount the final root filesystem. |
3891 | 3891 | ||
3892 | .. note:: | 3892 | Follow these steps to create an :term:`Initramfs` image: |
3893 | |||
3894 | The initramfs image is the successor of initial RAM disk (initrd). It | ||
3895 | is a "copy in and out" (cpio) archive of the initial filesystem that | ||
3896 | gets loaded into memory during the Linux startup process. Because | ||
3897 | Linux uses the contents of the archive during initialization, the | ||
3898 | initramfs image needs to contain all of the device drivers and tools | ||
3899 | needed to mount the final root filesystem. | ||
3900 | |||
3901 | Follow these steps to create an initramfs image: | ||
3902 | 3893 | ||
3903 | 1. *Create the initramfs Image Recipe:* You can reference the | 3894 | 1. *Create the Initramfs Image Recipe:* You can reference the |
3904 | ``core-image-minimal-initramfs.bb`` recipe found in the | 3895 | ``core-image-minimal-initramfs.bb`` recipe found in the |
3905 | ``meta/recipes-core`` directory of the :term:`Source Directory` | 3896 | ``meta/recipes-core`` directory of the :term:`Source Directory` |
3906 | as an example | 3897 | as an example from which to work. |
3907 | from which to work. | ||
3908 | |||
3909 | 2. *Decide if You Need to Bundle the initramfs Image Into the Kernel | ||
3910 | Image:* If you want the initramfs image that is built to be bundled | ||
3911 | in with the kernel image, set the | ||
3912 | :term:`INITRAMFS_IMAGE_BUNDLE` | ||
3913 | variable to "1" in your ``local.conf`` configuration file and set the | ||
3914 | :term:`INITRAMFS_IMAGE` | ||
3915 | variable in the recipe that builds the kernel image. | ||
3916 | |||
3917 | .. note:: | ||
3918 | 3898 | ||
3919 | It is recommended that you bundle the initramfs image with the | 3899 | 2. *Decide if You Need to Bundle the Initramfs Image Into the Kernel |
3920 | kernel image to avoid circular dependencies between the kernel | 3900 | Image:* If you want the :term:`Initramfs` image that is built to be bundled |
3921 | recipe and the initramfs recipe should the initramfs image include | 3901 | in with the kernel image, set the :term:`INITRAMFS_IMAGE_BUNDLE` |
3922 | kernel modules. | 3902 | variable to ``"1"`` in your ``local.conf`` configuration file and set the |
3903 | :term:`INITRAMFS_IMAGE` variable in the recipe that builds the kernel image. | ||
3923 | 3904 | ||
3924 | Setting the :term:`INITRAMFS_IMAGE_BUNDLE` flag causes the initramfs | 3905 | Setting the :term:`INITRAMFS_IMAGE_BUNDLE` flag causes the :term:`Initramfs` |
3925 | image to be unpacked into the ``${B}/usr/`` directory. The unpacked | 3906 | image to be unpacked into the ``${B}/usr/`` directory. The unpacked |
3926 | initramfs image is then passed to the kernel's ``Makefile`` using the | 3907 | :term:`Initramfs` image is then passed to the kernel's ``Makefile`` using the |
3927 | :term:`CONFIG_INITRAMFS_SOURCE` | 3908 | :term:`CONFIG_INITRAMFS_SOURCE` variable, allowing the :term:`Initramfs` |
3928 | variable, allowing the initramfs image to be built into the kernel | 3909 | image to be built into the kernel normally. |
3929 | normally. | 3910 | |
3930 | 3911 | 3. *Optionally Add Items to the Initramfs Image Through the Initramfs | |
3931 | .. note:: | 3912 | Image Recipe:* If you add items to the :term:`Initramfs` image by way of its |
3932 | 3913 | recipe, you should use :term:`PACKAGE_INSTALL` rather than | |
3933 | Bundling the initramfs with the kernel conflates the code in the initramfs | 3914 | :term:`IMAGE_INSTALL`. :term:`PACKAGE_INSTALL` gives more direct control of |
3934 | with the GPLv2 licensed Linux kernel binary. Thus only GPLv2 compatible | 3915 | what is added to the image as compared to the defaults you might not |
3935 | software may be part of a bundled initramfs. | 3916 | necessarily want that are set by the :ref:`image <ref-classes-image>` |
3936 | 3917 | or :ref:`core-image <ref-classes-core-image>` classes. | |
3937 | .. note:: | 3918 | |
3938 | 3919 | 4. *Build the Kernel Image and the Initramfs Image:* Build your kernel | |
3939 | If you choose to not bundle the initramfs image with the kernel | 3920 | image using BitBake. Because the :term:`Initramfs` image recipe is a |
3940 | image, you are essentially using an | 3921 | dependency of the kernel image, the :term:`Initramfs` image is built as well |
3941 | `Initial RAM Disk (initrd) <https://en.wikipedia.org/wiki/Initrd>`__. | ||
3942 | Creating an initrd is handled primarily through the :term:`INITRD_IMAGE`, | ||
3943 | ``INITRD_LIVE``, and ``INITRD_IMAGE_LIVE`` variables. For more | ||
3944 | information, see the :ref:`ref-classes-image-live` file. | ||
3945 | |||
3946 | 3. *Optionally Add Items to the initramfs Image Through the initramfs | ||
3947 | Image Recipe:* If you add items to the initramfs image by way of its | ||
3948 | recipe, you should use | ||
3949 | :term:`PACKAGE_INSTALL` | ||
3950 | rather than | ||
3951 | :term:`IMAGE_INSTALL`. | ||
3952 | :term:`PACKAGE_INSTALL` gives more direct control of what is added to the | ||
3953 | image as compared to the defaults you might not necessarily want that | ||
3954 | are set by the :ref:`image <ref-classes-image>` | ||
3955 | or :ref:`core-image <ref-classes-core-image>` | ||
3956 | classes. | ||
3957 | |||
3958 | 4. *Build the Kernel Image and the initramfs Image:* Build your kernel | ||
3959 | image using BitBake. Because the initramfs image recipe is a | ||
3960 | dependency of the kernel image, the initramfs image is built as well | ||
3961 | and bundled with the kernel image if you used the | 3922 | and bundled with the kernel image if you used the |
3962 | :term:`INITRAMFS_IMAGE_BUNDLE` | 3923 | :term:`INITRAMFS_IMAGE_BUNDLE` variable described earlier. |
3963 | variable described earlier. | ||
3964 | 3924 | ||
3965 | Bundling an Initramfs Image From a Separate Multiconfig | 3925 | Bundling an Initramfs Image From a Separate Multiconfig |
3966 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 3926 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
3967 | 3927 | ||
3968 | There may be a case where we want to build an initramfs image which does not | 3928 | There may be a case where we want to build an :term:`Initramfs` image which does not |
3969 | inherit the same distro policy as our main image, for example, we may want | 3929 | inherit the same distro policy as our main image, for example, we may want |
3970 | our main image to use ``TCLIBC="glibc"``, but to use ``TCLIBC="musl"`` in our initramfs | 3930 | our main image to use ``TCLIBC="glibc"``, but to use ``TCLIBC="musl"`` in our :term:`Initramfs` |
3971 | image to keep a smaller footprint. However, by performing the steps mentioned | 3931 | image to keep a smaller footprint. However, by performing the steps mentioned |
3972 | above the initramfs image will inherit ``TCLIBC="glibc"`` without allowing us | 3932 | above the :term:`Initramfs` image will inherit ``TCLIBC="glibc"`` without allowing us |
3973 | to override it. | 3933 | to override it. |
3974 | 3934 | ||
3975 | To achieve this, you need to perform some additional steps: | 3935 | To achieve this, you need to perform some additional steps: |
3976 | 3936 | ||
3977 | 1. *Create a multiconfig for your initramfs image:* You can perform the steps | 3937 | 1. *Create a multiconfig for your Initramfs image:* You can perform the steps |
3978 | on ":ref:`dev-manual/common-tasks:building images for multiple targets using multiple configurations`" to create a separate multiconfig. | 3938 | on ":ref:`dev-manual/common-tasks:building images for multiple targets using multiple configurations`" to create a separate multiconfig. |
3979 | For the sake of simplicity let's assume such multiconfig is called: ``initramfscfg.conf`` and | 3939 | For the sake of simplicity let's assume such multiconfig is called: ``initramfscfg.conf`` and |
3980 | contains the variables:: | 3940 | contains the variables:: |
@@ -3982,7 +3942,7 @@ To achieve this, you need to perform some additional steps: | |||
3982 | TMPDIR="${TOPDIR}/tmp-initramfscfg" | 3942 | TMPDIR="${TOPDIR}/tmp-initramfscfg" |
3983 | TCLIBC="musl" | 3943 | TCLIBC="musl" |
3984 | 3944 | ||
3985 | 2. *Set additional initramfs variables on your main configuration:* | 3945 | 2. *Set additional Initramfs variables on your main configuration:* |
3986 | Additionally, on your main configuration (``local.conf``) you need to set the | 3946 | Additionally, on your main configuration (``local.conf``) you need to set the |
3987 | variables:: | 3947 | variables:: |
3988 | 3948 | ||
@@ -3997,7 +3957,7 @@ To achieve this, you need to perform some additional steps: | |||
3997 | Building a system with such configuration will build the kernel using the | 3957 | Building a system with such configuration will build the kernel using the |
3998 | main configuration but the ``do_bundle_initramfs`` task will grab the | 3958 | main configuration but the ``do_bundle_initramfs`` task will grab the |
3999 | selected :term:`INITRAMFS_IMAGE` from :term:`INITRAMFS_DEPLOY_DIR_IMAGE` | 3959 | selected :term:`INITRAMFS_IMAGE` from :term:`INITRAMFS_DEPLOY_DIR_IMAGE` |
4000 | instead, resulting in a musl based initramfs image bundled in the kernel | 3960 | instead, resulting in a musl based :term:`Initramfs` image bundled in the kernel |
4001 | but a glibc based main image. | 3961 | but a glibc based main image. |
4002 | 3962 | ||
4003 | The same is applicable to avoid inheriting :term:`DISTRO_FEATURES` on :term:`INITRAMFS_IMAGE` | 3963 | The same is applicable to avoid inheriting :term:`DISTRO_FEATURES` on :term:`INITRAMFS_IMAGE` |
@@ -4171,7 +4131,7 @@ file:: | |||
4171 | Finally, you should consider exactly the type of root filesystem you | 4131 | Finally, you should consider exactly the type of root filesystem you |
4172 | need to meet your needs while also reducing its size. For example, | 4132 | need to meet your needs while also reducing its size. For example, |
4173 | consider ``cramfs``, ``squashfs``, ``ubifs``, ``ext2``, or an | 4133 | consider ``cramfs``, ``squashfs``, ``ubifs``, ``ext2``, or an |
4174 | ``initramfs`` using ``initramfs``. Be aware that ``ext3`` requires a 1 | 4134 | :term:`Initramfs` using ``initramfs``. Be aware that ``ext3`` requires a 1 |
4175 | Mbyte journal. If you are okay with running read-only, you do not need | 4135 | Mbyte journal. If you are okay with running read-only, you do not need |
4176 | this journal. | 4136 | this journal. |
4177 | 4137 | ||
@@ -8802,7 +8762,7 @@ perform a one-time setup of your controller image by doing the following: | |||
8802 | - Installs normal linux utilities not BusyBox ones (e.g. ``bash``, | 8762 | - Installs normal linux utilities not BusyBox ones (e.g. ``bash``, |
8803 | ``coreutils``, ``tar``, ``gzip``, and ``kmod``). | 8763 | ``coreutils``, ``tar``, ``gzip``, and ``kmod``). |
8804 | 8764 | ||
8805 | - Uses a custom Initial RAM Disk (initramfs) image with a custom | 8765 | - Uses a custom :term:`Initramfs` image with a custom |
8806 | installer. A normal image that you can install usually creates a | 8766 | installer. A normal image that you can install usually creates a |
8807 | single root filesystem partition. This image uses another installer that | 8767 | single root filesystem partition. This image uses another installer that |
8808 | creates a specific partition layout. Not all Board Support | 8768 | 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: | |||
123 | 123 | ||
124 | $ runqemu qemux86-64 core-image-minimal ext4 | 124 | $ runqemu qemux86-64 core-image-minimal ext4 |
125 | 125 | ||
126 | - This example specifies to boot an initial RAM disk image and to | 126 | - This example specifies to boot an :term:`Initramfs` image and to |
127 | enable audio in QEMU. For this case, ``runqemu`` set the internal | 127 | enable audio in QEMU. For this case, ``runqemu`` sets the internal |
128 | variable ``FSTYPE`` to "cpio.gz". Also, for audio to be enabled, | 128 | variable ``FSTYPE`` to ``cpio.gz``. Also, for audio to be enabled, |
129 | an appropriate driver must be installed (see the previous | 129 | an appropriate driver must be installed (see the previous |
130 | description for the ``audio`` option for more information). | 130 | description for the ``audio`` option for more information). |
131 | :: | 131 | :: |
@@ -394,7 +394,7 @@ command line: | |||
394 | options are basically identical. If you do not provide a MACHINE | 394 | options are basically identical. If you do not provide a MACHINE |
395 | option, ``runqemu`` tries to determine it based on other options. | 395 | option, ``runqemu`` tries to determine it based on other options. |
396 | 396 | ||
397 | - ``ramfs``: Indicates you are booting an initial RAM disk (initramfs) | 397 | - ``ramfs``: Indicates you are booting an :term:`Initramfs` |
398 | image, which means the ``FSTYPE`` is ``cpio.gz``. | 398 | image, which means the ``FSTYPE`` is ``cpio.gz``. |
399 | 399 | ||
400 | - ``iso``: Indicates you are booting an ISO image, which means the | 400 | - ``iso``: Indicates you are booting an ISO image, which means the |