diff options
| author |   ToshikazuOhiwa <toshikazu_ohiwa@mail.toyota.co.jp> | 2020-03-30 09:24:26 +0900 |
|---|---|---|
| committer | ToshikazuOhiwa <toshikazu_ohiwa@mail.toyota.co.jp> | 2020-03-30 09:24:26 +0900 |
| commit | 5b80bfd7bffd4c20d80b7c70a7130529e9a755dd (patch) | |
| tree | b4bb18dcd1487dbf1ea8127e5671b7bb2eded033 /external/poky/documentation/dev-manual/dev-manual-qemu.xml | |
| parent | 706ad73eb02caf8532deaf5d38995bd258725cb8 (diff) | |
agl-basesystem
Diffstat (limited to 'external/poky/documentation/dev-manual/dev-manual-qemu.xml')
| -rw-r--r-- | external/poky/documentation/dev-manual/dev-manual-qemu.xml | 687 |
1 files changed, 687 insertions, 0 deletions
diff --git a/external/poky/documentation/dev-manual/dev-manual-qemu.xml b/external/poky/documentation/dev-manual/dev-manual-qemu.xml new file mode 100644 index 00000000..4e7b5de4 --- /dev/null +++ b/external/poky/documentation/dev-manual/dev-manual-qemu.xml @@ -0,0 +1,687 @@ +<!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; ] > + +<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". + Assuming a standard + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, + <filename>runqemu</filename> automatically finds the + <filename>bzImage-qemux86.bin</filename> image file and + the + <filename>core-image-minimal-qemux86-20140707074611.rootfs.ext3</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 + </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 core-image-minimal ext3 + </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 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 ext3 + </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" and the root filesystem type to be "vmdk". + <literallayout class='monospaced'> + $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86.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/core-image-sato-qemux86.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 ./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". + </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 +--> |