diff --git a/documentation/dev-manual/dev-manual-qemu.xml b/documentation/dev-manual/dev-manual-qemu.xml
index a8f5c01265..ed4040ca60 100644
--- a/documentation/dev-manual/dev-manual-qemu.xml
+++ b/documentation/dev-manual/dev-manual-qemu.xml
@@ -6,425 +6,305 @@
Using the Quick EMUlator (QEMU)
-
- 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:
-
- QEMU Website:
- The official website for the QEMU Open Source project.
-
- Documentation:
- The QEMU user manual.
-
-
-
-
-
- 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.
-
-
-
- Overview
-
- 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.
+ This chapter provides procedures that show you how to use the
+ Quick EMUlator (QEMU), which is an Open Source project the Yocto
+ Project uses as part of its development "tool set".
+ For reference information on the Yocto Project implementation of QEMU,
+ see the
+ "Quick EMUlator (QEMU)"
+ section in the Yocto Project Reference Manual.
-
- 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
- Yocto Project Software Development Kit (SDK) Developer's Guide.
-
-
-
-
- Running QEMU
-
-
- 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
- runqemu command.
-
-
-
- Setting Up the Environment
+
+ Running QEMU
- You run QEMU in the same environment from which you run BitBake.
- This means you need to source a build environment script (i.e.
- &OE_INIT_FILE;
- or
- oe-init-build-env-memres).
-
-
+ To use QEMU, you need to have QEMU installed and initialized as
+ well as have the proper artifacts (i.e. image files and root
+ filesystems) available.
+ Follow these general steps to run QEMU:
+
+
+ Install QEMU:
+ See
+ "The QEMU Emulator"
+ section in the Yocto Project Software Development Kit (SDK)
+ Developer's Guide for information on how to install
+ QEMU.
+
+
+ Setting Up the Environment:
+ How you set up the QEMU environment depends on how you
+ installed QEMU:
+
+
+ If you cloned the poky
+ repository or you downloaded and unpacked a
+ Yocto Project release tarball, you can source
+ the build environment script (i.e.
+ &OE_INIT_FILE;
+ or
+ oe-init-build-env-memres):
+
+ $ cd ~/poky
+ $ source oe-init-build-env
+
+
+
+ If you installed a cross-toolchain, you can
+ run the script that initializes the toolchain.
+ For example, the following commands run the
+ initialization script from the default
+ poky_sdk directory:
+
+ . ~/poky_sdk/environment-setup-core2-64-poky-linux
+
+
+
+
+
+ Ensure the Artifacts are in Place:
+ You need to be sure you have a pre-built kernel that
+ will boot in QEMU.
+ You also need the target root filesystem for your target
+ machine’s architecture:
+
+
+ If you have previously built an image for QEMU
+ (e.g. qemux86,
+ qemuarm, and so forth),
+ then the artifacts are in place in your
+ Build Directory.
+
+
+ If you have not built an image, you can go to the
+ machines/qemu
+ area and download a pre-built image that matches
+ your architecture and can be run on QEMU.
+
+
-
- Using the <filename>runqemu</filename> Command
-
-
- The basic runqemu command syntax is as
- follows:
-
+ See the
+ "Extracting the Root Filesystem"
+ section in the Yocto Project Software Development Kit (SDK)
+ Developer's Guide for information on how to extract a
+ root filesystem.
+
+
+ Run QEMU:
+ The basic runqemu command syntax is as
+ follows:
+
$ runqemu [option ] [...]
-
- 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).
-
+
+ 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).
-
- 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 must be "qemuarm",
- "qemuarm64", "qemumips", "qemumips64", "qemuppc",
- "qemux86", or "qemux86-64".
-
- 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", "qemux86-64", "qemuarm", "qemuarm64",
- "qemumips", “qemumips64", or "qemuppc".
- 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.
-
- biosfilename:
- Establishes a custom BIOS name.
-
- 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:
+ Here are some additional examples to help illustrate
+ further QEMU:
- Your MACHINE must be either
-qemux86" or "qemux86-64".
+ 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
+
- Your build host has to have the KVM modules
- installed, which are
- /dev/kvm.
-
-
- The build host /dev/kvm
- directory has to be both writable and readable.
-
-
-
- kvm-vhost:
- 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:
-
-
- kvm option
- conditions must be met.
-
-
- Your build host has to have virtio net device, which
- are /dev/vhost-net.
-
-
- 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.
-
+ 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).
-
+
+
+
+ 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.
-
+
+
+
+ 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".
-
+
+
+
+ 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
+
+ Switching Between Consoles
- 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:
-
+ 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.
+
+
+
+
+ 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.
+ Follow these steps to set up for running QEMU using an NFS
+ server.
+
+
+ Extract a Root Filesystem:
+ 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 the runqemu
+ script.
+
+ The runqemu-extract-sdk takes a
+ root filesystem tarball and extracts it into a location
+ that you specify.
+ 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:
-
+
+
+
+ Start QEMU:
+ 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:
-
+
+
+
+
+
+ Should you need to start, stop, or restart the NFS share,
+ you can use the following commands:
+
+
+ The following command 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:
-
+
+
+
+ The following command stops the NFS share:
+
+ runqemu-export-rootfs stop file-system-location
+
+
+
+ The following command restarts the NFS share:
+
runqemu-export-rootfs restart file-system-location
-
-
-
+
+
+
+
+
-
-
-
- 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.
-
-
-
-
-