mirror of
https://github.com/izzy2lost/xemu.git
synced 2026-07-06 00:20:22 -07:00
Merge remote-tracking branch 'remotes/pmaydell/tags/pull-docs-20200306' into staging
docs: * Convert qemu-doc from Texinfo to rST # gpg: Signature made Fri 06 Mar 2020 11:08:15 GMT # gpg: using RSA key E1A5C593CD419DE28E8315CF3C2525ED14360CDE # gpg: issuer "peter.maydell@linaro.org" # gpg: Good signature from "Peter Maydell <peter.maydell@linaro.org>" [ultimate] # gpg: aka "Peter Maydell <pmaydell@gmail.com>" [ultimate] # gpg: aka "Peter Maydell <pmaydell@chiark.greenend.org.uk>" [ultimate] # Primary key fingerprint: E1A5 C593 CD41 9DE2 8E83 15CF 3C25 25ED 1436 0CDE * remotes/pmaydell/tags/pull-docs-20200306: (33 commits) *.hx: Remove all the STEXI/ETEXI blocks docs: Remove old texinfo sources docs: Stop building qemu-doc ui/cocoa.m: Update documentation file and pathname docs: Generate qemu.1 manpage with Sphinx docs: Split out sections for the manpage into .rst.inc files qemu-options.hx: Fix up the autogenerated rST qemu-options.hx: Add rST documentation fragments scripts/hxtool-conv: Archive script used in qemu-options.hx conversion docs: Roll -prom-env and -g target-specific info into qemu-options.hx docs: Roll semihosting option information into qemu-options.hx doc/scripts/hxtool.py: Strip trailing ':' from DEFHEADING/ARCHHEADING hmp-commands-info.hx: Add rST documentation fragments hmp-commands.hx: Add rST documentation fragments docs/system: convert Texinfo documentation to rST docs/system: convert the documentation of deprecated features to rST. docs/system: convert managed startup to rST. docs/system: Convert security.texi to rST format docs/system: Convert qemu-cpu-models.texi to rST docs: Create defs.rst.inc as a place to define substitutions ... Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
This commit is contained in:
Peter Maydell
@@ -46,9 +46,6 @@
|
||||
!/qapi/qapi-visit-core.c
|
||||
/qapi/qapi-visit.[ch]
|
||||
/qapi/qapi-doc.texi
|
||||
/qemu-doc.html
|
||||
/qemu-doc.info
|
||||
/qemu-doc.txt
|
||||
/qemu-edid
|
||||
/qemu-img
|
||||
/qemu-nbd
|
||||
|
||||
+4
-3
@@ -215,6 +215,7 @@ S: Maintained
|
||||
F: target/mips/
|
||||
F: default-configs/*mips*
|
||||
F: disas/*mips*
|
||||
F: docs/system/cpu-models-mips.rst.inc
|
||||
F: hw/intc/mips_gic.c
|
||||
F: hw/mips/
|
||||
F: hw/misc/mips_*
|
||||
@@ -319,7 +320,7 @@ F: tests/tcg/i386/
|
||||
F: tests/tcg/x86_64/
|
||||
F: hw/i386/
|
||||
F: disas/i386.c
|
||||
F: docs/qemu-cpu-models.texi
|
||||
F: docs/system/cpu-models-x86.rst.inc
|
||||
T: git https://github.com/ehabkost/qemu.git x86-next
|
||||
|
||||
Xtensa TCG CPUs
|
||||
@@ -2233,7 +2234,7 @@ M: Stefan Hajnoczi <stefanha@redhat.com>
|
||||
S: Maintained
|
||||
F: trace/
|
||||
F: trace-events
|
||||
F: qemu-option-trace.texi
|
||||
F: docs/qemu-option-trace.rst.inc
|
||||
F: scripts/tracetool.py
|
||||
F: scripts/tracetool/
|
||||
F: scripts/qemu-trace-stap*
|
||||
@@ -2803,7 +2804,7 @@ F: contrib/gitdm/*
|
||||
|
||||
Incompatible changes
|
||||
R: libvir-list@redhat.com
|
||||
F: qemu-deprecated.texi
|
||||
F: docs/system/deprecated.rst
|
||||
|
||||
Build System
|
||||
------------
|
||||
|
||||
@@ -344,7 +344,7 @@ MANUAL_BUILDDIR := docs
|
||||
endif
|
||||
|
||||
ifdef BUILD_DOCS
|
||||
DOCS=qemu-doc.html qemu-doc.txt qemu.1
|
||||
DOCS+=$(MANUAL_BUILDDIR)/system/qemu.1
|
||||
DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-img.1
|
||||
DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-nbd.8
|
||||
DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8
|
||||
@@ -354,7 +354,7 @@ endif
|
||||
DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7
|
||||
DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7
|
||||
DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7
|
||||
DOCS+=docs/qemu-cpu-models.7
|
||||
DOCS+=$(MANUAL_BUILDDIR)/system/qemu-cpu-models.7
|
||||
DOCS+=$(MANUAL_BUILDDIR)/index.html
|
||||
ifdef CONFIG_VIRTFS
|
||||
DOCS+=$(MANUAL_BUILDDIR)/tools/virtfs-proxy-helper.1
|
||||
@@ -767,10 +767,6 @@ distclean: clean
|
||||
rm -f $(SUBDIR_DEVICES_MAK)
|
||||
rm -f po/*.mo tests/qemu-iotests/common.env
|
||||
rm -f roms/seabios/config.mak roms/vgabios/config.mak
|
||||
rm -f qemu-doc.info qemu-doc.aux qemu-doc.cp qemu-doc.cps
|
||||
rm -f qemu-doc.fn qemu-doc.fns qemu-doc.info qemu-doc.ky qemu-doc.kys
|
||||
rm -f qemu-doc.log qemu-doc.pdf qemu-doc.pg qemu-doc.toc qemu-doc.tp
|
||||
rm -f qemu-doc.vr qemu-doc.txt
|
||||
rm -f qemu-plugins-ld.symbols qemu-plugins-ld64.symbols
|
||||
rm -f config.log
|
||||
rm -f linux-headers/asm
|
||||
@@ -780,13 +776,13 @@ distclean: clean
|
||||
rm -f docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
|
||||
rm -f docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
|
||||
rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html
|
||||
rm -f docs/qemu-cpu-models.7
|
||||
rm -rf .doctrees
|
||||
$(call clean-manual,devel)
|
||||
$(call clean-manual,interop)
|
||||
$(call clean-manual,specs)
|
||||
$(call clean-manual,system)
|
||||
$(call clean-manual,tools)
|
||||
$(call clean-manual,user)
|
||||
for d in $(TARGET_DIRS); do \
|
||||
rm -rf $$d || exit 1 ; \
|
||||
done
|
||||
@@ -845,21 +841,20 @@ install-sphinxdocs: sphinxdocs
|
||||
$(call install-manual,specs)
|
||||
$(call install-manual,system)
|
||||
$(call install-manual,tools)
|
||||
$(call install-manual,user)
|
||||
|
||||
install-doc: $(DOCS) install-sphinxdocs
|
||||
$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
|
||||
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/index.html "$(DESTDIR)$(qemu_docdir)"
|
||||
$(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)"
|
||||
$(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)"
|
||||
$(INSTALL_DATA) docs/interop/qemu-qmp-ref.html "$(DESTDIR)$(qemu_docdir)"
|
||||
$(INSTALL_DATA) docs/interop/qemu-qmp-ref.txt "$(DESTDIR)$(qemu_docdir)"
|
||||
ifdef CONFIG_POSIX
|
||||
$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
|
||||
$(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1"
|
||||
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu.1 "$(DESTDIR)$(mandir)/man1"
|
||||
$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man7"
|
||||
$(INSTALL_DATA) docs/interop/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7"
|
||||
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7"
|
||||
$(INSTALL_DATA) docs/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7"
|
||||
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7"
|
||||
ifeq ($(CONFIG_TOOLS),y)
|
||||
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/qemu-img.1 "$(DESTDIR)$(mandir)/man1"
|
||||
$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8"
|
||||
@@ -1039,7 +1034,8 @@ sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html \
|
||||
$(MANUAL_BUILDDIR)/interop/index.html \
|
||||
$(MANUAL_BUILDDIR)/specs/index.html \
|
||||
$(MANUAL_BUILDDIR)/system/index.html \
|
||||
$(MANUAL_BUILDDIR)/tools/index.html
|
||||
$(MANUAL_BUILDDIR)/tools/index.html \
|
||||
$(MANUAL_BUILDDIR)/user/index.html
|
||||
|
||||
# Canned command to build a single manual
|
||||
# Arguments: $1 = manual name, $2 = Sphinx builder ('html' or 'man')
|
||||
@@ -1049,6 +1045,7 @@ sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html \
|
||||
build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" $(SPHINX_BUILD) $(if $(V),,-q) -W -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1-$2 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
|
||||
# We assume all RST files in the manual's directory are used in it
|
||||
manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) \
|
||||
$(SRC_PATH)/docs/defs.rst.inc \
|
||||
$(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
|
||||
# Macro to write out the rule and dependencies for building manpages
|
||||
# Usage: $(call define-manpage-rule,manualname,manpage1 manpage2...[,extradeps])
|
||||
@@ -1068,15 +1065,18 @@ $(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
|
||||
$(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
|
||||
$(call build-manual,specs,html)
|
||||
|
||||
$(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system)
|
||||
$(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system) $(SRC_PATH)/hmp-commands.hx $(SRC_PATH)/hmp-commands-info.hx $(SRC_PATH)/qemu-options.hx
|
||||
$(call build-manual,system,html)
|
||||
|
||||
$(MANUAL_BUILDDIR)/tools/index.html: $(call manual-deps,tools) $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/docs/qemu-option-trace.rst.inc
|
||||
$(call build-manual,tools,html)
|
||||
|
||||
$(MANUAL_BUILDDIR)/user/index.html: $(call manual-deps,user)
|
||||
$(call build-manual,user,html)
|
||||
|
||||
$(call define-manpage-rule,interop,qemu-ga.8)
|
||||
|
||||
$(call define-manpage-rule,system,qemu-block-drivers.7)
|
||||
$(call define-manpage-rule,system,qemu.1 qemu-block-drivers.7 qemu-cpu-models.7)
|
||||
|
||||
$(call define-manpage-rule,tools,\
|
||||
qemu-img.1 qemu-nbd.8 qemu-trace-stap.1\
|
||||
@@ -1103,21 +1103,10 @@ docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi
|
||||
docs/interop/qemu-ga-qapi.texi: qga/qapi-generated/qga-qapi-doc.texi
|
||||
@cp -p $< $@
|
||||
|
||||
qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi
|
||||
qemu.1: qemu-option-trace.texi
|
||||
docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi
|
||||
|
||||
html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs
|
||||
info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info
|
||||
pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
|
||||
txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
|
||||
|
||||
qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
|
||||
qemu-options.texi \
|
||||
qemu-tech.texi qemu-option-trace.texi \
|
||||
qemu-deprecated.texi qemu-monitor.texi \
|
||||
qemu-monitor-info.texi \
|
||||
docs/qemu-cpu-models.texi docs/security.texi
|
||||
html: docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs
|
||||
info: docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info
|
||||
pdf: docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
|
||||
txt: docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
|
||||
|
||||
docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \
|
||||
docs/interop/qemu-ga-ref.info docs/interop/qemu-ga-ref.pdf \
|
||||
|
||||
@@ -132,6 +132,12 @@ suppress_warnings = ["ref.option"]
|
||||
# style document building; our Makefile always sets the variable.
|
||||
confdir = os.getenv('CONFDIR', "/etc/qemu")
|
||||
rst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n"
|
||||
# We slurp in the defs.rst.inc and literally include it into rst_epilog,
|
||||
# because Sphinx's include:: directive doesn't work with absolute paths
|
||||
# and there isn't any one single relative path that will work for all
|
||||
# documents and for both via-make and direct sphinx-build invocation.
|
||||
with open(os.path.join(qemu_docdir, 'defs.rst.inc')) as f:
|
||||
rst_epilog += f.read()
|
||||
|
||||
# -- Options for HTML output ----------------------------------------------
|
||||
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
..
|
||||
Generally useful rST substitution definitions. This is included for
|
||||
all rST files as part of the epilogue by docs/conf.py. conf.py
|
||||
also defines some dynamically generated substitutions like CONFDIR.
|
||||
|
||||
Note that |qemu_system| and |qemu_system_x86| are intended to be
|
||||
used inside a parsed-literal block: the definition must not include
|
||||
extra literal formatting with ``..``: this works in the HTML output
|
||||
but the manpages will end up misrendered with following normal text
|
||||
incorrectly in boldface.
|
||||
|
||||
.. |qemu_system| replace:: qemu-system-x86_64
|
||||
.. |qemu_system_x86| replace:: qemu_system-x86_64
|
||||
.. |I2C| replace:: I\ :sup:`2`\ C
|
||||
.. |I2S| replace:: I\ :sup:`2`\ S
|
||||
+1
-1
@@ -7,13 +7,13 @@
|
||||
<body>
|
||||
<h1>QEMU @@VERSION@@ Documentation</h1>
|
||||
<ul>
|
||||
<li><a href="qemu-doc.html">User Documentation</a></li>
|
||||
<li><a href="qemu-qmp-ref.html">QMP Reference Manual</a></li>
|
||||
<li><a href="qemu-ga-ref.html">Guest Agent Protocol Reference</a></li>
|
||||
<li><a href="interop/index.html">System Emulation Management and Interoperability Guide</a></li>
|
||||
<li><a href="specs/index.html">System Emulation Guest Hardware Specifications</a></li>
|
||||
<li><a href="system/index.html">System Emulation User's Guide</a></li>
|
||||
<li><a href="tools/index.html">Tools Guide</a></li>
|
||||
<li><a href="user/index.html">User Mode Emulation User's Guide</a></li>
|
||||
</ul>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -15,3 +15,4 @@ Welcome to QEMU's documentation!
|
||||
specs/index
|
||||
system/index
|
||||
tools/index
|
||||
user/index
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -38,8 +38,8 @@ There are two basic configurations:
|
||||
Interrupts are message-signaled (MSI-X). vectors=N configures the
|
||||
number of vectors to use.
|
||||
|
||||
For more details on ivshmem device properties, see The QEMU Emulator
|
||||
User Documentation (qemu-doc.*).
|
||||
For more details on ivshmem device properties, see the QEMU Emulator
|
||||
user documentation.
|
||||
|
||||
|
||||
== The ivshmem PCI device's guest interface ==
|
||||
|
||||
@@ -60,8 +60,9 @@ def parse_defheading(file, lnum, line):
|
||||
# empty we ignore the directive -- these are used only to add
|
||||
# blank lines in the plain-text content of the --help output.
|
||||
#
|
||||
# Return the heading text
|
||||
match = re.match(r'DEFHEADING\((.*)\)', line)
|
||||
# Return the heading text. We strip out any trailing ':' for
|
||||
# consistency with other headings in the rST documentation.
|
||||
match = re.match(r'DEFHEADING\((.*?):?\)', line)
|
||||
if match is None:
|
||||
serror(file, lnum, "Invalid DEFHEADING line")
|
||||
return match.group(1)
|
||||
@@ -72,8 +73,9 @@ def parse_archheading(file, lnum, line):
|
||||
# though note that the 'some string' could be the empty string.
|
||||
# As with DEFHEADING, empty string ARCHHEADINGs will be ignored.
|
||||
#
|
||||
# Return the heading text
|
||||
match = re.match(r'ARCHHEADING\((.*),.*\)', line)
|
||||
# Return the heading text. We strip out any trailing ':' for
|
||||
# consistency with other headings in the rST documentation.
|
||||
match = re.match(r'ARCHHEADING\((.*?):?,.*\)', line)
|
||||
if match is None:
|
||||
serror(file, lnum, "Invalid ARCHHEADING line")
|
||||
return match.group(1)
|
||||
|
||||
@@ -0,0 +1,79 @@
|
||||
.. _Supported-build-platforms:
|
||||
|
||||
Supported build platforms
|
||||
=========================
|
||||
|
||||
QEMU aims to support building and executing on multiple host OS
|
||||
platforms. This appendix outlines which platforms are the major build
|
||||
targets. These platforms are used as the basis for deciding upon the
|
||||
minimum required versions of 3rd party software QEMU depends on. The
|
||||
supported platforms are the targets for automated testing performed by
|
||||
the project when patches are submitted for review, and tested before and
|
||||
after merge.
|
||||
|
||||
If a platform is not listed here, it does not imply that QEMU won't
|
||||
work. If an unlisted platform has comparable software versions to a
|
||||
listed platform, there is every expectation that it will work. Bug
|
||||
reports are welcome for problems encountered on unlisted platforms
|
||||
unless they are clearly older vintage than what is described here.
|
||||
|
||||
Note that when considering software versions shipped in distros as
|
||||
support targets, QEMU considers only the version number, and assumes the
|
||||
features in that distro match the upstream release with the same
|
||||
version. In other words, if a distro backports extra features to the
|
||||
software in their distro, QEMU upstream code will not add explicit
|
||||
support for those backports, unless the feature is auto-detectable in a
|
||||
manner that works for the upstream releases too.
|
||||
|
||||
The Repology site https://repology.org is a useful resource to identify
|
||||
currently shipped versions of software in various operating systems,
|
||||
though it does not cover all distros listed below.
|
||||
|
||||
Linux OS
|
||||
--------
|
||||
|
||||
For distributions with frequent, short-lifetime releases, the project
|
||||
will aim to support all versions that are not end of life by their
|
||||
respective vendors. For the purposes of identifying supported software
|
||||
versions, the project will look at Fedora, Ubuntu, and openSUSE distros.
|
||||
Other short- lifetime distros will be assumed to ship similar software
|
||||
versions.
|
||||
|
||||
For distributions with long-lifetime releases, the project will aim to
|
||||
support the most recent major version at all times. Support for the
|
||||
previous major version will be dropped 2 years after the new major
|
||||
version is released, or when it reaches "end of life". For the purposes
|
||||
of identifying supported software versions, the project will look at
|
||||
RHEL, Debian, Ubuntu LTS, and SLES distros. Other long-lifetime distros
|
||||
will be assumed to ship similar software versions.
|
||||
|
||||
Windows
|
||||
-------
|
||||
|
||||
The project supports building with current versions of the MinGW
|
||||
toolchain, hosted on Linux.
|
||||
|
||||
macOS
|
||||
-----
|
||||
|
||||
The project supports building with the two most recent versions of
|
||||
macOS, with the current homebrew package set available.
|
||||
|
||||
FreeBSD
|
||||
-------
|
||||
|
||||
The project aims to support the all the versions which are not end of
|
||||
life.
|
||||
|
||||
NetBSD
|
||||
------
|
||||
|
||||
The project aims to support the most recent major version at all times.
|
||||
Support for the previous major version will be dropped 2 years after the
|
||||
new major version is released.
|
||||
|
||||
OpenBSD
|
||||
-------
|
||||
|
||||
The project aims to support the all the versions which are not end of
|
||||
life.
|
||||
+7
-1
@@ -13,10 +13,16 @@ exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
|
||||
# This slightly misuses the 'description', but is the best way to get
|
||||
# the manual title to appear in the sidebar.
|
||||
html_theme_options['description'] = u'System Emulation User''s Guide'
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [
|
||||
('qemu-manpage', 'qemu', u'QEMU User Documentation',
|
||||
['Fabrice Bellard'], 1),
|
||||
('qemu-block-drivers', 'qemu-block-drivers',
|
||||
u'QEMU block drivers reference',
|
||||
['Fabrice Bellard and the QEMU Project developers'], 7)
|
||||
['Fabrice Bellard and the QEMU Project developers'], 7),
|
||||
('qemu-cpu-models', 'qemu-cpu-models',
|
||||
u'QEMU CPU Models',
|
||||
['The QEMU Project developers'], 7)
|
||||
]
|
||||
|
||||
@@ -0,0 +1,105 @@
|
||||
Supported CPU model configurations on MIPS hosts
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
QEMU supports variety of MIPS CPU models:
|
||||
|
||||
Supported CPU models for MIPS32 hosts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following CPU models are supported for use on MIPS32 hosts.
|
||||
Administrators / applications are recommended to use the CPU model that
|
||||
matches the generation of the host CPUs in use. In a deployment with a
|
||||
mixture of host CPU models between machines, if live migration
|
||||
compatibility is required, use the newest CPU model that is compatible
|
||||
across all desired hosts.
|
||||
|
||||
``mips32r6-generic``
|
||||
MIPS32 Processor (Release 6, 2015)
|
||||
|
||||
``P5600``
|
||||
MIPS32 Processor (P5600, 2014)
|
||||
|
||||
``M14K``, ``M14Kc``
|
||||
MIPS32 Processor (M14K, 2009)
|
||||
|
||||
``74Kf``
|
||||
MIPS32 Processor (74K, 2007)
|
||||
|
||||
``34Kf``
|
||||
MIPS32 Processor (34K, 2006)
|
||||
|
||||
``24Kc``, ``24KEc``, ``24Kf``
|
||||
MIPS32 Processor (24K, 2003)
|
||||
|
||||
``4Kc``, ``4Km``, ``4KEcR1``, ``4KEmR1``, ``4KEc``, ``4KEm``
|
||||
MIPS32 Processor (4K, 1999)
|
||||
|
||||
|
||||
Supported CPU models for MIPS64 hosts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following CPU models are supported for use on MIPS64 hosts.
|
||||
Administrators / applications are recommended to use the CPU model that
|
||||
matches the generation of the host CPUs in use. In a deployment with a
|
||||
mixture of host CPU models between machines, if live migration
|
||||
compatibility is required, use the newest CPU model that is compatible
|
||||
across all desired hosts.
|
||||
|
||||
``I6400``
|
||||
MIPS64 Processor (Release 6, 2014)
|
||||
|
||||
``Loongson-2F``
|
||||
MIPS64 Processor (Loongson 2, 2008)
|
||||
|
||||
``Loongson-2E``
|
||||
MIPS64 Processor (Loongson 2, 2006)
|
||||
|
||||
``mips64dspr2``
|
||||
MIPS64 Processor (Release 2, 2006)
|
||||
|
||||
``MIPS64R2-generic``, ``5KEc``, ``5KEf``
|
||||
MIPS64 Processor (Release 2, 2002)
|
||||
|
||||
``20Kc``
|
||||
MIPS64 Processor (20K, 2000
|
||||
|
||||
``5Kc``, ``5Kf``
|
||||
MIPS64 Processor (5K, 1999)
|
||||
|
||||
``VR5432``
|
||||
MIPS64 Processor (VR, 1998)
|
||||
|
||||
``R4000``
|
||||
MIPS64 Processor (MIPS III, 1991)
|
||||
|
||||
|
||||
Supported CPU models for nanoMIPS hosts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following CPU models are supported for use on nanoMIPS hosts.
|
||||
Administrators / applications are recommended to use the CPU model that
|
||||
matches the generation of the host CPUs in use. In a deployment with a
|
||||
mixture of host CPU models between machines, if live migration
|
||||
compatibility is required, use the newest CPU model that is compatible
|
||||
across all desired hosts.
|
||||
|
||||
``I7200``
|
||||
MIPS I7200 (nanoMIPS, 2018)
|
||||
|
||||
Preferred CPU models for MIPS hosts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following CPU models are preferred for use on different MIPS hosts:
|
||||
|
||||
``MIPS III``
|
||||
R4000
|
||||
|
||||
``MIPS32R2``
|
||||
34Kf
|
||||
|
||||
``MIPS64R6``
|
||||
I6400
|
||||
|
||||
``nanoMIPS``
|
||||
I7200
|
||||
|
||||
@@ -0,0 +1,365 @@
|
||||
Recommendations for KVM CPU model configuration on x86 hosts
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The information that follows provides recommendations for configuring
|
||||
CPU models on x86 hosts. The goals are to maximise performance, while
|
||||
protecting guest OS against various CPU hardware flaws, and optionally
|
||||
enabling live migration between hosts with heterogeneous CPU models.
|
||||
|
||||
|
||||
Two ways to configure CPU models with QEMU / KVM
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
(1) **Host passthrough**
|
||||
|
||||
This passes the host CPU model features, model, stepping, exactly to
|
||||
the guest. Note that KVM may filter out some host CPU model features
|
||||
if they cannot be supported with virtualization. Live migration is
|
||||
unsafe when this mode is used as libvirt / QEMU cannot guarantee a
|
||||
stable CPU is exposed to the guest across hosts. This is the
|
||||
recommended CPU to use, provided live migration is not required.
|
||||
|
||||
(2) **Named model**
|
||||
|
||||
QEMU comes with a number of predefined named CPU models, that
|
||||
typically refer to specific generations of hardware released by
|
||||
Intel and AMD. These allow the guest VMs to have a degree of
|
||||
isolation from the host CPU, allowing greater flexibility in live
|
||||
migrating between hosts with differing hardware. @end table
|
||||
|
||||
In both cases, it is possible to optionally add or remove individual CPU
|
||||
features, to alter what is presented to the guest by default.
|
||||
|
||||
Libvirt supports a third way to configure CPU models known as "Host
|
||||
model". This uses the QEMU "Named model" feature, automatically picking
|
||||
a CPU model that is similar the host CPU, and then adding extra features
|
||||
to approximate the host model as closely as possible. This does not
|
||||
guarantee the CPU family, stepping, etc will precisely match the host
|
||||
CPU, as they would with "Host passthrough", but gives much of the
|
||||
benefit of passthrough, while making live migration safe.
|
||||
|
||||
|
||||
Preferred CPU models for Intel x86 hosts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following CPU models are preferred for use on Intel hosts.
|
||||
Administrators / applications are recommended to use the CPU model that
|
||||
matches the generation of the host CPUs in use. In a deployment with a
|
||||
mixture of host CPU models between machines, if live migration
|
||||
compatibility is required, use the newest CPU model that is compatible
|
||||
across all desired hosts.
|
||||
|
||||
``Skylake-Server``, ``Skylake-Server-IBRS``
|
||||
Intel Xeon Processor (Skylake, 2016)
|
||||
|
||||
``Skylake-Client``, ``Skylake-Client-IBRS``
|
||||
Intel Core Processor (Skylake, 2015)
|
||||
|
||||
``Broadwell``, ``Broadwell-IBRS``, ``Broadwell-noTSX``, ``Broadwell-noTSX-IBRS``
|
||||
Intel Core Processor (Broadwell, 2014)
|
||||
|
||||
``Haswell``, ``Haswell-IBRS``, ``Haswell-noTSX``, ``Haswell-noTSX-IBRS``
|
||||
Intel Core Processor (Haswell, 2013)
|
||||
|
||||
``IvyBridge``, ``IvyBridge-IBR``
|
||||
Intel Xeon E3-12xx v2 (Ivy Bridge, 2012)
|
||||
|
||||
``SandyBridge``, ``SandyBridge-IBRS``
|
||||
Intel Xeon E312xx (Sandy Bridge, 2011)
|
||||
|
||||
``Westmere``, ``Westmere-IBRS``
|
||||
Westmere E56xx/L56xx/X56xx (Nehalem-C, 2010)
|
||||
|
||||
``Nehalem``, ``Nehalem-IBRS``
|
||||
Intel Core i7 9xx (Nehalem Class Core i7, 2008)
|
||||
|
||||
``Penryn``
|
||||
Intel Core 2 Duo P9xxx (Penryn Class Core 2, 2007)
|
||||
|
||||
``Conroe``
|
||||
Intel Celeron_4x0 (Conroe/Merom Class Core 2, 2006)
|
||||
|
||||
|
||||
Important CPU features for Intel x86 hosts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following are important CPU features that should be used on Intel
|
||||
x86 hosts, when available in the host CPU. Some of them require explicit
|
||||
configuration to enable, as they are not included by default in some, or
|
||||
all, of the named CPU models listed above. In general all of these
|
||||
features are included if using "Host passthrough" or "Host model".
|
||||
|
||||
``pcid``
|
||||
Recommended to mitigate the cost of the Meltdown (CVE-2017-5754) fix.
|
||||
|
||||
Included by default in Haswell, Broadwell & Skylake Intel CPU models.
|
||||
|
||||
Should be explicitly turned on for Westmere, SandyBridge, and
|
||||
IvyBridge Intel CPU models. Note that some desktop/mobile Westmere
|
||||
CPUs cannot support this feature.
|
||||
|
||||
``spec-ctrl``
|
||||
Required to enable the Spectre v2 (CVE-2017-5715) fix.
|
||||
|
||||
Included by default in Intel CPU models with -IBRS suffix.
|
||||
|
||||
Must be explicitly turned on for Intel CPU models without -IBRS
|
||||
suffix.
|
||||
|
||||
Requires the host CPU microcode to support this feature before it
|
||||
can be used for guest CPUs.
|
||||
|
||||
``stibp``
|
||||
Required to enable stronger Spectre v2 (CVE-2017-5715) fixes in some
|
||||
operating systems.
|
||||
|
||||
Must be explicitly turned on for all Intel CPU models.
|
||||
|
||||
Requires the host CPU microcode to support this feature before it can
|
||||
be used for guest CPUs.
|
||||
|
||||
``ssbd``
|
||||
Required to enable the CVE-2018-3639 fix.
|
||||
|
||||
Not included by default in any Intel CPU model.
|
||||
|
||||
Must be explicitly turned on for all Intel CPU models.
|
||||
|
||||
Requires the host CPU microcode to support this feature before it
|
||||
can be used for guest CPUs.
|
||||
|
||||
``pdpe1gb``
|
||||
Recommended to allow guest OS to use 1GB size pages.
|
||||
|
||||
Not included by default in any Intel CPU model.
|
||||
|
||||
Should be explicitly turned on for all Intel CPU models.
|
||||
|
||||
Note that not all CPU hardware will support this feature.
|
||||
|
||||
``md-clear``
|
||||
Required to confirm the MDS (CVE-2018-12126, CVE-2018-12127,
|
||||
CVE-2018-12130, CVE-2019-11091) fixes.
|
||||
|
||||
Not included by default in any Intel CPU model.
|
||||
|
||||
Must be explicitly turned on for all Intel CPU models.
|
||||
|
||||
Requires the host CPU microcode to support this feature before it
|
||||
can be used for guest CPUs.
|
||||
|
||||
|
||||
Preferred CPU models for AMD x86 hosts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following CPU models are preferred for use on Intel hosts.
|
||||
Administrators / applications are recommended to use the CPU model that
|
||||
matches the generation of the host CPUs in use. In a deployment with a
|
||||
mixture of host CPU models between machines, if live migration
|
||||
compatibility is required, use the newest CPU model that is compatible
|
||||
across all desired hosts.
|
||||
|
||||
``EPYC``, ``EPYC-IBPB``
|
||||
AMD EPYC Processor (2017)
|
||||
|
||||
``Opteron_G5``
|
||||
AMD Opteron 63xx class CPU (2012)
|
||||
|
||||
``Opteron_G4``
|
||||
AMD Opteron 62xx class CPU (2011)
|
||||
|
||||
``Opteron_G3``
|
||||
AMD Opteron 23xx (Gen 3 Class Opteron, 2009)
|
||||
|
||||
``Opteron_G2``
|
||||
AMD Opteron 22xx (Gen 2 Class Opteron, 2006)
|
||||
|
||||
``Opteron_G1``
|
||||
AMD Opteron 240 (Gen 1 Class Opteron, 2004)
|
||||
|
||||
|
||||
Important CPU features for AMD x86 hosts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following are important CPU features that should be used on AMD x86
|
||||
hosts, when available in the host CPU. Some of them require explicit
|
||||
configuration to enable, as they are not included by default in some, or
|
||||
all, of the named CPU models listed above. In general all of these
|
||||
features are included if using "Host passthrough" or "Host model".
|
||||
|
||||
``ibpb``
|
||||
Required to enable the Spectre v2 (CVE-2017-5715) fix.
|
||||
|
||||
Included by default in AMD CPU models with -IBPB suffix.
|
||||
|
||||
Must be explicitly turned on for AMD CPU models without -IBPB suffix.
|
||||
|
||||
Requires the host CPU microcode to support this feature before it
|
||||
can be used for guest CPUs.
|
||||
|
||||
``stibp``
|
||||
Required to enable stronger Spectre v2 (CVE-2017-5715) fixes in some
|
||||
operating systems.
|
||||
|
||||
Must be explicitly turned on for all AMD CPU models.
|
||||
|
||||
Requires the host CPU microcode to support this feature before it
|
||||
can be used for guest CPUs.
|
||||
|
||||
``virt-ssbd``
|
||||
Required to enable the CVE-2018-3639 fix
|
||||
|
||||
Not included by default in any AMD CPU model.
|
||||
|
||||
Must be explicitly turned on for all AMD CPU models.
|
||||
|
||||
This should be provided to guests, even if amd-ssbd is also provided,
|
||||
for maximum guest compatibility.
|
||||
|
||||
Note for some QEMU / libvirt versions, this must be force enabled when
|
||||
when using "Host model", because this is a virtual feature that
|
||||
doesn't exist in the physical host CPUs.
|
||||
|
||||
``amd-ssbd``
|
||||
Required to enable the CVE-2018-3639 fix
|
||||
|
||||
Not included by default in any AMD CPU model.
|
||||
|
||||
Must be explicitly turned on for all AMD CPU models.
|
||||
|
||||
This provides higher performance than ``virt-ssbd`` so should be
|
||||
exposed to guests whenever available in the host. ``virt-ssbd`` should
|
||||
none the less also be exposed for maximum guest compatibility as some
|
||||
kernels only know about ``virt-ssbd``.
|
||||
|
||||
``amd-no-ssb``
|
||||
Recommended to indicate the host is not vulnerable CVE-2018-3639
|
||||
|
||||
Not included by default in any AMD CPU model.
|
||||
|
||||
Future hardware generations of CPU will not be vulnerable to
|
||||
CVE-2018-3639, and thus the guest should be told not to enable
|
||||
its mitigations, by exposing amd-no-ssb. This is mutually
|
||||
exclusive with virt-ssbd and amd-ssbd.
|
||||
|
||||
``pdpe1gb``
|
||||
Recommended to allow guest OS to use 1GB size pages
|
||||
|
||||
Not included by default in any AMD CPU model.
|
||||
|
||||
Should be explicitly turned on for all AMD CPU models.
|
||||
|
||||
Note that not all CPU hardware will support this feature.
|
||||
|
||||
|
||||
Default x86 CPU models
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The default QEMU CPU models are designed such that they can run on all
|
||||
hosts. If an application does not wish to do perform any host
|
||||
compatibility checks before launching guests, the default is guaranteed
|
||||
to work.
|
||||
|
||||
The default CPU models will, however, leave the guest OS vulnerable to
|
||||
various CPU hardware flaws, so their use is strongly discouraged.
|
||||
Applications should follow the earlier guidance to setup a better CPU
|
||||
configuration, with host passthrough recommended if live migration is
|
||||
not needed.
|
||||
|
||||
``qemu32``, ``qemu64``
|
||||
QEMU Virtual CPU version 2.5+ (32 & 64 bit variants)
|
||||
|
||||
``qemu64`` is used for x86_64 guests and ``qemu32`` is used for i686
|
||||
guests, when no ``-cpu`` argument is given to QEMU, or no ``<cpu>`` is
|
||||
provided in libvirt XML.
|
||||
|
||||
Other non-recommended x86 CPUs
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following CPUs models are compatible with most AMD and Intel x86
|
||||
hosts, but their usage is discouraged, as they expose a very limited
|
||||
featureset, which prevents guests having optimal performance.
|
||||
|
||||
``kvm32``, ``kvm64``
|
||||
Common KVM processor (32 & 64 bit variants).
|
||||
|
||||
Legacy models just for historical compatibility with ancient QEMU
|
||||
versions.
|
||||
|
||||
``486``, ``athlon``, ``phenom``, ``coreduo``, ``core2duo``, ``n270``, ``pentium``, ``pentium2``, ``pentium3``
|
||||
Various very old x86 CPU models, mostly predating the introduction
|
||||
of hardware assisted virtualization, that should thus not be
|
||||
required for running virtual machines.
|
||||
|
||||
|
||||
Syntax for configuring CPU models
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The examples below illustrate the approach to configuring the various
|
||||
CPU models / features in QEMU and libvirt.
|
||||
|
||||
QEMU command line
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
Host passthrough:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -cpu host
|
||||
|
||||
Host passthrough with feature customization:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -cpu host,-vmx,...
|
||||
|
||||
Named CPU models:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -cpu Westmere
|
||||
|
||||
Named CPU models with feature customization:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -cpu Westmere,+pcid,...
|
||||
|
||||
Libvirt guest XML
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
Host passthrough::
|
||||
|
||||
<cpu mode='host-passthrough'/>
|
||||
|
||||
Host passthrough with feature customization::
|
||||
|
||||
<cpu mode='host-passthrough'>
|
||||
<feature name="vmx" policy="disable"/>
|
||||
...
|
||||
</cpu>
|
||||
|
||||
Host model::
|
||||
|
||||
<cpu mode='host-model'/>
|
||||
|
||||
Host model with feature customization::
|
||||
|
||||
<cpu mode='host-model'>
|
||||
<feature name="vmx" policy="disable"/>
|
||||
...
|
||||
</cpu>
|
||||
|
||||
Named model::
|
||||
|
||||
<cpu mode='custom'>
|
||||
<model name="Westmere"/>
|
||||
</cpu>
|
||||
|
||||
Named model with feature customization::
|
||||
|
||||
<cpu mode='custom'>
|
||||
<model name="Westmere"/>
|
||||
<feature name="pcid" policy="require"/>
|
||||
...
|
||||
</cpu>
|
||||
@@ -0,0 +1,446 @@
|
||||
Deprecated features
|
||||
===================
|
||||
|
||||
In general features are intended to be supported indefinitely once
|
||||
introduced into QEMU. In the event that a feature needs to be removed,
|
||||
it will be listed in this section. The feature will remain functional
|
||||
for 2 releases prior to actual removal. Deprecated features may also
|
||||
generate warnings on the console when QEMU starts up, or if activated
|
||||
via a monitor command, however, this is not a mandatory requirement.
|
||||
|
||||
Prior to the 2.10.0 release there was no official policy on how
|
||||
long features would be deprecated prior to their removal, nor
|
||||
any documented list of which features were deprecated. Thus
|
||||
any features deprecated prior to 2.10.0 will be treated as if
|
||||
they were first deprecated in the 2.10.0 release.
|
||||
|
||||
What follows is a list of all features currently marked as
|
||||
deprecated.
|
||||
|
||||
System emulator command line arguments
|
||||
--------------------------------------
|
||||
|
||||
``-machine enforce-config-section=on|off`` (since 3.1)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``enforce-config-section`` parameter is replaced by the
|
||||
``-global migration.send-configuration={on|off}`` option.
|
||||
|
||||
``-no-kvm`` (since 1.3.0)
|
||||
'''''''''''''''''''''''''
|
||||
|
||||
The ``-no-kvm`` argument is now a synonym for setting ``-accel tcg``.
|
||||
|
||||
``-usbdevice`` (since 2.10.0)
|
||||
'''''''''''''''''''''''''''''
|
||||
|
||||
The ``-usbdevice DEV`` argument is now a synonym for setting
|
||||
the ``-device usb-DEV`` argument instead. The deprecated syntax
|
||||
would automatically enable USB support on the machine type.
|
||||
If using the new syntax, USB support must be explicitly
|
||||
enabled via the ``-machine usb=on`` argument.
|
||||
|
||||
``-drive file=json:{...{'driver':'file'}}`` (since 3.0)
|
||||
'''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The 'file' driver for drives is no longer appropriate for character or host
|
||||
devices and will only accept regular files (S_IFREG). The correct driver
|
||||
for these file types is 'host_cdrom' or 'host_device' as appropriate.
|
||||
|
||||
``-net ...,name=``\ *name* (since 3.1)
|
||||
''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``name`` parameter of the ``-net`` option is a synonym
|
||||
for the ``id`` parameter, which should now be used instead.
|
||||
|
||||
``-smp`` (invalid topologies) (since 3.1)
|
||||
'''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
CPU topology properties should describe whole machine topology including
|
||||
possible CPUs.
|
||||
|
||||
However, historically it was possible to start QEMU with an incorrect topology
|
||||
where *n* <= *sockets* * *cores* * *threads* < *maxcpus*,
|
||||
which could lead to an incorrect topology enumeration by the guest.
|
||||
Support for invalid topologies will be removed, the user must ensure
|
||||
topologies described with -smp include all possible cpus, i.e.
|
||||
*sockets* * *cores* * *threads* = *maxcpus*.
|
||||
|
||||
``-vnc acl`` (since 4.0.0)
|
||||
''''''''''''''''''''''''''
|
||||
|
||||
The ``acl`` option to the ``-vnc`` argument has been replaced
|
||||
by the ``tls-authz`` and ``sasl-authz`` options.
|
||||
|
||||
``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0)
|
||||
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``-audiodev`` argument is now the preferred way to specify audio
|
||||
backend settings instead of environment variables. To ease migration to
|
||||
the new format, the ``-audiodev-help`` option can be used to convert
|
||||
the current values of the environment variables to ``-audiodev`` options.
|
||||
|
||||
Creating sound card devices and vnc without ``audiodev=`` property (since 4.2)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
When not using the deprecated legacy audio config, each sound card
|
||||
should specify an ``audiodev=`` property. Additionally, when using
|
||||
vnc, you should specify an ``audiodev=`` propery if you plan to
|
||||
transmit audio through the VNC protocol.
|
||||
|
||||
``-mon ...,control=readline,pretty=on|off`` (since 4.1)
|
||||
'''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``pretty=on|off`` switch has no effect for HMP monitors, but is
|
||||
silently ignored. Using the switch with HMP monitors will become an
|
||||
error in the future.
|
||||
|
||||
``-realtime`` (since 4.1)
|
||||
'''''''''''''''''''''''''
|
||||
|
||||
The ``-realtime mlock=on|off`` argument has been replaced by the
|
||||
``-overcommit mem-lock=on|off`` argument.
|
||||
|
||||
``-numa node,mem=``\ *size* (since 4.1)
|
||||
'''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The parameter ``mem`` of ``-numa node`` is used to assign a part of
|
||||
guest RAM to a NUMA node. But when using it, it's impossible to manage specified
|
||||
RAM chunk on the host side (like bind it to a host node, setting bind policy, ...),
|
||||
so guest end-ups with the fake NUMA configuration with suboptiomal performance.
|
||||
However since 2014 there is an alternative way to assign RAM to a NUMA node
|
||||
using parameter ``memdev``, which does the same as ``mem`` and adds
|
||||
means to actualy manage node RAM on the host side. Use parameter ``memdev``
|
||||
with *memory-backend-ram* backend as an replacement for parameter ``mem``
|
||||
to achieve the same fake NUMA effect or a properly configured
|
||||
*memory-backend-file* backend to actually benefit from NUMA configuration.
|
||||
In future new machine versions will not accept the option but it will still
|
||||
work with old machine types. User can check QAPI schema to see if the legacy
|
||||
option is supported by looking at MachineInfo::numa-mem-supported property.
|
||||
|
||||
``-numa`` node (without memory specified) (since 4.1)
|
||||
'''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
Splitting RAM by default between NUMA nodes has the same issues as ``mem``
|
||||
parameter described above with the difference that the role of the user plays
|
||||
QEMU using implicit generic or board specific splitting rule.
|
||||
Use ``memdev`` with *memory-backend-ram* backend or ``mem`` (if
|
||||
it's supported by used machine type) to define mapping explictly instead.
|
||||
|
||||
``-mem-path`` fallback to RAM (since 4.1)
|
||||
'''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
Currently if guest RAM allocation from file pointed by ``mem-path``
|
||||
fails, QEMU falls back to allocating from RAM, which might result
|
||||
in unpredictable behavior since the backing file specified by the user
|
||||
is ignored. In the future, users will be responsible for making sure
|
||||
the backing storage specified with ``-mem-path`` can actually provide
|
||||
the guest RAM configured with ``-m`` and QEMU will fail to start up if
|
||||
RAM allocation is unsuccessful.
|
||||
|
||||
RISC-V ``-bios`` (since 4.1)
|
||||
''''''''''''''''''''''''''''
|
||||
|
||||
QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for the
|
||||
RISC-V virt machine and sifive_u machine.
|
||||
|
||||
QEMU 4.1 has no changes to the default behaviour to avoid breakages. This
|
||||
default will change in a future QEMU release, so please prepare now. All users
|
||||
of the virt or sifive_u machine must change their command line usage.
|
||||
|
||||
QEMU 4.1 has three options, please migrate to one of these three:
|
||||
1. ``-bios none`` - This is the current default behavior if no -bios option
|
||||
is included. QEMU will not automatically load any firmware. It is up
|
||||
to the user to load all the images they need.
|
||||
2. ``-bios default`` - In a future QEMU release this will become the default
|
||||
behaviour if no -bios option is specified. This option will load the
|
||||
default OpenSBI firmware automatically. The firmware is included with
|
||||
the QEMU release and no user interaction is required. All a user needs
|
||||
to do is specify the kernel they want to boot with the -kernel option
|
||||
3. ``-bios <file>`` - Tells QEMU to load the specified file as the firmwrae.
|
||||
|
||||
``-tb-size`` option (since 5.0)
|
||||
'''''''''''''''''''''''''''''''
|
||||
|
||||
QEMU 5.0 introduced an alternative syntax to specify the size of the translation
|
||||
block cache, ``-accel tcg,tb-size=``. The new syntax deprecates the
|
||||
previously available ``-tb-size`` option.
|
||||
|
||||
``-show-cursor`` option (since 5.0)
|
||||
'''''''''''''''''''''''''''''''''''
|
||||
|
||||
Use ``-display sdl,show-cursor=on`` or
|
||||
``-display gtk,show-cursor=on`` instead.
|
||||
|
||||
QEMU Machine Protocol (QMP) commands
|
||||
------------------------------------
|
||||
|
||||
``change`` (since 2.5.0)
|
||||
''''''''''''''''''''''''
|
||||
|
||||
Use ``blockdev-change-medium`` or ``change-vnc-password`` instead.
|
||||
|
||||
``migrate_set_downtime`` and ``migrate_set_speed`` (since 2.8.0)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
Use ``migrate-set-parameters`` instead.
|
||||
|
||||
``migrate-set-cache-size`` and ``query-migrate-cache-size`` (since 2.11.0)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
Use ``migrate-set-parameters`` and ``query-migrate-parameters`` instead.
|
||||
|
||||
``query-block`` result field ``dirty-bitmaps[i].status`` (since 4.0)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``status`` field of the ``BlockDirtyInfo`` structure, returned by
|
||||
the query-block command is deprecated. Two new boolean fields,
|
||||
``recording`` and ``busy`` effectively replace it.
|
||||
|
||||
``query-block`` result field ``dirty-bitmaps`` (Since 4.2)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by
|
||||
the query-block command is itself now deprecated. The ``dirty-bitmaps``
|
||||
field of the ``BlockDeviceInfo`` struct should be used instead, which is the
|
||||
type of the ``inserted`` field in query-block replies, as well as the
|
||||
type of array items in query-named-block-nodes.
|
||||
|
||||
Since the ``dirty-bitmaps`` field is optionally present in both the old and
|
||||
new locations, clients must use introspection to learn where to anticipate
|
||||
the field if/when it does appear in command output.
|
||||
|
||||
``query-cpus`` (since 2.12.0)
|
||||
'''''''''''''''''''''''''''''
|
||||
|
||||
The ``query-cpus`` command is replaced by the ``query-cpus-fast`` command.
|
||||
|
||||
``query-cpus-fast`` ``arch`` output member (since 3.0.0)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``arch`` output member of the ``query-cpus-fast`` command is
|
||||
replaced by the ``target`` output member.
|
||||
|
||||
``cpu-add`` (since 4.0)
|
||||
'''''''''''''''''''''''
|
||||
|
||||
Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``. See
|
||||
documentation of ``query-hotpluggable-cpus`` for additional
|
||||
details.
|
||||
|
||||
``query-events`` (since 4.0)
|
||||
''''''''''''''''''''''''''''
|
||||
|
||||
The ``query-events`` command has been superseded by the more powerful
|
||||
and accurate ``query-qmp-schema`` command.
|
||||
|
||||
chardev client socket with ``wait`` option (since 4.0)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
Character devices creating sockets in client mode should not specify
|
||||
the 'wait' field, which is only applicable to sockets in server mode
|
||||
|
||||
Human Monitor Protocol (HMP) commands
|
||||
-------------------------------------
|
||||
|
||||
The ``hub_id`` parameter of ``hostfwd_add`` / ``hostfwd_remove`` (since 3.1)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``[hub_id name]`` parameter tuple of the 'hostfwd_add' and
|
||||
'hostfwd_remove' HMP commands has been replaced by ``netdev_id``.
|
||||
|
||||
``cpu-add`` (since 4.0)
|
||||
'''''''''''''''''''''''
|
||||
|
||||
Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``. See
|
||||
documentation of ``query-hotpluggable-cpus`` for additional details.
|
||||
|
||||
``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, ``acl_remove`` (since 4.0.0)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, and
|
||||
``acl_remove`` commands are deprecated with no replacement. Authorization
|
||||
for VNC should be performed using the pluggable QAuthZ objects.
|
||||
|
||||
Guest Emulator ISAs
|
||||
-------------------
|
||||
|
||||
RISC-V ISA privledge specification version 1.09.1 (since 4.1)
|
||||
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The RISC-V ISA privledge specification version 1.09.1 has been deprecated.
|
||||
QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these
|
||||
should be used instead of the 1.09.1 version.
|
||||
|
||||
System emulator CPUS
|
||||
--------------------
|
||||
|
||||
RISC-V ISA CPUs (since 4.1)
|
||||
'''''''''''''''''''''''''''
|
||||
|
||||
The RISC-V cpus with the ISA version in the CPU name have been depcreated. The
|
||||
four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and
|
||||
``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec``
|
||||
option when using the ``rv32`` or ``rv64`` CPUs.
|
||||
|
||||
RISC-V ISA CPUs (since 4.1)
|
||||
'''''''''''''''''''''''''''
|
||||
|
||||
The RISC-V no MMU cpus have been depcreated. The two CPUs: ``rv32imacu-nommu`` and
|
||||
``rv64imacu-nommu`` should no longer be used. Instead the MMU status can be specified
|
||||
via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs.
|
||||
|
||||
System emulator devices
|
||||
-----------------------
|
||||
|
||||
``ide-drive`` (since 4.2)
|
||||
'''''''''''''''''''''''''
|
||||
|
||||
The 'ide-drive' device is deprecated. Users should use 'ide-hd' or
|
||||
'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed.
|
||||
|
||||
``scsi-disk`` (since 4.2)
|
||||
'''''''''''''''''''''''''
|
||||
|
||||
The 'scsi-disk' device is deprecated. Users should use 'scsi-hd' or
|
||||
'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed.
|
||||
|
||||
System emulator machines
|
||||
------------------------
|
||||
|
||||
mips ``r4k`` platform (since 5.0)
|
||||
'''''''''''''''''''''''''''''''''
|
||||
|
||||
This machine type is very old and unmaintained. Users should use the ``malta``
|
||||
machine type instead.
|
||||
|
||||
``pc-1.0``, ``pc-1.1``, ``pc-1.2`` and ``pc-1.3`` (since 5.0)
|
||||
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
These machine types are very old and likely can not be used for live migration
|
||||
from old QEMU versions anymore. A newer machine type should be used instead.
|
||||
|
||||
``spike_v1.9.1`` and ``spike_v1.10`` (since 4.1)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The version specific Spike machines have been deprecated in favour of the
|
||||
generic ``spike`` machine. If you need to specify an older version of the RISC-V
|
||||
spec you can use the ``-cpu rv64gcsu,priv_spec=v1.9.1`` command line argument.
|
||||
|
||||
Device options
|
||||
--------------
|
||||
|
||||
Emulated device options
|
||||
'''''''''''''''''''''''
|
||||
|
||||
``-device virtio-blk,scsi=on|off`` (since 5.0.0)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0
|
||||
and later do not support it because the virtio-scsi device was introduced for
|
||||
full SCSI support. Use virtio-scsi instead when SCSI passthrough is required.
|
||||
|
||||
Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
|
||||
alias.
|
||||
|
||||
Block device options
|
||||
''''''''''''''''''''
|
||||
|
||||
``"backing": ""`` (since 2.12.0)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In order to prevent QEMU from automatically opening an image's backing
|
||||
chain, use ``"backing": null`` instead.
|
||||
|
||||
``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1.0)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Options for ``rbd`` should be specified according to its runtime options,
|
||||
like other block drivers. Legacy parsing of keyvalue pair encoded
|
||||
filenames is useful to open images with the old format for backing files;
|
||||
These image files should be updated to use the current format.
|
||||
|
||||
Example of legacy encoding::
|
||||
|
||||
json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
|
||||
|
||||
The above, converted to the current supported format::
|
||||
|
||||
json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
|
||||
|
||||
Related binaries
|
||||
----------------
|
||||
|
||||
``qemu-img convert -n -o`` (since 4.2.0)
|
||||
''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
All options specified in ``-o`` are image creation options, so
|
||||
they have no effect when used with ``-n`` to skip image creation.
|
||||
Silently ignored options can be confusing, so this combination of
|
||||
options will be made an error in future versions.
|
||||
|
||||
Backwards compatibility
|
||||
-----------------------
|
||||
|
||||
Runnability guarantee of CPU models (since 4.1.0)
|
||||
'''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
Previous versions of QEMU never changed existing CPU models in
|
||||
ways that introduced additional host software or hardware
|
||||
requirements to the VM. This allowed management software to
|
||||
safely change the machine type of an existing VM without
|
||||
introducing new requirements ("runnability guarantee"). This
|
||||
prevented CPU models from being updated to include CPU
|
||||
vulnerability mitigations, leaving guests vulnerable in the
|
||||
default configuration.
|
||||
|
||||
The CPU model runnability guarantee won't apply anymore to
|
||||
existing CPU models. Management software that needs runnability
|
||||
guarantees must resolve the CPU model aliases using te
|
||||
``alias-of`` field returned by the ``query-cpu-definitions`` QMP
|
||||
command.
|
||||
|
||||
While those guarantees are kept, the return value of
|
||||
``query-cpu-definitions`` will have existing CPU model aliases
|
||||
point to a version that doesn't break runnability guarantees
|
||||
(specifically, version 1 of those CPU models). In future QEMU
|
||||
versions, aliases will point to newer CPU model versions
|
||||
depending on the machine type, so management software must
|
||||
resolve CPU model aliases before starting a virtual machine.
|
||||
|
||||
|
||||
Recently removed features
|
||||
=========================
|
||||
|
||||
What follows is a record of recently removed, formerly deprecated
|
||||
features that serves as a record for users who have encountered
|
||||
trouble after a recent upgrade.
|
||||
|
||||
QEMU Machine Protocol (QMP) commands
|
||||
------------------------------------
|
||||
|
||||
``block-dirty-bitmap-add`` "autoload" parameter (since 4.2.0)
|
||||
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The "autoload" parameter has been ignored since 2.12.0. All bitmaps
|
||||
are automatically loaded from qcow2 images.
|
||||
|
||||
Related binaries
|
||||
----------------
|
||||
|
||||
``qemu-nbd --partition`` (removed in 5.0.0)
|
||||
'''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``qemu-nbd --partition $digit`` code (also spelled ``-P``)
|
||||
could only handle MBR partitions, and never correctly handled logical
|
||||
partitions beyond partition 5. Exporting a partition can still be
|
||||
done by utilizing the ``--image-opts`` option with a raw blockdev
|
||||
using the ``offset`` and ``size`` parameters layered on top of
|
||||
any other existing blockdev. For example, if partition 1 is 100MiB
|
||||
long starting at 1MiB, the old command::
|
||||
|
||||
qemu-nbd -t -P 1 -f qcow2 file.qcow2
|
||||
|
||||
can be rewritten as::
|
||||
|
||||
qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2
|
||||
@@ -0,0 +1,228 @@
|
||||
|
||||
In addition to using normal file images for the emulated storage
|
||||
devices, QEMU can also use networked resources such as iSCSI devices.
|
||||
These are specified using a special URL syntax.
|
||||
|
||||
``iSCSI``
|
||||
iSCSI support allows QEMU to access iSCSI resources directly and use
|
||||
as images for the guest storage. Both disk and cdrom images are
|
||||
supported.
|
||||
|
||||
Syntax for specifying iSCSI LUNs is
|
||||
"iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>"
|
||||
|
||||
By default qemu will use the iSCSI initiator-name
|
||||
'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from
|
||||
the command line or a configuration file.
|
||||
|
||||
Since version Qemu 2.4 it is possible to specify a iSCSI request
|
||||
timeout to detect stalled requests and force a reestablishment of the
|
||||
session. The timeout is specified in seconds. The default is 0 which
|
||||
means no timeout. Libiscsi 1.15.0 or greater is required for this
|
||||
feature.
|
||||
|
||||
Example (without authentication):
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
|
||||
-cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
|
||||
-drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
|
||||
|
||||
Example (CHAP username/password via URL):
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
|
||||
|
||||
Example (CHAP username/password via environment variables):
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
LIBISCSI_CHAP_USERNAME="user" \
|
||||
LIBISCSI_CHAP_PASSWORD="password" \
|
||||
|qemu_system| -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
|
||||
|
||||
``NBD``
|
||||
QEMU supports NBD (Network Block Devices) both using TCP protocol as
|
||||
well as Unix Domain Sockets. With TCP, the default port is 10809.
|
||||
|
||||
Syntax for specifying a NBD device using TCP, in preferred URI form:
|
||||
"nbd://<server-ip>[:<port>]/[<export>]"
|
||||
|
||||
Syntax for specifying a NBD device using Unix Domain Sockets;
|
||||
remember that '?' is a shell glob character and may need quoting:
|
||||
"nbd+unix:///[<export>]?socket=<domain-socket>"
|
||||
|
||||
Older syntax that is also recognized:
|
||||
"nbd:<server-ip>:<port>[:exportname=<export>]"
|
||||
|
||||
Syntax for specifying a NBD device using Unix Domain Sockets
|
||||
"nbd:unix:<domain-socket>[:exportname=<export>]"
|
||||
|
||||
Example for TCP
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| --drive file=nbd:192.0.2.1:30000
|
||||
|
||||
Example for Unix Domain Sockets
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| --drive file=nbd:unix:/tmp/nbd-socket
|
||||
|
||||
``SSH``
|
||||
QEMU supports SSH (Secure Shell) access to remote disks.
|
||||
|
||||
Examples:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -drive file=ssh://user@host/path/to/disk.img
|
||||
|qemu_system| -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
|
||||
|
||||
Currently authentication must be done using ssh-agent. Other
|
||||
authentication methods may be supported in future.
|
||||
|
||||
``Sheepdog``
|
||||
Sheepdog is a distributed storage system for QEMU. QEMU supports
|
||||
using either local sheepdog devices or remote networked devices.
|
||||
|
||||
Syntax for specifying a sheepdog device
|
||||
|
||||
::
|
||||
|
||||
sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
|
||||
|
||||
Example
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
|
||||
|
||||
See also https://sheepdog.github.io/sheepdog/.
|
||||
|
||||
``GlusterFS``
|
||||
GlusterFS is a user space distributed file system. QEMU supports the
|
||||
use of GlusterFS volumes for hosting VM disk images using TCP, Unix
|
||||
Domain Sockets and RDMA transport protocols.
|
||||
|
||||
Syntax for specifying a VM disk image on GlusterFS volume is
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
URI:
|
||||
gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
|
||||
|
||||
JSON:
|
||||
'json:{"driver":"qcow2","file":{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
|
||||
"server":[{"type":"tcp","host":"...","port":"..."},
|
||||
{"type":"unix","socket":"..."}]}}'
|
||||
|
||||
Example
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
URI:
|
||||
|qemu_system| --drive file=gluster://192.0.2.1/testvol/a.img,
|
||||
file.debug=9,file.logfile=/var/log/qemu-gluster.log
|
||||
|
||||
JSON:
|
||||
|qemu_system| 'json:{"driver":"qcow2",
|
||||
"file":{"driver":"gluster",
|
||||
"volume":"testvol","path":"a.img",
|
||||
"debug":9,"logfile":"/var/log/qemu-gluster.log",
|
||||
"server":[{"type":"tcp","host":"1.2.3.4","port":24007},
|
||||
{"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
|
||||
|qemu_system| -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
|
||||
file.debug=9,file.logfile=/var/log/qemu-gluster.log,
|
||||
file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
|
||||
file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
|
||||
|
||||
See also http://www.gluster.org.
|
||||
|
||||
``HTTP/HTTPS/FTP/FTPS``
|
||||
QEMU supports read-only access to files accessed over http(s) and
|
||||
ftp(s).
|
||||
|
||||
Syntax using a single filename:
|
||||
|
||||
::
|
||||
|
||||
<protocol>://[<username>[:<password>]@]<host>/<path>
|
||||
|
||||
where:
|
||||
|
||||
``protocol``
|
||||
'http', 'https', 'ftp', or 'ftps'.
|
||||
|
||||
``username``
|
||||
Optional username for authentication to the remote server.
|
||||
|
||||
``password``
|
||||
Optional password for authentication to the remote server.
|
||||
|
||||
``host``
|
||||
Address of the remote server.
|
||||
|
||||
``path``
|
||||
Path on the remote server, including any query string.
|
||||
|
||||
The following options are also supported:
|
||||
|
||||
``url``
|
||||
The full URL when passing options to the driver explicitly.
|
||||
|
||||
``readahead``
|
||||
The amount of data to read ahead with each range request to the
|
||||
remote server. This value may optionally have the suffix 'T', 'G',
|
||||
'M', 'K', 'k' or 'b'. If it does not have a suffix, it will be
|
||||
assumed to be in bytes. The value must be a multiple of 512 bytes.
|
||||
It defaults to 256k.
|
||||
|
||||
``sslverify``
|
||||
Whether to verify the remote server's certificate when connecting
|
||||
over SSL. It can have the value 'on' or 'off'. It defaults to
|
||||
'on'.
|
||||
|
||||
``cookie``
|
||||
Send this cookie (it can also be a list of cookies separated by
|
||||
';') with each outgoing request. Only supported when using
|
||||
protocols such as HTTP which support cookies, otherwise ignored.
|
||||
|
||||
``timeout``
|
||||
Set the timeout in seconds of the CURL connection. This timeout is
|
||||
the time that CURL waits for a response from the remote server to
|
||||
get the size of the image to be downloaded. If not set, the
|
||||
default timeout of 5 seconds is used.
|
||||
|
||||
Note that when passing options to qemu explicitly, ``driver`` is the
|
||||
value of <protocol>.
|
||||
|
||||
Example: boot from a remote Fedora 20 live ISO image
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system_x86| --drive media=cdrom,file=https://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
|
||||
|
||||
|qemu_system_x86| --drive media=cdrom,file.driver=http,file.url=http://archives.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
|
||||
|
||||
Example: boot from a remote Fedora 20 cloud image using a local
|
||||
overlay for writes, copy-on-read, and a readahead of 64k
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"http",, "file.url":"http://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2
|
||||
|
||||
|qemu_system_x86| -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
|
||||
|
||||
Example: boot from an image stored on a VMware vSphere server with a
|
||||
self-signed certificate using a local overlay for writes, a readahead
|
||||
of 64k and a timeout of 10 seconds.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"https",, "file.url":"https://user:password@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10}' /tmp/test.qcow2
|
||||
|
||||
|qemu_system_x86| -drive file=/tmp/test.qcow2
|
||||
@@ -0,0 +1,81 @@
|
||||
.. _gdb_005fusage:
|
||||
|
||||
GDB usage
|
||||
---------
|
||||
|
||||
QEMU has a primitive support to work with gdb, so that you can do
|
||||
'Ctrl-C' while the virtual machine is running and inspect its state.
|
||||
|
||||
In order to use gdb, launch QEMU with the '-s' option. It will wait for
|
||||
a gdb connection:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -s -kernel bzImage -hda rootdisk.img -append "root=/dev/hda"
|
||||
Connected to host network interface: tun0
|
||||
Waiting gdb connection on port 1234
|
||||
|
||||
Then launch gdb on the 'vmlinux' executable::
|
||||
|
||||
> gdb vmlinux
|
||||
|
||||
In gdb, connect to QEMU::
|
||||
|
||||
(gdb) target remote localhost:1234
|
||||
|
||||
Then you can use gdb normally. For example, type 'c' to launch the
|
||||
kernel::
|
||||
|
||||
(gdb) c
|
||||
|
||||
Here are some useful tips in order to use gdb on system code:
|
||||
|
||||
1. Use ``info reg`` to display all the CPU registers.
|
||||
|
||||
2. Use ``x/10i $eip`` to display the code at the PC position.
|
||||
|
||||
3. Use ``set architecture i8086`` to dump 16 bit code. Then use
|
||||
``x/10i $cs*16+$eip`` to dump the code at the PC position.
|
||||
|
||||
Advanced debugging options:
|
||||
|
||||
The default single stepping behavior is step with the IRQs and timer
|
||||
service routines off. It is set this way because when gdb executes a
|
||||
single step it expects to advance beyond the current instruction. With
|
||||
the IRQs and timer service routines on, a single step might jump into
|
||||
the one of the interrupt or exception vectors instead of executing the
|
||||
current instruction. This means you may hit the same breakpoint a number
|
||||
of times before executing the instruction gdb wants to have executed.
|
||||
Because there are rare circumstances where you want to single step into
|
||||
an interrupt vector the behavior can be controlled from GDB. There are
|
||||
three commands you can query and set the single step behavior:
|
||||
|
||||
``maintenance packet qqemu.sstepbits``
|
||||
This will display the MASK bits used to control the single stepping
|
||||
IE:
|
||||
|
||||
::
|
||||
|
||||
(gdb) maintenance packet qqemu.sstepbits
|
||||
sending: "qqemu.sstepbits"
|
||||
received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
|
||||
|
||||
``maintenance packet qqemu.sstep``
|
||||
This will display the current value of the mask used when single
|
||||
stepping IE:
|
||||
|
||||
::
|
||||
|
||||
(gdb) maintenance packet qqemu.sstep
|
||||
sending: "qqemu.sstep"
|
||||
received: "0x7"
|
||||
|
||||
``maintenance packet Qqemu.sstep=HEX_VALUE``
|
||||
This will change the single step mask, so if wanted to enable IRQs on
|
||||
the single step, but not timers, you would use:
|
||||
|
||||
::
|
||||
|
||||
(gdb) maintenance packet Qqemu.sstep=0x5
|
||||
sending: "qemu.sstep=0x5"
|
||||
received: "OK"
|
||||
@@ -0,0 +1,85 @@
|
||||
.. _disk_005fimages:
|
||||
|
||||
Disk Images
|
||||
-----------
|
||||
|
||||
QEMU supports many disk image formats, including growable disk images
|
||||
(their size increase as non empty sectors are written), compressed and
|
||||
encrypted disk images.
|
||||
|
||||
.. _disk_005fimages_005fquickstart:
|
||||
|
||||
Quick start for disk image creation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can create a disk image with the command::
|
||||
|
||||
qemu-img create myimage.img mysize
|
||||
|
||||
where myimage.img is the disk image filename and mysize is its size in
|
||||
kilobytes. You can add an ``M`` suffix to give the size in megabytes and
|
||||
a ``G`` suffix for gigabytes.
|
||||
|
||||
See the qemu-img invocation documentation for more information.
|
||||
|
||||
.. _disk_005fimages_005fsnapshot_005fmode:
|
||||
|
||||
Snapshot mode
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
If you use the option ``-snapshot``, all disk images are considered as
|
||||
read only. When sectors in written, they are written in a temporary file
|
||||
created in ``/tmp``. You can however force the write back to the raw
|
||||
disk images by using the ``commit`` monitor command (or C-a s in the
|
||||
serial console).
|
||||
|
||||
.. _vm_005fsnapshots:
|
||||
|
||||
VM snapshots
|
||||
~~~~~~~~~~~~
|
||||
|
||||
VM snapshots are snapshots of the complete virtual machine including CPU
|
||||
state, RAM, device state and the content of all the writable disks. In
|
||||
order to use VM snapshots, you must have at least one non removable and
|
||||
writable block device using the ``qcow2`` disk image format. Normally
|
||||
this device is the first virtual hard drive.
|
||||
|
||||
Use the monitor command ``savevm`` to create a new VM snapshot or
|
||||
replace an existing one. A human readable name can be assigned to each
|
||||
snapshot in addition to its numerical ID.
|
||||
|
||||
Use ``loadvm`` to restore a VM snapshot and ``delvm`` to remove a VM
|
||||
snapshot. ``info snapshots`` lists the available snapshots with their
|
||||
associated information::
|
||||
|
||||
(qemu) info snapshots
|
||||
Snapshot devices: hda
|
||||
Snapshot list (from hda):
|
||||
ID TAG VM SIZE DATE VM CLOCK
|
||||
1 start 41M 2006-08-06 12:38:02 00:00:14.954
|
||||
2 40M 2006-08-06 12:43:29 00:00:18.633
|
||||
3 msys 40M 2006-08-06 12:44:04 00:00:23.514
|
||||
|
||||
A VM snapshot is made of a VM state info (its size is shown in
|
||||
``info snapshots``) and a snapshot of every writable disk image. The VM
|
||||
state info is stored in the first ``qcow2`` non removable and writable
|
||||
block device. The disk image snapshots are stored in every disk image.
|
||||
The size of a snapshot in a disk image is difficult to evaluate and is
|
||||
not shown by ``info snapshots`` because the associated disk sectors are
|
||||
shared among all the snapshots to save disk space (otherwise each
|
||||
snapshot would need a full copy of all the disk images).
|
||||
|
||||
When using the (unrelated) ``-snapshot`` option
|
||||
(:ref:`disk_005fimages_005fsnapshot_005fmode`),
|
||||
you can always make VM snapshots, but they are deleted as soon as you
|
||||
exit QEMU.
|
||||
|
||||
VM snapshots currently have the following known limitations:
|
||||
|
||||
- They cannot cope with removable devices if they are removed or
|
||||
inserted after a snapshot is done.
|
||||
|
||||
- A few device drivers still have incomplete snapshot support so their
|
||||
state is not saved or restored properly (in particular USB).
|
||||
|
||||
.. include:: qemu-block-drivers.rst.inc
|
||||
+20
-2
@@ -12,7 +12,25 @@ or Hypervisor.Framework.
|
||||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:maxdepth: 3
|
||||
|
||||
qemu-block-drivers
|
||||
quickstart
|
||||
invocation
|
||||
keys
|
||||
mux-chardev
|
||||
monitor
|
||||
images
|
||||
net
|
||||
usb
|
||||
ivshmem
|
||||
linuxboot
|
||||
vnc-security
|
||||
tls
|
||||
gdb
|
||||
managed-startup
|
||||
targets
|
||||
security
|
||||
vfio-ap
|
||||
deprecated
|
||||
build-platforms
|
||||
license
|
||||
|
||||
@@ -0,0 +1,18 @@
|
||||
.. _sec_005finvocation:
|
||||
|
||||
Invocation
|
||||
----------
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| [options] [disk_image]
|
||||
|
||||
disk_image is a raw hard disk image for IDE hard disk 0. Some targets do
|
||||
not need a disk image.
|
||||
|
||||
.. hxtool-doc:: qemu-options.hx
|
||||
|
||||
Device URL Syntax
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. include:: device-url-syntax.rst.inc
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user