diff --git a/documentation/dev-manual/dev-manual-qemu.xml b/documentation/dev-manual/dev-manual-qemu.xml
index 85e7315872..f4719ebc3c 100644
--- a/documentation/dev-manual/dev-manual-qemu.xml
+++ b/documentation/dev-manual/dev-manual-qemu.xml
@@ -7,15 +7,51 @@
Using the Quick EMUlator (QEMU)
- 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.
+ The Yocto Project uses an implementation of the Quick EMUlator (QEMU)
+ Open Source project as part of the Yocto Project development "tool
+ set".
+ This chapter provides both procedures that show you how to use the
+ Quick EMUlator (QEMU) and other QEMU information helpful for
+ development purposes.
+
+ 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 implementation is not the same as QEMU in general.
+
+ This section provides a brief reference for the Yocto Project
+ implementation of QEMU.
+
+
+
+ For official information and documentation on QEMU in general, see
+ the following references:
+
+
+ QEMU Website:
+ The official website for the QEMU Open Source project.
+
+
+ Documentation:
+ The QEMU user manual.
+
+
+
+
+
Running QEMU
@@ -27,6 +63,9 @@
Install QEMU:
+ QEMU is made available with the Yocto Project a number of
+ ways.
+ One method is to install a Software Development Kit (SDK).
See
"The QEMU Emulator"
section in the Yocto Project Application Development and
@@ -303,6 +342,311 @@
+
+
+ QEMU Performance
+
+
+ Using QEMU to emulate your hardware can result in speed issues
+ depending on the target and host architecture mix.
+ For example, using the qemux86 image in the
+ emulator on an Intel-based 32-bit (x86) host machine is fast
+ because the target and host architectures match.
+ On the other hand, using the qemuarm image
+ on the same Intel-based host can be slower.
+ But, you still achieve faithful emulation of ARM-specific issues.
+
+
+
+ To speed things up, the QEMU images support using
+ distcc to call a cross-compiler outside the
+ emulated system.
+ If you used runqemu to start QEMU, and the
+ distccd application is present on the host
+ system, any BitBake cross-compiling toolchain available from the
+ build system is automatically used from within QEMU simply by
+ calling distcc.
+ You can accomplish this by defining the cross-compiler variable
+ (e.g. export CC="distcc").
+ Alternatively, if you are using a suitable SDK image or the
+ appropriate stand-alone toolchain is present, the toolchain is
+ also automatically used.
+
+ Several mechanisms exist that let you connect to the system
+ running on the QEMU emulator:
+
+
+ QEMU provides a framebuffer interface that makes
+ standard consoles available.
+
+
+ Generally, headless embedded devices have a serial port.
+ If so, you can configure the operating system of the
+ running image to use that port to run a console.
+ The connection uses standard IP networking.
+
+
+ SSH servers exist in some QEMU images.
+ The core-image-sato QEMU image
+ has a Dropbear secure shell (SSH) server that runs
+ with the root password disabled.
+ The core-image-full-cmdline and
+ core-image-lsb QEMU images
+ have OpenSSH instead of Dropbear.
+ Including these SSH servers allow you to use standard
+ ssh and scp
+ commands.
+ The core-image-minimal QEMU image,
+ however, contains no SSH server.
+
+
+ You can use a provided, user-space NFS server to boot
+ the QEMU session using a local copy of the root
+ filesystem on the host.
+ In order to make this connection, you must extract a
+ root filesystem tarball by using the
+ runqemu-extract-sdk command.
+ After running the command, you must then point the
+ runqemu
+ script to the extracted directory instead of a root
+ filesystem image file.
+ See the
+ "Running Under a Network File System (NFS) Server"
+ section for more information.
+
+
+
+
+
+
+
+ QEMU Command-Line Syntax
+
+
+ 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
+ (*wic.vmdk), or a kernel image
+ (*.bin).
+
+
+
+ Following is the command-line help output for the
+ runqemu command:
+
+ $ runqemu --help
+
+ Usage: you can run this script with any valid combination
+ of the following environment variables (in any order):
+ KERNEL - the kernel image file to use
+ ROOTFS - the rootfs image file or nfsroot directory to use
+ MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)
+ Simplified QEMU command-line options can be passed with:
+ nographic - disable video console
+ serial - enable a serial console on /dev/ttyS0
+ slirp - enable user networking, no root privileges is required
+ kvm - enable KVM when running x86/x86_64 (VT-capable CPU required)
+ kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required)
+ publicvnc - enable a VNC server open to all hosts
+ audio - enable audio
+ [*/]ovmf* - OVMF firmware file or base name for booting with UEFI
+ tcpserial=<port> - specify tcp serial port number
+ biosdir=<dir> - specify custom bios dir
+ biosfilename=<filename> - specify bios filename
+ qemuparams=<xyz> - specify custom parameters to QEMU
+ bootparams=<xyz> - specify custom kernel parameters during boot
+ help, -h, --help: print this text
+
+ Examples:
+ runqemu
+ runqemu qemuarm
+ runqemu tmp/deploy/images/qemuarm
+ runqemu tmp/deploy/images/qemux86/<qemuboot.conf>
+ runqemu qemux86-64 core-image-sato ext4
+ runqemu qemux86-64 wic-image-minimal wic
+ runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial
+ runqemu qemux86 iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz...
+ runqemu qemux86 qemuparams="-m 256"
+ runqemu qemux86 bootparams="psplash=false"
+ runqemu path/to/<image>-<machine>.wic
+ runqemu path/to/<image>-<machine>.wic.vmdk
+
+
+
+
+
+ <filename>runqemu</filename> Command-Line Options
+
+
+ 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
+ .wic.vmdk file.
+ Use this option when you want to boot a
+ .wic.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",
+ "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:
+
+
+ Your MACHINE must be either
+qemux86" or "qemux86-64".
+
+
+ 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.
+
+
+
+