summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-qemu.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-qemu.xml')
-rw-r--r--documentation/dev-manual/dev-manual-qemu.xml358
1 files changed, 351 insertions, 7 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
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-10 09:19:13 +0000