mirror of
https://git.yoctoproject.org/poky
synced 2026-03-20 06:09:41 +01:00
dev-manual: Moved "Building an Initial RAM Filesystem (initramfs) Image"
This section now belongs under the parent "building" section in the common tasks chapter. (From yocto-docs rev: dad6029b9b45fd6ec564894ba101991fd8a2162e) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
committed by
Richard Purdie
Richard Purdie
parent
95d778d74f
commit
95c73d34ee
@@ -5420,6 +5420,108 @@
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='building-an-initramfs-image'>
|
||||
<title>Building an Initial RAM Filesystem (initramfs) Image</title>
|
||||
|
||||
<para>
|
||||
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).
|
||||
<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.
|
||||
</note>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Follow these steps to create an initramfs image:
|
||||
<orderedlist>
|
||||
<listitem><para>
|
||||
<emphasis>Create the initramfs Image Recipe:</emphasis>
|
||||
You can reference the
|
||||
<filename>core-image-minimal-initramfs.bb</filename>
|
||||
recipe found in the <filename>meta/recipes-core</filename>
|
||||
directory of the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
|
||||
as an example from which to work.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<emphasis>Decide if You Need to Bundle the initramfs Image
|
||||
Into the Kernel Image:</emphasis>
|
||||
If you want the initramfs image that is built to be
|
||||
bundled in with the kernel image, set the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
|
||||
variable to "1" in your <filename>local.conf</filename>
|
||||
configuration file and set the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink>
|
||||
variable in the recipe that builds the kernel image.
|
||||
<note><title>Tip</title>
|
||||
It is recommended that you do 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.
|
||||
</note>
|
||||
Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename>
|
||||
flag causes the initramfs image to be unpacked
|
||||
into the <filename>${B}/usr/</filename> directory.
|
||||
The unpacked initramfs image is then passed to the kernel's
|
||||
<filename>Makefile</filename> using the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></ulink>
|
||||
variable, allowing the initramfs image to be built into
|
||||
the kernel normally.
|
||||
<note>
|
||||
If you choose to not bundle the initramfs image with
|
||||
the kernel image, you are essentially using an
|
||||
<ulink url='https://en.wikipedia.org/wiki/Initrd'>Initial RAM Disk (initrd)</ulink>.
|
||||
Creating an initrd is handled primarily through the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-INITRD_IMAGE'><filename>INITRD_IMAGE</filename></ulink>,
|
||||
<filename>INITRD_LIVE</filename>, and
|
||||
<filename>INITRD_IMAGE_LIVE</filename> variables.
|
||||
For more information, see the
|
||||
<ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/image-live.bbclass'><filename>image-live.bbclass</filename></ulink>
|
||||
file.
|
||||
</note>
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<emphasis>Optionally Add Items to the initramfs Image
|
||||
Through the initramfs Image Recipe:</emphasis>
|
||||
If you add items to the initramfs image by way of its
|
||||
recipe, you should use
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink>
|
||||
rather than
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>.
|
||||
<filename>PACKAGE_INSTALL</filename> 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
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
|
||||
or
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-core-image'><filename>core-image</filename></ulink>
|
||||
classes.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<emphasis>Build the Kernel Image and the initramfs
|
||||
Image:</emphasis>
|
||||
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 and
|
||||
bundled with the kernel image if you used the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
|
||||
variable described earlier.
|
||||
</para></listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
|
||||
@@ -5427,6 +5529,9 @@
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<section id="platdev-working-with-libraries">
|
||||
<title>Working With Libraries</title>
|
||||
|
||||
@@ -7128,145 +7233,6 @@
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section id='building-an-initramfs-image'>
|
||||
<title>Building an Initial RAM Filesystem (initramfs) Image</title>
|
||||
|
||||
<para>
|
||||
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).
|
||||
<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.
|
||||
</note>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Follow these steps to create an initramfs image:
|
||||
<orderedlist>
|
||||
<listitem><para>
|
||||
<emphasis>Create the initramfs Image Recipe:</emphasis>
|
||||
You can reference the
|
||||
<filename>core-image-minimal-initramfs.bb</filename>
|
||||
recipe found in the <filename>meta/recipes-core</filename>
|
||||
directory of the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
|
||||
as an example from which to work.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<emphasis>Decide if You Need to Bundle the initramfs Image
|
||||
Into the Kernel Image:</emphasis>
|
||||
If you want the initramfs image that is built to be
|
||||
bundled in with the kernel image, set the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
|
||||
variable to "1" in your <filename>local.conf</filename>
|
||||
configuration file and set the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink>
|
||||
variable in the recipe that builds the kernel image.
|
||||
<note><title>Tip</title>
|
||||
It is recommended that you do 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.
|
||||
</note>
|
||||
Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename>
|
||||
flag causes the initramfs image to be unpacked
|
||||
into the <filename>${B}/usr/</filename> directory.
|
||||
The unpacked initramfs image is then passed to the kernel's
|
||||
<filename>Makefile</filename> using the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></ulink>
|
||||
variable, allowing the initramfs image to be built into
|
||||
the kernel normally.
|
||||
<note>
|
||||
If you choose to not bundle the initramfs image with
|
||||
the kernel image, you are essentially using an
|
||||
<ulink url='https://en.wikipedia.org/wiki/Initrd'>Initial RAM Disk (initrd)</ulink>.
|
||||
Creating an initrd is handled primarily through the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-INITRD_IMAGE'><filename>INITRD_IMAGE</filename></ulink>,
|
||||
<filename>INITRD_LIVE</filename>, and
|
||||
<filename>INITRD_IMAGE_LIVE</filename> variables.
|
||||
For more information, see the
|
||||
<ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/image-live.bbclass'><filename>image-live.bbclass</filename></ulink>
|
||||
file.
|
||||
</note>
|
||||
</para></listitem>
|
||||
<!--
|
||||
Some notes from Cal:
|
||||
|
||||
A non-bundled initramfs is essentially an initrd, which I am discovering
|
||||
to be rather confusingly supported in OE at the moment.
|
||||
|
||||
Its primarily handled through INITRD_IMAGE(_LIVE/_VM) and INITRD(_LIVE/_VM)
|
||||
variables. INITRD_IMAGE* is the primary image target, which gets added to
|
||||
INITRD*, which is a list of cpio filesystems. You can add more cpio
|
||||
filesystems to the INITRD variable to add more to the initrd. For
|
||||
instance, meta-intel adds intel-microcode via the following:
|
||||
|
||||
INITRD_LIVE_prepend = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', '${DEPLOY_DIR_IMAGE}/microcode.cpio ', '', d)}"
|
||||
|
||||
If 'intel-ucode' is in MACHINE_FEATURES, this resolves to:
|
||||
|
||||
INITRD_LIVE_prepend = "${DEPLOY_DIR_IMAGE}/microcode.cpio "
|
||||
|
||||
Unfortunately you need the full path, and its up to you to sort out
|
||||
dependencies as well. For instance, we have the following:
|
||||
|
||||
MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', ' intel-microcode', '', d)}"
|
||||
|
||||
which resolves to:
|
||||
|
||||
MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "intel-microcode"
|
||||
|
||||
However, the above is only true with the "live" IMAGE_FSTYPE. Wic is
|
||||
another beast entirely, with current wic kickstart files not supporting
|
||||
initrds, and only partial support in the source plugins. That being said,
|
||||
I know the generic bootfs work Ed is working on will help immensely in this
|
||||
aspect. He or Saul can provide more details here.
|
||||
|
||||
Anyhow, its rather fractured and confusing and could probably use a
|
||||
rework honestly. I don't know how feasible it is to document all the
|
||||
details and corner cases of this area.
|
||||
-->
|
||||
<listitem><para>
|
||||
<emphasis>Optionally Add Items to the initramfs Image
|
||||
Through the initramfs Image Recipe:</emphasis>
|
||||
If you add items to the initramfs image by way of its
|
||||
recipe, you should use
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink>
|
||||
rather than
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>.
|
||||
<filename>PACKAGE_INSTALL</filename> 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
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
|
||||
or
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-core-image'><filename>core-image</filename></ulink>
|
||||
classes.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<emphasis>Build the Kernel Image and the initramfs
|
||||
Image:</emphasis>
|
||||
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 and
|
||||
bundled with the kernel image if you used the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
|
||||
variable described earlier.
|
||||
</para></listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='flashing-images-using-bmaptool'>
|
||||
<title>Flashing Images Using <filename>bmaptool</filename></title>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user