1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
|
<!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 Software Development Kit (SDK)
Developer's Guide 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 Software Development Kit (SDK)
Developer's Guide 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>*.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
-->
|
