mirror of
https://git.yoctoproject.org/poky
synced 2026-04-22 06:32:12 +02:00
ref-manual, dev-manual: Moved QEMU info from ref-manual to dev-manual
Fixes [YOCTO #12370] The QEMU information in the ref-manual "using" chapter has been moved to the dev-manual's chapter 5, which is a dedicated QEMU chapter. Some information is reference and that is why I had it separated out into the reference manual. However, pressures are mounting to get that stuff out of the ref-manual and into the dev-manual. So, it has been moved. (From yocto-docs rev: 69098ad83b10fab341ec3d5532e377dcfbbfc05e) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
committed by
Richard Purdie
Richard Purdie
parent
0d52f18d39
commit
c6f8814461
@@ -7,15 +7,51 @@
|
||||
<title>Using the Quick EMUlator (QEMU)</title>
|
||||
|
||||
<para>
|
||||
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
|
||||
"<ulink url='&YOCTO_DOCS_REF_URL;#ref-quick-emulator-qemu'>Quick EMUlator (QEMU)</ulink>"
|
||||
section in the Yocto Project Reference Manual.
|
||||
The Yocto Project uses an implementation of the Quick EMUlator (QEMU)
|
||||
Open Source project as part of the Yocto Project development "tool
|
||||
set".
|
||||
This chapter provides both procedures that show you how to use the
|
||||
Quick EMUlator (QEMU) and other QEMU information helpful for
|
||||
development purposes.
|
||||
</para>
|
||||
|
||||
<section id='qemu-dev-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.
|
||||
<note>
|
||||
This implementation is not the same as QEMU in general.
|
||||
</note>
|
||||
This section provides a brief reference for the Yocto Project
|
||||
implementation of QEMU.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For official information and documentation on QEMU in general, 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>
|
||||
</section>
|
||||
|
||||
<section id='qemu-running-qemu'>
|
||||
<title>Running QEMU</title>
|
||||
|
||||
@@ -27,6 +63,9 @@
|
||||
<orderedlist>
|
||||
<listitem><para>
|
||||
<emphasis>Install QEMU:</emphasis>
|
||||
QEMU is made available with the Yocto Project a number of
|
||||
ways.
|
||||
One method is to install a Software Development Kit (SDK).
|
||||
See
|
||||
"<ulink url='&YOCTO_DOCS_SDK_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>"
|
||||
section in the Yocto Project Application Development and
|
||||
@@ -303,6 +342,311 @@
|
||||
</note>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='qemu-dev-performance'>
|
||||
<title>QEMU Performance</title>
|
||||
|
||||
<para>
|
||||
Using QEMU to emulate your hardware can result in speed issues
|
||||
depending on the target and host architecture mix.
|
||||
For example, using the <filename>qemux86</filename> image in the
|
||||
emulator on an Intel-based 32-bit (x86) host machine is fast
|
||||
because the target and host architectures match.
|
||||
On the other hand, using the <filename>qemuarm</filename> image
|
||||
on the same Intel-based host can be slower.
|
||||
But, you still achieve faithful emulation of ARM-specific issues.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To speed things up, the QEMU images support using
|
||||
<filename>distcc</filename> to call a cross-compiler outside the
|
||||
emulated system.
|
||||
If you used <filename>runqemu</filename> to start QEMU, and the
|
||||
<filename>distccd</filename> application is present on the host
|
||||
system, any BitBake cross-compiling toolchain available from the
|
||||
build system is automatically used from within QEMU simply by
|
||||
calling <filename>distcc</filename>.
|
||||
You can accomplish this by defining the cross-compiler variable
|
||||
(e.g. <filename>export CC="distcc"</filename>).
|
||||
Alternatively, if you are using a suitable SDK image or the
|
||||
appropriate stand-alone toolchain is present, the toolchain is
|
||||
also automatically used.
|
||||
<note>
|
||||
Several mechanisms exist that let you connect to the system
|
||||
running on the QEMU emulator:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
QEMU provides a framebuffer interface that makes
|
||||
standard consoles available.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Generally, headless embedded devices have a serial port.
|
||||
If so, you can configure the operating system of the
|
||||
running image to use that port to run a console.
|
||||
The connection uses standard IP networking.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
SSH servers exist in some QEMU images.
|
||||
The <filename>core-image-sato</filename> QEMU image
|
||||
has a Dropbear secure shell (SSH) server that runs
|
||||
with the root password disabled.
|
||||
The <filename>core-image-full-cmdline</filename> and
|
||||
<filename>core-image-lsb</filename> QEMU images
|
||||
have OpenSSH instead of Dropbear.
|
||||
Including these SSH servers allow you to use standard
|
||||
<filename>ssh</filename> and <filename>scp</filename>
|
||||
commands.
|
||||
The <filename>core-image-minimal</filename> QEMU image,
|
||||
however, contains no SSH server.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
You can use a provided, user-space NFS server to boot
|
||||
the QEMU session using a local copy of the root
|
||||
filesystem on the host.
|
||||
In order to make this connection, you must extract a
|
||||
root filesystem tarball by using the
|
||||
<filename>runqemu-extract-sdk</filename> command.
|
||||
After running the command, you must then point the
|
||||
<filename>runqemu</filename>
|
||||
script to the extracted directory instead of a root
|
||||
filesystem image file.
|
||||
See the
|
||||
"<link linkend='qemu-running-under-a-network-file-system-nfs-server'>Running Under a Network File System (NFS) Server</link>"
|
||||
section for more information.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</note>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='qemu-dev-command-line-syntax'>
|
||||
<title>QEMU Command-Line Syntax</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>*wic.vmdk</filename>), or a kernel image
|
||||
(<filename>*.bin</filename>).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Following is the command-line help output for the
|
||||
<filename>runqemu</filename> command:
|
||||
<literallayout class='monospaced'>
|
||||
$ 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/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz...
|
||||
runqemu qemux86 qemuparams="-m 256"
|
||||
runqemu qemux86 bootparams="psplash=false"
|
||||
runqemu path/to/<image>-<machine>.wic
|
||||
runqemu path/to/<image>-<machine>.wic.vmdk
|
||||
</literallayout>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='qemu-dev-runqemu-command-line-options'>
|
||||
<title><filename>runqemu</filename> Command-Line Options</title>
|
||||
|
||||
<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 "qemuarm",
|
||||
"qemuarm64", "qemumips", "qemumips64", "qemuppc",
|
||||
"qemux86", or "qemux86-64".
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<filename><replaceable>VM</replaceable></filename>:
|
||||
The virtual machine image, which must be a
|
||||
<filename>.wic.vmdk</filename> file.
|
||||
Use this option when you want to boot a
|
||||
<filename>.wic.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",
|
||||
"qemuarm64", "qemumips", “qemumips64", or "qemuppc".
|
||||
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>
|
||||
</section>
|
||||
</chapter>
|
||||
<!--
|
||||
vim: expandtab tw=80 ts=4
|
||||
|
||||
@@ -11,376 +11,6 @@
|
||||
documentation set provide more details on how to use the Yocto Project.
|
||||
</para>
|
||||
|
||||
<section id='ref-quick-emulator-qemu'>
|
||||
<title>Quick EMUlator (QEMU)</title>
|
||||
|
||||
<para>
|
||||
The Yocto Project uses an implementation of the Quick EMUlator (QEMU)
|
||||
Open Source project as part of the Yocto Project development "tool
|
||||
set".
|
||||
</para>
|
||||
|
||||
<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.
|
||||
<note>
|
||||
This implementation is not the same as QEMU in general.
|
||||
</note>
|
||||
This section provides a brief reference for the Yocto Project
|
||||
implementation of QEMU.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For official information and documentation on QEMU in general, 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>
|
||||
For information on how to use the Yocto Project implementation of
|
||||
QEMU, see the
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
|
||||
chapter in the Yocto Project Development Tasks Manual.
|
||||
</para>
|
||||
|
||||
<section id='qemu-availability'>
|
||||
<title>QEMU Availability</title>
|
||||
|
||||
<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
|
||||
"<ulink url='&YOCTO_DOCS_SDK_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>"
|
||||
section in the Yocto Project Application Development and the
|
||||
Extensible Software Development Kit (eSDK) manual.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='qemu-performance'>
|
||||
<title>QEMU Performance</title>
|
||||
|
||||
<para>
|
||||
Using QEMU to emulate your hardware can result in speed issues
|
||||
depending on the target and host architecture mix.
|
||||
For example, using the <filename>qemux86</filename> image in the
|
||||
emulator on an Intel-based 32-bit (x86) host machine is fast
|
||||
because the target and host architectures match.
|
||||
On the other hand, using the <filename>qemuarm</filename> image
|
||||
on the same Intel-based host can be slower.
|
||||
But, you still achieve faithful emulation of ARM-specific issues.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To speed things up, the QEMU images support using
|
||||
<filename>distcc</filename> to call a cross-compiler outside the
|
||||
emulated system.
|
||||
If you used <filename>runqemu</filename> to start QEMU, and the
|
||||
<filename>distccd</filename> application is present on the host
|
||||
system, any BitBake cross-compiling toolchain available from the
|
||||
build system is automatically used from within QEMU simply by
|
||||
calling <filename>distcc</filename>.
|
||||
You can accomplish this by defining the cross-compiler variable
|
||||
(e.g. <filename>export CC="distcc"</filename>).
|
||||
Alternatively, if you are using a suitable SDK image or the
|
||||
appropriate stand-alone toolchain is present, the toolchain is
|
||||
also automatically used.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
Several mechanisms exist that let you connect to the system
|
||||
running on the QEMU emulator:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
QEMU provides a framebuffer interface that makes standard
|
||||
consoles available.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Generally, headless embedded devices have a serial port.
|
||||
If so, you can configure the operating system of the
|
||||
running image to use that port to run a console.
|
||||
The connection uses standard IP networking.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
SSH servers exist in some QEMU images.
|
||||
The <filename>core-image-sato</filename> QEMU image has a
|
||||
Dropbear secure shell (SSH) server that runs with the root
|
||||
password disabled.
|
||||
The <filename>core-image-full-cmdline</filename> and
|
||||
<filename>core-image-lsb</filename> QEMU images
|
||||
have OpenSSH instead of Dropbear.
|
||||
Including these SSH servers allow you to use standard
|
||||
<filename>ssh</filename> and <filename>scp</filename>
|
||||
commands.
|
||||
The <filename>core-image-minimal</filename> QEMU image,
|
||||
however, contains no SSH server.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
You can use a provided, user-space NFS server to boot
|
||||
the QEMU session using a local copy of the root
|
||||
filesystem on the host.
|
||||
In order to make this connection, you must extract a
|
||||
root filesystem tarball by using the
|
||||
<filename>runqemu-extract-sdk</filename> command.
|
||||
After running the command, you must then point the
|
||||
<filename>runqemu</filename>
|
||||
script to the extracted directory instead of a root
|
||||
filesystem image file.
|
||||
See the
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-running-under-a-network-file-system-nfs-server'>Running Under a Network File System (NFS) Server</ulink>"
|
||||
section in the Yocto Project Development Tasks Manual for
|
||||
more information.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</note>
|
||||
</section>
|
||||
|
||||
<section id='qemu-command-line-syntax'>
|
||||
<title>QEMU Command-Line Syntax</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>*wic.vmdk</filename>), or a kernel image
|
||||
(<filename>*.bin</filename>).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Following is the command-line help output for the
|
||||
<filename>runqemu</filename> command:
|
||||
<literallayout class='monospaced'>
|
||||
$ 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/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz...
|
||||
runqemu qemux86 qemuparams="-m 256"
|
||||
runqemu qemux86 bootparams="psplash=false"
|
||||
runqemu path/to/<image>-<machine>.wic
|
||||
runqemu path/to/<image>-<machine>.wic.vmdk
|
||||
</literallayout>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='runqemu-command-line-options'>
|
||||
<title><filename>runqemu</filename> Command-Line Options</title>
|
||||
|
||||
<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 "qemuarm",
|
||||
"qemuarm64", "qemumips", "qemumips64", "qemuppc",
|
||||
"qemux86", or "qemux86-64".
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<filename><replaceable>VM</replaceable></filename>:
|
||||
The virtual machine image, which must be a
|
||||
<filename>.wic.vmdk</filename> file.
|
||||
Use this option when you want to boot a
|
||||
<filename>.wic.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",
|
||||
"qemuarm64", "qemumips", “qemumips64", or "qemuppc".
|
||||
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>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section id='maintaining-build-output-quality'>
|
||||
<title>Maintaining Build Output Quality</title>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user