diff options
Diffstat (limited to 'import-layers/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml')
| -rw-r--r-- | import-layers/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml | 392 |
1 files changed, 385 insertions, 7 deletions
diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml index 85e731587..4e7b5de4e 100644 --- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml +++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml @@ -7,15 +7,51 @@ <title>Using the Quick EMUlator (QEMU)</title> <para> - This chapter provides procedures that show you how to use the - Quick EMUlator (QEMU), which is an Open Source project the Yocto - Project uses as part of its development "tool set". - For reference information on the Yocto Project implementation of QEMU, - see the - "<ulink url='&YOCTO_DOCS_REF_URL;#ref-quick-emulator-qemu'>Quick EMUlator (QEMU)</ulink>" - section in the Yocto Project Reference Manual. + 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> @@ -27,6 +63,9 @@ <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 @@ -303,6 +342,345 @@ </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=<port> - specify tcp serial port number + biosdir=<dir> - specify custom bios dir + biosfilename=<filename> - specify bios filename + qemuparams=<xyz> - specify custom parameters to QEMU + bootparams=<xyz> - 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/<qemuboot.conf> + 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/<image>-<machine>.wic + runqemu path/to/<image>-<machine>.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". + </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 |
