mirror of
https://git.yoctoproject.org/poky
synced 2026-05-31 12:49:46 +00: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
5c5a8e3d34
commit
16e730e638
@@ -5420,6 +5420,108 @@
|
|||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</para>
|
</para>
|
||||||
</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>
|
||||||
|
<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>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
@@ -5427,6 +5529,9 @@
|
|||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<section id="platdev-working-with-libraries">
|
<section id="platdev-working-with-libraries">
|
||||||
<title>Working With Libraries</title>
|
<title>Working With Libraries</title>
|
||||||
|
|
||||||
@@ -7128,145 +7233,6 @@
|
|||||||
</section>
|
</section>
|
||||||
</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'>
|
<section id='flashing-images-using-bmaptool'>
|
||||||
<title>Flashing Images Using <filename>bmaptool</filename></title>
|
<title>Flashing Images Using <filename>bmaptool</filename></title>
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user