diff options
Diffstat (limited to 'documentation/dev-manual/dev-manual-qemu.xml')
| -rw-r--r-- | documentation/dev-manual/dev-manual-qemu.xml | 691 |
1 files changed, 0 insertions, 691 deletions
diff --git a/documentation/dev-manual/dev-manual-qemu.xml b/documentation/dev-manual/dev-manual-qemu.xml deleted file mode 100644 index 46fe67bab0..0000000000 --- a/documentation/dev-manual/dev-manual-qemu.xml +++ /dev/null @@ -1,691 +0,0 @@ -<!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=<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". - 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 ---> |