summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-qemu.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-qemu.xml')
-rw-r--r--documentation/dev-manual/dev-manual-qemu.xml419
1 files changed, 419 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-qemu.xml b/documentation/dev-manual/dev-manual-qemu.xml
new file mode 100644
index 0000000000..739fd7104b
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-qemu.xml
@@ -0,0 +1,419 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='dev-manual-qemu'>
6
7<title>Using the Quick EMUlator (QEMU)</title>
8
9<para>
10 Quick EMUlator (QEMU) is an Open Source project the Yocto Project uses
11 as part of its development "tool set".
12 As such, the information in this chapter is limited to the
13 Yocto Project integration of QEMU and not QEMU in general.
14 For official information and documentation on QEMU, see the
15 following references:
16 <itemizedlist>
17 <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Main_Page'>QEMU Website</ulink>:</emphasis>
18 The official website for the QEMU Open Source project.
19 </para></listitem>
20 <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Manual'>Documentation</ulink>:</emphasis>
21 The QEMU user manual.
22 </para></listitem>
23 </itemizedlist>
24</para>
25
26<para>
27 This chapter provides an overview of the Yocto Project's integration of
28 QEMU, a description of how you use QEMU and its various options, running
29 under a Network File System (NFS) server, and a few tips and tricks you
30 might find helpful when using QEMU.
31</para>
32
33<section id='qemu-overview'>
34 <title>Overview</title>
35
36 <para>
37 Within the context of the Yocto Project, QEMU is an
38 emulator and virtualization machine that allows you to run a complete
39 image you have built using the Yocto Project as just another task
40 on your build system.
41 QEMU is useful for running and testing images and applications on
42 supported Yocto Project architectures without having actual hardware.
43 Among other things, the Yocto Project uses QEMU to run automated
44 Quality Assurance (QA) tests on final images shipped with each
45 release.
46 </para>
47
48 <para>
49 QEMU is made available with the Yocto Project a number of ways.
50 The easiest and recommended method for getting QEMU is to run the
51 ADT installer. For more information on how to make sure you have
52 QEMU available, see the
53 "<ulink url='&YOCTO_DOCS_ADT_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>"
54 section in the Yocto Project Application Developer's Guide.
55 </para>
56</section>
57
58<section id='qemu-running-qemu'>
59 <title>Running QEMU</title>
60
61 <para>
62 Running QEMU involves having your build environment set up, having the
63 right artifacts available, and understanding how to use the many
64 options that are available to you when you start QEMU using the
65 <filename>runqemu</filename> command.
66 </para>
67
68 <section id='qemu-setting-up-the-environment'>
69 <title>Setting Up the Environment</title>
70
71 <para>
72 You run QEMU in the same environment from which you run BitBake.
73 This means you need to source a build environment script (i.e.
74 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
75 or
76 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
77 </para>
78 </section>
79
80 <section id='qemu-using-the-runqemu-command'>
81 <title>Using the <filename>runqemu</filename> Command</title>
82
83 <para>
84 The basic <filename>runqemu</filename> command syntax is as
85 follows:
86 <literallayout class='monospaced'>
87 $ runqemu [<replaceable>option</replaceable> ] [...]
88 </literallayout>
89 Based on what you provide on the command line,
90 <filename>runqemu</filename> does a good job of figuring out what
91 you are trying to do.
92 For example, by default, QEMU looks for the most recently built
93 image according to the timestamp when it needs to look for an
94 image.
95 Minimally, through the use of options, you must provide either
96 a machine name, a virtual machine image
97 (<filename>*.vmdk</filename>), or a kernel image
98 (<filename>*.bin</filename>).
99 </para>
100
101 <para>
102 Following is a description of <filename>runqemu</filename>
103 options you can provide on the command line:
104 <note><title>Tip</title>
105 If you do provide some "illegal" option combination or perhaps
106 you do not provide enough in the way of options,
107 <filename>runqemu</filename> provides appropriate error
108 messaging to help you correct the problem.
109 </note>
110 <itemizedlist>
111 <listitem><para><replaceable>QEMUARCH</replaceable>:
112 The QEMU machine architecture, which must be "qemux86",
113 "qemux86-64", "qemuarm", "qemumips", "qemumipsel",
114 “qemumips64", "qemush4", "qemuppc", "qemumicroblaze",
115 or "qemuzynq".
116 </para></listitem>
117 <listitem><para><filename><replaceable>VM</replaceable></filename>:
118 The virtual machine image, which must be a
119 <filename>.vmdk</filename> file.
120 Use this option when you want to boot a
121 <filename>.vmdk</filename> image.
122 The image filename you provide must contain one of the
123 following strings: "qemux86-64", "qemux86", "qemuarm",
124 "qemumips64", "qemumips", "qemuppc", or "qemush4".
125 </para></listitem>
126 <listitem><para><replaceable>ROOTFS</replaceable>:
127 A root filesystem that has one of the following
128 filetype extensions: "ext2", "ext3", "ext4", "jffs2",
129 "nfs", or "btrfs".
130 If the filename you provide for this option uses “nfs”, it
131 must provide an explicit root filesystem path.
132 </para></listitem>
133 <listitem><para><replaceable>KERNEL</replaceable>:
134 A kernel image, which is a <filename>.bin</filename> file.
135 When you provide a <filename>.bin</filename> file,
136 <filename>runqemu</filename> detects it and assumes the
137 file is a kernel image.
138 </para></listitem>
139 <listitem><para><replaceable>MACHINE</replaceable>:
140 The architecture of the QEMU machine, which must be one
141 of the following: "qemux86",
142 "qemux86-64", "qemuarm", "qemumips", "qemumipsel",
143 “qemumips64", "qemush4", "qemuppc", "qemumicroblaze",
144 or "qemuzynq".
145 The <replaceable>MACHINE</replaceable> and
146 <replaceable>QEMUARCH</replaceable> options are basically
147 identical.
148 If you do not provide a <replaceable>MACHINE</replaceable>
149 option, <filename>runqemu</filename> tries to determine
150 it based on other options.
151 </para></listitem>
152 <listitem><para><filename>ramfs</filename>:
153 Indicates you are booting an initial RAM disk (initramfs)
154 image, which means the <filename>FSTYPE</filename> is
155 <filename>cpio.gz</filename>.
156 </para></listitem>
157 <listitem><para><filename>iso</filename>:
158 Indicates you are booting an ISO image, which means the
159 <filename>FSTYPE</filename> is
160 <filename>.iso</filename>.
161 </para></listitem>
162 <listitem><para><filename>nographic</filename>:
163 Disables the video console, which sets the console to
164 "ttys0".
165 </para></listitem>
166 <listitem><para><filename>serial</filename>:
167 Enables a serial console on
168 <filename>/dev/ttyS0</filename>.
169 </para></listitem>
170 <listitem><para><filename>biosdir</filename>:
171 Establishes a custom directory for BIOS, VGA BIOS and
172 keymaps.
173 </para></listitem>
174 <listitem><para><filename>qemuparams=\"<replaceable>xyz</replaceable>\"</filename>:
175 Specifies custom QEMU parameters.
176 Use this option to pass options other than the simple
177 "kvm" and "serial" options.
178 </para></listitem>
179 <listitem><para><filename>bootparams=\"<replaceable>xyz</replaceable>\"</filename>:
180 Specifies custom boot parameters for the kernel.
181 </para></listitem>
182 <listitem><para><filename>audio</filename>:
183 Enables audio in QEMU.
184 The <replaceable>MACHINE</replaceable> option must be
185 either "qemux86" or "qemux86-64" in order for audio to be
186 enabled.
187 Additionally, the <filename>snd_intel8x0</filename>
188 or <filename>snd_ens1370</filename> driver must be
189 installed in linux guest.
190 </para></listitem>
191 <listitem><para><filename>slirp</filename>:
192 Enables "slirp" networking, which is a different way
193 of networking that does not need root access
194 but also is not as easy to use or comprehensive
195 as the default.
196 </para></listitem>
197 <listitem><para><filename>kvm</filename>:
198 Enables KVM when running "qemux86" or "qemux86-64"
199 QEMU architectures.
200 For KVM to work, all the following conditions must be met:
201 <itemizedlist>
202 <listitem><para>
203 Your <replaceable>MACHINE</replaceable> must be either
204 "qemux86" or "qemux86-64".
205 </para></listitem>
206 <listitem><para>
207 Your build host has to have the KVM modules
208 installed, which are
209 <filename>/dev/kvm</filename>.
210 </para></listitem>
211 <listitem><para>
212 Your build host has to have virtio net device, which
213 are <filename>/dev/vhost-net</filename>.
214 </para></listitem>
215 <listitem><para>
216 The build host <filename>/dev/kvm</filename>
217 directory has to be both writable and readable.
218 </para></listitem>
219 <listitem><para>
220 The build host <filename>/dev/vhost-net</filename>
221 directory has to be either readable or writable
222 and “slirp-enabled”.
223 </para></listitem>
224 </itemizedlist>
225 </para></listitem>
226 <listitem><para><filename>publicvnc</filename>:
227 Enables a VNC server open to all hosts.
228 </para></listitem>
229 </itemizedlist>
230 </para>
231
232 <para>
233 For further understanding regarding option use with
234 <filename>runqemu</filename>, consider some examples.
235 </para>
236
237 <para>
238 This example starts QEMU with
239 <replaceable>MACHINE</replaceable> set to "qemux86".
240 Assuming a standard
241 <link linkend='build-directory'>Build Directory</link>,
242 <filename>runqemu</filename> automatically finds the
243 <filename>bzImage-qemux86.bin</filename> image file and
244 the
245 <filename>core-image-minimal-qemux86-20140707074611.rootfs.ext3</filename>
246 (assuming the current build created a
247 <filename>core-image-minimal</filename> image).
248 <note>
249 When more than one image with the same name exists, QEMU finds
250 and uses the most recently built image according to the
251 timestamp.
252 </note>
253 <literallayout class='monospaced'>
254 $ runqemu qemux86
255 </literallayout>
256 This example produces the exact same results as the
257 previous example.
258 This command, however, specifically provides the image
259 and root filesystem type.
260 <literallayout class='monospaced'>
261 $ runqemu qemux86 core-image-minimal ext3
262 </literallayout>
263 This example specifies to boot an initial RAM disk image
264 and to enable audio in QEMU.
265 For this case, <filename>runqemu</filename> set the
266 internal variable <filename>FSTYPE</filename> to
267 "cpio.gz".
268 Also, for audio to be enabled, an appropriate driver must
269 be installed (see the previous description for the
270 <filename>audio</filename> option for more information).
271 <literallayout class='monospaced'>
272 $ runqemu qemux86 ramfs audio
273 </literallayout>
274 This example does not provide enough information for
275 QEMU to launch.
276 While the command does provide a root filesystem type, it
277 must also minimally provide a
278 <replaceable>MACHINE</replaceable>,
279 <replaceable>KERNEL</replaceable>, or
280 <replaceable>VM</replaceable> option.
281 <literallayout class='monospaced'>
282 $ runqemu ext3
283 </literallayout>
284 This example specifies to boot a virtual machine image
285 (<filename>.vmdk</filename> file).
286 From the <filename>.vmdk</filename>,
287 <filename>runqemu</filename> determines the QEMU
288 architecture (<replaceable>MACHINE</replaceable>) to be
289 "qemux86" and the root filesystem type to be "vmdk".
290 <literallayout class='monospaced'>
291 $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86.vmdk
292 </literallayout>
293 </para>
294 </section>
295</section>
296
297<section id='qemu-running-under-a-network-file-system-nfs-server'>
298 <title>Running Under a Network File System (NFS) Server</title>
299
300 <para>
301 One method for running QEMU is to run it on an NFS server.
302 This is useful when you need to access the same file system from both
303 the build and the emulated system at the same time.
304 It is also worth noting that the system does not need root privileges
305 to run.
306 It uses a user space NFS server to avoid that.
307 This section describes how to set up for running QEMU using an NFS
308 server and then how you can start and stop the server.
309 </para>
310
311 <section id='qemu-setting-up-to-use-nfs'>
312 <title>Setting Up to Use NFS</title>
313
314 <para>
315 Once you are able to run QEMU in your environment, you can use the
316 <filename>runqemu-extract-sdk</filename> script, which is located
317 in the <filename>scripts</filename> directory along with
318 <filename>runqemu</filename> script.
319 The <filename>runqemu-extract-sdk</filename> takes a root
320 file system tarball and extracts it into a location that you
321 specify.
322 Then, when you run <filename>runqemu</filename>, you can specify
323 the location that has the file system to pass it to QEMU.
324 Here is an example that takes a file system and extracts it to
325 a directory named <filename>test-nfs</filename>:
326 <literallayout class='monospaced'>
327 runqemu-extract-sdk ./tmp/deploy/images/qemux86/core-image-sato-qemux86.tar.bz2 test-nfs
328 </literallayout>
329 Once you have extracted the file system, you can run
330 <filename>runqemu</filename> normally with the additional
331 location of the file system.
332 You can then also make changes to the files within
333 <filename>./test-nfs</filename> and see those changes appear in the
334 image in real time.
335 Here is an example using the <filename>qemux86</filename> image:
336 <literallayout class='monospaced'>
337 runqemu qemux86 ./test-nfs
338 </literallayout>
339 </para>
340 </section>
341
342 <section id='qemu-starting-and-stopping-nfs'>
343 <title>Starting and Stopping NFS</title>
344
345 <para>
346 You can manually start and stop the NFS share using these
347 commands:
348 <itemizedlist>
349 <listitem><para><emphasis><filename>start</filename>:</emphasis>
350 Starts the NFS share:
351 <literallayout class='monospaced'>
352 runqemu-export-rootfs start <replaceable>file-system-location</replaceable>
353 </literallayout>
354 </para></listitem>
355 <listitem><para><emphasis><filename>stop</filename>:</emphasis>
356 Stops the NFS share:
357 <literallayout class='monospaced'>
358 runqemu-export-rootfs stop <replaceable>file-system-location</replaceable>
359 </literallayout>
360 </para></listitem>
361 <listitem><para><emphasis><filename>restart</filename>:</emphasis>
362 Restarts the NFS share:
363 <literallayout class='monospaced'>
364 runqemu-export-rootfs restart <replaceable>file-system-location</replaceable>
365 </literallayout>
366 </para></listitem>
367 </itemizedlist>
368 </para>
369 </section>
370</section>
371
372<section id='qemu-tips-and-tricks'>
373 <title>Tips and Tricks</title>
374
375 <para>
376 The following list describes things you can do to make running QEMU
377 in the context of the Yocto Project a better experience:
378 <itemizedlist>
379 <listitem><para><emphasis>Switching Between Consoles:</emphasis>
380 When booting or running QEMU, you can switch between
381 supported consoles by using
382 Ctrl+Alt+<replaceable>number</replaceable>.
383 For example, Ctrl+Alt+3 switches you to the serial console as
384 long as that console is enabled.
385 Being able to switch consoles is helpful, for example, if the
386 main QEMU console breaks for some reason.
387 <note>
388 Usually, "2" gets you to the main console and "3" gets you
389 to the serial console.
390 </note>
391 </para></listitem>
392 <listitem><para><emphasis>Removing the Splash Screen:</emphasis>
393 You can remove the splash screen when QEMU is booting by
394 using Alt+left.
395 Removing the splash screen allows you to see what is happening
396 in the background.
397 </para></listitem>
398 <listitem><para><emphasis>Disabling the Cursor Grab:</emphasis>
399 The default QEMU integration captures the cursor within the
400 main window.
401 It does this since standard mouse devices only provide relative
402 input and not absolute coordinates.
403 You then have to break out of the grab using the "Ctrl+Alt" key
404 combination.
405 However, the Yocto Project's integration of QEMU enables the
406 wacom USB touch pad driver by default to allow input of absolute
407 coordinates.
408 This default means that the mouse can enter and leave the
409 main window without the grab taking effect leading to a better
410 user experience.
411 </para></listitem>
412 </itemizedlist>
413 </para>
414</section>
415
416</chapter>
417<!--
418vim: expandtab tw=80 ts=4
419-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-19 22:44:19 +0000