summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-qemu.xml358
-rw-r--r--documentation/ref-manual/usingpoky.xml370
2 files changed, 351 insertions, 377 deletions
diff --git a/documentation/dev-manual/dev-manual-qemu.xml b/documentation/dev-manual/dev-manual-qemu.xml
index 85e7315872..f4719ebc3c 100644
--- a/documentation/dev-manual/dev-manual-qemu.xml
+++ b/documentation/dev-manual/dev-manual-qemu.xml
@@ -7,15 +7,51 @@
7<title>Using the Quick EMUlator (QEMU)</title> 7<title>Using the Quick EMUlator (QEMU)</title>
8 8
9 <para> 9 <para>
10 This chapter provides procedures that show you how to use the 10 The Yocto Project uses an implementation of the Quick EMUlator (QEMU)
11 Quick EMUlator (QEMU), which is an Open Source project the Yocto 11 Open Source project as part of the Yocto Project development "tool
12 Project uses as part of its development "tool set". 12 set".
13 For reference information on the Yocto Project implementation of QEMU, 13 This chapter provides both procedures that show you how to use the
14 see the 14 Quick EMUlator (QEMU) and other QEMU information helpful for
15 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-quick-emulator-qemu'>Quick EMUlator (QEMU)</ulink>" 15 development purposes.
16 section in the Yocto Project Reference Manual.
17 </para> 16 </para>
18 17
18 <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
19 <section id='qemu-running-qemu'> 55 <section id='qemu-running-qemu'>
20 <title>Running QEMU</title> 56 <title>Running QEMU</title>
21 57
@@ -27,6 +63,9 @@
27 <orderedlist> 63 <orderedlist>
28 <listitem><para> 64 <listitem><para>
29 <emphasis>Install QEMU:</emphasis> 65 <emphasis>Install QEMU:</emphasis>
66 QEMU is made available with the Yocto Project a number of
67 ways.
68 One method is to install a Software Development Kit (SDK).
30 See 69 See
31 "<ulink url='&YOCTO_DOCS_SDK_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>" 70 "<ulink url='&YOCTO_DOCS_SDK_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>"
32 section in the Yocto Project Application Development and 71 section in the Yocto Project Application Development and
@@ -303,6 +342,311 @@
303 </note> 342 </note>
304 </para> 343 </para>
305 </section> 344 </section>
345
346 <section id='qemu-dev-performance'>
347 <title>QEMU Performance</title>
348
349 <para>
350 Using QEMU to emulate your hardware can result in speed issues
351 depending on the target and host architecture mix.
352 For example, using the <filename>qemux86</filename> image in the
353 emulator on an Intel-based 32-bit (x86) host machine is fast
354 because the target and host architectures match.
355 On the other hand, using the <filename>qemuarm</filename> image
356 on the same Intel-based host can be slower.
357 But, you still achieve faithful emulation of ARM-specific issues.
358 </para>
359
360 <para>
361 To speed things up, the QEMU images support using
362 <filename>distcc</filename> to call a cross-compiler outside the
363 emulated system.
364 If you used <filename>runqemu</filename> to start QEMU, and the
365 <filename>distccd</filename> application is present on the host
366 system, any BitBake cross-compiling toolchain available from the
367 build system is automatically used from within QEMU simply by
368 calling <filename>distcc</filename>.
369 You can accomplish this by defining the cross-compiler variable
370 (e.g. <filename>export CC="distcc"</filename>).
371 Alternatively, if you are using a suitable SDK image or the
372 appropriate stand-alone toolchain is present, the toolchain is
373 also automatically used.
374 <note>
375 Several mechanisms exist that let you connect to the system
376 running on the QEMU emulator:
377 <itemizedlist>
378 <listitem><para>
379 QEMU provides a framebuffer interface that makes
380 standard consoles available.
381 </para></listitem>
382 <listitem><para>
383 Generally, headless embedded devices have a serial port.
384 If so, you can configure the operating system of the
385 running image to use that port to run a console.
386 The connection uses standard IP networking.
387 </para></listitem>
388 <listitem><para>
389 SSH servers exist in some QEMU images.
390 The <filename>core-image-sato</filename> QEMU image
391 has a Dropbear secure shell (SSH) server that runs
392 with the root password disabled.
393 The <filename>core-image-full-cmdline</filename> and
394 <filename>core-image-lsb</filename> QEMU images
395 have OpenSSH instead of Dropbear.
396 Including these SSH servers allow you to use standard
397 <filename>ssh</filename> and <filename>scp</filename>
398 commands.
399 The <filename>core-image-minimal</filename> QEMU image,
400 however, contains no SSH server.
401 </para></listitem>
402 <listitem><para>
403 You can use a provided, user-space NFS server to boot
404 the QEMU session using a local copy of the root
405 filesystem on the host.
406 In order to make this connection, you must extract a
407 root filesystem tarball by using the
408 <filename>runqemu-extract-sdk</filename> command.
409 After running the command, you must then point the
410 <filename>runqemu</filename>
411 script to the extracted directory instead of a root
412 filesystem image file.
413 See the
414 "<link linkend='qemu-running-under-a-network-file-system-nfs-server'>Running Under a Network File System (NFS) Server</link>"
415 section for more information.
416 </para></listitem>
417 </itemizedlist>
418 </note>
419 </para>
420 </section>
421
422 <section id='qemu-dev-command-line-syntax'>
423 <title>QEMU Command-Line Syntax</title>
424
425 <para>
426 The basic <filename>runqemu</filename> command syntax is as
427 follows:
428 <literallayout class='monospaced'>
429 $ runqemu [<replaceable>option</replaceable> ] [...]
430 </literallayout>
431 Based on what you provide on the command line,
432 <filename>runqemu</filename> does a good job of figuring out what
433 you are trying to do.
434 For example, by default, QEMU looks for the most recently built
435 image according to the timestamp when it needs to look for an
436 image.
437 Minimally, through the use of options, you must provide either
438 a machine name, a virtual machine image
439 (<filename>*wic.vmdk</filename>), or a kernel image
440 (<filename>*.bin</filename>).
441 </para>
442
443 <para>
444 Following is the command-line help output for the
445 <filename>runqemu</filename> command:
446 <literallayout class='monospaced'>
447 $ runqemu --help
448
449 Usage: you can run this script with any valid combination
450 of the following environment variables (in any order):
451 KERNEL - the kernel image file to use
452 ROOTFS - the rootfs image file or nfsroot directory to use
453 MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)
454 Simplified QEMU command-line options can be passed with:
455 nographic - disable video console
456 serial - enable a serial console on /dev/ttyS0
457 slirp - enable user networking, no root privileges is required
458 kvm - enable KVM when running x86/x86_64 (VT-capable CPU required)
459 kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required)
460 publicvnc - enable a VNC server open to all hosts
461 audio - enable audio
462 [*/]ovmf* - OVMF firmware file or base name for booting with UEFI
463 tcpserial=&lt;port&gt; - specify tcp serial port number
464 biosdir=&lt;dir&gt; - specify custom bios dir
465 biosfilename=&lt;filename&gt; - specify bios filename
466 qemuparams=&lt;xyz&gt; - specify custom parameters to QEMU
467 bootparams=&lt;xyz&gt; - specify custom kernel parameters during boot
468 help, -h, --help: print this text
469
470 Examples:
471 runqemu
472 runqemu qemuarm
473 runqemu tmp/deploy/images/qemuarm
474 runqemu tmp/deploy/images/qemux86/&lt;qemuboot.conf&gt;
475 runqemu qemux86-64 core-image-sato ext4
476 runqemu qemux86-64 wic-image-minimal wic
477 runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial
478 runqemu qemux86 iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz...
479 runqemu qemux86 qemuparams="-m 256"
480 runqemu qemux86 bootparams="psplash=false"
481 runqemu path/to/&lt;image&gt;-&lt;machine&gt;.wic
482 runqemu path/to/&lt;image&gt;-&lt;machine&gt;.wic.vmdk
483 </literallayout>
484 </para>
485 </section>
486
487 <section id='qemu-dev-runqemu-command-line-options'>
488 <title><filename>runqemu</filename> Command-Line Options</title>
489
490 <para>
491 Following is a description of <filename>runqemu</filename>
492 options you can provide on the command line:
493 <note><title>Tip</title>
494 If you do provide some "illegal" option combination or perhaps
495 you do not provide enough in the way of options,
496 <filename>runqemu</filename> provides appropriate error
497 messaging to help you correct the problem.
498 </note>
499 <itemizedlist>
500 <listitem><para>
501 <replaceable>QEMUARCH</replaceable>:
502 The QEMU machine architecture, which must be "qemuarm",
503 "qemuarm64", "qemumips", "qemumips64", "qemuppc",
504 "qemux86", or "qemux86-64".
505 </para></listitem>
506 <listitem><para>
507 <filename><replaceable>VM</replaceable></filename>:
508 The virtual machine image, which must be a
509 <filename>.wic.vmdk</filename> file.
510 Use this option when you want to boot a
511 <filename>.wic.vmdk</filename> image.
512 The image filename you provide must contain one of the
513 following strings: "qemux86-64", "qemux86", "qemuarm",
514 "qemumips64", "qemumips", "qemuppc", or "qemush4".
515 </para></listitem>
516 <listitem><para>
517 <replaceable>ROOTFS</replaceable>:
518 A root filesystem that has one of the following
519 filetype extensions: "ext2", "ext3", "ext4", "jffs2",
520 "nfs", or "btrfs".
521 If the filename you provide for this option uses “nfs”, it
522 must provide an explicit root filesystem path.
523 </para></listitem>
524 <listitem><para>
525 <replaceable>KERNEL</replaceable>:
526 A kernel image, which is a <filename>.bin</filename> file.
527 When you provide a <filename>.bin</filename> file,
528 <filename>runqemu</filename> detects it and assumes the
529 file is a kernel image.
530 </para></listitem>
531 <listitem><para>
532 <replaceable>MACHINE</replaceable>:
533 The architecture of the QEMU machine, which must be one
534 of the following: "qemux86", "qemux86-64", "qemuarm",
535 "qemuarm64", "qemumips", “qemumips64", or "qemuppc".
536 The <replaceable>MACHINE</replaceable> and
537 <replaceable>QEMUARCH</replaceable> options are basically
538 identical.
539 If you do not provide a <replaceable>MACHINE</replaceable>
540 option, <filename>runqemu</filename> tries to determine
541 it based on other options.
542 </para></listitem>
543 <listitem><para>
544 <filename>ramfs</filename>:
545 Indicates you are booting an initial RAM disk (initramfs)
546 image, which means the <filename>FSTYPE</filename> is
547 <filename>cpio.gz</filename>.
548 </para></listitem>
549 <listitem><para>
550 <filename>iso</filename>:
551 Indicates you are booting an ISO image, which means the
552 <filename>FSTYPE</filename> is
553 <filename>.iso</filename>.
554 </para></listitem>
555 <listitem><para>
556 <filename>nographic</filename>:
557 Disables the video console, which sets the console to
558 "ttys0".
559 </para></listitem>
560 <listitem><para>
561 <filename>serial</filename>:
562 Enables a serial console on
563 <filename>/dev/ttyS0</filename>.
564 </para></listitem>
565 <listitem><para>
566 <filename>biosdir</filename>:
567 Establishes a custom directory for BIOS, VGA BIOS and
568 keymaps.
569 </para></listitem>
570 <listitem><para>
571 <filename>biosfilename</filename>:
572 Establishes a custom BIOS name.
573 </para></listitem>
574 <listitem><para>
575 <filename>qemuparams=\"<replaceable>xyz</replaceable>\"</filename>:
576 Specifies custom QEMU parameters.
577 Use this option to pass options other than the simple
578 "kvm" and "serial" options.
579 </para></listitem>
580 <listitem><para><filename>bootparams=\"<replaceable>xyz</replaceable>\"</filename>:
581 Specifies custom boot parameters for the kernel.
582 </para></listitem>
583 <listitem><para>
584 <filename>audio</filename>:
585 Enables audio in QEMU.
586 The <replaceable>MACHINE</replaceable> option must be
587 either "qemux86" or "qemux86-64" in order for audio to be
588 enabled.
589 Additionally, the <filename>snd_intel8x0</filename>
590 or <filename>snd_ens1370</filename> driver must be
591 installed in linux guest.
592 </para></listitem>
593 <listitem><para>
594 <filename>slirp</filename>:
595 Enables "slirp" networking, which is a different way
596 of networking that does not need root access
597 but also is not as easy to use or comprehensive
598 as the default.
599 </para></listitem>
600 <listitem><para id='kvm-cond'>
601 <filename>kvm</filename>:
602 Enables KVM when running "qemux86" or "qemux86-64"
603 QEMU architectures.
604 For KVM to work, all the following conditions must be met:
605 <itemizedlist>
606 <listitem><para>
607 Your <replaceable>MACHINE</replaceable> must be either
608qemux86" or "qemux86-64".
609 </para></listitem>
610 <listitem><para>
611 Your build host has to have the KVM modules
612 installed, which are
613 <filename>/dev/kvm</filename>.
614 </para></listitem>
615 <listitem><para>
616 The build host <filename>/dev/kvm</filename>
617 directory has to be both writable and readable.
618 </para></listitem>
619 </itemizedlist>
620 </para></listitem>
621 <listitem><para>
622 <filename>kvm-vhost</filename>:
623 Enables KVM with VHOST support when running "qemux86"
624 or "qemux86-64" QEMU architectures.
625 For KVM with VHOST to work, the following conditions must
626 be met:
627 <itemizedlist>
628 <listitem><para>
629 <link linkend='kvm-cond'>kvm</link> option
630 conditions must be met.
631 </para></listitem>
632 <listitem><para>
633 Your build host has to have virtio net device, which
634 are <filename>/dev/vhost-net</filename>.
635 </para></listitem>
636 <listitem><para>
637 The build host <filename>/dev/vhost-net</filename>
638 directory has to be either readable or writable
639 and “slirp-enabled”.
640 </para></listitem>
641 </itemizedlist>
642 </para></listitem>
643 <listitem><para>
644 <filename>publicvnc</filename>:
645 Enables a VNC server open to all hosts.
646 </para></listitem>
647 </itemizedlist>
648 </para>
649 </section>
306</chapter> 650</chapter>
307<!-- 651<!--
308vim: expandtab tw=80 ts=4 652vim: expandtab tw=80 ts=4
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index 7c2f0f67bc..e379459a20 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -11,376 +11,6 @@
11 documentation set provide more details on how to use the Yocto Project. 11 documentation set provide more details on how to use the Yocto Project.
12 </para> 12 </para>
13 13
14<section id='ref-quick-emulator-qemu'>
15 <title>Quick EMUlator (QEMU)</title>
16
17 <para>
18 The Yocto Project uses an implementation of the Quick EMUlator (QEMU)
19 Open Source project as part of the Yocto Project development "tool
20 set".
21 </para>
22
23 <para>
24 Within the context of the Yocto Project, QEMU is an
25 emulator and virtualization machine that allows you to run a complete
26 image you have built using the Yocto Project as just another task
27 on your build system.
28 QEMU is useful for running and testing images and applications on
29 supported Yocto Project architectures without having actual 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 the
42 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
55 <para>
56 For information on how to use the Yocto Project implementation of
57 QEMU, see the
58 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
59 chapter in the Yocto Project Development Tasks Manual.
60 </para>
61
62 <section id='qemu-availability'>
63 <title>QEMU Availability</title>
64
65 <para>
66 QEMU is made available with the Yocto Project a number of ways.
67 One method is to install a Software Development Kit (SDK).
68 For more information on how to make sure you have
69 QEMU available, see
70 "<ulink url='&YOCTO_DOCS_SDK_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>"
71 section in the Yocto Project Application Development and the
72 Extensible Software Development Kit (eSDK) manual.
73 </para>
74 </section>
75
76 <section id='qemu-performance'>
77 <title>QEMU Performance</title>
78
79 <para>
80 Using QEMU to emulate your hardware can result in speed issues
81 depending on the target and host architecture mix.
82 For example, using the <filename>qemux86</filename> image in the
83 emulator on an Intel-based 32-bit (x86) host machine is fast
84 because the target and host architectures match.
85 On the other hand, using the <filename>qemuarm</filename> image
86 on the same Intel-based host can be slower.
87 But, you still achieve faithful emulation of ARM-specific issues.
88 </para>
89
90 <para>
91 To speed things up, the QEMU images support using
92 <filename>distcc</filename> to call a cross-compiler outside the
93 emulated system.
94 If you used <filename>runqemu</filename> to start QEMU, and the
95 <filename>distccd</filename> application is present on the host
96 system, any BitBake cross-compiling toolchain available from the
97 build system is automatically used from within QEMU simply by
98 calling <filename>distcc</filename>.
99 You can accomplish this by defining the cross-compiler variable
100 (e.g. <filename>export CC="distcc"</filename>).
101 Alternatively, if you are using a suitable SDK image or the
102 appropriate stand-alone toolchain is present, the toolchain is
103 also automatically used.
104 </para>
105
106 <note>
107 Several mechanisms exist that let you connect to the system
108 running on the QEMU emulator:
109 <itemizedlist>
110 <listitem><para>
111 QEMU provides a framebuffer interface that makes standard
112 consoles available.
113 </para></listitem>
114 <listitem><para>
115 Generally, headless embedded devices have a serial port.
116 If so, you can configure the operating system of the
117 running image to use that port to run a console.
118 The connection uses standard IP networking.
119 </para></listitem>
120 <listitem><para>
121 SSH servers exist in some QEMU images.
122 The <filename>core-image-sato</filename> QEMU image has a
123 Dropbear secure shell (SSH) server that runs with the root
124 password disabled.
125 The <filename>core-image-full-cmdline</filename> and
126 <filename>core-image-lsb</filename> QEMU images
127 have OpenSSH instead of Dropbear.
128 Including these SSH servers allow you to use standard
129 <filename>ssh</filename> and <filename>scp</filename>
130 commands.
131 The <filename>core-image-minimal</filename> QEMU image,
132 however, contains no SSH server.
133 </para></listitem>
134 <listitem><para>
135 You can use a provided, user-space NFS server to boot
136 the QEMU session using a local copy of the root
137 filesystem on the host.
138 In order to make this connection, you must extract a
139 root filesystem tarball by using the
140 <filename>runqemu-extract-sdk</filename> command.
141 After running the command, you must then point the
142 <filename>runqemu</filename>
143 script to the extracted directory instead of a root
144 filesystem image file.
145 See the
146 "<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-running-under-a-network-file-system-nfs-server'>Running Under a Network File System (NFS) Server</ulink>"
147 section in the Yocto Project Development Tasks Manual for
148 more information.
149 </para></listitem>
150 </itemizedlist>
151 </note>
152 </section>
153
154 <section id='qemu-command-line-syntax'>
155 <title>QEMU Command-Line Syntax</title>
156
157 <para>
158 The basic <filename>runqemu</filename> command syntax is as
159 follows:
160 <literallayout class='monospaced'>
161 $ runqemu [<replaceable>option</replaceable> ] [...]
162 </literallayout>
163 Based on what you provide on the command line,
164 <filename>runqemu</filename> does a good job of figuring out what
165 you are trying to do.
166 For example, by default, QEMU looks for the most recently built
167 image according to the timestamp when it needs to look for an
168 image.
169 Minimally, through the use of options, you must provide either
170 a machine name, a virtual machine image
171 (<filename>*wic.vmdk</filename>), or a kernel image
172 (<filename>*.bin</filename>).
173 </para>
174
175 <para>
176 Following is the command-line help output for the
177 <filename>runqemu</filename> command:
178 <literallayout class='monospaced'>
179 $ runqemu --help
180
181 Usage: you can run this script with any valid combination
182 of the following environment variables (in any order):
183 KERNEL - the kernel image file to use
184 ROOTFS - the rootfs image file or nfsroot directory to use
185 MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)
186 Simplified QEMU command-line options can be passed with:
187 nographic - disable video console
188 serial - enable a serial console on /dev/ttyS0
189 slirp - enable user networking, no root privileges is required
190 kvm - enable KVM when running x86/x86_64 (VT-capable CPU required)
191 kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required)
192 publicvnc - enable a VNC server open to all hosts
193 audio - enable audio
194 [*/]ovmf* - OVMF firmware file or base name for booting with UEFI
195 tcpserial=&lt;port&gt; - specify tcp serial port number
196 biosdir=&lt;dir&gt; - specify custom bios dir
197 biosfilename=&lt;filename&gt; - specify bios filename
198 qemuparams=&lt;xyz&gt; - specify custom parameters to QEMU
199 bootparams=&lt;xyz&gt; - specify custom kernel parameters during boot
200 help, -h, --help: print this text
201
202 Examples:
203 runqemu
204 runqemu qemuarm
205 runqemu tmp/deploy/images/qemuarm
206 runqemu tmp/deploy/images/qemux86/&lt;qemuboot.conf&gt;
207 runqemu qemux86-64 core-image-sato ext4
208 runqemu qemux86-64 wic-image-minimal wic
209 runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial
210 runqemu qemux86 iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz...
211 runqemu qemux86 qemuparams="-m 256"
212 runqemu qemux86 bootparams="psplash=false"
213 runqemu path/to/&lt;image&gt;-&lt;machine&gt;.wic
214 runqemu path/to/&lt;image&gt;-&lt;machine&gt;.wic.vmdk
215 </literallayout>
216 </para>
217 </section>
218
219 <section id='runqemu-command-line-options'>
220 <title><filename>runqemu</filename> Command-Line Options</title>
221
222 <para>
223 Following is a description of <filename>runqemu</filename>
224 options you can provide on the command line:
225 <note><title>Tip</title>
226 If you do provide some "illegal" option combination or perhaps
227 you do not provide enough in the way of options,
228 <filename>runqemu</filename> provides appropriate error
229 messaging to help you correct the problem.
230 </note>
231 <itemizedlist>
232 <listitem><para>
233 <replaceable>QEMUARCH</replaceable>:
234 The QEMU machine architecture, which must be "qemuarm",
235 "qemuarm64", "qemumips", "qemumips64", "qemuppc",
236 "qemux86", or "qemux86-64".
237 </para></listitem>
238 <listitem><para>
239 <filename><replaceable>VM</replaceable></filename>:
240 The virtual machine image, which must be a
241 <filename>.wic.vmdk</filename> file.
242 Use this option when you want to boot a
243 <filename>.wic.vmdk</filename> image.
244 The image filename you provide must contain one of the
245 following strings: "qemux86-64", "qemux86", "qemuarm",
246 "qemumips64", "qemumips", "qemuppc", or "qemush4".
247 </para></listitem>
248 <listitem><para>
249 <replaceable>ROOTFS</replaceable>:
250 A root filesystem that has one of the following
251 filetype extensions: "ext2", "ext3", "ext4", "jffs2",
252 "nfs", or "btrfs".
253 If the filename you provide for this option uses “nfs”, it
254 must provide an explicit root filesystem path.
255 </para></listitem>
256 <listitem><para>
257 <replaceable>KERNEL</replaceable>:
258 A kernel image, which is a <filename>.bin</filename> file.
259 When you provide a <filename>.bin</filename> file,
260 <filename>runqemu</filename> detects it and assumes the
261 file is a kernel image.
262 </para></listitem>
263 <listitem><para>
264 <replaceable>MACHINE</replaceable>:
265 The architecture of the QEMU machine, which must be one
266 of the following: "qemux86", "qemux86-64", "qemuarm",
267 "qemuarm64", "qemumips", “qemumips64", or "qemuppc".
268 The <replaceable>MACHINE</replaceable> and
269 <replaceable>QEMUARCH</replaceable> options are basically
270 identical.
271 If you do not provide a <replaceable>MACHINE</replaceable>
272 option, <filename>runqemu</filename> tries to determine
273 it based on other options.
274 </para></listitem>
275 <listitem><para>
276 <filename>ramfs</filename>:
277 Indicates you are booting an initial RAM disk (initramfs)
278 image, which means the <filename>FSTYPE</filename> is
279 <filename>cpio.gz</filename>.
280 </para></listitem>
281 <listitem><para>
282 <filename>iso</filename>:
283 Indicates you are booting an ISO image, which means the
284 <filename>FSTYPE</filename> is
285 <filename>.iso</filename>.
286 </para></listitem>
287 <listitem><para>
288 <filename>nographic</filename>:
289 Disables the video console, which sets the console to
290 "ttys0".
291 </para></listitem>
292 <listitem><para>
293 <filename>serial</filename>:
294 Enables a serial console on
295 <filename>/dev/ttyS0</filename>.
296 </para></listitem>
297 <listitem><para>
298 <filename>biosdir</filename>:
299 Establishes a custom directory for BIOS, VGA BIOS and
300 keymaps.
301 </para></listitem>
302 <listitem><para>
303 <filename>biosfilename</filename>:
304 Establishes a custom BIOS name.
305 </para></listitem>
306 <listitem><para>
307 <filename>qemuparams=\"<replaceable>xyz</replaceable>\"</filename>:
308 Specifies custom QEMU parameters.
309 Use this option to pass options other than the simple
310 "kvm" and "serial" options.
311 </para></listitem>
312 <listitem><para><filename>bootparams=\"<replaceable>xyz</replaceable>\"</filename>:
313 Specifies custom boot parameters for the kernel.
314 </para></listitem>
315 <listitem><para>
316 <filename>audio</filename>:
317 Enables audio in QEMU.
318 The <replaceable>MACHINE</replaceable> option must be
319 either "qemux86" or "qemux86-64" in order for audio to be
320 enabled.
321 Additionally, the <filename>snd_intel8x0</filename>
322 or <filename>snd_ens1370</filename> driver must be
323 installed in linux guest.
324 </para></listitem>
325 <listitem><para>
326 <filename>slirp</filename>:
327 Enables "slirp" networking, which is a different way
328 of networking that does not need root access
329 but also is not as easy to use or comprehensive
330 as the default.
331 </para></listitem>
332 <listitem><para id='kvm-cond'>
333 <filename>kvm</filename>:
334 Enables KVM when running "qemux86" or "qemux86-64"
335 QEMU architectures.
336 For KVM to work, all the following conditions must be met:
337 <itemizedlist>
338 <listitem><para>
339 Your <replaceable>MACHINE</replaceable> must be either
340qemux86" or "qemux86-64".
341 </para></listitem>
342 <listitem><para>
343 Your build host has to have the KVM modules
344 installed, which are
345 <filename>/dev/kvm</filename>.
346 </para></listitem>
347 <listitem><para>
348 The build host <filename>/dev/kvm</filename>
349 directory has to be both writable and readable.
350 </para></listitem>
351 </itemizedlist>
352 </para></listitem>
353 <listitem><para>
354 <filename>kvm-vhost</filename>:
355 Enables KVM with VHOST support when running "qemux86"
356 or "qemux86-64" QEMU architectures.
357 For KVM with VHOST to work, the following conditions must
358 be met:
359 <itemizedlist>
360 <listitem><para>
361 <link linkend='kvm-cond'>kvm</link> option
362 conditions must be met.
363 </para></listitem>
364 <listitem><para>
365 Your build host has to have virtio net device, which
366 are <filename>/dev/vhost-net</filename>.
367 </para></listitem>
368 <listitem><para>
369 The build host <filename>/dev/vhost-net</filename>
370 directory has to be either readable or writable
371 and “slirp-enabled”.
372 </para></listitem>
373 </itemizedlist>
374 </para></listitem>
375 <listitem><para>
376 <filename>publicvnc</filename>:
377 Enables a VNC server open to all hosts.
378 </para></listitem>
379 </itemizedlist>
380 </para>
381 </section>
382</section>
383
384<section id='maintaining-build-output-quality'> 14<section id='maintaining-build-output-quality'>
385 <title>Maintaining Build Output Quality</title> 15 <title>Maintaining Build Output Quality</title>
386 16
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-13 14:54:05 +0000