%poky; ] > 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. QEMU is made available with the Yocto Project a number of ways. The easiest and recommended method for getting QEMU is to run the ADT installer. For more information on how to make sure you have QEMU available, see the "The QEMU Emulator" section in the Yocto Project Application 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 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).
Using the <filename>runqemu</filename> Command 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). 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 "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
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.