summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-12-29 10:26:15 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-01-11 17:23:17 +0000
commitecaab75be6be1147caad0900278df534cec2e89e (patch)
treea2260b8e9ff51f08609b4067b091018c2d9ba7be /documentation/dev-manual/dev-manual-common-tasks.xml
parentd229fded3ecb2332bb8602a4924990417385cf09 (diff)
downloadpoky-ecaab75be6be1147caad0900278df534cec2e89e.tar.gz
dev-manual, ref-manual: Created new section on initramfs
Fixes [YOCTO #7096] We did not document how to create an initramfs image to be included with a kernel build. Various variables sort of inferred the knowledge. I created a new section in the "Common Tasks" section of the dev-manual that describes how to create an initramfs image. Also, I updated the kernel.bbclass reference section to point back to the new "how-to" section. Finally, I also created a bunch of cross-reference links from various related variables back to the new "how-to" section. (From yocto-docs rev: 289dfbd5d24241e42446a043104eecd6dca76f13) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml73
1 files changed, 73 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 603ca1ff8e..f3f2a4b026 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -5475,6 +5475,79 @@
5475 </section> 5475 </section>
5476 </section> 5476 </section>
5477 5477
5478 <section id='building-an-initramfs-image'>
5479 <title>Building an Initial RAM Filesystem (initramfs) Image</title>
5480
5481 <para>
5482 initramfs is the successor of Initial RAM Disk (initrd).
5483 It is a "copy in and out" (cpio) archive of the initial file system
5484 that gets loaded into memory during the Linux startup process.
5485 Because Linux uses the contents of the archive during
5486 initialization, the initramfs needs to contain all of the device
5487 drivers and tools needed to mount the final root filesystem.
5488 </para>
5489
5490 <para>
5491 To build an initramfs image and bundle it into the kernel, set the
5492 following variables:
5493 <literallayout class='monospaced'>
5494 INITRAMFS_IMAGE_BUNDLE = "1"
5495 INITRAMFS_IMAGE = "<replaceable>image_recipe_name</replaceable>"
5496 </literallayout>
5497 Setting the
5498 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
5499 flag causes the initramfs created by the recipe
5500 and defined by
5501 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink>
5502 to be unpacked into the <filename>${B}/usr/</filename> directory.
5503 The unpacked initramfs is then passed to the kernel's
5504 <filename>Makefile</filename> using the
5505 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></ulink>
5506 variable, allowing initramfs to be built in to the kernel
5507 normally.
5508 <note>
5509 The preferred method is to use the
5510 <filename>INITRAMFS_IMAGE</filename> variable rather than the
5511 <filename>INITRAMFS_TASK</filename> variable.
5512 Setting <filename>INITRAMFS_TASK</filename> is supported for
5513 backward compatibility.
5514 However, use of this variable has circular dependency
5515 problems.
5516 See the
5517 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
5518 variable for additional information on these dependency
5519 problems.
5520 </note>
5521 </para>
5522
5523 <para>
5524 The recipe that <filename>INITRAMFS_IMAGE</filename>
5525 points to must produce a <filename>.cpio.gz</filename>,
5526 <filename>.cpio.tar</filename>, <filename>.cpio.lz4</filename>,
5527 <filename>.cpio.lzma</filename>, or
5528 <filename>.cpio.xz</filename> file.
5529 You can ensure you produce one of these <filename>.cpio.*</filename>
5530 files by setting the
5531 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>
5532 variable in your configuration file to one or more of the above
5533 file types.
5534 <note>
5535 If you add items to the initramfs image by way of its recipe,
5536 you should use
5537 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink>
5538 rather than
5539 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>.
5540 <filename>PACKAGE_INSTALL</filename> gives more direct control
5541 of what is added to the image as compared to the defaults you
5542 might not necessarily want that are set by the
5543 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
5544 or
5545 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-core-image'><filename>core-image</filename></ulink>
5546 classes.
5547 </note>
5548 </para>
5549 </section>
5550
5478 <section id='configuring-the-kernel'> 5551 <section id='configuring-the-kernel'>
5479 <title>Configuring the Kernel</title> 5552 <title>Configuring the Kernel</title>
5480 5553