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 @@
-Using the Quick EMUlator
+Using the Quick EMUlator (QEMU)
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:
@@ -24,9 +24,10 @@
- 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.
@@ -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.
@@ -80,47 +84,333 @@
The basic runqemu command syntax is as
follows:
- $ runqemu [option ] [option ] [...]
+ $ runqemu [option ] [...]
- runqemu 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,
+ runqemu 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
(*.vmdk), or a kernel image
(*.bin).
-
- If you do provide some "illegal" combination or options or perhaps
- do not provide enough in the way of options,
- runqemu provides appropriate error messaging
- to help you figure it out.
-
-
Following is a description of runqemu
options you can provide on the command line:
+ Tip
+ If you do provide some "illegal" option combination or perhaps
+ you do not provide enough in the way of options,
+ runqemu provides appropriate error
+ messaging to help you correct the problem.
+
- QEMUARCH:
- The QEMU machine architecture, which can be "qemux86",
+ QEMUARCH:
+ The QEMU machine architecture, which must be "qemux86",
"qemux86-64", "qemuarm", "qemumips", "qemumipsel",
“qemumips64", "qemush4", "qemuppc", "qemumicroblaze",
or "qemuzynq".
+ VM:
+ The virtual machine image, which must be a
+ .vmdk file.
+ Use this option when you want to boot a
+ .vmdk image.
+ The image filename you provide must contain one of the
+ following strings: "qemux86-64", "qemux86", "qemuarm",
+ "qemumips64", "qemumips", "qemuppc", or "qemush4".
+
+ ROOTFS:
+ 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.
+
+ KERNEL:
+ A kernel image, which is a .bin file.
+ When you provide a .bin file,
+ runqemu detects it and assumes the
+ file is a kernel image.
+
+ MACHINE:
+ 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 MACHINE and
+ QEMUARCH options are basically
+ identical.
+ If you do not provide a MACHINE
+ option, runqemu tries to determine
+ it based on other options.
+
+ ramfs:
+ Indicates you are booting an initial RAM disk (initramfs)
+ image, which means the FSTYPE is
+ cpio.gz.
+
+ iso:
+ Indicates you are booting an ISO image, which means the
+ FSTYPE is
+ .iso.
+
+ nographic:
+ Disables the video console, which sets the console to
+ "ttys0".
+
+ serial:
+ Enables a serial console on
+ /dev/ttyS0.
+
+ biosdir:
+ Establishes a custom directory for BIOS, VGA BIOS and
+ keymaps.
+
+ qemuparams=\"xyz\":
+ Specifies custom QEMU parameters.
+ Use this option to pass options other than the simple
+ "kvm" and "serial" options.
+
+ bootparams=\"xyz\":
+ Specifies custom boot parameters for the kernel.
+
+ audio:
+ Enables audio in QEMU.
+ The MACHINE option must be
+ either "qemux86" or "qemux86-64" in order for audio to be
+ enabled.
+ Additionally, the snd_intel8x0
+ or snd_ens1370 driver must be
+ installed in linux guest.
+
+ slirp:
+ 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.
+
+ kvm:
+ Enables KVM when running "qemux86" or "qemux86-64"
+ QEMU architectures.
+ For KVM to work, all the following conditions must be met:
+
+
+ Your MACHINE must be either
+ "qemux86" or "qemux86-64".
+
+
+ Your build host has to have the KVM modules
+ installed, which are
+ /dev/kvm.
+
+
+ Your build host has to have virtio net device, which
+ are /dev/vhost-net.
+
+
+ The build host /dev/kvm
+ directory has to be both writable and readable.
+
+
+ The build host /dev/vhost-net
+ directory has to be either readable or writable
+ and “slirp-enabled”.
+
+
+
+ publicvnc:
+ Enables a VNC server open to all hosts.
+
+
+
+
+
+ For further understanding regarding option use with
+ runqemu, consider some examples.
+
+
+
+ This example starts QEMU with
+ MACHINE set to "qemux86".
+ Assuming a standard
+ Build Directory,
+ runqemu automatically finds the
+ bzImage-qemux86.bin image file and
+ the
+ core-image-minimal-qemux86-20140707074611.rootfs.ext3
+ (assuming the current build created a
+ core-image-minimal image).
+
+ When more than one image with the same name exists, QEMU finds
+ and uses the most recently built image according to the
+ timestamp.
+
+
+ $ runqemu qemux86
+
+ This example produces the exact same results as the
+ previous example.
+ This command, however, specifically provides the image
+ and root filesystem type.
+
+ $ runqemu qemux86 core-image-minimal ext3
+
+ This example specifies to boot an initial RAM disk image
+ and to enable audio in QEMU.
+ For this case, runqemu set the
+ internal variable FSTYPE to
+ "cpio.gz".
+ Also, for audio to be enabled, an appropriate driver must
+ be installed (see the previous description for the
+ audio option for more information).
+
+ $ runqemu qemux86 ramfs audio
+
+ 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
+ MACHINE,
+ KERNEL, or
+ VM option.
+
+ $ runqemu ext3
+
+ This example specifies to boot a virtual machine image
+ (.vmdk file).
+ From the .vmdk,
+ runqemu determines the QEMU
+ architecture (MACHINE) to be
+ "qemux86" and the root filesystem type to be "vmdk".
+
+ $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86.vmdk
+
+
+
+
+
+
+ Running Under a Network File System (NFS) Server
+
+
+ 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.
+
+
+
+ Setting Up to Use NFS
+
+
+ Once you are able to run QEMU in your environment, you can use the
+ runqemu-extract-sdk script, which is located
+ in the scripts directory along with
+ runqemu script.
+ The runqemu-extract-sdk takes a root
+ file system tarball and extracts it into a location that you
+ specify.
+ Then, when you run runqemu, 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 test-nfs:
+
+ runqemu-extract-sdk ./tmp/deploy/images/qemux86/core-image-sato-qemux86.tar.bz2 test-nfs
+
+ Once you have extracted the file system, you can run
+ runqemu normally with the additional
+ location of the file system.
+ You can then also make changes to the files within
+ ./test-nfs and see those changes appear in the
+ image in real time.
+ Here is an example using the qemux86 image:
+
+ runqemu qemux86 ./test-nfs
+
+
+
+
+
+ Starting and Stopping NFS
+
+
+ You can manually start and stop the NFS share using these
+ commands:
+
+ start:
+ Starts the NFS share:
+
+ runqemu-export-rootfs start <file-system-location>
+
+
+ stop:
+ Stops the NFS share:
+
+ runqemu-export-rootfs stop <file-system-location>
+
+
+ restart:
+ Restarts the NFS share:
+
+ runqemu-export-rootfs restart <file-system-location>
+
+
-
- Modes
-
-
-
Tips and Tricks
+
+ The following list describes things you can do to make running QEMU
+ in the context of the Yocto Project a better experience:
+
+ Switching Between Consoles:
+ When booting or running QEMU, you can switch between
+ supported consoles by using
+ Ctrl+Alt+<number>.
+ 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.
+
+ Usually, "2" gets you to the main console and "3" gets you
+ to the serial console.
+
+
+ Removing the Splash Screen:
+ 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.
+
+ Disabling the Cursor Grab:
+ 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.
+
+
+
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 @@
+
+