blob: 46fe67bab0cb810a513b2102d518cce53a5c6731 [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001<!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; ] >
Andrew Geisslerd25ed322020-06-27 00:28:28 -05004<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005
6<chapter id='dev-manual-qemu'>
7
8<title>Using the Quick EMUlator (QEMU)</title>
9
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011 The Yocto Project uses an implementation of the Quick EMUlator (QEMU)
12 Open Source project as part of the Yocto Project development "tool
13 set".
14 This chapter provides both procedures that show you how to use the
15 Quick EMUlator (QEMU) and other QEMU information helpful for
16 development purposes.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050017 </para>
18
Brad Bishop316dfdd2018-06-25 12:45:53 -040019 <section id='qemu-dev-overview'>
20 <title>Overview</title>
21
22 <para>
23 Within the context of the Yocto Project, QEMU is an
24 emulator and virtualization machine that allows you to run a
25 complete image you have built using the Yocto Project as just
26 another task on your build system.
27 QEMU is useful for running and testing images and applications on
28 supported Yocto Project architectures without having actual
29 hardware.
30 Among other things, the Yocto Project uses QEMU to run automated
31 Quality Assurance (QA) tests on final images shipped with each
32 release.
33 <note>
34 This implementation is not the same as QEMU in general.
35 </note>
36 This section provides a brief reference for the Yocto Project
37 implementation of QEMU.
38 </para>
39
40 <para>
41 For official information and documentation on QEMU in general, see
42 the following references:
43 <itemizedlist>
44 <listitem><para>
45 <emphasis><ulink url='http://wiki.qemu.org/Main_Page'>QEMU Website</ulink>:</emphasis>
46 The official website for the QEMU Open Source project.
47 </para></listitem>
48 <listitem><para>
49 <emphasis><ulink url='http://wiki.qemu.org/Manual'>Documentation</ulink>:</emphasis>
50 The QEMU user manual.
51 </para></listitem>
52 </itemizedlist>
53 </para>
54 </section>
55
Brad Bishopd7bf8c12018-02-25 22:55:05 -050056 <section id='qemu-running-qemu'>
57 <title>Running QEMU</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050058
59 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -050060 To use QEMU, you need to have QEMU installed and initialized as
61 well as have the proper artifacts (i.e. image files and root
62 filesystems) available.
63 Follow these general steps to run QEMU:
64 <orderedlist>
65 <listitem><para>
66 <emphasis>Install QEMU:</emphasis>
Brad Bishop316dfdd2018-06-25 12:45:53 -040067 QEMU is made available with the Yocto Project a number of
68 ways.
69 One method is to install a Software Development Kit (SDK).
Brad Bishopd7bf8c12018-02-25 22:55:05 -050070 See
71 "<ulink url='&YOCTO_DOCS_SDK_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>"
72 section in the Yocto Project Application Development and
73 the Extensible Software Development Kit (eSDK) manual
74 for information on how to install QEMU.
75 </para></listitem>
76 <listitem><para>
77 <emphasis>Setting Up the Environment:</emphasis>
78 How you set up the QEMU environment depends on how you
79 installed QEMU:
80 <itemizedlist>
81 <listitem><para>
82 If you cloned the <filename>poky</filename>
83 repository or you downloaded and unpacked a
84 Yocto Project release tarball, you can source
85 the build environment script (i.e.
86 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>):
87 <literallayout class='monospaced'>
88 $ cd ~/poky
89 $ source oe-init-build-env
90 </literallayout>
91 </para></listitem>
92 <listitem><para>
93 If you installed a cross-toolchain, you can
94 run the script that initializes the toolchain.
95 For example, the following commands run the
96 initialization script from the default
97 <filename>poky_sdk</filename> directory:
98 <literallayout class='monospaced'>
99 . ~/poky_sdk/environment-setup-core2-64-poky-linux
100 </literallayout>
101 </para></listitem>
102 </itemizedlist>
103 </para></listitem>
104 <listitem><para>
105 <emphasis>Ensure the Artifacts are in Place:</emphasis>
106 You need to be sure you have a pre-built kernel that
107 will boot in QEMU.
108 You also need the target root filesystem for your target
109 machine’s architecture:
110 <itemizedlist>
111 <listitem><para>
112 If you have previously built an image for QEMU
113 (e.g. <filename>qemux86</filename>,
114 <filename>qemuarm</filename>, and so forth),
115 then the artifacts are in place in your
116 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
117 </para></listitem>
118 <listitem><para>
119 If you have not built an image, you can go to the
120 <ulink url='&YOCTO_MACHINES_DL_URL;'>machines/qemu</ulink>
121 area and download a pre-built image that matches
122 your architecture and can be run on QEMU.
123 </para></listitem>
124 </itemizedlist></para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500125
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500126 <para>See the
127 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>"
128 section in the Yocto Project Application Development and
129 the Extensible Software Development Kit (eSDK) manual
130 for information on how to extract a root filesystem.
131 </para></listitem>
132 <listitem><para>
133 <emphasis>Run QEMU:</emphasis>
134 The basic <filename>runqemu</filename> command syntax is as
135 follows:
136 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500137 $ runqemu [<replaceable>option</replaceable> ] [...]
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500138 </literallayout>
139 Based on what you provide on the command line,
140 <filename>runqemu</filename> does a good job of figuring
141 out what you are trying to do.
142 For example, by default, QEMU looks for the most recently
143 built image according to the timestamp when it needs to
144 look for an image.
145 Minimally, through the use of options, you must provide
146 either a machine name, a virtual machine image
147 (<filename>*wic.vmdk</filename>), or a kernel image
148 (<filename>*.bin</filename>).</para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500149
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500150 <para>Here are some additional examples to help illustrate
151 further QEMU:
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500152 <itemizedlist>
153 <listitem><para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500154 This example starts QEMU with
Andrew Geissler82c905d2020-04-13 13:39:40 -0500155 <replaceable>MACHINE</replaceable> set to "qemux86-64".
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500156 Assuming a standard
157 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
158 <filename>runqemu</filename> automatically finds the
Andrew Geissler82c905d2020-04-13 13:39:40 -0500159 <filename>bzImage-qemux86-64.bin</filename> image file and
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500160 the
Andrew Geissler82c905d2020-04-13 13:39:40 -0500161 <filename>core-image-minimal-qemux86-64-20200218002850.rootfs.ext4</filename>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500162 (assuming the current build created a
163 <filename>core-image-minimal</filename> image).
164 <note>
165 When more than one image with the same name exists, QEMU finds
166 and uses the most recently built image according to the
167 timestamp.
168 </note>
169 <literallayout class='monospaced'>
Andrew Geissler82c905d2020-04-13 13:39:40 -0500170 $ runqemu qemux86-64
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500171 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500172 </para></listitem>
173 <listitem><para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500174 This example produces the exact same results as the
175 previous example.
176 This command, however, specifically provides the image
177 and root filesystem type.
178 <literallayout class='monospaced'>
Andrew Geissler82c905d2020-04-13 13:39:40 -0500179 $ runqemu qemux86-64 core-image-minimal ext4
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500180 </literallayout>
181 </para></listitem>
182 <listitem><para>
183 This example specifies to boot an initial RAM disk image
184 and to enable audio in QEMU.
185 For this case, <filename>runqemu</filename> set the
186 internal variable <filename>FSTYPE</filename> to
187 "cpio.gz".
188 Also, for audio to be enabled, an appropriate driver must
189 be installed (see the previous description for the
190 <filename>audio</filename> option for more information).
191 <literallayout class='monospaced'>
Andrew Geissler82c905d2020-04-13 13:39:40 -0500192 $ runqemu qemux86-64 ramfs audio
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500193 </literallayout>
194 </para></listitem>
195 <listitem><para>
196 This example does not provide enough information for
197 QEMU to launch.
198 While the command does provide a root filesystem type, it
199 must also minimally provide a
200 <replaceable>MACHINE</replaceable>,
201 <replaceable>KERNEL</replaceable>, or
202 <replaceable>VM</replaceable> option.
203 <literallayout class='monospaced'>
Andrew Geissler82c905d2020-04-13 13:39:40 -0500204 $ runqemu ext4
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500205 </literallayout>
206 </para></listitem>
207 <listitem><para>
208 This example specifies to boot a virtual machine
209 image (<filename>.wic.vmdk</filename> file).
210 From the <filename>.wic.vmdk</filename>,
211 <filename>runqemu</filename> determines the QEMU
212 architecture (<replaceable>MACHINE</replaceable>) to be
Andrew Geissler82c905d2020-04-13 13:39:40 -0500213 "qemux86-64" and the root filesystem type to be "vmdk".
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500214 <literallayout class='monospaced'>
Andrew Geissler82c905d2020-04-13 13:39:40 -0500215 $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500216 </literallayout>
217 </para></listitem>
218 </itemizedlist>
219 </para></listitem>
220 </orderedlist>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500221 </para>
222 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500223
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500224 <section id='switching-between-consoles'>
225 <title>Switching Between Consoles</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500226
227 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500228 When booting or running QEMU, you can switch between
229 supported consoles by using
230 Ctrl+Alt+<replaceable>number</replaceable>.
231 For example, Ctrl+Alt+3 switches you to the serial console
232 as long as that console is enabled.
233 Being able to switch consoles is helpful, for example, if
234 the main QEMU console breaks for some reason.
235 <note>
236 Usually, "2" gets you to the main console and "3"
237 gets you to the serial console.
238 </note>
239 </para>
240 </section>
241
242 <section id='removing-the-splash-screen'>
243 <title>Removing the Splash Screen</title>
244
245 <para>
246 You can remove the splash screen when QEMU is booting by
247 using Alt+left.
248 Removing the splash screen allows you to see what is
249 happening in the background.
250 </para>
251 </section>
252
253 <section id='disabling-the-cursor-grab'>
254 <title>Disabling the Cursor Grab</title>
255
256 <para>
257 The default QEMU integration captures the cursor within the
258 main window.
259 It does this since standard mouse devices only provide
260 relative input and not absolute coordinates.
261 You then have to break out of the grab using the "Ctrl+Alt"
262 key combination.
263 However, the Yocto Project's integration of QEMU enables
264 the wacom USB touch pad driver by default to allow input
265 of absolute coordinates.
266 This default means that the mouse can enter and leave the
267 main window without the grab taking effect leading to a
268 better user experience.
269 </para>
270 </section>
271
272 <section id='qemu-running-under-a-network-file-system-nfs-server'>
273 <title>Running Under a Network File System (NFS) Server</title>
274
275 <para>
276 One method for running QEMU is to run it on an NFS server.
277 This is useful when you need to access the same file system
278 from both the build and the emulated system at the same time.
279 It is also worth noting that the system does not need root
280 privileges to run.
281 It uses a user space NFS server to avoid that.
282 Follow these steps to set up for running QEMU using an NFS
283 server.
284 <orderedlist>
285 <listitem><para>
286 <emphasis>Extract a Root Filesystem:</emphasis>
287 Once you are able to run QEMU in your environment, you can
288 use the <filename>runqemu-extract-sdk</filename> script,
289 which is located in the <filename>scripts</filename>
290 directory along with the <filename>runqemu</filename>
291 script.</para>
292
293 <para>The <filename>runqemu-extract-sdk</filename> takes a
294 root filesystem tarball and extracts it into a location
295 that you specify.
296 Here is an example that takes a file system and
297 extracts it to a directory named
298 <filename>test-nfs</filename>:
299 <literallayout class='monospaced'>
Andrew Geissler82c905d2020-04-13 13:39:40 -0500300 runqemu-extract-sdk ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 test-nfs
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500301 </literallayout>
302 </para></listitem>
303 <listitem><para>
304 <emphasis>Start QEMU:</emphasis>
305 Once you have extracted the file system, you can run
306 <filename>runqemu</filename> normally with the additional
307 location of the file system.
308 You can then also make changes to the files within
309 <filename>./test-nfs</filename> and see those changes
310 appear in the image in real time.
311 Here is an example using the <filename>qemux86</filename>
312 image:
313 <literallayout class='monospaced'>
Andrew Geissler82c905d2020-04-13 13:39:40 -0500314 runqemu qemux86-64 ./test-nfs
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500315 </literallayout>
316 </para></listitem>
317 </orderedlist>
318 <note>
319 <para>
320 Should you need to start, stop, or restart the NFS share,
321 you can use the following commands:
322 <itemizedlist>
323 <listitem><para>
324 The following command starts the NFS share:
325 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500326 runqemu-export-rootfs start <replaceable>file-system-location</replaceable>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500327 </literallayout>
328 </para></listitem>
329 <listitem><para>
330 The following command stops the NFS share:
331 <literallayout class='monospaced'>
332 runqemu-export-rootfs stop <replaceable>file-system-location</replaceable>
333 </literallayout>
334 </para></listitem>
335 <listitem><para>
336 The following command restarts the NFS share:
337 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500338 runqemu-export-rootfs restart <replaceable>file-system-location</replaceable>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500339 </literallayout>
340 </para></listitem>
341 </itemizedlist>
342 </para>
343 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500344 </para>
345 </section>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400346
347 <section id='qemu-kvm-cpu-compatibility'>
348 <title>QEMU CPU Compatibility Under KVM</title>
349
350 <para>
351 By default, the QEMU build compiles for and targets 64-bit and x86
352 <trademark class='registered'>Intel</trademark> <trademark class='trademark'>Core</trademark>2
353 Duo processors and 32-bit x86
354 <trademark class='registered'>Intel</trademark> <trademark class='registered'>Pentium</trademark>
355 II processors.
356 QEMU builds for and targets these CPU types because they display
357 a broad range of CPU feature compatibility with many commonly
358 used CPUs.
359 </para>
360
361 <para>
362 Despite this broad range of compatibility, the CPUs could support
363 a feature that your host CPU does not support.
364 Although this situation is not a problem when QEMU uses software
365 emulation of the feature, it can be a problem when QEMU is
366 running with KVM enabled.
367 Specifically, software compiled with a certain CPU feature crashes
368 when run on a CPU under KVM that does not support that feature.
369 To work around this problem, you can override QEMU's runtime CPU
370 setting by changing the <filename>QB_CPU_KVM</filename>
371 variable in <filename>qemuboot.conf</filename> in the
372 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory's</ulink>
373 <filename>deploy/image</filename> directory.
374 This setting specifies a <filename>-cpu</filename> option
375 passed into QEMU in the <filename>runqemu</filename> script.
376 Running <filename>qemu -cpu help</filename> returns a list of
377 available supported CPU types.
378 </para>
379 </section>
380
381 <section id='qemu-dev-performance'>
382 <title>QEMU Performance</title>
383
384 <para>
385 Using QEMU to emulate your hardware can result in speed issues
386 depending on the target and host architecture mix.
387 For example, using the <filename>qemux86</filename> image in the
388 emulator on an Intel-based 32-bit (x86) host machine is fast
389 because the target and host architectures match.
390 On the other hand, using the <filename>qemuarm</filename> image
391 on the same Intel-based host can be slower.
392 But, you still achieve faithful emulation of ARM-specific issues.
393 </para>
394
395 <para>
396 To speed things up, the QEMU images support using
397 <filename>distcc</filename> to call a cross-compiler outside the
398 emulated system.
399 If you used <filename>runqemu</filename> to start QEMU, and the
400 <filename>distccd</filename> application is present on the host
401 system, any BitBake cross-compiling toolchain available from the
402 build system is automatically used from within QEMU simply by
403 calling <filename>distcc</filename>.
404 You can accomplish this by defining the cross-compiler variable
405 (e.g. <filename>export CC="distcc"</filename>).
406 Alternatively, if you are using a suitable SDK image or the
407 appropriate stand-alone toolchain is present, the toolchain is
408 also automatically used.
409 <note>
410 Several mechanisms exist that let you connect to the system
411 running on the QEMU emulator:
412 <itemizedlist>
413 <listitem><para>
414 QEMU provides a framebuffer interface that makes
415 standard consoles available.
416 </para></listitem>
417 <listitem><para>
418 Generally, headless embedded devices have a serial port.
419 If so, you can configure the operating system of the
420 running image to use that port to run a console.
421 The connection uses standard IP networking.
422 </para></listitem>
423 <listitem><para>
424 SSH servers exist in some QEMU images.
425 The <filename>core-image-sato</filename> QEMU image
426 has a Dropbear secure shell (SSH) server that runs
427 with the root password disabled.
428 The <filename>core-image-full-cmdline</filename> and
429 <filename>core-image-lsb</filename> QEMU images
430 have OpenSSH instead of Dropbear.
431 Including these SSH servers allow you to use standard
432 <filename>ssh</filename> and <filename>scp</filename>
433 commands.
434 The <filename>core-image-minimal</filename> QEMU image,
435 however, contains no SSH server.
436 </para></listitem>
437 <listitem><para>
438 You can use a provided, user-space NFS server to boot
439 the QEMU session using a local copy of the root
440 filesystem on the host.
441 In order to make this connection, you must extract a
442 root filesystem tarball by using the
443 <filename>runqemu-extract-sdk</filename> command.
444 After running the command, you must then point the
445 <filename>runqemu</filename>
446 script to the extracted directory instead of a root
447 filesystem image file.
448 See the
449 "<link linkend='qemu-running-under-a-network-file-system-nfs-server'>Running Under a Network File System (NFS) Server</link>"
450 section for more information.
451 </para></listitem>
452 </itemizedlist>
453 </note>
454 </para>
455 </section>
456
457 <section id='qemu-dev-command-line-syntax'>
458 <title>QEMU Command-Line Syntax</title>
459
460 <para>
461 The basic <filename>runqemu</filename> command syntax is as
462 follows:
463 <literallayout class='monospaced'>
464 $ runqemu [<replaceable>option</replaceable> ] [...]
465 </literallayout>
466 Based on what you provide on the command line,
467 <filename>runqemu</filename> does a good job of figuring out what
468 you are trying to do.
469 For example, by default, QEMU looks for the most recently built
470 image according to the timestamp when it needs to look for an
471 image.
472 Minimally, through the use of options, you must provide either
473 a machine name, a virtual machine image
474 (<filename>*wic.vmdk</filename>), or a kernel image
475 (<filename>*.bin</filename>).
476 </para>
477
478 <para>
479 Following is the command-line help output for the
480 <filename>runqemu</filename> command:
481 <literallayout class='monospaced'>
482 $ runqemu --help
483
484 Usage: you can run this script with any valid combination
485 of the following environment variables (in any order):
486 KERNEL - the kernel image file to use
487 ROOTFS - the rootfs image file or nfsroot directory to use
488 MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)
489 Simplified QEMU command-line options can be passed with:
490 nographic - disable video console
491 serial - enable a serial console on /dev/ttyS0
492 slirp - enable user networking, no root privileges is required
493 kvm - enable KVM when running x86/x86_64 (VT-capable CPU required)
494 kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required)
495 publicvnc - enable a VNC server open to all hosts
496 audio - enable audio
497 [*/]ovmf* - OVMF firmware file or base name for booting with UEFI
498 tcpserial=&lt;port&gt; - specify tcp serial port number
499 biosdir=&lt;dir&gt; - specify custom bios dir
500 biosfilename=&lt;filename&gt; - specify bios filename
501 qemuparams=&lt;xyz&gt; - specify custom parameters to QEMU
502 bootparams=&lt;xyz&gt; - specify custom kernel parameters during boot
503 help, -h, --help: print this text
504
505 Examples:
506 runqemu
507 runqemu qemuarm
508 runqemu tmp/deploy/images/qemuarm
509 runqemu tmp/deploy/images/qemux86/&lt;qemuboot.conf&gt;
510 runqemu qemux86-64 core-image-sato ext4
511 runqemu qemux86-64 wic-image-minimal wic
512 runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial
513 runqemu qemux86 iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz...
514 runqemu qemux86 qemuparams="-m 256"
515 runqemu qemux86 bootparams="psplash=false"
516 runqemu path/to/&lt;image&gt;-&lt;machine&gt;.wic
517 runqemu path/to/&lt;image&gt;-&lt;machine&gt;.wic.vmdk
518 </literallayout>
519 </para>
520 </section>
521
522 <section id='qemu-dev-runqemu-command-line-options'>
523 <title><filename>runqemu</filename> Command-Line Options</title>
524
525 <para>
526 Following is a description of <filename>runqemu</filename>
527 options you can provide on the command line:
528 <note><title>Tip</title>
529 If you do provide some "illegal" option combination or perhaps
530 you do not provide enough in the way of options,
531 <filename>runqemu</filename> provides appropriate error
532 messaging to help you correct the problem.
533 </note>
534 <itemizedlist>
535 <listitem><para>
536 <replaceable>QEMUARCH</replaceable>:
537 The QEMU machine architecture, which must be "qemuarm",
538 "qemuarm64", "qemumips", "qemumips64", "qemuppc",
539 "qemux86", or "qemux86-64".
540 </para></listitem>
541 <listitem><para>
542 <filename><replaceable>VM</replaceable></filename>:
543 The virtual machine image, which must be a
544 <filename>.wic.vmdk</filename> file.
545 Use this option when you want to boot a
546 <filename>.wic.vmdk</filename> image.
547 The image filename you provide must contain one of the
548 following strings: "qemux86-64", "qemux86", "qemuarm",
549 "qemumips64", "qemumips", "qemuppc", or "qemush4".
550 </para></listitem>
551 <listitem><para>
552 <replaceable>ROOTFS</replaceable>:
553 A root filesystem that has one of the following
554 filetype extensions: "ext2", "ext3", "ext4", "jffs2",
555 "nfs", or "btrfs".
556 If the filename you provide for this option uses “nfs”, it
557 must provide an explicit root filesystem path.
558 </para></listitem>
559 <listitem><para>
560 <replaceable>KERNEL</replaceable>:
561 A kernel image, which is a <filename>.bin</filename> file.
562 When you provide a <filename>.bin</filename> file,
563 <filename>runqemu</filename> detects it and assumes the
564 file is a kernel image.
565 </para></listitem>
566 <listitem><para>
567 <replaceable>MACHINE</replaceable>:
568 The architecture of the QEMU machine, which must be one
569 of the following: "qemux86", "qemux86-64", "qemuarm",
570 "qemuarm64", "qemumips", “qemumips64", or "qemuppc".
571 The <replaceable>MACHINE</replaceable> and
572 <replaceable>QEMUARCH</replaceable> options are basically
573 identical.
574 If you do not provide a <replaceable>MACHINE</replaceable>
575 option, <filename>runqemu</filename> tries to determine
576 it based on other options.
577 </para></listitem>
578 <listitem><para>
579 <filename>ramfs</filename>:
580 Indicates you are booting an initial RAM disk (initramfs)
581 image, which means the <filename>FSTYPE</filename> is
582 <filename>cpio.gz</filename>.
583 </para></listitem>
584 <listitem><para>
585 <filename>iso</filename>:
586 Indicates you are booting an ISO image, which means the
587 <filename>FSTYPE</filename> is
588 <filename>.iso</filename>.
589 </para></listitem>
590 <listitem><para>
591 <filename>nographic</filename>:
592 Disables the video console, which sets the console to
593 "ttys0".
Brad Bishop19323692019-04-05 15:28:33 -0400594 This option is useful when you have logged into a server
595 and you do not want to disable forwarding from the
596 X Window System (X11) to your workstation or laptop.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400597 </para></listitem>
598 <listitem><para>
599 <filename>serial</filename>:
600 Enables a serial console on
601 <filename>/dev/ttyS0</filename>.
602 </para></listitem>
603 <listitem><para>
604 <filename>biosdir</filename>:
605 Establishes a custom directory for BIOS, VGA BIOS and
606 keymaps.
607 </para></listitem>
608 <listitem><para>
609 <filename>biosfilename</filename>:
610 Establishes a custom BIOS name.
611 </para></listitem>
612 <listitem><para>
613 <filename>qemuparams=\"<replaceable>xyz</replaceable>\"</filename>:
614 Specifies custom QEMU parameters.
615 Use this option to pass options other than the simple
616 "kvm" and "serial" options.
617 </para></listitem>
618 <listitem><para><filename>bootparams=\"<replaceable>xyz</replaceable>\"</filename>:
619 Specifies custom boot parameters for the kernel.
620 </para></listitem>
621 <listitem><para>
622 <filename>audio</filename>:
623 Enables audio in QEMU.
624 The <replaceable>MACHINE</replaceable> option must be
625 either "qemux86" or "qemux86-64" in order for audio to be
626 enabled.
627 Additionally, the <filename>snd_intel8x0</filename>
628 or <filename>snd_ens1370</filename> driver must be
629 installed in linux guest.
630 </para></listitem>
631 <listitem><para>
632 <filename>slirp</filename>:
633 Enables "slirp" networking, which is a different way
634 of networking that does not need root access
635 but also is not as easy to use or comprehensive
636 as the default.
637 </para></listitem>
638 <listitem><para id='kvm-cond'>
639 <filename>kvm</filename>:
640 Enables KVM when running "qemux86" or "qemux86-64"
641 QEMU architectures.
642 For KVM to work, all the following conditions must be met:
643 <itemizedlist>
644 <listitem><para>
645 Your <replaceable>MACHINE</replaceable> must be either
646qemux86" or "qemux86-64".
647 </para></listitem>
648 <listitem><para>
649 Your build host has to have the KVM modules
650 installed, which are
651 <filename>/dev/kvm</filename>.
652 </para></listitem>
653 <listitem><para>
654 The build host <filename>/dev/kvm</filename>
655 directory has to be both writable and readable.
656 </para></listitem>
657 </itemizedlist>
658 </para></listitem>
659 <listitem><para>
660 <filename>kvm-vhost</filename>:
661 Enables KVM with VHOST support when running "qemux86"
662 or "qemux86-64" QEMU architectures.
663 For KVM with VHOST to work, the following conditions must
664 be met:
665 <itemizedlist>
666 <listitem><para>
667 <link linkend='kvm-cond'>kvm</link> option
668 conditions must be met.
669 </para></listitem>
670 <listitem><para>
671 Your build host has to have virtio net device, which
672 are <filename>/dev/vhost-net</filename>.
673 </para></listitem>
674 <listitem><para>
675 The build host <filename>/dev/vhost-net</filename>
676 directory has to be either readable or writable
677 and “slirp-enabled”.
678 </para></listitem>
679 </itemizedlist>
680 </para></listitem>
681 <listitem><para>
682 <filename>publicvnc</filename>:
683 Enables a VNC server open to all hosts.
684 </para></listitem>
685 </itemizedlist>
686 </para>
687 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500688</chapter>
689<!--
690vim: expandtab tw=80 ts=4
691-->