import-layers/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml - openbmc/openbmc - Gitiles

 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >

 <chapter id='dev-manual-qemu'>

 <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 "tool set".
     As such, the information in this chapter is limited to the
     Yocto Project integration of QEMU and not QEMU in general.
     For official information and documentation on QEMU, see the
     following references:
     <itemizedlist>
         <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Main_Page'>QEMU Website</ulink>:</emphasis>
             The official website for the QEMU Open Source project.
             </para></listitem>
         <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Manual'>Documentation</ulink>:</emphasis>
             The QEMU user manual.
             </para></listitem>
     </itemizedlist>
 </para>

 <para>
     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'>
     <title>Overview</title>

     <para>
         Within the context of the Yocto Project, QEMU is an
         emulator and virtualization machine that allows you to run a complete
         image you have built using the Yocto Project as just another task
         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>
         QEMU is made available with the Yocto Project a number of ways.
         One method is to install a Software Development Kit (SDK).
         For more information on how to make sure you have
         QEMU available, see the
         <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.
     </para>
 </section>

 <section id='qemu-running-qemu'>
     <title>Running QEMU</title>

     <para>
         Running QEMU involves having your build environment set up, having the
         right artifacts available, and understanding how to use the many
         options that are available to you when you start QEMU using the
         <filename>runqemu</filename> command.
     </para>

     <section id='qemu-setting-up-the-environment'>
         <title>Setting Up the Environment</title>

         <para>
             You run QEMU in the same environment from which you run BitBake.
             This means you need to source a build environment script (i.e.
             <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
             or
             <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
         </para>
     </section>

     <section id='qemu-using-the-runqemu-command'>
         <title>Using the <filename>runqemu</filename> Command</title>

         <para>
             The basic <filename>runqemu</filename> command syntax is as
             follows:
             <literallayout class='monospaced'>
      $ runqemu [<replaceable>option</replaceable> ]  [...]
             </literallayout>
             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
             (<filename>*.bin</filename>).
         </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><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>biosfilename</filename>:
                     Establishes a custom BIOS name.
                     </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 id='kvm-cond'><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>
                             The  build host <filename>/dev/kvm</filename>
                             directory has to be both writable and readable.
                             </para></listitem>
                     </itemizedlist>
                     </para></listitem>
                 <listitem><para><filename>kvm-vhost</filename>:
                     Enables KVM with VHOST support when running "qemux86" or "qemux86-64"
                     QEMU architectures.
                     For KVM with VHOST to work, the following conditions must
                     be met:
                     <itemizedlist>
                         <listitem><para>
                             <link linkend='kvm-cond'>kvm</link> option
                             conditions must be met.
                             </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/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-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 <replaceable>file-system-location</replaceable>
                     </literallayout>
                     </para></listitem>
                 <listitem><para><emphasis><filename>stop</filename>:</emphasis>
                     Stops the NFS share:
                     <literallayout class='monospaced'>
      runqemu-export-rootfs stop <replaceable>file-system-location</replaceable>
                     </literallayout>
                     </para></listitem>
                 <listitem><para><emphasis><filename>restart</filename>:</emphasis>
                     Restarts the NFS share:
                     <literallayout class='monospaced'>
      runqemu-export-rootfs restart <replaceable>file-system-location</replaceable>
                     </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+<replaceable>number</replaceable>.
                 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>
 <!--
 vim: expandtab tw=80 ts=4
 -->
	<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
	[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >

	<chapter id='dev-manual-qemu'>

	<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 "tool set".
	As such, the information in this chapter is limited to the
	Yocto Project integration of QEMU and not QEMU in general.
	For official information and documentation on QEMU, see the
	following references:
	<itemizedlist>
	<listitem><para><emphasis><ulink url='http://wiki.qemu.org/Main_Page'>QEMU Website</ulink>:</emphasis>
	The official website for the QEMU Open Source project.
	</para></listitem>
	<listitem><para><emphasis><ulink url='http://wiki.qemu.org/Manual'>Documentation</ulink>:</emphasis>
	The QEMU user manual.
	</para></listitem>
	</itemizedlist>
	</para>

	<para>
	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'>
	<title>Overview</title>

	<para>
	Within the context of the Yocto Project, QEMU is an
	emulator and virtualization machine that allows you to run a complete
	image you have built using the Yocto Project as just another task
	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>
	QEMU is made available with the Yocto Project a number of ways.
	One method is to install a Software Development Kit (SDK).
	For more information on how to make sure you have
	QEMU available, see the
	<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.
	</para>
	</section>

	<section id='qemu-running-qemu'>
	<title>Running QEMU</title>

	<para>
	Running QEMU involves having your build environment set up, having the
	right artifacts available, and understanding how to use the many
	options that are available to you when you start QEMU using the
	<filename>runqemu</filename> command.
	</para>

	<section id='qemu-setting-up-the-environment'>
	<title>Setting Up the Environment</title>

	<para>
	You run QEMU in the same environment from which you run BitBake.
	This means you need to source a build environment script (i.e.
	<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
	or
	<ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
	</para>
	</section>

	<section id='qemu-using-the-runqemu-command'>
	<title>Using the <filename>runqemu</filename> Command</title>

	<para>
	The basic <filename>runqemu</filename> command syntax is as
	follows:
	<literallayout class='monospaced'>
	$ runqemu [<replaceable>option</replaceable> ] [...]
	</literallayout>
	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
	(<filename>*.bin</filename>).
	</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><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>biosfilename</filename>:
	Establishes a custom BIOS name.
	</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 id='kvm-cond'><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>
	The build host <filename>/dev/kvm</filename>
	directory has to be both writable and readable.
	</para></listitem>
	</itemizedlist>
	</para></listitem>
	<listitem><para><filename>kvm-vhost</filename>:
	Enables KVM with VHOST support when running "qemux86" or "qemux86-64"
	QEMU architectures.
	For KVM with VHOST to work, the following conditions must
	be met:
	<itemizedlist>
	<listitem><para>
	<link linkend='kvm-cond'>kvm</link> option
	conditions must be met.
	</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/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-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 <replaceable>file-system-location</replaceable>
	</literallayout>
	</para></listitem>
	<listitem><para><emphasis><filename>stop</filename>:</emphasis>
	Stops the NFS share:
	<literallayout class='monospaced'>
	runqemu-export-rootfs stop <replaceable>file-system-location</replaceable>
	</literallayout>
	</para></listitem>
	<listitem><para><emphasis><filename>restart</filename>:</emphasis>
	Restarts the NFS share:
	<literallayout class='monospaced'>
	runqemu-export-rootfs restart <replaceable>file-system-location</replaceable>
	</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+<replaceable>number</replaceable>.
	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>
	<!--
	vim: expandtab tw=80 ts=4
	-->