From 5ba68f32a86a20b3f3544903fea2a24f2e59afbf Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 23 Jul 2014 09:28:16 +0300 Subject: dev-manual: Added the section on "Creating Partitioned Images" This is the section on 'wic'. I have dropped in the same exact section from the 1.5.3 (dora branch) release as a starting point for Tom Zanussi to scrub and update for the master branch. (From yocto-docs rev: e189992bff4249664ba959b1c440541e0b84e03d) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 726 +++++++++++++++++++++ 1 file changed, 726 insertions(+) (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml') diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 6aabdf4877..c4c3d9fc3e 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -3348,6 +3348,732 @@ +
+ Creating Partitioned Images + + + Creating an image for a particular hardware target using the + OpenEmbedded build system does not necessarily mean you can boot + that image as is on your device. + Physical devices accept and boot images in various ways depending + on the specifics of the device. + Usually, information about the hardware can tell you what image + format the device requires. + Should your device require multiple partitions on an SD card, flash, + or an HDD, you can use the OpenEmbedded Image Creator + to create the properly partitioned image. + + + + The wic command generates partitioned images + from existing OpenEmbedded build artifacts. + Image generation is driven by partitioning commands contained + in an Openembedded kickstart file (.wks) + specified either directly on the command-line or as one of a + selection of canned .wks files as shown + with the wic list images command in the + "Using a Provided Kickstart File" + section. + When applied to a given set of build artifacts, the result is an + image or set of images that can be directly written onto media and + used on a particular system. + + + + This section provides some background information on + wic, describes what you need to have in + place to run the tool, provides instruction on how to use + wic, and provides several examples. + + +
+ Background + + + This section provides some background on the + wic utility. + While none of this information is required to use + wic, you might find it interesting. + + + The name "wic" is derived from OpenEmbedded + Image Creator (oeic). + The "oe" diphthong in "oeic" was promoted to the + letter "w", because "oeic" is both difficult to remember and + pronounce. + + wic is loosely based on the + Meego Image Creator (mic) + framework. + The wic implementation has been + heavily modified to make direct use of OpenEmbedded + build artifacts instead of package installation and + configuration, which are already incorporated within + the OpenEmbedded artifacts. + + wic is a completely independent + standalone utility that initially provides + easier-to-use and more flexible replacements for a + couple bits of existing functionality in OE Core's + directdisk.bbclass and + mkefidisk.sh script. + The replaced scripts are implemented by a + general-purpose partitioning language based on Red Hat + kickstart syntax. + Underlying code for wic succeeded + from several projects over time. + + +
+ +
+ Requirements + + + In order to use the wic utility with the + OpenEmbedded Build system, you need to meet the following + requirements: + + The Linux distribution on your + development host must support the Yocto Project. + See the + "Supported Linux Distributions" + section in the Yocto Project Reference Manual for this + list of distributions. + + The standard system utilities, such as + cp, must be installed on your + development host system. + + + The + GNU Parted + package must be installed on your development host + system. + + + Have the build artifacts already available. + You must already have created an image using the + Openembedded build system (e.g. + core-image-minimal. + It might seem redundant to generate an image in order + to create an image using wic, + but the artifacts are needed and they are generated + with the build system. + + You must have sourced one of the build environment + setup scripts (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres) + found in the + Build Directory. + + + +
+ +
+ Getting Help + + + You can get general help for the wic + by entering the wic command by itself + or by entering the command with a help argument as follows: + + $ wic -h + $ wic --help + + + + + Currently, wic supports two commands: + create and list. + You can get help for these commands as follows: + + $ wic help <command> + + + + + You can find more out about the images + wic creates using the provided + kickstart files with the following form of the command: + + $ wic list <image> help + + Where <image> is either + directdisk or + mkefidisk. + +
+ +
+ Operational Modes + + + You can run wic in two modes: Raw and + Cooked: + + Raw Mode: + You explicitly specify build artifacts through + command-line arguments. + Cooked Mode: + The current + MACHINE + setting and image name are used to automatically locate + and provide the build artifacts. + + + + + Regardless of the mode you use, you need to have the build + artifacts ready and available. + Additionally, the environment must be set up using the + &OE_INIT_FILE; + or + oe-init-build-env-memres + script found in the + Build Directory. + + +
+ Raw Mode + + + The general form of the 'wic' command in raw mode is: + + $ wic create image_name.wks [options] [...] + + Where: + + image_name.wks + An an OpenEmbedded kickstart file. You can provide + your own custom file or use a file from a set of + provided files as described by further options. + + -o OUTDIR, --outdir=OUTDIR + The name of a directory in which to create image. + + -i PROPERTIES_FILE, --infile=PROPERTIES_FILE + The name of a file containing the values for image + properties as a JSON file. + + -e IMAGE_NAME, --image-name=IMAGE_NAME + The name of the image from which to use the artifacts + (e.g. core-image-sato). + + -r ROOTFS_DIR, --rootfs-dir=ROOTFS_DIR + The path to the /rootfs directory to use as the + .wks rootfs source. + + -b BOOTIMG_DIR, --bootimg-dir=BOOTIMG_DIR + The path to the directory containing the boot artifacts + (e.g. /EFI or /syslinux) to use as the .wks bootimg + source. + + -k KERNEL_DIR, --kernel-dir=KERNEL_DIR + The path to the directory containing the kernel to use + in the .wks boot image. + + -n NATIVE_SYSROOT, --native-sysroot=NATIVE_SYSROOT + The path to the native sysroot containing the tools to use + to build the image. + + -p, --skip-build-check + Skips the build check. + + -D, --debug + Output debug information. + + + You do not need root privileges to run + wic. + In fact, you should not run as root when using the + utility. + + +
+ +
+ Cooked Mode + + + The general form of the wic command + using Cooked Mode is: + + $ wic create kickstart_file -e image_name + + Where: + + kickstart_file + An OpenEmbedded kickstart file. You can provide your own + custom file or supplied file. + + image_name + Specifies the image built using the OpenEmbedded build + system. + + This form is the simplest and most user-friendly, as it + does not require specifying all individual parameters. + All you need to provide is your own + .wks file or one provided with the + release. + +
+
+ +
+ Using a Provided Kickstart File + + + If you do not want to create your own + .wks file, you can use a provided + file. + Use the following command to list the available files: + + $ wic list images + directdisk Create a 'pcbios' direct disk image + mkefidisk Create an EFI disk image + + When you use a provided file, you do not have to use the + .wks extension. + Here is an example in Raw Mode that uses the + directdisk file: + + $ wic create directdisk -r rootfs_dir -b bootimg_dir \ + -k kernel_dir -n native_sysroot + + + + + Here are the actual partition language commands + used in the mkefidisk.wks file to generate + an image: + + # short-description: Create an EFI disk image + # long-description: Creates a partitioned EFI disk image that the user + # can directly dd to boot media. + + part /boot ‐‐source bootimg-efi ‐‐ondisk sda ‐‐fstype=efi ‐‐active + + part / ‐‐source rootfs ‐‐ondisk sda ‐‐fstype=ext3 ‐‐label platform + + part swap ‐‐ondisk sda ‐‐size 44 ‐‐label swap1 ‐‐fstype=swap + + bootloader ‐‐timeout=10 ‐‐append="rootwait console=ttyPCH0,115200" + + +
+ +
+ Examples + + + This section provides several examples that show how to use + the wic utility. + All the examples assume the list of requirements in the + "Requirements" section + have been met. + The examples assume the previously generated image is + core-image-minimal. + + +
+ Generate an Image using a Provided Kickstart File + + + This example runs in Cooked Mode and uses the + mkefidisk kickstart file: + + $ wic create mkefidisk -e core-image-minimal + Checking basic build environment... + Done. + + Creating image(s)... + + Info: The new image(s) can be found here: + /var/tmp/wic/build/mkefidisk-201310230946-sda.direct + + The following build artifacts were used to create the image(s): + ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/rootfs + BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/core-image-minimal-1.0/hddimg + KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/minnow/usr/src/kernel + NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux + + + The image(s) were created using OE kickstart file: + /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks + + This example shows the easiest way to create an image + by running in Cooked Mode and using the + -e option with a provided kickstart + file. + All that is necessary is to specify the image used to + generate the artifacts. + Your local.conf needs to have the + MACHINE + variable set to the machine you are using, which is + "minnow" in this example. + + + + The output specifies exactly which image was + created as well as where it was created. + The output also names the artifacts used and the exact + .wks script that was used to generate + the image. + + You should always verify the details provided in the + output to make sure that the image was indeed created + exactly as expected. + + + + + Continuing with the example, you can now directly + dd the image to a USB stick, or + whatever media for which you built your image, + and boot the resulting media: + + $ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdb + [sudo] password for trz: + 182274+0 records in + 182274+0 records out + 93324288 bytes (93 MB) copied, 14.4777 s, 6.4 MB/s + [trz@empanada ~]$ sudo eject /dev/sdb + + +
+ +
+ Using a Modified Kickstart File + + + Because wic image creation is driven + by the kickstart file, it is easy to affect image creation + by changing the parameters in the file. + This next example demonstrates that through modification + of the directdisk kickstart file. + + + + As mentioned earlier, you can use the command + wic list images to show the list + of provided kickstart files. + The directory in which these files reside is + scripts/lib/image/canned-wks/ + located in the + Source Directory. + Because the available files reside in this directory, you + can create and add your own custom files to the directory. + Subsequent use of the wic list images + command would then include your kickstart files. + + + + In this example, the existing + directdisk file already does most + of what is needed. + However, for the hardware in this example, the image will + need to boot from sdb instead of + sda, which is what the + directdisk kickstart file uses. + + + + The example begins by making a copy of the + directdisk.wks file in the + scripts/lib/image/canned-wks + directory and then changing the lines that specify the + target disk from which to boot. + + $ cp /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks \ + /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks + + Next, the example modifies the + directdisksdb.wks file and changes all + instances of "--ondisk sda" + to "--ondisk sdb". + The example changes the following two lines and leaves the + remaining lines untouched: + + part /boot --source bootimg --ondisk sdb --fstype=msdos --label boot --active --align 1024 + part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 + + Once the lines are changed, the example generates the + directdisksdb image. + The command points the process at the + core-image-minimal artifacts for the + Next Unit of Computing (nuc) + MACHINE + the local.conf. + + $ wic create directdisksdb -e core-image-minimal + Checking basic build environment... + Done. + + Creating image(s)... + + Info: The new image(s) can be found here: + /var/tmp/wic/build/directdisksdb-201310231131-sdb.direct + + The following build artifacts were used to create the image(s): + ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/nuc-poky-linux/core-image-minimal/1.0-r0/rootfs + BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/share + KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/src/kernel + NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux + + + The image(s) were created using OE kickstart file: + /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks + + Continuing with the example, you can now directly + dd the image to a USB stick, or + whatever media for which you built your image, + and boot the resulting media: + + $ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb + 86018+0 records in + 86018+0 records out + 44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s + [trz@empanada tmp]$ sudo eject /dev/sdb + + +
+ +
+ Creating an Image Based on <filename>core-image-minimal</filename> and <filename>crownbay-noemgd</filename> + + + This example creates an image based on + core-image-minimal and a + crownbay-noemgd + MACHINE + that works right out of the box. + + $ wic create directdisk -e core-image-minimal + + Checking basic build environment... + Done. + + Creating image(s)... + + Info: The new image(s) can be found here: + /var/tmp/wic/build/directdisk-201309252350-sda.direct + + The following build artifacts were used to create the image(s): + + ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs + BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share + KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel + NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel + + The image(s) were created using OE kickstart file: + /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks + + +
+ +
+ Using a Modified Kickstart File and Running in Raw Mode + + + This next example manually specifies each build artifact + (runs in Raw Mode) and uses a modified kickstart file. + The example also uses the -o option + to cause wic to create the output + somewhere other than the default + /var/tmp/wic directory: + + $ wic create ~/test.wks -o /home/trz/testwic --rootfs-dir \ + /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs \ + --bootimg-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share \ + --kernel-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel \ + --native-sysroot /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux + + Creating image(s)... + + Info: The new image(s) can be found here: + /home/trz/testwic/build/test-201309260032-sda.direct + + The following build artifacts were used to create the image(s): + + ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs + BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share + KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel + NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel + + The image(s) were created using OE kickstart file: + /home/trz/test.wks + + For this example, + MACHINE + did not have to be specified in the + local.conf file since the artifact is + manually specified. + +
+
+ +
+ OpenEmbedded Kickstart (.wks) Reference + + + The current wic implementation supports + only the basic kickstart partitioning commands: + partition (or part + for short) and bootloader. + + + + Following is a listing of the commands, their syntax, and + meanings. + The commands are based on the Fedora kickstart documentation + but with modifications to reflect wic + capabilities. + + http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition + http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader + + + +
+ Command: part or partition + + + This command creates a partition on the system and uses the + following syntax: + + part <mntpoint> + + The <mntpoint> is where the + partition will be mounted and must be of one of the + following forms: + + /<path>: + For example, /, + /usr, and + /home + swap: + The partition will be used as swap space. + + + + + + Following are the supported options: + + --size: + The minimum partition size in MBytes. + Specify an integer value such as 500. + Do not append the number with "MB". + You do not need this option if you use + --source. + --source: + This option is a wic-specific option that can + currently have one of two values, "bootimg" or + "rootfs". + If --source rootfs is + used, it tells the wic command + to create a partition as large as needed to fill + with the contents of the root filesystem + (specified by the -r + wic option) and to fill it + with the contents of /rootfs. + + If --source bootimg + is used, it tells the wic + command to create a partition as large as needed to + fill with the contents of the boot partition + (specified by the -b + wic option). + Exactly what those contents are depend on the value + of the --fstype option for + that partition. + If --fstype=efi is specified, + the boot artifacts contained in HDDDIR are used, + and if --fstype=msdos is + specified, the boot artifacts found in + STAGING_DATADIR are used. + + --ondisk or --ondrive: + Forces the partition to be created on a particular + disk. + --fstype: + Sets the file system type for the partition. + Valid values are: + + msdos + + efi + + ext4 + + ext3 + + ext2 + + btrfs + + swap + + + --label label: + Specifies the label to give to the filesystem to + be made on the partition. + If the given label is already in use by another + filesystem, a new label is created for the + partition. + --active: + Marks the partition as active. + --align (in KBytes): + This option is specific to the Meego Image + Creator (mic) that says to start a partition on an + x KBytes boundary. + + +
+ +
+ Command: bootloader + + + This command specifies how the boot loader should be + and supports the following options: + + --timeout: + Specifies the number of seconds before the + bootloader times out and boots the default option. + + --append: + Specifies kernel parameters. + These will be added to the syslinux + APPEND or + grub kernel command line. + + The boot type is determined by the fstype of + the /boot mountpoint. + If the fstype is "msdos" the boot type is + "pcbios", otherwise it is the fstype, which + is currently "efi" (more to be added later). + + If the boot type is "efi", the image will + use grub and has one + menuentry: "boot". + If the boot type is "pcbios", the image + will use syslinux and has one menu label: "boot". + + Future updates will implement more options. + If you use anything that is not specifically + supported, results can be unpredictable. + + + +
+
+
+
Configuring the Kernel -- cgit v1.2.3-54-g00ecf