diff --git a/documentation/dev-manual/dev-manual-qemu.xml b/documentation/dev-manual/dev-manual-qemu.xml index 17bbc2774a..d206c111ed 100644 --- a/documentation/dev-manual/dev-manual-qemu.xml +++ b/documentation/dev-manual/dev-manual-qemu.xml @@ -4,13 +4,13 @@ -Using the Quick EMUlator +Using the Quick EMUlator (QEMU) 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: @@ -24,9 +24,10 @@ - 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.
@@ -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. @@ -80,47 +84,333 @@ The basic runqemu command syntax is as follows: - $ runqemu [option ] [option ] [...] + $ runqemu [option ] [...] - runqemu 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, + runqemu 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 (*.vmdk), or a kernel image (*.bin). - - If you do provide some "illegal" combination or options or perhaps - do not provide enough in the way of options, - runqemu provides appropriate error messaging - to help you figure it out. - - Following is a description of runqemu options you can provide on the command line: + Tip + If you do provide some "illegal" option combination or perhaps + you do not provide enough in the way of options, + runqemu provides appropriate error + messaging to help you correct the problem. + - QEMUARCH: - The QEMU machine architecture, which can be "qemux86", + QEMUARCH: + The QEMU machine architecture, which must be "qemux86", "qemux86-64", "qemuarm", "qemumips", "qemumipsel", “qemumips64", "qemush4", "qemuppc", "qemumicroblaze", or "qemuzynq". + VM: + The virtual machine image, which must be a + .vmdk file. + Use this option when you want to boot a + .vmdk image. + The image filename you provide must contain one of the + following strings: "qemux86-64", "qemux86", "qemuarm", + "qemumips64", "qemumips", "qemuppc", or "qemush4". + + ROOTFS: + 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. + + KERNEL: + A kernel image, which is a .bin file. + When you provide a .bin file, + runqemu detects it and assumes the + file is a kernel image. + + MACHINE: + 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 MACHINE and + QEMUARCH options are basically + identical. + If you do not provide a MACHINE + option, runqemu tries to determine + it based on other options. + + ramfs: + Indicates you are booting an initial RAM disk (initramfs) + image, which means the FSTYPE is + cpio.gz. + + iso: + Indicates you are booting an ISO image, which means the + FSTYPE is + .iso. + + nographic: + Disables the video console, which sets the console to + "ttys0". + + serial: + Enables a serial console on + /dev/ttyS0. + + biosdir: + Establishes a custom directory for BIOS, VGA BIOS and + keymaps. + + qemuparams=\"xyz\": + Specifies custom QEMU parameters. + Use this option to pass options other than the simple + "kvm" and "serial" options. + + bootparams=\"xyz\": + Specifies custom boot parameters for the kernel. + + audio: + Enables audio in QEMU. + The MACHINE option must be + either "qemux86" or "qemux86-64" in order for audio to be + enabled. + Additionally, the snd_intel8x0 + or snd_ens1370 driver must be + installed in linux guest. + + slirp: + 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. + + kvm: + Enables KVM when running "qemux86" or "qemux86-64" + QEMU architectures. + For KVM to work, all the following conditions must be met: + + + Your MACHINE must be either + "qemux86" or "qemux86-64". + + + Your build host has to have the KVM modules + installed, which are + /dev/kvm. + + + Your build host has to have virtio net device, which + are /dev/vhost-net. + + + The build host /dev/kvm + directory has to be both writable and readable. + + + The build host /dev/vhost-net + directory has to be either readable or writable + and “slirp-enabled”. + + + + publicvnc: + Enables a VNC server open to all hosts. + + + + + + For further understanding regarding option use with + runqemu, consider some examples. + + + + This example starts QEMU with + MACHINE set to "qemux86". + Assuming a standard + Build Directory, + runqemu automatically finds the + bzImage-qemux86.bin image file and + the + core-image-minimal-qemux86-20140707074611.rootfs.ext3 + (assuming the current build created a + core-image-minimal image). + + When more than one image with the same name exists, QEMU finds + and uses the most recently built image according to the + timestamp. + + + $ runqemu qemux86 + + This example produces the exact same results as the + previous example. + This command, however, specifically provides the image + and root filesystem type. + + $ runqemu qemux86 core-image-minimal ext3 + + This example specifies to boot an initial RAM disk image + and to enable audio in QEMU. + For this case, runqemu set the + internal variable FSTYPE to + "cpio.gz". + Also, for audio to be enabled, an appropriate driver must + be installed (see the previous description for the + audio option for more information). + + $ runqemu qemux86 ramfs audio + + 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 + MACHINE, + KERNEL, or + VM option. + + $ runqemu ext3 + + This example specifies to boot a virtual machine image + (.vmdk file). + From the .vmdk, + runqemu determines the QEMU + architecture (MACHINE) to be + "qemux86" and the root filesystem type to be "vmdk". + + $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86.vmdk + + +
+ + +
+ Running Under a Network File System (NFS) Server + + + 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. + + +
+ Setting Up to Use NFS + + + Once you are able to run QEMU in your environment, you can use the + runqemu-extract-sdk script, which is located + in the scripts directory along with + runqemu script. + The runqemu-extract-sdk takes a root + file system tarball and extracts it into a location that you + specify. + Then, when you run runqemu, 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 test-nfs: + + runqemu-extract-sdk ./tmp/deploy/images/qemux86/core-image-sato-qemux86.tar.bz2 test-nfs + + Once you have extracted the file system, you can run + runqemu normally with the additional + location of the file system. + You can then also make changes to the files within + ./test-nfs and see those changes appear in the + image in real time. + Here is an example using the qemux86 image: + + runqemu qemux86 ./test-nfs + + +
+ +
+ Starting and Stopping NFS + + + You can manually start and stop the NFS share using these + commands: + + start: + Starts the NFS share: + + runqemu-export-rootfs start <file-system-location> + + + stop: + Stops the NFS share: + + runqemu-export-rootfs stop <file-system-location> + + + restart: + Restarts the NFS share: + + runqemu-export-rootfs restart <file-system-location> + +
-
- Modes - -
-
Tips and Tricks + + The following list describes things you can do to make running QEMU + in the context of the Yocto Project a better experience: + + Switching Between Consoles: + When booting or running QEMU, you can switch between + supported consoles by using + Ctrl+Alt+<number>. + 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. + + Usually, "2" gets you to the main console and "3" gets you + to the serial console. + + + Removing the Splash Screen: + 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. + + Disabling the Cursor Grab: + 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. + + +
diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml index b89e2b357e..d7e3177af8 100644 --- a/documentation/dev-manual/dev-manual.xml +++ b/documentation/dev-manual/dev-manual.xml @@ -106,6 +106,8 @@ + +