310 lines
16 KiB
XML
310 lines
16 KiB
XML
|
<!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
|
|||
|
|
-->
|