From 2217d97ba9f48ded4f229981ed4ad7e846b87db0 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 18 Jul 2017 10:15:33 -0700 Subject: dev-manual, ref-manual: Re-wrote QEMU section. Fixes [YOCTO #11630] I converted the QEMU section to a procedure. Also took the tips section and created individual sections from that. Cleaned up some areas in the QEMU conceptual section in the ref-manual (From yocto-docs rev: dfd3466be605fdd7438653bf54fd0df3594a5c50) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-qemu.xml | 618 +++++++++++---------------- documentation/ref-manual/usingpoky.xml | 12 + 2 files changed, 261 insertions(+), 369 deletions(-) diff --git a/documentation/dev-manual/dev-manual-qemu.xml b/documentation/dev-manual/dev-manual-qemu.xml index a8f5c01265..ed4040ca60 100644 --- a/documentation/dev-manual/dev-manual-qemu.xml +++ b/documentation/dev-manual/dev-manual-qemu.xml @@ -6,425 +6,305 @@ Using the Quick EMUlator (QEMU) - - 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: - - QEMU Website: - The official website for the QEMU Open Source project. - - Documentation: - The QEMU user manual. - - - - - - 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. - - -
- Overview - - - 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. - - - 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 - Yocto Project Software Development Kit (SDK) Developer's Guide. + This chapter provides procedures that show you how to use the + Quick EMUlator (QEMU), which is an Open Source project the Yocto + Project uses as part of its development "tool set". + For reference information on the Yocto Project implementation of QEMU, + see the + "Quick EMUlator (QEMU)" + section in the Yocto Project Reference Manual. -
-
- Running QEMU - - - 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 - runqemu command. - - -
- Setting Up the Environment +
+ Running QEMU - You run QEMU in the same environment from which you run BitBake. - This means you need to source a build environment script (i.e. - &OE_INIT_FILE; - or - oe-init-build-env-memres). - -
- -
- Using the <filename>runqemu</filename> Command - - - The basic runqemu command syntax is as - follows: - - $ runqemu [option ] [...] - - 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). - - - - 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 must be "qemuarm", - "qemuarm64", "qemumips", "qemumips64", "qemuppc", - "qemux86", or "qemux86-64". - - 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. + 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: + + + Install QEMU: + See + "The QEMU Emulator" + section in the Yocto Project Software Development Kit (SDK) + Developer's Guide for information on how to install + QEMU. - MACHINE: - The architecture of the QEMU machine, which must be one - of the following: "qemux86", - "qemux86", "qemux86-64", "qemuarm", "qemuarm64", - "qemumips", “qemumips64", or "qemuppc". - 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. - - biosfilename: - Establishes a custom BIOS name. - - 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: + + Setting Up the Environment: + How you set up the QEMU environment depends on how you + installed QEMU: - Your MACHINE must be either -qemux86" or "qemux86-64". + If you cloned the poky + repository or you downloaded and unpacked a + Yocto Project release tarball, you can source + the build environment script (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres): + + $ cd ~/poky + $ source oe-init-build-env + - Your build host has to have the KVM modules - installed, which are - /dev/kvm. + 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 + poky_sdk directory: + + . ~/poky_sdk/environment-setup-core2-64-poky-linux + + + + + Ensure the Artifacts are in Place: + 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: + - The build host /dev/kvm - directory has to be both writable and readable. + If you have previously built an image for QEMU + (e.g. qemux86, + qemuarm, and so forth), + then the artifacts are in place in your + Build Directory. - + + If you have not built an image, you can go to the + machines/qemu + area and download a pre-built image that matches + your architecture and can be run on QEMU. + + + + See the + "Extracting the Root Filesystem" + section in the Yocto Project Software Development Kit (SDK) + Developer's Guide for information on how to extract a + root filesystem. - kvm-vhost: - 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: + + Run QEMU: + The basic runqemu command syntax is as + follows: + + $ runqemu [option ] [...] + + 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). + + Here are some additional examples to help illustrate + further QEMU: - kvm option - conditions must be met. + 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 + - Your build host has to have virtio net device, which - are /dev/vhost-net. + 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 + - The build host /dev/vhost-net - directory has to be either readable or writable - and “slirp-enabled”. + 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 + - publicvnc: - Enables a VNC server open to all hosts. - - + +
- - For further understanding regarding option use with - runqemu, consider some examples. - +
+ Switching Between Consoles - 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 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. - When more than one image with the same name exists, QEMU finds - and uses the most recently built image according to the - timestamp. + Usually, "2" gets you to the main console and "3" + gets you to the serial console. - - $ 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 +
+ Removing the Splash Screen - - 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. - + + 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. + +
-
- Setting Up to Use NFS +
+ Disabling the Cursor Grab - 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 - + 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.
-
- Starting and Stopping NFS +
+ Running Under a Network File System (NFS) Server - You can manually start and stop the NFS share using these - commands: - - start: - Starts the NFS share: + 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. + + + Extract a Root Filesystem: + 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 the runqemu + script. + + The runqemu-extract-sdk 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 + test-nfs: - runqemu-export-rootfs start file-system-location + runqemu-extract-sdk ./tmp/deploy/images/qemux86/core-image-sato-qemux86.tar.bz2 test-nfs - stop: - Stops the NFS share: + + Start QEMU: + 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-export-rootfs stop file-system-location + runqemu qemux86 ./test-nfs - restart: - Restarts the NFS share: - + + + + Should you need to start, stop, or restart the NFS share, + you can use the following commands: + + + The following command starts the NFS share: + + runqemu-export-rootfs start file-system-location + + + + The following command stops the NFS share: + + runqemu-export-rootfs stop file-system-location + + + + The following command restarts the NFS share: + runqemu-export-rootfs restart file-system-location - - - + + + + +
-
- -
- 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. - - - -
-