From b0c4c855a0d5d4d2efcdf4da4b06e943be310887 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 13 Nov 2013 17:14:56 -0800 Subject: dev-manual: More work on the new wic section. I am working through the raw text. Not clear through yet but needed to commit this. (From yocto-docs rev: 4da28c311443ad31a0a36b07b39aa7ce4180b49c) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 769 ++++++++++----------- 1 file changed, 374 insertions(+), 395 deletions(-) (limited to 'documentation/dev-manual') diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 1d2d74927c..305dc316b4 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -1926,18 +1926,16 @@ 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 + 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 - (wic) to create the properly partitioned image. + () to create the properly partitioned image. - Using the wic command, you can also describe - your desired final image and have BitBake assemble the image. - The 'wic' command generates partitioned images from existing - OpenEmbedded build artifacts. + 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 @@ -1949,28 +1947,53 @@ - 'wic' is based loosely on the 'mic' (Meego Image Creator) framework, -but heavily modified to make direct use of OpenEmbedded build -artifacts instead of package installation and configuration, things -already incorporated in the OE artifacts. + 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. - -The name 'wic' comes from 'oeic', which stands for 'OpenEmbedded -Image Creator'. The 'oe' diphthong in 'oeic' has been promoted to the -letter 'w', because 'oeic' is impossible to remember or pronounce. - +
+ Background - -This 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: directdisk.bbclass -and mkefidisk.sh. The replaced scripts are implemented by a -general-purpose partitioning 'language' based on Red Hat kickstart -syntax (with the underlying code borrowed from Tizen mic, which in -turn was borrowed from Meego mic, in turn borrowed from Fedora livecd, -etc.). - + + 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. + + +
+ + - - wic has only been tested on and is only designed to work on the -distros officially supported by Yocto. - +
+ Requirements - Aside from the standard system utilities, such as 'cp', wic expects the -following utilities to be installed on the host machine: + In order to use the wic utility with the + OpenEmbedded Build system, you need to meet the following + requirements: - parted: - GNU Parted - a partition manipulation program + 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.
-
- Raw Vs. Cooked Mode +
+ Getting Help - 'wic' can be used in 'raw' mode, where artifacts are explicitly -specified via command-line arguments (see the command documentation -and examples below), or it can be used in a more easily usable -'cooked' mode which uses the current MACHINE setting and a specified -image name to automatically locate the artifacts used to create the -image. + 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 + - - The prerequisite for generating any image is to have the build -artifacts already available. For example, to create a 'wic' image -using the build artifacts from a core-image-minimal build, you must -already have created a core-image-minimal OpenembeddedCore image. It -may seem redundant to generate an OpenEmbedded image in order to -create a 'wic' image, and in fact to some degree it is. At the -moment, however, that's typically how build artifacts are generated, -and future versions will likely be more integrated into the build -system and will be able to skip that step. There is a benefit -however, in that 'wic' images are created more quickly and without the -need for root access. - -
- -
- Command Summary - - The general form of the 'wic' command in raw mode is: + Currently, wic supports two commands: + create and list. + You can get help for these commands as follows: - $ wic create myimage.wks -r <rootfs-dir> -b <bootimg-dir> - -k <kernel-dir> -n <native-sysroot> + $ wic help <command> - - The 'wic' does NOT require root privileges, and in fact should -not be run as root. - - The .wks file specified in the command is an OE kickstart file (see -the OE kickstart syntax section below) and can of course be specified -directly on the command-line, but the user can also choose from a set -of 'canned' .wks files available via the 'wic list images' command -(example below). + 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 - The -r, -b, -k, and -n options refer to the corresponding OpenEmbedded -build artifacts. Using OpenEmbedded terminology: + You can run wic in two modes: Raw and + Cooked: - -r option: - Used to specify the path to the /rootfs dir to - use as the .wks rootfs source. - -b option: - Used to specify the path to the dir containing - the boot artifacts (e.g. /EFI or /syslinux dirs) to use as the - .wks bootimg source. - -k option: - Used to specify the path to the dir containing - the kernel to use in the .wks bootimg. - - -n option: - Used to specify the path to the native sysroot - containing the tools to use to build the image. - + 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. - - For more technical detail on the origin and meanings of those -artifacts, see the Yocto documentation corresponding to those topics -elsewhere. In most cases, it's not important to know that, because -'cooked' mode provides a convenient shortcut allowing the user to -forget about the raw details and simply specify artifacts via a -high-level OpenEmbedded image name. - +
+ Raw Mode - - If instead of specifying a user-defined .wks file, you prefer to use -one of the 'canned' wic images, you can simply specify a canned image -name (without the .wks extension) in place of a .wks file. Use 'wic -list images' to get a list of 'canned' images: - - $ wic list images - mkefidisk Create an EFI disk image - directdisk Create a 'pcbios' direct disk image - - To use one of the canned images, simply specify it in the raw command. -For example: - - $ wic create directdisk -r <rootfs-dir> -b <bootimg-dir> - -k <kernel-dir> -n <native-sysroot> - - Finally, the general form of the 'wic' command in cooked mode is: - - $ wic create directdisk -e <image-name> - - This form is the simplest and most user-friendly, as it allows you to -skip the need for specifying all the parameters individually. - + + The general form of the 'wic' command in raw mode is: + + $ wic create <image_name>.wks -r <rootfs_dir> -b <bootimg_dir> / + -k <kernel_dir> -n <native_sysroot> + + + You do not need root privileges to run + wic. + In fact, you should not run as root when using the + utility. + + - - <image-name> refers to the Openembedded image name that you've already -build the artifacts for, for example, 'core-image-minimal'. - - In order to use cooked mode, you must have the machine that you -built the artifacts with selected in local.conf. - - -
+ + Following is a description of the wic + parameters and options: + + <image_name>.wks: + An OpenEmbedded kickstart file. + You can provide your own custom file or use a + file from a set of provided files as described + following this list. + -r <rootfs_dir>: + Specifies the path to the root filesystem directory + to be used and the .wks + root filesystem source. + -b <bootimg_dir>: + Specifies the path to the directory that contains + the boot artifacts (e.g. the + EFI or + syslinux directories) to use + as the .wks boot image source. + + -k <kernel_dir>: + Specifies the path to the dir containing the kernel + to use in the .wks boot + image. + -n <native_sysroot>: + Specifies the path to the native sysroot + that contains the tools used to build the image. + + + +
-
- 'wic' Usage Examples +
+ Cooked Mode - - As mentioned, the main prerequisite for generating any image is to -have the build artifacts already available. The below examples assume -the user has already built a 'core-image-minimal' for a specific -machine (future versions won't require this redundant step, but for -now that's typically how build artifacts get generated). - + + The general form of the wic command + using Cooked Mode is: + + $ wic create <kickstart_file> -e <image_name> + + This form is the simplest and most user-friendly, as it + does not requre specifying all individual parameters. + All you need to provide is your own + .wks file or one provided with the + release. + + + + Following is a description of the wic + parameters and options: + + <kickstart>: + An OpenEmbedded kickstart file. + You can provide your own custom file or supplied + file. + -e <image_name>: + Specifies the image built using the OpenEmbedded + build system. + + +
+
+ +
+ Using a Provided Kickstart File - The other prerequisite is to source the build environment: - - $ source oe-init-build-env - - To start out with, we'll generate an image from one of the canned .wks -files. The following generates a list of available images: + 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 mkefidisk Create an EFI disk image directdisk Create a 'pcbios' direct 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> - You can get more information about any of the available images by typing -'wic list xxx help', where 'xxx' is one of the image names. - - - - For example: - - $ wic list mkefidisk help - - Creates a partitioned EFI disk image that the user -can directly dd to boot media. +
- - At any time, you can get help on the 'wic' command or any subcommand -(currently 'list' and 'create'). For instance, to get the description -of 'wic create' command and its parameters: - - $ wic create - - Usage: - - Create a new OpenEmbedded image - - usage: wic create <wks file or image name> [-o <DIRNAME> | --outdir <DIRNAME>] - [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY FILE>] - [-e | --image-name] [-r, --rootfs-dir] [-b, --bootimg-dir] - [-k, --kernel-dir] [-n, --native-sysroot] [-s, --skip-build-check] - - This command creates an OpenEmbedded image based on the 'OE kickstart - commands' found in the <wks file>. - - The -o option can be used to place the image in a directory with a - different name and location. - - See 'wic help create' for more detailed instructions. - - [...] - - +
+ Examples - Continuing further, as mentioned in the command, you can get even more -detailed information by adding 'help' to the above: - - $ wic help create - - NAME - wic create - Create a new OpenEmbedded image - - SYNOPSIS - wic create <wks file or image name> [-o <DIRNAME> | --outdir <DIRNAME>] - [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY FILE>] - [-e | --image-name] [-r, --rootfs-dir] [-b, --bootimg-dir] - [-k, --kernel-dir] [-n, --native-sysroot] [-s, - --skip-build-check] - - DESCRIPTION - This command creates an OpenEmbedded image based on the 'OE - kickstart commands' found in the <wks file>. - - In order to do this, wic needs to know the locations of the - various build artifacts required to build the image. - - Users can explicitly specify the build artifact locations using - the -r, -b, -k, and -n options. See below for details on where - the corresponding artifacts are typically found in a normal - OpenEmbedded build. - - Alternatively, users can use the -e option to have 'mic' determine - those locations for a given image. If the -e option is used, the - user needs to have set the appropriate MACHINE variable in - local.conf, and have sourced the build environment. - - The -e option is used to specify the name of the image to use the - artifacts from e.g. core-image-sato. - - The -r option is used to specify the path to the /rootfs dir to - use as the .wks rootfs source. - - The -b option is used to specify the path to the dir containing - the boot artifacts (e.g. /EFI or /syslinux dirs) to use as the - .wks bootimg source. - - The -k option is used to specify the path to the dir containing - the kernel to use in the .wks bootimg. - - The -n option is used to specify the path to the native sysroot - containing the tools to use to build the image. - - The -s option is used to skip the build check. The build check is - a simple sanity check used to determine whether the user has - sourced the build environment so that the -e option can operate - correctly. If the user has specified the build artifact locations - explicitly, 'wic' assumes the user knows what he or she is doing - and skips the build check. - - When 'wic -e' is used, the locations for the build artifacts - values are determined by 'wic -e' from the output of the 'bitbake - -e' command given an image name e.g. 'core-image-minimal' and a - given machine set in local.conf. In that case, the image is - created as if the following 'bitbake -e' variables were used: - - -r: IMAGE_ROOTFS - -k: STAGING_KERNEL_DIR - -n: STAGING_DIR_NATIVE - -b: HDDDIR and STAGING_DATA_DIR (handlers decide which to use) - - If 'wic -e' is not used, the user needs to select the appropriate - value for -b (as well as -r, -k, and -n). - - The -o option can be used to place the image in a directory with a - different name and location. - - As an alternative to the wks file, the image-specific properties - that define the values that will be used to generate a particular - image can be specified on the command-line using the -i option and - supplying a JSON object consisting of the set of name:value pairs - needed by image creation. - - The set of properties available for a given image type can be - listed using the 'wic list' command. - - So, the easiest way to create an image is to use the -e option with a -canned .wks file. To use the -e option, you need to specify the image -used to generate the artifacts and you actually need to have the -MACHINE used to build them specified in your local.conf (these -requirements aren't necessary if you aren't using the -e options. + 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. - - Below, we generate a mkefidisk image, pointing the process at the -core-image-minimal artifacts for the minnow, selected as our current -MACHINE in local.conf. - +
+ Generate an Image using a Provided Kickstart File - - First, once we've set the build up, we run a core-image-minimal minnow -build: - - $ bitbake core-image-minimal - - Once the build is finished, we can then use wic to create an EFI image -for the minnow to boot. In this case, we'll use the '-e' option to -have wic discover the appropriate build artifacts and generate the -image: - + + This example runs in Cooked Mode and uses the + mkefidisk kickstart file: + $ wic create mkefidisk -e core-image-minimal Checking basic build environment... Done. @@ -2318,86 +2264,118 @@ image: The image(s) were created using OE kickstart file: /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks - - The output specifies exactly which image was created and where it was -created. It also names the artifacts that were 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. - + + 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. + - - Using the path specified in the output for the image name and -location, you can now directly dd the image to a USB stick or whatever -media you built the image for, and boot the resulting media: - + + The output specifies exactly which image were + created and where the image 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 imagewas 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 - - The next example uses a modified 'directdisk' script as an example. - - - - Because wic image creation is driven by .wks files, it's easy to -change the parameters that drive image creation: simply modify the -.wks file. - + + +
- - As illustrated previously, 'wic list images' provides a list of -available images. The images displayed are simply the list of .wks -files in the scripts/lib/image/canned-wks/ directory, minus the .wks -extension. - +
+ Using a Modified Kickstart File - - To add a new image to that list, simply add a new .wks file. - + + Because wic image creation is driven + by the kickstart file, it is easy to drive image creation + by changing the parameters in the file. + This next example demonstrates that through modification + of the directdisk kickstart file. + - - For this example, we already have a .wks file that already does pretty -much what we want, but for our particular hardware, we know we'll be -booting from sdb instead of sda, which is what the directdisk script uses. - + + 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 in the + Source Directory + in scripts/lib/image/canned-wks/. + 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. + - - What we can do is simply create a copy of the directdisk.wks file in -the scripts/lib/image/canned-wks/ directory and change the lines that -specify the target disk to boot from. - + + 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. + - - First, we copy the directdisk.wks file to directdisksdb.wks: - + + 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 - - Then we modify the directdisksdb.wks file and change all instances of -'--ondisk sda' to '--ondisk sdb'. The following two lines are the -lines we end up changing (leaving the rest alone): - + + 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 we've made that change, we generate a directdisksdb image, + + (I AM HERE) + Once the lines are changed, Once we've made that change, we generate a directdisksdb image, pointing the process at the core-image-minimal artifacts for the nuc (Next Unit of Computing), selected as our current MACHINE in local.conf. - + - - Once we've set the build up, we run a core-image-minimal nuc build: - + + Once we've set the build up, we run a core-image-minimal nuc build: + $ bitbake core-image-minimal - + Once the build is finished, we can then use nuc to create our directdisk image for the nuc to boot. In this case, we'll use the '-e' option to have wic discover the appropriate build artifacts and generate the image: - + $ wic create directdisksdb -e core-image-minimal Checking basic build environment... Done. @@ -2416,25 +2394,25 @@ generate the image: The image(s) were created using OE kickstart file: /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks - + Using the path specified in the output for the image name and location, you can now directly dd the image to a USB stick or whatever media you built the image for, 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 - + Of course, you can just use the directdisk image directly if you don't have any special needs. - + - + Here'we're creating a wic image based on core-image-minimal and crownbay-noemgd, which works right out of the box. - + $ wic create directdisk -e core-image-minimal Checking basic build environment... @@ -2454,12 +2432,12 @@ crownbay-noemgd, which works right out of the box. The image(s) were created using OE kickstart file: /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks - + Finally, here's an example that doesn't take the easy way out and manually specifies each build artifact, along with a non-canned .wks file, and also uses the -o option to have wic create the output somewhere other than the default /var/tmp/wic: - + $ 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)... @@ -2476,17 +2454,17 @@ somewhere other than the default /var/tmp/wic: The image(s) were created using OE kickstart file: /home/trz/test.wks - + In this case, we didn't need to have the proper machine selected in local.conf - we manually specified each artifact and therefore wic doesn't need further information from the build system. - + - + Finally, here's an example of the actual partition language commands used to generate the mkefidisk image i.e. these are the contents of the mkefidisk.wks OE kickstart file: - + # short-description: Create an EFI disk image # long-description: Creates a partitioned EFI disk image that the user # can directly dd to boot media. @@ -2498,56 +2476,56 @@ mkefidisk.wks OE kickstart file: part swap --ondisk sda --size 44 --label swap1 --fstype=swap bootloader --timeout=10 --append="rootwait rootfstype=ext3 console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda- intel.enable_msi=0" - - + + +
-
-
- OpenEmbedded Kickstart (.wks) Reference +
+ OpenEmbedded Kickstart (.wks) Reference - + The current 'wic' implementation supports only the basic kickstart partitioning commands: 'partition' (or 'part' for short) and 'bootloader'. - + - + They are listed below and mostly follow the syntax and meaning of the standard kickstart options for those commands. The documentation below is based on the Fedora kickstart documentation of the same commands, but modified to reflect wic capabilities. For reference: - + http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader - - + + -
- Command: part or partition +
+ Command: part or partition - + Creates a partition on the system. Use 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. - - - + + /<path>: + For example, /, + /usr, and + /home + swap: + The partition will be used as swap space. + + + - - Following are the supported options: - + + Following are the supported options: + --size The minimum partition size in megabytes. Specify an integer value here such as 500. Do not append the number with MB. Not needed if @@ -2597,20 +2575,20 @@ one of the following forms: --align (in kB) The '--align' option is a mic-specific option that says to start a partition on an x kB boundary. - - -
+ + +
-
- Command: bootloader +
+ Command: bootloader - - This command specifies how the boot loader should be installed. - + + This command specifies how the boot loader should be installed. + - - Following are the supported options: - + + Following are the supported options: + --timeout Specify the number of seconds before the bootloader times out and boots the default option. @@ -2631,8 +2609,9 @@ one of the following forms: Future updates will implement more options - using anything not explicitly supported can result in unpredictable results. - - + + +
-- cgit v1.2.3-54-g00ecf