mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-04-20 18:32:12 +02:00
Code Issues Packages Projects Releases Wiki Activity

ref-manual: Added QEMU reference section

Browse Source 
Fixes [YOCTO #11630]

The dev-manual had a section on QEMU that combined a lot of
reference information and usage information.  I took the reference
information out and moved it to the ref-manual into a new section
in the second chapter, "Using YP".

(From yocto-docs rev: 188596c576e357925383d0cc3bd2b0cdf41926ec)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
2017-07-17 08:21:39 -07:00
committed by Richard Purdie
parent da066d8cdf
commit 88c188f990
1 changed files with 281 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

281
documentation/ref-manual/usingpoky.xml
View File

@@ -1049,6 +1049,287 @@
</section>
</section>
<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".
<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 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 Software Development Kit (SDK)
Developer's Guide.
</para>
</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>*.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=&lt;port&gt; - specify tcp serial port number
biosdir=&lt;dir&gt; - specify custom bios dir
biosfilename=&lt;filename&gt; - specify bios filename
qemuparams=&lt;xyz&gt; - specify custom parameters to QEMU
bootparams=&lt;xyz&gt; - 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/&lt;qemuboot.conf&gt;
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/&lt;image&gt;-&lt;machine&gt;.vmdk
runqemu path/to/&lt;image&gt;-&lt;machine&gt;.wic
</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>.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", "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>