sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

dev-manual: Complete first draft of the new wic section. 

(From yocto-docs rev: 4bd0f5db0e0d8a2c3d28f415afaf92fed93102f0)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2013-11-14 10:39:45 -08:00 committed by Richard Purdie
parent b0c4c855a0
commit acd3784933
1 changed files with 185 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

337
documentation/dev-manual/dev-manual-common-tasks.xml
View File

@ -2008,13 +2008,13 @@ any arguments to get started).
</para> </para>
<note> <note>
Just because 'wic' can generate an image doesn't mean that it Just because 'wic' can generate an image does not mean that it
will boot on a given machine. 'wic' tries to spot the most obvious will boot on a given machine. 'wic' tries to spot the most obvious
usages that are likely to cause problems but, as a relatively usages that are likely to cause problems but, as a relatively
low-level tool, it can't in general figure out whether a generated low-level tool, it can't in general figure out whether a generated
image is appropriate for a given piece of hardware - it's really up to image is appropriate for a given piece of hardware - it's really up to
you to provide intelligent inputs to the image creation process. If you to provide intelligent inputs to the image creation process. If
you suspect that your image isn't working as expected due to some bug you suspect that your image is not working as expected due to some bug
or missing feature of the tool, please file a bug report describing or missing feature of the tool, please file a bug report describing
the details. the details.
</note> </note>
@ -2180,7 +2180,7 @@ the details.
$ wic create &lt;kickstart_file&gt; -e &lt;image_name&gt; $ wic create &lt;kickstart_file&gt; -e &lt;image_name&gt;
</literallayout> </literallayout>
This form is the simplest and most user-friendly, as it This form is the simplest and most user-friendly, as it
does not requre specifying all individual parameters. does not require specifying all individual parameters.
All you need to provide is your own All you need to provide is your own
<filename>.wks</filename> file or one provided with the <filename>.wks</filename> file or one provided with the
release. release.
@ -2224,6 +2224,25 @@ the details.
-k &lt;kernel_dir&gt; -n &lt;native_sysroot&gt; -k &lt;kernel_dir&gt; -n &lt;native_sysroot&gt;
</literallayout> </literallayout>
</para> </para>
<para>
Here are the actual partition language commands
used in the <filename>mkefidisk.wks</filename> file to generate
an image:
<literallayout class='monospaced'>
# 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 --ondisk sda --fstype=efi --label msdos --active --align 1024
part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024
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"
</literallayout>
</para>
</section> </section>
<section id='wic-usage-examples'> <section id='wic-usage-examples'>
@ -2267,10 +2286,10 @@ the details.
</literallayout> </literallayout>
This example shows the easiest way to create an image This example shows the easiest way to create an image
by running in Cooked Mode and using the by running in Cooked Mode and using the
<filename>&lt;-e&gt;</filename> option with a <filename>-e</filename> option with a provided kickstart
provided kickstart file. file.
All that is necessary is to specify the image All that is necessary is to specify the image used to
used to generate the artifacts. generate the artifacts.
Your <filename>local.conf</filename> needs to have the Your <filename>local.conf</filename> needs to have the
<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
variable set to the machine you are using, which is variable set to the machine you are using, which is
@ -2278,14 +2297,14 @@ the details.
</para> </para>
<para> <para>
The output specifies exactly which image were The output specifies exactly which image was
created and where the image was created. created as well as where it was created.
The output also names the artifacts used and the exact The output also names the artifacts used and the exact
<filename>.wks</filename> script that was used to generate <filename>.wks</filename> script that was used to generate
the image. the image.
<note> <note>
You should always verify the details provided in the You should always verify the details provided in the
output to make sure that the imagewas indeed created output to make sure that the image was indeed created
exactly as expected. exactly as expected.
</note> </note>
</para> </para>
@ -2311,7 +2330,7 @@ the details.
<para> <para>
Because <filename>wic</filename> image creation is driven Because <filename>wic</filename> image creation is driven
by the kickstart file, it is easy to drive image creation by the kickstart file, it is easy to affect image creation
by changing the parameters in the file. by changing the parameters in the file.
This next example demonstrates that through modification This next example demonstrates that through modification
of the <filename>directdisk</filename> kickstart file. of the <filename>directdisk</filename> kickstart file.
@ -2321,9 +2340,10 @@ the details.
As mentioned earlier, you can use the command As mentioned earlier, you can use the command
<filename>wic list images</filename> to show the list <filename>wic list images</filename> to show the list
of provided kickstart files. of provided kickstart files.
The directory in which these files reside is in the The directory in which these files reside is
<link linkend='source-directory'>Source Directory</link> <filename>scripts/lib/image/canned-wks/</filename>
in <filename>scripts/lib/image/canned-wks/</filename>. located in the
<link linkend='source-directory'>Source Directory</link>.
Because the available files reside in this directory, you Because the available files reside in this directory, you
can create and add your own custom files to the directory. can create and add your own custom files to the directory.
Subsequent use of the <filename>wic list images</filename> Subsequent use of the <filename>wic list images</filename>
@ -2359,22 +2379,13 @@ the details.
part /boot --source bootimg --ondisk sdb --fstype=msdos --label boot --active --align 1024 part /boot --source bootimg --ondisk sdb --fstype=msdos --label boot --active --align 1024
part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
</literallayout> </literallayout>
(I AM HERE) Once the lines are changed, the example generates the
Once the lines are changed, Once we've made that change, we generate a directdisksdb image, <filename>directdisksdb</filename> image.
pointing the process at the core-image-minimal artifacts for the nuc The command points the process at the
(Next Unit of Computing), selected as our current MACHINE in <filename>core-image-minimal</filename> artifacts for the
local.conf. Next Unit of Computing (nuc)
</para> <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
the <filename>local.conf</filename>.
<para>
Once we've set the build up, we run a core-image-minimal nuc build:
<literallayout class='monospaced'>
$ bitbake core-image-minimal
</literallayout>
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:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ wic create directdisksdb -e core-image-minimal $ wic create directdisksdb -e core-image-minimal
Checking basic build environment... Checking basic build environment...
@ -2395,9 +2406,10 @@ generate the image:
The image(s) were created using OE kickstart file: The image(s) were created using OE kickstart file:
/home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks
</literallayout> </literallayout>
Using the path specified in the output for the image name and Continuing with the example, you can now directly
location, you can now directly dd the image to a USB stick or whatever <filename>dd</filename> the image to a USB stick, or
media you built the image for, and boot the resulting media: whatever media for which you built your image,
and boot the resulting media:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb $ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb
86018+0 records in 86018+0 records in
@ -2405,13 +2417,18 @@ media you built the image for, and boot the resulting media:
44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s 44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s
[trz@empanada tmp]$ sudo eject /dev/sdb [trz@empanada tmp]$ sudo eject /dev/sdb
</literallayout> </literallayout>
Of course, you can just use the directdisk image directly if you don't
have any special needs.
</para> </para>
</section>
<section id='creating-an-image-based-on-core-image-minimal-and-crownbay-noemgd'>
<title>Creating an Image Based on <filename>core-image-minimal</filename> and <filename>crownbay-noemgd</filename></title>
<para> <para>
Here'we're creating a wic image based on core-image-minimal and This example creates an image based on
crownbay-noemgd, which works right out of the box. <filename>core-image-minimal</filename> and a
<filename>crownbay-noemgd</filename>
<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
that works right out of the box.
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ wic create directdisk -e core-image-minimal $ wic create directdisk -e core-image-minimal
@ -2433,10 +2450,19 @@ crownbay-noemgd, which works right out of the box.
The image(s) were created using OE kickstart file: The image(s) were created using OE kickstart file:
/home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks
</literallayout> </literallayout>
Finally, here's an example that doesn't take the easy way out and </para>
manually specifies each build artifact, along with a non-canned .wks </section>
file, and also uses the -o option to have wic create the output
somewhere other than the default /var/tmp/wic: <section id='using-a-modified-kickstart-file-and-running-in-raw-mode'>
<title>Using a Modified Kickstart File and Running in Raw Mode</title>
<para>
This next example manually specifies each build artifact
(runs in Raw Mode) and uses a modified kickstart file.
The example also uses the <filename>-o</filename> option
to cause <filename>wic</filename> to create the output
somewhere other than the default
<filename>/var/tmp/wic</filename> directory:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ 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 $ 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
@ -2455,28 +2481,11 @@ somewhere other than the default /var/tmp/wic:
The image(s) were created using OE kickstart file: The image(s) were created using OE kickstart file:
/home/trz/test.wks /home/trz/test.wks
</literallayout> </literallayout>
In this case, we didn't need to have the proper machine selected in For this example,
local.conf - we manually specified each artifact and therefore wic <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
doesn't need further information from the build system. did not have to be specified in the
</para> <filename>local.conf</filename> file since the artifact is
manually specified.
<para>
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:
<literallayout class='monospaced'>
# 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 --ondisk sda --fstype=efi --label msdos --active --align 1024
part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024
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"
</literallayout>
</para> </para>
</section> </section>
</section> </section>
@ -2485,16 +2494,18 @@ mkefidisk.wks OE kickstart file:
<title>OpenEmbedded Kickstart (.wks) Reference</title> <title>OpenEmbedded Kickstart (.wks) Reference</title>
<para> <para>
The current 'wic' implementation supports only the basic kickstart The current <filename>wic</filename> implementation supports
partitioning commands: 'partition' (or 'part' for short) and only the basic kickstart partitioning commands:
'bootloader'. <filename>partition</filename> (or <filename>part</filename>
for short) and <filename>bootloader</filename>.
</para> </para>
<para> <para>
They are listed below and mostly follow the syntax and meaning of the Following is a listing of the commands, their syntax, and
standard kickstart options for those commands. The documentation below meanings.
is based on the Fedora kickstart documentation of the same commands, The commands are based on the Fedora kickstart documentation
but modified to reflect wic capabilities. For reference: but with modifications to reflect <filename>wic</filename>
capabilities.
<literallayout class='monospaced'> <literallayout class='monospaced'>
http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition
http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader
@ -2505,13 +2516,14 @@ but modified to reflect wic capabilities. For reference:
<title>Command: part or partition</title> <title>Command: part or partition</title>
<para> <para>
Creates a partition on the system. This command creates a partition on the system and uses the
Use the following syntax: following syntax:
<literallayout class='monospaced'> <literallayout class='monospaced'>
part &lt;mntpoint&gt; part &lt;mntpoint&gt;
</literallayout> </literallayout>
The &lt;mntpoint&gt; is where the partition will be mounted and must be of The <filename>&lt;mntpoint&gt;</filename> is where the
one of the following forms: partition will be mounted and must be of one of the
following forms:
<itemizedlist> <itemizedlist>
<listitem><para><filename>/&lt;path&gt;</filename>: <listitem><para><filename>/&lt;path&gt;</filename>:
For example, <filename>/</filename>, For example, <filename>/</filename>,
@ -2525,57 +2537,75 @@ one of the following forms:
<para> <para>
Following are the supported options: Following are the supported options:
<literallayout class='monospaced'> <itemizedlist>
--size <listitem><para><emphasis><filename>--size</filename>:</emphasis>
The minimum partition size in megabytes. Specify an integer value The minimum partition size in MBytes.
here such as 500. Do not append the number with MB. Not needed if Specify an integer value such as 500.
--source is used. Do not append the number with "MB".
You do not need this option if you use
--source <filename>--source</filename>.</para></listitem>
bootimg <listitem><para><emphasis><filename>--source</filename>:</emphasis>
rootfs This option is a wic-specific option that can
currently have one of two values, "bootimg" or
The --source option is a wic-specific option that can currently "rootfs".</para>
have one of two values, 'bootimg' or 'rootfs'. <para>If <filename>--source rootfs</filename> is
used, it tells the <filename>wic</filename> command
If '--source rootfs' is used, it tells the wic command to create a to create a partition as large as needed to fill
partition as large as needed to fill with the contents of /rootfs with the contents of the root filesystem
(specified by the -r 'wic' option) and to fill it with the (specified by the <filename>-r</filename>
contents of /rootfs. <filename>wic</filename> option) and to fill it
with the contents of <filename>/rootfs</filename>.
If '--source bootimg' is used, it tells the wic command to create </para>
a partition as large as needed to fill with the contents of the <para>If <filename>--source bootimg</filename>
boot partition (specified by the -b 'wic' option). Exactly what is used, it tells the <filename>wic</filename>
those contents are depend on the value of the --fstype option for command to create a partition as large as needed to
that partition. If '--fstype=efi' is specified, the boot fill with the contents of the boot partition
artifacts contained in HDDDIR are used, and if '--fstype=msdos' is (specified by the <filename>-b</filename>
specified, the boot artifacts found in STAGING_DATADIR are used. <filename>wic</filename> option).
Exactly what those contents are depend on the value
--ondisk or --ondrive of the <filename>--fstype</filename> option for
Forces the partition to be created on a particular disk. that partition.
If <filename>--fstype=efi</filename> is specified,
--fstype the boot artifacts contained in HDDDIR are used,
Sets the file system type for the partition. Valid values are: and if <filename>--fstype=msdos</filename> is
msdos specified, the boot artifacts found in
efi <filename>STAGING_DATADIR</filename> are used.
ext4 </para></listitem>
ext3 <listitem><para><emphasis><filename>--ondisk</filename> or <filename>--ondrive</filename>:</emphasis>
ext2 Forces the partition to be created on a particular
btrfs disk.</para></listitem>
swap <listitem><para><emphasis><filename>--fstype</filename>:</emphasis>
Sets the file system type for the partition.
--label label Valid values are:
Specify the label to give to the filesystem to be made on the <itemizedlist>
partition. If the given label is already in use by another <listitem><para><filename>msdos</filename>
filesystem, a new label will be created for this partition. </para></listitem>
<listitem><para><filename>efi</filename>
--active </para></listitem>
Mark the partition as active. <listitem><para><filename>ext4</filename>
</para></listitem>
--align (in kB) <listitem><para><filename>ext3</filename>
The '--align' option is a mic-specific option that says to start a </para></listitem>
partition on an x kB boundary. <listitem><para><filename>ext2</filename>
</literallayout> </para></listitem>
<listitem><para><filename>btrfs</filename>
</para></listitem>
<listitem><para><filename>swap</filename>
</para></listitem>
</itemizedlist></para></listitem>
<listitem><para><emphasis><filename>--label label</filename>:</emphasis>
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.</para></listitem>
<listitem><para><emphasis><filename>--active</filename>:</emphasis>
Marks the partition as active.</para></listitem>
<listitem><para><emphasis><filename>--align (in KBytes)</filename>:</emphasis>
This option is specific to the Meego Image
Creator (mic) that says to start a partition on an
x KBytes boundary.</para></listitem>
</itemizedlist>
</para> </para>
</section> </section>
@ -2583,33 +2613,36 @@ one of the following forms:
<title>Command: bootloader</title> <title>Command: bootloader</title>
<para> <para>
This command specifies how the boot loader should be installed. This command specifies how the boot loader should be
</para> and supports the following options:
<itemizedlist>
<para> <listitem><para><emphasis><filename>--timeout</filename>:</emphasis>
Following are the supported options: Specifies the number of seconds before the
<literallayout class='monospaced'> bootloader times out and boots the default option.
--timeout </para></listitem>
Specify the number of seconds before the bootloader times out and <listitem><para><emphasis><filename>--append</filename>:</emphasis>
boots the default option. Specifies kernel parameters.
These will be added to the syslinux
--append <filename>APPEND</filename> or
Specifies kernel parameters. These will be added to the syslinux <filename>grub</filename> kernel command line.
APPEND or grub kernel command line. </para>
<para>The boot type is determined by the fstype of
The boot type is determined by the fstype of the /boot mountpoint. If the <filename>/boot</filename> mountpoint.
the fstype is 'msdos' the boot type is 'pcbios', otherwise it's the If the fstype is "msdos" the boot type is
fstype, which currently be: 'efi' (more to be added later). "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 </para>
menuentry: 'boot'. <para>If the boot type is "efi", the image will
use <filename>grub</filename> and has one
If the boot type is 'pcbios', the image will use syslinux and has one menuentry: "boot".</para>
menu label: 'boot'. <para>If the boot type is "pcbios", the image
will use syslinux and has one menu label: "boot".
Future updates will implement more options - using anything not </para>
explicitly supported can result in unpredictable results. <para>Future updates will implement more options.
</literallayout> If you use anything that is not specifically
supported, results can be unpredictable.
</para></listitem>
</itemizedlist>
</para> </para>
</section> </section>
</section> </section>