dev-manual: Created new chapter on QEMU.

Fixes [YOCTO #641]

New chapter added that covers the YP instance of QEMU.

(From yocto-docs rev: 7ca17d02364af7e5924e23df6c138ab4dd2203d6)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

2 files changed, 313 insertions, 21 deletions

diff --git a/documentation/dev-manual/dev-manual-qemu.xml b/documentation/dev-manual/dev-manual-qemu.xml
index 17bbc2774a..d206c111ed 100644
--- a/documentation/dev-manual/dev-manual-qemu.xml
+++ b/documentation/dev-manual/dev-manual-qemu.xml
@@ -4,13 +4,13 @@
 
 <chapter id='dev-manual-qemu'>
 
-<title>Using the Quick EMUlator</title>
+<title>Using the Quick EMUlator (QEMU)</title>
 
 <para>
     Quick EMUlator (QEMU) is an Open Source project the Yocto Project uses
-    as part of its development "toolset".
+    as part of its development "tool set".
     As such, the information in this chapter is limited to the
-    Yocto Project instatiation of QEMU and not QEMU in general.
+    Yocto Project integration of QEMU and not QEMU in general.
     For official information and documentation on QEMU, see the
     following references:
     <itemizedlist>
@@ -24,9 +24,10 @@
 </para>
 
 <para>
-    This chapter provides an overview of the Yocto Project instantiation of
-    QEMU, a description of how you use QEMU and its various options and modes,
-    and a few tips and tricks you might find helpful when using QEMU.
+    This chapter provides an overview of the Yocto Project's integration of
+    QEMU, a description of how you use QEMU and its various options, running
+    under a Network File System (NFS) server, and a few tips and tricks you
+    might find helpful when using QEMU.
 </para>
 
 <section id='qemu-overview'>
@@ -39,6 +40,9 @@
         on your build system.
         QEMU is useful for running and testing images and applications on
         supported Yocto Project architectures without having actual hardware.
+        Among other things, the Yocto Project uses QEMU to run automated
+        Quality Assurance (QA) tests on final images shipped with each
+        release.
     </para>
 
     <para>
@@ -80,11 +84,14 @@
             The basic <filename>runqemu</filename> command syntax is as
             follows:
             <literallayout class='monospaced'>
-     $ runqemu [<replaceable>option</replaceable> ]  [<replaceable>option</replaceable> ] [...]
+     $ runqemu [<replaceable>option</replaceable> ]  [...]
             </literallayout>
-            <filename>runqemu</filename> does a good job based on what you
-            provide with the command at figuring out what you are trying
-            to do.
+            Based on what you provide on the command line,
+            <filename>runqemu</filename> does a good job of figuring out what
+            you are trying to do.
+            For example, by default, QEMU looks for the most recently built
+            image according to the timestamp when it needs to look for an
+            image.
             Minimally, through the use of options, you must provide either
             a machine name, a virtual machine image
             (<filename>*.vmdk</filename>), or a kernel image
@@ -92,35 +99,318 @@
         </para>
 
         <para>
-            If you do provide some "illegal" combination or options or perhaps
-            do not provide enough in the way of options,
-            <filename>runqemu</filename> provides appropriate error messaging
-            to help you figure it out.
-        </para>
-
-        <para>
             Following is a description of <filename>runqemu</filename>
             options you can provide on the command line:
+            <note><title>Tip</title>
+                If you do provide some "illegal" option combination or perhaps
+                you do not provide enough in the way of options,
+                <filename>runqemu</filename> provides appropriate error
+                messaging to help you correct the problem.
+            </note>
             <itemizedlist>
-                <listitem><para><emphasis><replaceable>QEMUARCH</replaceable>:</emphasis>
-                    The QEMU machine architecture, which can be "qemux86",
+                <listitem><para><replaceable>QEMUARCH</replaceable>:
+                    The QEMU machine architecture, which must be "qemux86",
                     "qemux86-64", "qemuarm", "qemumips", "qemumipsel",
                     “qemumips64", "qemush4", "qemuppc", "qemumicroblaze",
                     or "qemuzynq".
                     </para></listitem>
+                <listitem><para><filename><replaceable>VM</replaceable></filename>:
+                    The virtual machine image, which must be a
+                    <filename>.vmdk</filename> file.
+                    Use this option when you want to boot a
+                    <filename>.vmdk</filename> image.
+                    The image filename you provide must contain one of the
+                    following strings: "qemux86-64", "qemux86", "qemuarm",
+                    "qemumips64", "qemumips", "qemuppc", or "qemush4".
+                    </para></listitem>
+                <listitem><para><replaceable>ROOTFS</replaceable>:
+                    A root filesystem that has one of the following
+                    filetype extensions: "ext2", "ext3", "ext4", "jffs2",
+                    "nfs", or "btrfs".
+                    If the filename you provide for this option uses “nfs”, it
+                    must provide an explicit root filesystem path.
+                    </para></listitem>
+                <listitem><para><replaceable>KERNEL</replaceable>:
+                    A kernel image, which is a <filename>.bin</filename> file.
+                    When you provide a <filename>.bin</filename> file,
+                    <filename>runqemu</filename> detects it and assumes the
+                    file is a kernel image.
+                    </para></listitem>
+                <listitem><para><replaceable>MACHINE</replaceable>:
+                    The architecture of the QEMU machine, which must be one
+                    of the following: "qemux86",
+                    "qemux86-64", "qemuarm", "qemumips", "qemumipsel",
+                    “qemumips64", "qemush4", "qemuppc", "qemumicroblaze",
+                    or "qemuzynq".
+                    The <replaceable>MACHINE</replaceable> and
+                    <replaceable>QEMUARCH</replaceable> options are basically
+                    identical.
+                    If you do not provide a <replaceable>MACHINE</replaceable>
+                    option, <filename>runqemu</filename> tries to determine
+                    it based on other options.
+                    </para></listitem>
+                <listitem><para><filename>ramfs</filename>:
+                    Indicates you are booting an initial RAM disk (initramfs)
+                    image, which means the <filename>FSTYPE</filename> is
+                    <filename>cpio.gz</filename>.
+                    </para></listitem>
+                <listitem><para><filename>iso</filename>:
+                    Indicates you are booting an ISO image, which means the
+                    <filename>FSTYPE</filename> is
+                    <filename>.iso</filename>.
+                    </para></listitem>
+                <listitem><para><filename>nographic</filename>:
+                    Disables the video console, which sets the console to
+                    "ttys0".
+                    </para></listitem>
+                <listitem><para><filename>serial</filename>:
+                    Enables a serial console on
+                    <filename>/dev/ttyS0</filename>.
+                    </para></listitem>
+                <listitem><para><filename>biosdir</filename>:
+                    Establishes a custom directory for BIOS, VGA BIOS and
+                    keymaps.
+                    </para></listitem>
+                <listitem><para><filename>qemuparams=\"<replaceable>xyz</replaceable>\"</filename>:
+                    Specifies custom QEMU parameters.
+                    Use this option to pass options other than the simple
+                    "kvm" and "serial" options.
+                    </para></listitem>
+                <listitem><para><filename>bootparams=\"<replaceable>xyz</replaceable>\"</filename>:
+                    Specifies custom boot parameters for the kernel.
+                    </para></listitem>
+                <listitem><para><filename>audio</filename>:
+                    Enables audio in QEMU.
+                    The <replaceable>MACHINE</replaceable> option must be
+                    either "qemux86" or "qemux86-64" in order for audio to be
+                    enabled.
+                    Additionally, the <filename>snd_intel8x0</filename>
+                    or <filename>snd_ens1370</filename> driver must be
+                    installed in linux guest.
+                    </para></listitem>
+                <listitem><para><filename>slirp</filename>:
+                    Enables "slirp" networking, which is a different way
+                    of networking that does not need root access
+                    but also is not as easy to use or comprehensive
+                    as the default.
+                    </para></listitem>
+                <listitem><para><filename>kvm</filename>:
+                    Enables KVM when running "qemux86" or "qemux86-64"
+                    QEMU architectures.
+                    For KVM to work, all the following conditions must be met:
+                    <itemizedlist>
+                        <listitem><para>
+                            Your <replaceable>MACHINE</replaceable> must be either
+                            "qemux86" or "qemux86-64".
+                            </para></listitem>
+                        <listitem><para>
+                            Your build host has to have the KVM modules
+                            installed, which are
+                            <filename>/dev/kvm</filename>.
+                            </para></listitem>
+                        <listitem><para>
+                            Your build host has to have virtio net device, which
+                            are <filename>/dev/vhost-net</filename>.
+                            </para></listitem>
+                        <listitem><para>
+                            The  build host <filename>/dev/kvm</filename>
+                            directory has to be both writable and readable.
+                            </para></listitem>
+                        <listitem><para>
+                            The build host <filename>/dev/vhost-net</filename>
+                            directory has to be either readable or writable
+                            and “slirp-enabled”.
+                            </para></listitem>
+                    </itemizedlist>
+                    </para></listitem>
+                <listitem><para><filename>publicvnc</filename>:
+                    Enables a VNC server open to all hosts.
+                    </para></listitem>
             </itemizedlist>
         </para>
+
+        <para>
+            For further understanding regarding option use with
+            <filename>runqemu</filename>, consider some examples.
+        </para>
+
+        <para>
+            This example starts QEMU with
+            <replaceable>MACHINE</replaceable> set to "qemux86".
+            Assuming a standard
+            <link linkend='build-directory'>Build Directory</link>,
+            <filename>runqemu</filename> automatically finds the
+            <filename>bzImage-qemux86.bin</filename> image file and
+            the
+            <filename>core-image-minimal-qemux86-20140707074611.rootfs.ext3</filename>
+            (assuming the current build created a
+            <filename>core-image-minimal</filename> image).
+            <note>
+                When more than one image with the same name exists, QEMU finds
+                and uses the most recently built image according to the
+                timestamp.
+            </note>
+            <literallayout class='monospaced'>
+    $ runqemu qemux86
+            </literallayout>
+            This example produces the exact same results as the
+            previous example.
+            This command, however, specifically provides the image
+            and root filesystem type.
+            <literallayout class='monospaced'>
+     $ runqemu qemux86 core-image-minimal ext3
+            </literallayout>
+            This example specifies to boot an initial RAM disk image
+            and to enable audio in QEMU.
+            For this case, <filename>runqemu</filename> set the
+            internal variable <filename>FSTYPE</filename> to
+            "cpio.gz".
+            Also, for audio to be enabled, an appropriate driver must
+            be installed (see the previous description for the
+            <filename>audio</filename> option for more information).
+            <literallayout class='monospaced'>
+     $ runqemu qemux86 ramfs audio
+            </literallayout>
+            This example does not provide enough information for
+            QEMU to launch.
+            While the command does provide a root filesystem type, it
+            must also minimally provide a
+            <replaceable>MACHINE</replaceable>,
+            <replaceable>KERNEL</replaceable>, or
+            <replaceable>VM</replaceable> option.
+            <literallayout class='monospaced'>
+     $ runqemu ext3
+            </literallayout>
+            This example specifies to boot a virtual machine image
+            (<filename>.vmdk</filename> file).
+            From the <filename>.vmdk</filename>,
+            <filename>runqemu</filename> determines the QEMU
+            architecture (<replaceable>MACHINE</replaceable>) to be
+            "qemux86" and the root filesystem type to be "vmdk".
+            <literallayout class='monospaced'>
+     $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86.vmdk
+            </literallayout>
+        </para>
     </section>
 </section>
 
-<section id='qemu-modes'>
-    <title>Modes</title>
+<section id='qemu-running-under-a-network-file-system-nfs-server'>
+    <title>Running Under a Network File System (NFS) Server</title>
+
+    <para>
+        One method for running QEMU is to run it on an NFS server.
+        This is useful when you need to access the same file system from both
+        the build and the emulated system at the same time.
+        It is also worth noting that the system does not need root privileges
+        to run.
+        It uses a user space NFS server to avoid that.
+        This section describes how to set up for running QEMU using an NFS
+        server and then how you can start and stop the server.
+    </para>
+
+    <section id='qemu-setting-up-to-use-nfs'>
+        <title>Setting Up to Use NFS</title>
+
+        <para>
+            Once you are able to run QEMU in your environment, you can use the
+            <filename>runqemu-extract-sdk</filename> script, which is located
+            in the <filename>scripts</filename> directory along with
+            <filename>runqemu</filename> script.
+            The <filename>runqemu-extract-sdk</filename> takes a root
+            file system tarball and extracts it into a location that you
+            specify.
+            Then, when you run <filename>runqemu</filename>, you can specify
+            the location that has the file system to pass it to QEMU.
+            Here is an example that takes a file system and extracts it to
+            a directory named <filename>test-nfs</filename>:
+            <literallayout class='monospaced'>
+     runqemu-extract-sdk ./tmp/deploy/images/qemux86/core-image-sato-qemux86.tar.bz2 test-nfs
+            </literallayout>
+            Once you have extracted the file system, you can run
+            <filename>runqemu</filename> normally with the additional
+            location of the file system.
+            You can then also make changes to the files within
+            <filename>./test-nfs</filename> and see those changes appear in the
+            image in real time.
+            Here is an example using the <filename>qemux86</filename> image:
+            <literallayout class='monospaced'>
+     runqemu qemux86 ./test-nfs
+            </literallayout>
+        </para>
+    </section>
+
+    <section id='qemu-starting-and-stopping-nfs'>
+        <title>Starting and Stopping NFS</title>
 
+        <para>
+            You can manually start and stop the NFS share using these
+            commands:
+            <itemizedlist>
+                <listitem><para><emphasis><filename>start</filename>:</emphasis>
+                    Starts the NFS share:
+                    <literallayout class='monospaced'>
+     runqemu-export-rootfs start &lt;<replaceable>file-system-location</replaceable>&gt;
+                    </literallayout>
+                    </para></listitem>
+                <listitem><para><emphasis><filename>stop</filename>:</emphasis>
+                    Stops the NFS share:
+                    <literallayout class='monospaced'>
+     runqemu-export-rootfs stop &lt;<replaceable>file-system-location</replaceable>&gt;
+                    </literallayout>
+                    </para></listitem>
+                <listitem><para><emphasis><filename>restart</filename>:</emphasis>
+                    Restarts the NFS share:
+                    <literallayout class='monospaced'>
+     runqemu-export-rootfs restart &lt;<replaceable>file-system-location</replaceable>&gt;
+                    </literallayout>
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
 </section>
 
 <section id='qemu-tips-and-tricks'>
     <title>Tips and Tricks</title>
 
+    <para>
+        The following list describes things you can do to make running QEMU
+        in the context of the Yocto Project a better experience:
+        <itemizedlist>
+            <listitem><para><emphasis>Switching Between Consoles:</emphasis>
+                When booting or running QEMU, you can switch between
+                supported consoles by using
+                Ctrl+Alt+&lt;<replaceable>number</replaceable>&gt;.
+                For example, Ctrl+Alt+3 switches you to the serial console as
+                long as that console is enabled.
+                Being able to switch consoles is helpful, for example, if the
+                main QEMU console breaks for some reason.
+                <note>
+                    Usually, "2" gets you to the main console and "3" gets you
+                    to the serial console.
+                </note>
+                </para></listitem>
+            <listitem><para><emphasis>Removing the Splash Screen:</emphasis>
+                You can remove the splash screen when QEMU is booting by
+                using Alt+left.
+                Removing the splash screen allows you to see what is happening
+                in the background.
+                </para></listitem>
+            <listitem><para><emphasis>Disabling the Cursor Grab:</emphasis>
+                The default QEMU integration captures the cursor within the
+                main window.
+                It does this since standard mouse devices only provide relative
+                input and not absolute coordinates.
+                You then have to break out of the grab using the "Ctrl+Alt" key
+                combination.
+                However, the Yocto Project's integration of QEMU enables the
+                wacom USB touch pad driver by default to allow input of absolute
+                coordinates.
+                This default means that the mouse can enter and leave the
+                main window without the grab taking effect leading to a better
+                user experience.
+                </para></listitem>
+        </itemizedlist>
+    </para>
 </section>
 
 </chapter>
diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml
index b89e2b357e..d7e3177af8 100644
--- a/documentation/dev-manual/dev-manual.xml
+++ b/documentation/dev-manual/dev-manual.xml
@@ -106,6 +106,8 @@
 
     <xi:include href="dev-manual-common-tasks.xml"/>
 
+    <xi:include href="dev-manual-qemu.xml"/>
+
 </book>
 <!--
 vim: expandtab tw=80 ts=4