diff options
Diffstat (limited to 'yocto-poky/documentation/dev-manual/dev-manual-qemu.xml')
-rw-r--r-- | yocto-poky/documentation/dev-manual/dev-manual-qemu.xml | 433 |
1 files changed, 0 insertions, 433 deletions
diff --git a/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml b/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml deleted file mode 100644 index 41c18298a..000000000 --- a/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml +++ /dev/null @@ -1,433 +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; ] > - -<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 ---> |