From c6f881446153676de4ecbd467e6834eed4199b5e Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 22 Jan 2018 16:13:34 -0800 Subject: ref-manual, dev-manual: Moved QEMU info from ref-manual to dev-manual Fixes [YOCTO #12370] The QEMU information in the ref-manual "using" chapter has been moved to the dev-manual's chapter 5, which is a dedicated QEMU chapter. Some information is reference and that is why I had it separated out into the reference manual. However, pressures are mounting to get that stuff out of the ref-manual and into the dev-manual. So, it has been moved. (From yocto-docs rev: 69098ad83b10fab341ec3d5532e377dcfbbfc05e) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-qemu.xml | 358 +++++++++++++++++++++++++- documentation/ref-manual/usingpoky.xml | 370 --------------------------- 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 @@ Using the Quick EMUlator (QEMU) - 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 - "Quick EMUlator (QEMU)" - 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. +
+ Overview + + + 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. + + This implementation is not the same as QEMU in general. + + This section provides a brief reference for the Yocto Project + implementation of QEMU. + + + + For official information and documentation on QEMU in general, see + the following references: + + + QEMU Website: + The official website for the QEMU Open Source project. + + + Documentation: + The QEMU user manual. + + + +
+
Running QEMU @@ -27,6 +63,9 @@ Install QEMU: + QEMU is made available with the Yocto Project a number of + ways. + One method is to install a Software Development Kit (SDK). See "The QEMU Emulator" section in the Yocto Project Application Development and @@ -303,6 +342,311 @@
+ +
+ QEMU Performance + + + Using QEMU to emulate your hardware can result in speed issues + depending on the target and host architecture mix. + For example, using the qemux86 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 qemuarm image + on the same Intel-based host can be slower. + But, you still achieve faithful emulation of ARM-specific issues. + + + + To speed things up, the QEMU images support using + distcc to call a cross-compiler outside the + emulated system. + If you used runqemu to start QEMU, and the + distccd 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 distcc. + You can accomplish this by defining the cross-compiler variable + (e.g. export CC="distcc"). + Alternatively, if you are using a suitable SDK image or the + appropriate stand-alone toolchain is present, the toolchain is + also automatically used. + + Several mechanisms exist that let you connect to the system + running on the QEMU emulator: + + + QEMU provides a framebuffer interface that makes + standard consoles available. + + + 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. + + + SSH servers exist in some QEMU images. + The core-image-sato QEMU image + has a Dropbear secure shell (SSH) server that runs + with the root password disabled. + The core-image-full-cmdline and + core-image-lsb QEMU images + have OpenSSH instead of Dropbear. + Including these SSH servers allow you to use standard + ssh and scp + commands. + The core-image-minimal QEMU image, + however, contains no SSH server. + + + 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 + runqemu-extract-sdk command. + After running the command, you must then point the + runqemu + script to the extracted directory instead of a root + filesystem image file. + See the + "Running Under a Network File System (NFS) Server" + section for more information. + + + + +
+ +
+ QEMU Command-Line Syntax + + + The basic runqemu command syntax is as + follows: + + $ runqemu [option ] [...] + + Based on what you provide on the command line, + runqemu 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 + (*wic.vmdk), or a kernel image + (*.bin). + + + + Following is the command-line help output for the + runqemu command: + + $ 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 + + +
+ +
+ <filename>runqemu</filename> Command-Line Options + + + Following is a description of runqemu + options you can provide on the command line: + Tip + If you do provide some "illegal" option combination or perhaps + you do not provide enough in the way of options, + runqemu provides appropriate error + messaging to help you correct the problem. + + + + QEMUARCH: + The QEMU machine architecture, which must be "qemuarm", + "qemuarm64", "qemumips", "qemumips64", "qemuppc", + "qemux86", or "qemux86-64". + + + VM: + The virtual machine image, which must be a + .wic.vmdk file. + Use this option when you want to boot a + .wic.vmdk image. + The image filename you provide must contain one of the + following strings: "qemux86-64", "qemux86", "qemuarm", + "qemumips64", "qemumips", "qemuppc", or "qemush4". + + + ROOTFS: + 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. + + + KERNEL: + A kernel image, which is a .bin file. + When you provide a .bin file, + runqemu detects it and assumes the + file is a kernel image. + + + MACHINE: + The architecture of the QEMU machine, which must be one + of the following: "qemux86", "qemux86-64", "qemuarm", + "qemuarm64", "qemumips", “qemumips64", or "qemuppc". + The MACHINE and + QEMUARCH options are basically + identical. + If you do not provide a MACHINE + option, runqemu tries to determine + it based on other options. + + + ramfs: + Indicates you are booting an initial RAM disk (initramfs) + image, which means the FSTYPE is + cpio.gz. + + + iso: + Indicates you are booting an ISO image, which means the + FSTYPE is + .iso. + + + nographic: + Disables the video console, which sets the console to + "ttys0". + + + serial: + Enables a serial console on + /dev/ttyS0. + + + biosdir: + Establishes a custom directory for BIOS, VGA BIOS and + keymaps. + + + biosfilename: + Establishes a custom BIOS name. + + + qemuparams=\"xyz\": + Specifies custom QEMU parameters. + Use this option to pass options other than the simple + "kvm" and "serial" options. + + bootparams=\"xyz\": + Specifies custom boot parameters for the kernel. + + + audio: + Enables audio in QEMU. + The MACHINE option must be + either "qemux86" or "qemux86-64" in order for audio to be + enabled. + Additionally, the snd_intel8x0 + or snd_ens1370 driver must be + installed in linux guest. + + + slirp: + 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. + + + kvm: + Enables KVM when running "qemux86" or "qemux86-64" + QEMU architectures. + For KVM to work, all the following conditions must be met: + + + Your MACHINE must be either +qemux86" or "qemux86-64". + + + Your build host has to have the KVM modules + installed, which are + /dev/kvm. + + + The build host /dev/kvm + directory has to be both writable and readable. + + + + + kvm-vhost: + 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: + + + kvm option + conditions must be met. + + + Your build host has to have virtio net device, which + are /dev/vhost-net. + + + The build host /dev/vhost-net + directory has to be either readable or writable + and “slirp-enabled”. + + + + + publicvnc: + Enables a VNC server open to all hosts. + + + +