# 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.

## Running QEMU

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:

1. Install QEMU: See "The QEMU Emulator" section in the Yocto Project Application Development and the Extensible Software Development Kit (eSDK) manual for information on how to install QEMU.

2. 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;`):

              $ 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

3. 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.

   See the "Extracting the Root Filesystem" section in the Yocto Project Application Development and the Extensible Software Development Kit (eSDK) manual for information on how to extract a root filesystem.

4. 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 (`*wic.vmdk`), or a kernel image (`*.bin`).

   Here are some additional examples to help illustrate further QEMU:

   - 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 (`.wic.vmdk` file). From the `.wic.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.wic.vmdk

## 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.

## 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.

1. 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

2. 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

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

- 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