diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2014-07-09 21:13:56 +0300 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-08-02 10:00:26 +0100 |
commit | 3152e693837e72d08a2eda58bb81eefcd4150250 (patch) | |
tree | 540a3baa5b39920432e52ce4da67f82db4d020a1 /documentation/dev-manual | |
parent | 5f31e281ec28a48e2bb91ec34a729242a9c601a1 (diff) | |
download | ast2050-yocto-poky-3152e693837e72d08a2eda58bb81eefcd4150250.zip ast2050-yocto-poky-3152e693837e72d08a2eda58bb81eefcd4150250.tar.gz |
dev-manual: Created new chapter on QEMU.
Fixes [YOCTO #641]
New chapter added that covers the YP instance of QEMU.
(From yocto-docs rev: 7ca17d02364af7e5924e23df6c138ab4dd2203d6)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r-- | documentation/dev-manual/dev-manual-qemu.xml | 332 | ||||
-rw-r--r-- | documentation/dev-manual/dev-manual.xml | 2 |
2 files changed, 313 insertions, 21 deletions
diff --git a/documentation/dev-manual/dev-manual-qemu.xml b/documentation/dev-manual/dev-manual-qemu.xml index 17bbc27..d206c11 100644 --- a/documentation/dev-manual/dev-manual-qemu.xml +++ b/documentation/dev-manual/dev-manual-qemu.xml @@ -4,13 +4,13 @@ <chapter id='dev-manual-qemu'> -<title>Using the Quick EMUlator</title> +<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 "toolset". + as part of its development "tool set". As such, the information in this chapter is limited to the - Yocto Project instatiation of QEMU and not QEMU in general. + Yocto Project integration of QEMU and not QEMU in general. For official information and documentation on QEMU, see the following references: <itemizedlist> @@ -24,9 +24,10 @@ </para> <para> - This chapter provides an overview of the Yocto Project instantiation of - QEMU, a description of how you use QEMU and its various options and modes, - and a few tips and tricks you might find helpful when using QEMU. + 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'> @@ -39,6 +40,9 @@ 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> @@ -80,11 +84,14 @@ The basic <filename>runqemu</filename> command syntax is as follows: <literallayout class='monospaced'> - $ runqemu [<replaceable>option</replaceable> ] [<replaceable>option</replaceable> ] [...] + $ runqemu [<replaceable>option</replaceable> ] [...] </literallayout> - <filename>runqemu</filename> does a good job based on what you - provide with the command at figuring out what you are trying - to do. + 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 @@ -92,35 +99,318 @@ </para> <para> - If you do provide some "illegal" combination or options or perhaps - do not provide enough in the way of options, - <filename>runqemu</filename> provides appropriate error messaging - to help you figure it out. - </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><emphasis><replaceable>QEMUARCH</replaceable>:</emphasis> - The QEMU machine architecture, which can be "qemux86", + <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>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><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> + 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/kvm</filename> + directory has to be both writable and readable. + </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-modes'> - <title>Modes</title> +<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> diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml index b89e2b3..d7e3177 100644 --- a/documentation/dev-manual/dev-manual.xml +++ b/documentation/dev-manual/dev-manual.xml @@ -106,6 +106,8 @@ <xi:include href="dev-manual-common-tasks.xml"/> + <xi:include href="dev-manual-qemu.xml"/> + </book> <!-- vim: expandtab tw=80 ts=4 |