summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-qemu.xml
blob: 1a526dd2f52c20f440ef209764896146cf620f0f (plain)
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
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
<!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; ] >
<!--SPDX-License-Identifier: CC-BY-2.0-UK-->

<chapter id='dev-manual-qemu'>

<title>Using the Quick EMUlator (QEMU)</title>

    <para>
        The Yocto Project uses an implementation of the Quick EMUlator (QEMU)
        Open Source project as part of the Yocto Project development "tool
        set".
        This chapter provides both procedures that show you how to use the
        Quick EMUlator (QEMU) and other QEMU information helpful for
        development purposes.
    </para>

    <section id='qemu-dev-overview'>
        <title>Overview</title>

        <para>
            Within the context of the Yocto Project, QEMU is an
            emulator and virtualization machine that allows you to run a
            complete image you have built using the Yocto Project as just
            another task on your build system.
            QEMU is useful for running and testing images and applications on
            supported Yocto Project architectures without having actual
            hardware.
            Among other things, the Yocto Project uses QEMU to run automated
            Quality Assurance (QA) tests on final images shipped with each
            release.
            <note>
                This implementation is not the same as QEMU in general.
            </note>
            This section provides a brief reference for the Yocto Project
            implementation of QEMU.
        </para>

        <para>
            For official information and documentation on QEMU in general, see
            the following references:
            <itemizedlist>
                <listitem><para>
                    <emphasis><ulink url='http://wiki.qemu.org/Main_Page'>QEMU Website</ulink>:</emphasis>
                    The official website for the QEMU Open Source project.
                    </para></listitem>
                <listitem><para>
                    <emphasis><ulink url='http://wiki.qemu.org/Manual'>Documentation</ulink>:</emphasis>
                    The QEMU user manual.
                    </para></listitem>
            </itemizedlist>
        </para>
    </section>

    <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>
                    QEMU is made available with the Yocto Project a number of
                    ways.
                    One method is to install a Software Development Kit (SDK).
                    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-64".
                            Assuming a standard
                            <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
                            <filename>runqemu</filename> automatically finds the
                            <filename>bzImage-qemux86-64.bin</filename> image file and
                            the
                            <filename>core-image-minimal-qemux86-64-20200218002850.rootfs.ext4</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-64
                            </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-64 core-image-minimal ext4
                            </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-64 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 ext4
                            </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-64" and the root filesystem type to be "vmdk".
                            <literallayout class='monospaced'>
     $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86-64.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-64/core-image-sato-qemux86-64.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-64 ./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>

    <section id='qemu-kvm-cpu-compatibility'>
        <title>QEMU CPU Compatibility Under KVM</title>

        <para>
            By default, the QEMU build compiles for and targets 64-bit and x86
            <trademark class='registered'>Intel</trademark> <trademark class='trademark'>Core</trademark>2
            Duo processors and 32-bit x86
            <trademark class='registered'>Intel</trademark> <trademark class='registered'>Pentium</trademark>
            II processors.
            QEMU builds for and targets these CPU types because they display
            a broad range of CPU feature compatibility with many commonly
            used CPUs.
        </para>

        <para>
            Despite this broad range of compatibility, the CPUs could support
            a feature that your host CPU does not support.
            Although this situation is not a problem when QEMU uses software
            emulation of the feature, it can be a problem when QEMU is
            running with KVM enabled.
            Specifically, software compiled with a certain CPU feature crashes
            when run on a CPU under KVM that does not support that feature.
            To work around this problem, you can override QEMU's runtime CPU
            setting by changing the <filename>QB_CPU_KVM</filename>
            variable in <filename>qemuboot.conf</filename> in the
            <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory's</ulink>
            <filename>deploy/image</filename> directory.
            This setting specifies a <filename>-cpu</filename> option
            passed into QEMU in the <filename>runqemu</filename> script.
            Running <filename>qemu -cpu help</filename> returns a list of
            available supported CPU types.
        </para>
    </section>

    <section id='qemu-dev-performance'>
        <title>QEMU Performance</title>

        <para>
            Using QEMU to emulate your hardware can result in speed issues
            depending on the target and host architecture mix.
            For example, using the <filename>qemux86</filename> image in the
            emulator on an Intel-based 32-bit (x86) host machine is fast
            because the target and host architectures match.
            On the other hand, using the <filename>qemuarm</filename> image
            on the same Intel-based host can be slower.
            But, you still achieve faithful emulation of ARM-specific issues.
        </para>

        <para>
            To speed things up, the QEMU images support using
            <filename>distcc</filename> to call a cross-compiler outside the
            emulated system.
            If you used <filename>runqemu</filename> to start QEMU, and the
            <filename>distccd</filename> application is present on the host
            system, any BitBake cross-compiling toolchain available from the
            build system is automatically used from within QEMU simply by
            calling <filename>distcc</filename>.
            You can accomplish this by defining the cross-compiler variable
            (e.g. <filename>export CC="distcc"</filename>).
            Alternatively, if you are using a suitable SDK image or the
            appropriate stand-alone toolchain is present, the toolchain is
            also automatically used.
            <note>
                Several mechanisms exist that let you connect to the system
                running on the QEMU emulator:
                <itemizedlist>
                    <listitem><para>
                        QEMU provides a framebuffer interface that makes
                        standard consoles available.
                        </para></listitem>
                    <listitem><para>
                        Generally, headless embedded devices have a serial port.
                        If so, you can configure the operating system of the
                        running image to use that port to run a console.
                        The connection uses standard IP networking.
                        </para></listitem>
                    <listitem><para>
                        SSH servers exist in some QEMU images.
                        The <filename>core-image-sato</filename> QEMU image
                        has a Dropbear secure shell (SSH) server that runs
                        with the root password disabled.
                        The <filename>core-image-full-cmdline</filename> and
                        <filename>core-image-lsb</filename> QEMU images
                        have OpenSSH instead of Dropbear.
                        Including these SSH servers allow you to use standard
                        <filename>ssh</filename> and <filename>scp</filename>
                        commands.
                        The <filename>core-image-minimal</filename> QEMU image,
                        however, contains no SSH server.
                        </para></listitem>
                    <listitem><para>
                        You can use a provided, user-space NFS server to boot
                        the QEMU session using a local copy of the root
                        filesystem on the host.
                        In order to make this connection, you must extract a
                        root filesystem tarball by using the
                        <filename>runqemu-extract-sdk</filename> command.
                        After running the command, you must then point the
                        <filename>runqemu</filename>
                        script to the extracted directory instead of a root
                        filesystem image file.
                        See the
                        "<link linkend='qemu-running-under-a-network-file-system-nfs-server'>Running Under a Network File System (NFS) Server</link>"
                        section for more information.
                        </para></listitem>
                </itemizedlist>
            </note>
        </para>
    </section>

    <section id='qemu-dev-command-line-syntax'>
        <title>QEMU Command-Line Syntax</title>

        <para>
            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>
            Following is the command-line help output for the
            <filename>runqemu</filename> command:
            <literallayout class='monospaced'>
     $ runqemu --help

     Usage: you can run this script with any valid combination
     of the following environment variables (in any order):
       KERNEL - the kernel image file to use
       ROOTFS - the rootfs image file or nfsroot directory to use
       MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)
       Simplified QEMU command-line options can be passed with:
         nographic - disable video console
         serial - enable a serial console on /dev/ttyS0
         slirp - enable user networking, no root privileges is required
         kvm - enable KVM when running x86/x86_64 (VT-capable CPU required)
         kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required)
         publicvnc - enable a VNC server open to all hosts
         audio - enable audio
         [*/]ovmf* - OVMF firmware file or base name for booting with UEFI
       tcpserial=&lt;port&gt; - specify tcp serial port number
       biosdir=&lt;dir&gt; - specify custom bios dir
       biosfilename=&lt;filename&gt; - specify bios filename
       qemuparams=&lt;xyz&gt; - specify custom parameters to QEMU
       bootparams=&lt;xyz&gt; - specify custom kernel parameters during boot
       help, -h, --help: print this text

     Examples:
       runqemu
       runqemu qemuarm
       runqemu tmp/deploy/images/qemuarm
       runqemu tmp/deploy/images/qemux86/&lt;qemuboot.conf&gt;
       runqemu qemux86-64 core-image-sato ext4
       runqemu qemux86-64 wic-image-minimal wic
       runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial
       runqemu qemux86 iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz...
       runqemu qemux86 qemuparams="-m 256"
       runqemu qemux86 bootparams="psplash=false"
       runqemu path/to/&lt;image&gt;-&lt;machine&gt;.wic
       runqemu path/to/&lt;image&gt;-&lt;machine&gt;.wic.vmdk
            </literallayout>
        </para>
    </section>

    <section id='qemu-dev-runqemu-command-line-options'>
        <title><filename>runqemu</filename> Command-Line Options</title>

        <para>
            Following is a description of <filename>runqemu</filename>
            options you can provide on the command line:
            <note><title>Tip</title>
                If you do provide some "illegal" option combination or perhaps
                you do not provide enough in the way of options,
                <filename>runqemu</filename> provides appropriate error
                messaging to help you correct the problem.
            </note>
            <itemizedlist>
                <listitem><para>
                    <replaceable>QEMUARCH</replaceable>:
                    The QEMU machine architecture, which must be "qemuarm",
                    "qemuarm64", "qemumips", "qemumips64", "qemuppc",
                    "qemux86", or "qemux86-64".
                    </para></listitem>
                <listitem><para>
                    <filename><replaceable>VM</replaceable></filename>:
                    The virtual machine image, which must be a
                    <filename>.wic.vmdk</filename> file.
                    Use this option when you want to boot a
                    <filename>.wic.vmdk</filename> image.
                    The image filename you provide must contain one of the
                    following strings: "qemux86-64", "qemux86", "qemuarm",
                    "qemumips64", "qemumips", "qemuppc", or "qemush4".
                    </para></listitem>
                <listitem><para>
                    <replaceable>ROOTFS</replaceable>:
                    A root filesystem that has one of the following
                    filetype extensions: "ext2", "ext3", "ext4", "jffs2",
                    "nfs", or "btrfs".
                    If the filename you provide for this option uses "nfs", it
                    must provide an explicit root filesystem path.
                    </para></listitem>
                <listitem><para>
                    <replaceable>KERNEL</replaceable>:
                    A kernel image, which is a <filename>.bin</filename> file.
                    When you provide a <filename>.bin</filename> file,
                    <filename>runqemu</filename> detects it and assumes the
                    file is a kernel image.
                    </para></listitem>
                <listitem><para>
                    <replaceable>MACHINE</replaceable>:
                    The architecture of the QEMU machine, which must be one
                    of the following: "qemux86", "qemux86-64", "qemuarm",
                    "qemuarm64", "qemumips", "qemumips64", or "qemuppc".
                    The <replaceable>MACHINE</replaceable> and
                    <replaceable>QEMUARCH</replaceable> options are basically
                    identical.
                    If you do not provide a <replaceable>MACHINE</replaceable>
                    option, <filename>runqemu</filename> tries to determine
                    it based on other options.
                    </para></listitem>
                <listitem><para>
                    <filename>ramfs</filename>:
                    Indicates you are booting an initial RAM disk (initramfs)
                    image, which means the <filename>FSTYPE</filename> is
                    <filename>cpio.gz</filename>.
                    </para></listitem>
                <listitem><para>
                    <filename>iso</filename>:
                    Indicates you are booting an ISO image, which means the
                    <filename>FSTYPE</filename> is
                    <filename>.iso</filename>.
                    </para></listitem>
                <listitem><para>
                    <filename>nographic</filename>:
                    Disables the video console, which sets the console to
                    "ttys0".
                    This option is useful when you have logged into a server
                    and you do not want to disable forwarding from the
                    X Window System (X11) to your workstation or laptop.
                    </para></listitem>
                <listitem><para>
                    <filename>serial</filename>:
                    Enables a serial console on
                    <filename>/dev/ttyS0</filename>.
                    </para></listitem>
                <listitem><para>
                    <filename>biosdir</filename>:
                    Establishes a custom directory for BIOS, VGA BIOS and
                    keymaps.
                    </para></listitem>
                <listitem><para>
                    <filename>biosfilename</filename>:
                    Establishes a custom BIOS name.
                    </para></listitem>
                <listitem><para>
                    <filename>qemuparams=\"<replaceable>xyz</replaceable>\"</filename>:
                    Specifies custom QEMU parameters.
                    Use this option to pass options other than the simple
                    "kvm" and "serial" options.
                    </para></listitem>
                <listitem><para><filename>bootparams=\"<replaceable>xyz</replaceable>\"</filename>:
                    Specifies custom boot parameters for the kernel.
                    </para></listitem>
                <listitem><para>
                    <filename>audio</filename>:
                    Enables audio in QEMU.
                    The <replaceable>MACHINE</replaceable> option must be
                    either "qemux86" or "qemux86-64" in order for audio to be
                    enabled.
                    Additionally, the <filename>snd_intel8x0</filename>
                    or <filename>snd_ens1370</filename> driver must be
                    installed in linux guest.
                    </para></listitem>
                <listitem><para>
                    <filename>slirp</filename>:
                    Enables "slirp" networking, which is a different way
                    of networking that does not need root access
                    but also is not as easy to use or comprehensive
                    as the default.
                    </para></listitem>
                <listitem><para id='kvm-cond'>
                    <filename>kvm</filename>:
                    Enables KVM when running "qemux86" or "qemux86-64"
                    QEMU architectures.
                    For KVM to work, all the following conditions must be met:
                    <itemizedlist>
                        <listitem><para>
                            Your <replaceable>MACHINE</replaceable> must be either
