summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-07-07 13:38:20 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-07-12 00:28:15 +0100
commitf49fa46e19135668b372df3a3c7d9adefe4809da (patch)
tree837a48653d470abc91c3214cd7dba4d24350be9c /documentation/dev-manual/dev-manual-common-tasks.xml
parentaa1162685fd383d0e0c062f63105f624bdef5027 (diff)
downloadpoky-f49fa46e19135668b372df3a3c7d9adefe4809da.tar.gz
dev-manual: Updated the section on initramfs
I did a rewrite of the section to get it into a procedural form. Missing some technical information and needs a review but it is the best that can be done at this time. The code for initrd is not settled. (From yocto-docs rev: 0fdef8c5fed6ac510d1604a677e6546494b4c96b) 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.xml189
1 files changed, 127 insertions, 62 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index f040c402c4..6cdf2a41ca 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -6229,73 +6229,138 @@
6229 <title>Building an Initial RAM Filesystem (initramfs) Image</title> 6229 <title>Building an Initial RAM Filesystem (initramfs) Image</title>
6230 6230
6231 <para> 6231 <para>
6232 initramfs is the successor of Initial RAM Disk (initrd). 6232 An initial RAM filesystem (initramfs) image provides a temporary
6233 It is a "copy in and out" (cpio) archive of the initial file system 6233 root filesystem used for early system initialization (e.g.
6234 that gets loaded into memory during the Linux startup process. 6234 loading of modules needed to locate and mount the "real" root
6235 Because Linux uses the contents of the archive during 6235 filesystem).
6236 initialization, the initramfs needs to contain all of the device
6237 drivers and tools needed to mount the final root filesystem.
6238 </para>
6239
6240 <para>
6241 To build an initramfs image and bundle it into the kernel, set the
6242 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
6243 variable in your <filename>local.conf</filename> file, and set the
6244 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink>
6245 variable in your <filename>machine.conf</filename> file:
6246 <literallayout class='monospaced'>
6247 INITRAMFS_IMAGE_BUNDLE = "1"
6248 INITRAMFS_IMAGE = "<replaceable>image_recipe_name</replaceable>"
6249 </literallayout>
6250 Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename>
6251 flag causes the initramfs created by the recipe and defined by
6252 <filename>INITRAMFS_IMAGE</filename> to be unpacked into the
6253 <filename>${B}/usr/</filename> directory.
6254 The unpacked initramfs is then passed to the kernel's
6255 <filename>Makefile</filename> using the
6256 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></ulink>
6257 variable, allowing initramfs to be built in to the kernel
6258 normally.
6259 <note> 6236 <note>
6260 The preferred method is to use the 6237 The initramfs image is the successor of initial RAM disk
6261 <filename>INITRAMFS_IMAGE</filename> variable rather than the 6238 (initrd).
6262 <filename>INITRAMFS_TASK</filename> variable. 6239 It is a "copy in and out" (cpio) archive of the initial
6263 Setting <filename>INITRAMFS_TASK</filename> is supported for 6240 filesystem that gets loaded into memory during the Linux
6264 backward compatibility. 6241 startup process.
6265 However, use of this variable has circular dependency 6242 Because Linux uses the contents of the archive during
6266 problems. 6243 initialization, the initramfs image needs to contain all of the
6267 See the 6244 device drivers and tools needed to mount the final root
6268 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink> 6245 filesystem.
6269 variable for additional information on these dependency
6270 problems.
6271 </note> 6246 </note>
6272 </para> 6247 </para>
6273 6248
6274 <para> 6249 <para>
6275 The recipe that <filename>INITRAMFS_IMAGE</filename> 6250 Follow these steps to create an initramfs image:
6276 points to must produce a <filename>.cpio.gz</filename>, 6251 <orderedlist>
6277 <filename>.cpio.tar</filename>, <filename>.cpio.lz4</filename>, 6252 <listitem><para>
6278 <filename>.cpio.lzma</filename>, or 6253 <emphasis>Create the initramfs Image Recipe:</emphasis>
6279 <filename>.cpio.xz</filename> file. 6254 You can reference the
6280 You can ensure you produce one of these <filename>.cpio.*</filename> 6255 <filename>core-image-minimal-initramfs.bb</filename>
6281 files by setting the 6256 recipe found in the <filename>meta/recipes-core</filename>
6282 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_FSTYPES'><filename>INITRAMFS_FSTYPES</filename></ulink> 6257 directory of the
6283 variable in your configuration file to one or more of the above 6258 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
6284 file types. 6259 as an example from which to work.
6285 <note> 6260 </para></listitem>
6286 If you add items to the initramfs image by way of its recipe, 6261 <listitem><para>
6287 you should use 6262 <emphasis>Decide if You Need to Bundle the initramfs Image
6288 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink> 6263 Into the Kernel Image:</emphasis>
6289 rather than 6264 If you want the initramfs image that is built to be
6290 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>. 6265 bundled in with the kernel image, set the
6291 <filename>PACKAGE_INSTALL</filename> gives more direct control 6266 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
6292 of what is added to the image as compared to the defaults you 6267 variable to "1" in your <filename>local.conf</filename>
6293 might not necessarily want that are set by the 6268 configuration file and set the
6294 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink> 6269 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink>
6295 or 6270 variable in the recipe that builds the kernel image.
6296 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-core-image'><filename>core-image</filename></ulink> 6271 <note><title>Tip</title>
6297 classes. 6272 It is recommended that you do bundle the initramfs
6298 </note> 6273 image with the kernel image to avoid circular
6274 dependencies between the kernel recipe and the
6275 initramfs recipe should the initramfs image
6276 include kernel modules.
6277 </note>
6278 Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename>
6279 flag causes the initramfs image to be unpacked
6280 into the <filename>${B}/usr/</filename> directory.
6281 The unpacked initramfs image is then passed to the kernel's
6282 <filename>Makefile</filename> using the
6283 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></ulink>
6284 variable, allowing the initramfs image to be built into
6285 the kernel normally.
6286 <note>
6287 If you choose to not bundle the initramfs image with
6288 the kernel image, you are essentially using an
6289 <ulink url='https://en.wikipedia.org/wiki/Initrd'>Initial RAM Disk (initrd)</ulink>.
6290 Creating an initrd is handled primarily through the
6291 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRD_IMAGE'><filename>INITRD_IMAGE</filename></ulink>,
6292 <filename>INITRD_LIVE</filename>, and
6293 <filename>INITRD_IMAGE_LIVE</filename> variables.
6294 For more information, see the
6295 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/image-live.bbclass'><filename>image-live.bbclass</filename></ulink>
6296 file.
6297 </note>
6298 </para></listitem>
6299<!--
6300Some notes from Cal:
6301
6302 A non-bundled initramfs is essentially an initrd, which I am discovering
6303 to be rather confusingly supported in OE at the moment.
6304
6305 Its primarily handled through INITRD_IMAGE(_LIVE/_VM) and INITRD(_LIVE/_VM)
6306 variables. INITRD_IMAGE* is the primary image target, which gets added to
6307 INITRD*, which is a list of cpio filesystems. You can add more cpio
6308 filesystems to the INITRD variable to add more to the initrd. For
6309 instance, meta-intel adds intel-microcode via the following:
6310
6311 INITRD_LIVE_prepend = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', '${DEPLOY_DIR_IMAGE}/microcode.cpio ', '', d)}"
6312
6313 If 'intel-ucode' is in MACHINE_FEATURES, this resolves to:
6314
6315 INITRD_LIVE_prepend = "${DEPLOY_DIR_IMAGE}/microcode.cpio "
6316
6317 Unfortunately you need the full path, and its up to you to sort out
6318 dependencies as well. For instance, we have the following:
6319
6320 MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', ' intel-microcode', '', d)}"
6321
6322 which resolves to:
6323
6324 MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "intel-microcode"
6325
6326 However, the above is only true with the "live" IMAGE_FSTYPE. Wic is
6327 another beast entirely, with current wic kickstart files not supporting
6328 initrds, and only partial support in the source plugins. That being said,
6329 I know the generic bootfs work Ed is working on will help immensely in this
6330 aspect. He or Saul can provide more details here.
6331
6332 Anyhow, its rather fractured and confusing and could probably use a
6333 rework honestly. I don't know how feasible it is to document all the
6334 details and corner cases of this area.
6335-->
6336 <listitem><para>
6337 <emphasis>Optionally Add Items to the initramfs Image
6338 Through the initramfs Image Recipe:</emphasis>
6339 If you add items to the initramfs image by way of its
6340 recipe, you should use
6341 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink>
6342 rather than
6343 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>.
6344 <filename>PACKAGE_INSTALL</filename> gives more direct
6345 control of what is added to the image as compared to
6346 the defaults you might not necessarily want that are
6347 set by the
6348 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
6349 or
6350 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-core-image'><filename>core-image</filename></ulink>
6351 classes.
6352 </para></listitem>
6353 <listitem><para>
6354 <emphasis>Build the Kernel Image and the initramfs
6355 Image:</emphasis>
6356 Build your kernel image using BitBake.
6357 Because the initramfs image recipe is a dependency of the
6358 kernel image, the initramfs image is built as well and
6359 bundled with the kernel image if you used the
6360 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
6361 variable described earlier.
6362 </para></listitem>
6363 </orderedlist>
6299 </para> 6364 </para>
6300 </section> 6365 </section>
6301 6366