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