qemux86" or "qemux86-64".
                            </para></listitem>
                        <listitem><para>
                            Your build host has to have the KVM modules
                            installed, which are
                            <filename>/dev/kvm</filename>.
                            </para></listitem>
                        <listitem><para>
                            The  build host <filename>/dev/kvm</filename>
                            directory has to be both writable and readable.
                            </para></listitem>
                    </itemizedlist>
                    </para></listitem>
                <listitem><para>
                    <filename>kvm-vhost</filename>:
                    Enables KVM with VHOST support when running "qemux86"
                    or "qemux86-64" QEMU architectures.
                    For KVM with VHOST to work, the following conditions must
                    be met:
                    <itemizedlist>
                        <listitem><para>
                            <link linkend='kvm-cond'>kvm</link> option
                            conditions must be met.
                            </para></listitem>
                        <listitem><para>
                            Your build host has to have virtio net device, which
                            are <filename>/dev/vhost-net</filename>.
                            </para></listitem>
                        <listitem><para>
                            The build host <filename>/dev/vhost-net</filename>
                            directory has to be either readable or writable
                            and "slirp-enabled".
                            </para></listitem>
                    </itemizedlist>
                    </para></listitem>
                <listitem><para>
                    <filename>publicvnc</filename>:
                    Enables a VNC server open to all hosts.
                    </para></listitem>
            </itemizedlist>
        </para>
    </section>
</chapter>
<!--
vim: expandtab tw=80 ts=4
-->