diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml index c81818840a..5517a7541c 100644 --- a/documentation/ref-manual/usingpoky.xml +++ b/documentation/ref-manual/usingpoky.xml @@ -1049,6 +1049,287 @@ +
+ Quick EMUlator (QEMU) + + + The Yocto Project uses an implementation of the Quick EMUlator (QEMU) + Open Source project as part of the Yocto Project development "tool + set". + + This implementation is not the same as QEMU in general. + + This section provides a brief reference for the Yocto Project + implementation of QEMU. + + + + For official information and documentation on QEMU in general, see the + following references: + + + QEMU Website: + The official website for the QEMU Open Source project. + + + Documentation: + The QEMU user manual. + + + + + + For information on how to use the Yocto Project implementation of + QEMU, see the + "Using the Quick EMUlator (QEMU)" + chapter in the Yocto Project Development Manual. + + +
+ QEMU Availability + + + 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 QEMU Emulator" + section in the Yocto Project Software Development Kit (SDK) + Developer's Guide. + +
+ +
+ QEMU Command-Line Syntax + + + 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 the command-line help output for the + runqemu command: + + $ runqemu --help + + Usage: you can run this script with any valid combination + of the following environment variables (in any order): + KERNEL - the kernel image file to use + ROOTFS - the rootfs image file or nfsroot directory to use + MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified) + Simplified QEMU command-line options can be passed with: + nographic - disable video console + serial - enable a serial console on /dev/ttyS0 + slirp - enable user networking, no root privileges is required + kvm - enable KVM when running x86/x86_64 (VT-capable CPU required) + kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required) + publicvnc - enable a VNC server open to all hosts + audio - enable audio + [*/]ovmf* - OVMF firmware file or base name for booting with UEFI + tcpserial=<port> - specify tcp serial port number + biosdir=<dir> - specify custom bios dir + biosfilename=<filename> - specify bios filename + qemuparams=<xyz> - specify custom parameters to QEMU + bootparams=<xyz> - specify custom kernel parameters during boot + help, -h, --help: print this text + + Examples: + runqemu + runqemu qemuarm + runqemu tmp/deploy/images/qemuarm + runqemu tmp/deploy/images/qemux86/<qemuboot.conf> + runqemu qemux86-64 core-image-sato ext4 + runqemu qemux86-64 wic-image-minimal wic + runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial + runqemu qemux86 iso/hddimg/vmdk/qcow2/vdi/ramfs/cpio.gz... + runqemu qemux86 qemuparams="-m 256" + runqemu qemux86 bootparams="psplash=false" + runqemu path/to/<image>-<machine>.vmdk + runqemu path/to/<image>-<machine>.wic + + +
+ +
+ <filename>runqemu</filename> Command-Line Options + + + 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. + + + 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: + + + Your MACHINE must be either +qemux86" or "qemux86-64". + + + Your build host has to have the KVM modules + installed, which are + /dev/kvm. + + + The build host /dev/kvm + directory has to be both writable and readable. + + + + + 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: + + + kvm option + conditions must be met. + + + Your build host has to have virtio net device, which + are /dev/vhost-net. + + + 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. + + + +
+
+
Maintaining Build Output Quality