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 core-image-minimal and crownbay-noemgd
+
+
+ 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