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 | 433 |
1 files changed, 433 insertions, 0 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 new file mode 100644 index 000000000..41c18298a --- /dev/null +++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml @@ -0,0 +1,433 @@ +<!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> + Quick EMUlator (QEMU) is an Open Source project the Yocto Project uses + as part of its development "tool set". + As such, the information in this chapter is limited to the + Yocto Project integration of QEMU and not QEMU in general. + For official information and documentation on QEMU, 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> + +<para> + This chapter provides an overview of the Yocto Project's integration of + QEMU, a description of how you use QEMU and its various options, running + under a Network File System (NFS) server, and a few tips and tricks you + might find helpful when using QEMU. +</para> + +<section id='qemu-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. + </para> + + <para> + QEMU is made available with the Yocto Project a number of ways. + One method is to install a Software Development Kit (SDK). + For more information on how to make sure you have + QEMU available, see the + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. + </para> +</section> + +<section id='qemu-running-qemu'> + <title>Running QEMU</title> + + <para> + Running QEMU involves having your build environment set up, having the + right artifacts available, and understanding how to use the many + options that are available to you when you start QEMU using the + <filename>runqemu</filename> command. + </para> + + <section id='qemu-setting-up-the-environment'> + <title>Setting Up the Environment</title> + + <para> + You run QEMU in the same environment from which you run BitBake. + This means you need to source a build environment script (i.e. + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> + or + <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>). + </para> + </section> + + <section id='qemu-using-the-runqemu-command'> + <title>Using the <filename>runqemu</filename> Command</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>*.vmdk</filename>), or a kernel image + (<filename>*.bin</filename>). + </para> + + <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 "qemux86", + "qemux86_64", "qemuarm", "qemumips", "qemumipsel", + “qemumips64", "qemush4", "qemuppc", "qemumicroblaze", + or "qemuzynq". + </para></listitem> + <listitem><para><filename><replaceable>VM</replaceable></filename>: + The virtual machine image, which must be a + <filename>.vmdk</filename> file. + Use this option when you want to boot a + <filename>.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", "qemumips", "qemumipsel", + “qemumips64", "qemush4", "qemuppc", "qemumicroblaze", + or "qemuzynq". + 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> + + <para> + For further understanding regarding option use with + <filename>runqemu</filename>, consider some examples. + </para> + + <para> + This example starts QEMU with + <replaceable>MACHINE</replaceable> set to "qemux86". + Assuming a standard + <link linkend='build-directory'>Build Directory</link>, + <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> + 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> + 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> + 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> + This example specifies to boot a virtual machine image + (<filename>.vmdk</filename> file). + From the <filename>.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.vmdk + </literallayout> + </para> + </section> +</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. + This section describes how to set up for running QEMU using an NFS + server and then how you can start and stop the server. + </para> + + <section id='qemu-setting-up-to-use-nfs'> + <title>Setting Up to Use NFS</title> + + <para> + 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 + <filename>runqemu</filename> script. + The <filename>runqemu-extract-sdk</filename> takes a root + file system tarball and extracts it into a location that you + specify. + Then, when you run <filename>runqemu</filename>, you can specify + the location that has the file system to pass it to QEMU. + 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> + 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> + </section> + + <section id='qemu-starting-and-stopping-nfs'> + <title>Starting and Stopping NFS</title> + + <para> + You can manually start and stop the NFS share using these + commands: + <itemizedlist> + <listitem><para><emphasis><filename>start</filename>:</emphasis> + Starts the NFS share: + <literallayout class='monospaced'> + runqemu-export-rootfs start <replaceable>file-system-location</replaceable> + </literallayout> + </para></listitem> + <listitem><para><emphasis><filename>stop</filename>:</emphasis> + Stops the NFS share: + <literallayout class='monospaced'> + runqemu-export-rootfs stop <replaceable>file-system-location</replaceable> + </literallayout> + </para></listitem> + <listitem><para><emphasis><filename>restart</filename>:</emphasis> + Restarts the NFS share: + <literallayout class='monospaced'> + runqemu-export-rootfs restart <replaceable>file-system-location</replaceable> + </literallayout> + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + +<section id='qemu-tips-and-tricks'> + <title>Tips and Tricks</title> + + <para> + The following list describes things you can do to make running QEMU + in the context of the Yocto Project a better experience: + <itemizedlist> + <listitem><para><emphasis>Switching Between Consoles:</emphasis> + 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></listitem> + <listitem><para><emphasis>Removing the Splash Screen:</emphasis> + 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></listitem> + <listitem><para><emphasis>Disabling the Cursor Grab:</emphasis> + 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></listitem> + </itemizedlist> + </para> +</section> + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> |
