| <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
| [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
| |
| <chapter id='dev-manual-qemu'> |
| |
| <title>Using the Quick EMUlator (QEMU)</title> |
| |
| <para> |
| 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 |
| "<ulink url='&YOCTO_DOCS_REF_URL;#ref-quick-emulator-qemu'>Quick EMUlator (QEMU)</ulink>" |
| section in the Yocto Project Reference Manual. |
| </para> |
| |
| <section id='qemu-running-qemu'> |
| <title>Running QEMU</title> |
| |
| <para> |
| 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: |
| <orderedlist> |
| <listitem><para> |
| <emphasis>Install QEMU:</emphasis> |
| See |
| "<ulink url='&YOCTO_DOCS_SDK_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>" |
| section in the Yocto Project Application Development and |
| the Extensible Software Development Kit (eSDK) manual |
| for information on how to install QEMU. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Setting Up the Environment:</emphasis> |
| How you set up the QEMU environment depends on how you |
| installed QEMU: |
| <itemizedlist> |
| <listitem><para> |
| If you cloned the <filename>poky</filename> |
| repository or you downloaded and unpacked a |
| Yocto Project release tarball, you can source |
| the build environment script (i.e. |
| <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>): |
| <literallayout class='monospaced'> |
| $ cd ~/poky |
| $ source oe-init-build-env |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| 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 |
| <filename>poky_sdk</filename> directory: |
| <literallayout class='monospaced'> |
| . ~/poky_sdk/environment-setup-core2-64-poky-linux |
| </literallayout> |
| </para></listitem> |
| </itemizedlist> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Ensure the Artifacts are in Place:</emphasis> |
| 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: |
| <itemizedlist> |
| <listitem><para> |
| If you have previously built an image for QEMU |
| (e.g. <filename>qemux86</filename>, |
| <filename>qemuarm</filename>, and so forth), |
| then the artifacts are in place in your |
| <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. |
| </para></listitem> |
| <listitem><para> |
| If you have not built an image, you can go to the |
| <ulink url='&YOCTO_MACHINES_DL_URL;'>machines/qemu</ulink> |
| area and download a pre-built image that matches |
| your architecture and can be run on QEMU. |
| </para></listitem> |
| </itemizedlist></para> |
| |
| <para>See the |
| "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>" |
| section in the Yocto Project Application Development and |
| the Extensible Software Development Kit (eSDK) manual |
| for information on how to extract a root filesystem. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Run QEMU:</emphasis> |
| The basic <filename>runqemu</filename> command syntax is as |
| follows: |
| <literallayout class='monospaced'> |
| $ runqemu [<replaceable>option</replaceable> ] [...] |
| </literallayout> |
| Based on what you provide on the command line, |
| <filename>runqemu</filename> 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 |
| (<filename>*wic.vmdk</filename>), or a kernel image |
| (<filename>*.bin</filename>).</para> |
| |
| <para>Here are some additional examples to help illustrate |
| further QEMU: |
| <itemizedlist> |
| <listitem><para> |
| This example starts QEMU with |
| <replaceable>MACHINE</replaceable> set to "qemux86". |
| Assuming a standard |
| <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, |
| <filename>runqemu</filename> automatically finds the |
| <filename>bzImage-qemux86.bin</filename> image file and |
| the |
| <filename>core-image-minimal-qemux86-20140707074611.rootfs.ext3</filename> |
| (assuming the current build created a |
| <filename>core-image-minimal</filename> image). |
| <note> |
| When more than one image with the same name exists, QEMU finds |
| and uses the most recently built image according to the |
| timestamp. |
| </note> |
| <literallayout class='monospaced'> |
| $ runqemu qemux86 |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| This example produces the exact same results as the |
| previous example. |
| This command, however, specifically provides the image |
| and root filesystem type. |
| <literallayout class='monospaced'> |
| $ runqemu qemux86 core-image-minimal ext3 |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| This example specifies to boot an initial RAM disk image |
| and to enable audio in QEMU. |
| For this case, <filename>runqemu</filename> set the |
| internal variable <filename>FSTYPE</filename> to |
| "cpio.gz". |
| Also, for audio to be enabled, an appropriate driver must |
| be installed (see the previous description for the |
| <filename>audio</filename> option for more information). |
| <literallayout class='monospaced'> |
| $ runqemu qemux86 ramfs audio |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| 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 |
| <replaceable>MACHINE</replaceable>, |
| <replaceable>KERNEL</replaceable>, or |
| <replaceable>VM</replaceable> option. |
| <literallayout class='monospaced'> |
| $ runqemu ext3 |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| This example specifies to boot a virtual machine |
| image (<filename>.wic.vmdk</filename> file). |
| From the <filename>.wic.vmdk</filename>, |
| <filename>runqemu</filename> determines the QEMU |
| architecture (<replaceable>MACHINE</replaceable>) to be |
| "qemux86" and the root filesystem type to be "vmdk". |
| <literallayout class='monospaced'> |
| $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86.wic.vmdk |
| </literallayout> |
| </para></listitem> |
| </itemizedlist> |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| |
| <section id='switching-between-consoles'> |
| <title>Switching Between Consoles</title> |
| |
| <para> |
| When booting or running QEMU, you can switch between |
| supported consoles by using |
| Ctrl+Alt+<replaceable>number</replaceable>. |
| 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. |
| <note> |
| Usually, "2" gets you to the main console and "3" |
| gets you to the serial console. |
| </note> |
| </para> |
| </section> |
| |
| <section id='removing-the-splash-screen'> |
| <title>Removing the Splash Screen</title> |
| |
| <para> |
| 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. |
| </para> |
| </section> |
| |
| <section id='disabling-the-cursor-grab'> |
| <title>Disabling the Cursor Grab</title> |
| |
| <para> |
| 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. |
| </para> |
| </section> |
| |
| <section id='qemu-running-under-a-network-file-system-nfs-server'> |
| <title>Running Under a Network File System (NFS) Server</title> |
| |
| <para> |
| 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. |
| <orderedlist> |
| <listitem><para> |
| <emphasis>Extract a Root Filesystem:</emphasis> |
| Once you are able to run QEMU in your environment, you can |
| use the <filename>runqemu-extract-sdk</filename> script, |
| which is located in the <filename>scripts</filename> |
| directory along with the <filename>runqemu</filename> |
| script.</para> |
| |
| <para>The <filename>runqemu-extract-sdk</filename> 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 |
| <filename>test-nfs</filename>: |
| <literallayout class='monospaced'> |
| runqemu-extract-sdk ./tmp/deploy/images/qemux86/core-image-sato-qemux86.tar.bz2 test-nfs |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Start QEMU:</emphasis> |
| Once you have extracted the file system, you can run |
| <filename>runqemu</filename> normally with the additional |
| location of the file system. |
| You can then also make changes to the files within |
| <filename>./test-nfs</filename> and see those changes |
| appear in the image in real time. |
| Here is an example using the <filename>qemux86</filename> |
| image: |
| <literallayout class='monospaced'> |
| runqemu qemux86 ./test-nfs |
| </literallayout> |
| </para></listitem> |
| </orderedlist> |
| <note> |
| <para> |
| Should you need to start, stop, or restart the NFS share, |
| you can use the following commands: |
| <itemizedlist> |
| <listitem><para> |
| The following command starts the NFS share: |
| <literallayout class='monospaced'> |
| runqemu-export-rootfs start <replaceable>file-system-location</replaceable> |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| The following command stops the NFS share: |
| <literallayout class='monospaced'> |
| runqemu-export-rootfs stop <replaceable>file-system-location</replaceable> |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| The following command restarts the NFS share: |
| <literallayout class='monospaced'> |
| runqemu-export-rootfs restart <replaceable>file-system-location</replaceable> |
| </literallayout> |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </note> |
| </para> |
| </section> |
| </chapter> |
| <!-- |
| vim: expandtab tw=80 ts=4 |
| --> |