xemu-project/xemu
1
0
Fork 0
mirror of https://github.com/xemu-project/xemu.git synced 2024-11-24 03:59:52 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

QAPI patches for 2020-02-15

Browse Source 
-----BEGIN PGP SIGNATURE-----
 
 iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAl5Hy4wSHGFybWJydUBy
 ZWRoYXQuY29tAAoJEDhwtADrkYZTTygP/3Oaqnsye6AvJZ5UOxSmh5hMQ8Q10AL7
 HVulvQbWhbNfdRPT8maYIfES/EIsUNXmH7DGvXoh4vlhTiRUzECJM02PbehHyZaV
 cv9xQG5dcRUHnACB4YeJ6htLGIcuENhFbjOzm8alYtSlsvEvnVgdZkeBlU6X6xdr
 EuZ2L3FhLUE6kZ9+eyzFUQuFENnopakwEBzSJ3Zx9XQz8Stav8uDcP5n2N2Mot3f
 7x/MIrFTmY1Zs8Vg9KhLi9+uWwj0JnWKGJdsfEnl61hf5SelKWwLmMp+UasNNCm8
 jdHQBsV3qEYEUCwiM4CpQ/jHVypAXWNJKjsJl2GpPRjpH73/8DHX+0suNmIF3WRk
 25MtcFip+1AbinPb2U3h/huJ20S6/aYamtnuAUSaNFd0Dx3pv5Boi/J7BAKPmY63
 z4teyJ6NfjU8Iy8dtu28GfacnF/85ydOYYCkTpCJYe2EIBLZTTWSg7NHMNb2vwG9
 MlnVZeo42HUn8mKC8mXhFzgBNc6pjw/8VX2Nw6nj66Xw/3IkJZMi3k9E6zfQEDxm
 GEDPZ3nB058iZ4WdLQ8nQdlvlBlhSbYsVvs1m+uSpjZwC4G7Qq4jRB/c/r/05gwS
 SRX8rvqx9Ho0Qui3qlJ49iwZod6sIqEcGPVRJjWsA/5afpJO95EPCJ/+/Vu1gJUV
 qjyuuCGdjXFU
 =UwrK
 -----END PGP SIGNATURE-----

Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2020-02-15' into staging

QAPI patches for 2020-02-15

# gpg: Signature made Sat 15 Feb 2020 10:44:28 GMT
# gpg:                using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg:                issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full]
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>" [full]
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* remotes/armbru/tags/pull-qapi-2020-02-15:
  qapi: Delete all the "foo: dropped in n.n" notes
  qapi/migration.json: Replace _this_ with *this*
  qapi: Add blank lines before bulleted lists
  qapi: Use explicit bulleted lists
  qapi/ui.json: Avoid `...' Texinfo style quoting
  qapi/ui.json: Put input-send-event body text in the right place
  qapi: Remove hardcoded tabs
  qapi: Fix indent level on doc comments in json files
  qapi: Fix incorrect "Not documented" claims in QMP documentation
  qapi/block-core.json: Use literal block for ascii art
  qga/qapi-schema.json: minor format fixups for rST
  qga/qapi-schema.json: Fix indent level on doc comments
  qga/qapi-schema.json: Fix missing '-' in GuestDiskBusType doc comment
  Makefile: Fix typo in dependency list for interop manpages
  configure: Check that sphinx-build is using Python 3
  configure: Pick sphinx-build-3 when available
  configure: Allow user to specify sphinx-build binary
  qapi: Expand documentation for LostTickPolicy

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
This commit is contained in:
Peter Maydell 2020-02-16 21:15:25 +00:00
commit 9ced5c7c20
25 changed files with 1070 additions and 1022 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Makefile
View File

@ -1030,7 +1030,7 @@ sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html \
# Note the use of different doctree for each (manual, builder) tuple;
# this works around Sphinx not handling parallel invocation on
# a single doctree: https://github.com/sphinx-doc/sphinx/issues/2946
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")
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) \
$(wildcard $(SRC_PATH)/docs/$1/*.rst.inc) \
@ -1059,7 +1059,7 @@ $(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system)
$(call define-manpage-rule,interop,\
qemu-ga.8 qemu-img.1 qemu-nbd.8 qemu-trace-stap.1\
virtiofsd.1 virtfs-proxy-helper.1,\
$(SRC_PATH/qemu-img-cmds.hx))
$(SRC_PATH)/qemu-img-cmds.hx)
$(call define-manpage-rule,system,qemu-block-drivers.7)

32
configure vendored
View File

@ -914,6 +914,17 @@ do
break
fi
done
sphinx_build=
for binary in sphinx-build-3 sphinx-build
do
if has "$binary"
then
sphinx_build=$(command -v "$binary")
break
fi
done
: ${smbd=${SMBD-/usr/sbin/smbd}}
# Default objcc to clang if available, otherwise use CC
@ -975,6 +986,8 @@ for opt do
;;
--python=*) python="$optarg"
;;
--sphinx-build=*) sphinx_build="$optarg"
;;
--gcov=*) gcov_tool="$optarg"
;;
--smbd=*) smbd="$optarg"
@ -1677,6 +1690,7 @@ Advanced options (experts only):
--make=MAKE use specified make [$make]
--install=INSTALL use specified install [$install]
--python=PYTHON use specified python [$python]
--sphinx-build=SPHINX use specified sphinx-build [$sphinx_build]
--smbd=SMBD use specified smbd [$smbd]
--with-git=GIT use specified git [$git]
--static enable static build [$static]
@ -4799,16 +4813,24 @@ has_sphinx_build() {
# sphinx-build doesn't exist at all or if it is too old.
mkdir -p "$TMPDIR1/sphinx"
touch "$TMPDIR1/sphinx/index.rst"
sphinx-build -c "$source_path/docs" -b html "$TMPDIR1/sphinx" "$TMPDIR1/sphinx/out" >/dev/null 2>&1
"$sphinx_build" -c "$source_path/docs" -b html "$TMPDIR1/sphinx" "$TMPDIR1/sphinx/out" >/dev/null 2>&1
}
# Check if tools are available to build documentation.
if test "$docs" != "no" ; then
if has makeinfo && has pod2man && has_sphinx_build; then
if has_sphinx_build; then
sphinx_ok=yes
else
sphinx_ok=no
fi
if has makeinfo && has pod2man && test "$sphinx_ok" = "yes"; then
docs=yes
else
if test "$docs" = "yes" ; then
feature_not_found "docs" "Install texinfo, Perl/perl-podlators and python-sphinx"
if has $sphinx_build && test "$sphinx_ok" != "yes"; then
echo "Warning: $sphinx_build exists but it is either too old or uses too old a Python version" >&2
fi
feature_not_found "docs" "Install texinfo, Perl/perl-podlators and a Python 3 version of python-sphinx"
fi
docs=no
fi
@ -6474,6 +6496,9 @@ echo "QEMU_LDFLAGS $QEMU_LDFLAGS"
echo "make $make"
echo "install $install"
echo "python $python ($python_version)"
if test "$docs" != "no"; then
echo "sphinx-build $sphinx_build"
fi
echo "slirp support $slirp $(echo_version $slirp $slirp_version)"
if test "$slirp" != "no" ; then
echo "smbd $smbd"
@ -7506,6 +7531,7 @@ echo "INSTALL_DATA=$install -c -m 0644" >> $config_host_mak
echo "INSTALL_PROG=$install -c -m 0755" >> $config_host_mak
echo "INSTALL_LIB=$install -c -m 0644" >> $config_host_mak
echo "PYTHON=$python" >> $config_host_mak
echo "SPHINX_BUILD=$sphinx_build" >> $config_host_mak
echo "CC=$cc" >> $config_host_mak
if $iasl -h > /dev/null 2>&1; then
echo "IASL=$iasl" >> $config_host_mak

10
docs/conf.py
View File

@ -28,6 +28,16 @@
import os
import sys
import sphinx
from sphinx.errors import VersionRequirementError
# Make Sphinx fail cleanly if using an old Python, rather than obscurely
# failing because some code in one of our extensions doesn't work there.
# Unfortunately this doesn't display very neatly (there's an unavoidable
# Python backtrace) but at least the information gets printed...
if sys.version_info < (3,5):
raise VersionRequirementError(
"QEMU requires a Sphinx that uses Python 3.5 or better\n")
# The per-manual conf.py will set qemu_docdir for a single-manual build;
# otherwise set it here if this is an entire-manual-set build.

1139
qapi/block-core.json
View File

File diff suppressed because it is too large Load Diff

47
qapi/block.json
View File

@ -115,15 +115,12 @@
#
# For the arguments, see the documentation of BlockdevSnapshotInternal.
#
# Returns: nothing on success
#
# If @device is not a valid block device, GenericError
#
# If any snapshot matching @name exists, or @name is empty,
# GenericError
#
# If the format of the image used does not support it,
# BlockFormatFeatureNotSupported
# Returns: - nothing on success
# - If @device is not a valid block device, GenericError
# - If any snapshot matching @name exists, or @name is empty,
# GenericError
# - If the format of the image used does not support it,
# BlockFormatFeatureNotSupported
#
# Since: 1.7
#
@ -154,12 +151,12 @@
#
# @name: optional the snapshot's name to be deleted
#
# Returns: SnapshotInfo on success
# If @device is not a valid block device, GenericError
# If snapshot not found, GenericError
# If the format of the image used does not support it,
# BlockFormatFeatureNotSupported
# If @id and @name are both not specified, GenericError
# Returns: - SnapshotInfo on success
# - If @device is not a valid block device, GenericError
# - If snapshot not found, GenericError
# - If the format of the image used does not support it,
# BlockFormatFeatureNotSupported
# - If @id and @name are both not specified, GenericError
#
# Since: 1.7
#
@ -190,17 +187,15 @@
#
# Ejects a device from a removable drive.
#
# @device: Block device name (deprecated, use @id instead)
# @device: Block device name (deprecated, use @id instead)
#
# @id: The name or QOM path of the guest device (since: 2.8)
# @id: The name or QOM path of the guest device (since: 2.8)
#
# @force: If true, eject regardless of whether the drive is locked.
# If not specified, the default value is false.
#
# Returns: Nothing on success
#
# If @device is not a valid block device, DeviceNotFound
# @force: If true, eject regardless of whether the drive is locked.
# If not specified, the default value is false.
#
# Returns: - Nothing on success
# - If @device is not a valid block device, DeviceNotFound
# Notes: Ejecting a device with no media results in success
#
# Since: 0.14.0
@ -254,7 +249,7 @@
# (Since 5.0)
#
# @writable: Whether clients should be able to write to the device via the
# NBD connection (default false).
# NBD connection (default false).
#
# @bitmap: Also export the dirty bitmap reachable from @device, so the
# NBD client can use NBD_OPT_SET_META_CONTEXT with
@ -281,10 +276,10 @@
# Potential additional modes to be added in the future:
#
# hide: Just hide export from new clients, leave existing connections as is.
# Remove export after all clients are disconnected.
# Remove export after all clients are disconnected.
#
# soft: Hide export from new clients, answer with ESHUTDOWN for all further
# requests from existing clients.
# requests from existing clients.
#
# Since: 2.12
##

10
qapi/char.json
View File

@ -133,6 +133,7 @@
# @data: data to write
#
# @format: data encoding (default 'utf8').
#
# - base64: data must be base64 encoded text. Its binary
# decoding gets written.
# - utf8: data's UTF-8 encoding is written
@ -167,6 +168,7 @@
# @size: how many bytes to read at most
#
# @format: data encoding (default 'utf8').
#
# - base64: the data read is returned in base64 encoding.
# - utf8: the data read is interpreted as UTF-8.
# Bug: can screw up when the buffer contains invalid UTF-8
@ -262,11 +264,11 @@
# @tn3270: enable tn3270 protocol on server
# sockets (default: false) (Since: 2.10)
# @websocket: enable websocket protocol on server
# sockets (default: false) (Since: 3.1)
# sockets (default: false) (Since: 3.1)
# @reconnect: For a client socket, if a socket is disconnected,
# then attempt a reconnect after the given number of seconds.
# Setting this to zero disables this function. (default: 0)
# (Since: 2.2)
# then attempt a reconnect after the given number of seconds.
# Setting this to zero disables this function. (default: 0)
# (Since: 2.2)
#
# Since: 1.4
##

4
qapi/dump.json
View File

@ -38,8 +38,8 @@
# using gdb to process the core file.
#
# IMPORTANT: this option can make QEMU allocate several gigabytes
# of RAM. This can happen for a large guest, or a
# malicious guest pretending to be large.
# of RAM. This can happen for a large guest, or a
# malicious guest pretending to be large.
#
# Also, paging=true has the following limitations:
#

12
qapi/introspect.json
View File

@ -34,15 +34,15 @@
# alternate that includes the original type alongside something else.
#
# Returns: array of @SchemaInfo, where each element describes an
# entity in the ABI: command, event, type, ...
# entity in the ABI: command, event, type, ...
#
# The order of the various SchemaInfo is unspecified; however, all
# names are guaranteed to be unique (no name will be duplicated with
# different meta-types).
# The order of the various SchemaInfo is unspecified; however, all
# names are guaranteed to be unique (no name will be duplicated with
# different meta-types).
#
# Note: the QAPI schema is also used to help define *internal*
# interfaces, by defining QAPI types. These are not part of the QMP
# wire ABI, and therefore not returned by this command.
# interfaces, by defining QAPI types. These are not part of the QMP
# wire ABI, and therefore not returned by this command.
#
# Since: 2.5
##

32
qapi/job.json
View File

@ -214,28 +214,28 @@
#
# Information about a job.
#
# @id: The job identifier
# @id: The job identifier
#
# @type: The kind of job that is being performed
# @type: The kind of job that is being performed
#
# @status: Current job state/status
# @status: Current job state/status
#
# @current-progress: Progress made until now. The unit is arbitrary and the
# value can only meaningfully be used for the ratio of
# @current-progress to @total-progress. The value is
# monotonically increasing.
# @current-progress: Progress made until now. The unit is arbitrary and the
# value can only meaningfully be used for the ratio of
# @current-progress to @total-progress. The value is
# monotonically increasing.
#
# @total-progress: Estimated @current-progress value at the completion of
# the job. This value can arbitrarily change while the
# job is running, in both directions.
# @total-progress: Estimated @current-progress value at the completion of
# the job. This value can arbitrarily change while the
# job is running, in both directions.
#
# @error: If this field is present, the job failed; if it is
# still missing in the CONCLUDED state, this indicates
# successful completion.
# @error: If this field is present, the job failed; if it is
# still missing in the CONCLUDED state, this indicates
# successful completion.
#
# The value is a human-readable error message to describe
# the reason for the job failure. It should not be parsed
# by applications.
# The value is a human-readable error message to describe
# the reason for the job failure. It should not be parsed
# by applications.
#
# Since: 3.0
##

18
qapi/machine-target.json
View File

@ -40,13 +40,13 @@
# model details.
#
# Note: When a non-migration-safe CPU model is expanded in static mode, some
# features enabled by the CPU model may be omitted, because they can't be
# implemented by a static CPU model definition (e.g. cache info passthrough and
# PMU passthrough in x86). If you need an accurate representation of the
# features enabled by a non-migration-safe CPU model, use @full. If you need a
# static representation that will keep ABI compatibility even when changing QEMU
# version or machine-type, use @static (but keep in mind that some features may
# be omitted).
# features enabled by the CPU model may be omitted, because they can't be
# implemented by a static CPU model definition (e.g. cache info passthrough and
# PMU passthrough in x86). If you need an accurate representation of the
# features enabled by a non-migration-safe CPU model, use @full. If you need a
# static representation that will keep ABI compatibility even when changing QEMU
# version or machine-type, use @static (but keep in mind that some features may
# be omitted).
#
# Since: 2.8.0
##
@ -148,7 +148,7 @@
# with wrong types.
#
# Note: this command isn't specific to s390x, but is only implemented
# on this architecture currently.
# on this architecture currently.
#
# Since: 2.8.0
##
@ -191,7 +191,7 @@
# with wrong types.
#
# Note: this command isn't specific to s390x, but is only implemented
# on this architecture currently.
# on this architecture currently.
#
# Since: 2.8.0
##

14
qapi/machine.json
View File

@ -20,8 +20,6 @@
# prefix to produce the corresponding QEMU executable name. This
# is true even for "qemu-system-x86_64".
#
# ppcemb: dropped in 3.1
#
# Since: 3.0
##
{ 'enum' : 'SysEmuTarget',
@ -680,7 +678,7 @@
# 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
#
# @none: None (no memory side cache in this proximity domain,
# or cache write policy unknown)
# or cache write policy unknown)
#
# @write-back: Write Back (WB)
#
@ -706,7 +704,7 @@
# @level: the cache level described in this structure.
#
# @associativity: the cache associativity,
# none/direct-mapped/complex(complex cache indexing).
# none/direct-mapped/complex(complex cache indexing).
#
# @policy: the write policy, none/write-back/write-through.
#
@ -823,10 +821,10 @@
# @core-id: core number within die the CPU belongs to# @thread-id: thread number within core the CPU belongs to
#
# Note: currently there are 5 properties that could be present
# but management should be prepared to pass through other
# properties with device_add command to allow for future
# interface extension. This also requires the filed names to be kept in
# sync with the properties passed to -device/device_add.
# but management should be prepared to pass through other
# properties with device_add command to allow for future
# interface extension. This also requires the filed names to be kept in
# sync with the properties passed to -device/device_add.
#
# Since: 2.7
##

206
qapi/migration.json
View File

@ -28,22 +28,22 @@
# @normal-bytes: number of normal bytes sent (since 1.2)
#
# @dirty-pages-rate: number of pages dirtied by second by the
# guest (since 1.3)
# guest (since 1.3)
#
# @mbps: throughput in megabits/sec. (since 1.6)
#
# @dirty-sync-count: number of times that dirty ram was synchronized (since 2.1)
#
# @postcopy-requests: The number of page requests received from the destination
# (since 2.7)
# (since 2.7)
#
# @page-size: The number of bytes per page for the various page-based
# statistics (since 2.10)
# statistics (since 2.10)
#
# @multifd-bytes: The number of bytes sent through multifd (since 3.0)
#
# @pages-per-second: the number of memory pages transferred per second
# (Since 4.0)
# (Since 4.0)
#
# Since: 0.14.0
##
@ -98,7 +98,7 @@
##
{ 'struct': 'CompressionStats',
'data': {'pages': 'int', 'busy': 'int', 'busy-rate': 'number',
'compressed-size': 'int', 'compression-rate': 'number' } }
'compressed-size': 'int', 'compression-rate': 'number' } }
##
# @MigrationStatus:
@ -131,7 +131,7 @@
# @pre-switchover: Paused before device serialisation. (since 2.11)
#
# @device: During device serialisation when pause-before-switchover is enabled
# (since 2.11)
# (since 2.11)
#
# @wait-unplug: wait for device unplug request by guest OS to be completed.
# (since 4.2)
@ -167,41 +167,41 @@
# status is 'active' or 'completed' (since 1.2)
#
# @total-time: total amount of milliseconds since migration started.
# If migration has ended, it returns the total migration
# time. (since 1.2)
# If migration has ended, it returns the total migration
# time. (since 1.2)
#
# @downtime: only present when migration finishes correctly
# total downtime in milliseconds for the guest.
# (since 1.3)
# total downtime in milliseconds for the guest.
# (since 1.3)
#
# @expected-downtime: only present while migration is active
# expected downtime in milliseconds for the guest in last walk
# of the dirty bitmap. (since 1.3)
# expected downtime in milliseconds for the guest in last walk
# of the dirty bitmap. (since 1.3)
#
# @setup-time: amount of setup time in milliseconds _before_ the
# iterations begin but _after_ the QMP command is issued. This is designed
# to provide an accounting of any activities (such as RDMA pinning) which
# may be expensive, but do not actually occur during the iterative
# migration rounds themselves. (since 1.6)
# @setup-time: amount of setup time in milliseconds *before* the
# iterations begin but *after* the QMP command is issued. This is designed
# to provide an accounting of any activities (such as RDMA pinning) which
# may be expensive, but do not actually occur during the iterative
# migration rounds themselves. (since 1.6)
#
# @cpu-throttle-percentage: percentage of time guest cpus are being
# throttled during auto-converge. This is only present when auto-converge
# has started throttling guest cpus. (Since 2.7)
# throttled during auto-converge. This is only present when auto-converge
# has started throttling guest cpus. (Since 2.7)
#
# @error-desc: the human readable error description string, when
# @status is 'failed'. Clients should not attempt to parse the
# error strings. (Since 2.7)
#
# @postcopy-blocktime: total time when all vCPU were blocked during postcopy
# live migration. This is only present when the postcopy-blocktime
# migration capability is enabled. (Since 3.0)
# live migration. This is only present when the postcopy-blocktime
# migration capability is enabled. (Since 3.0)
#
# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. This is
# only present when the postcopy-blocktime migration capability
# is enabled. (Since 3.0)
# only present when the postcopy-blocktime migration capability
# is enabled. (Since 3.0)
#
# @compression: migration compression statistics, only returned if compression
# feature is on and status is 'active' or 'completed' (Since 3.1)
# feature is on and status is 'active' or 'completed' (Since 3.1)
#
# @socket-address: Only used for tcp, to know what the real port is (Since 4.0)
#
@ -355,54 +355,54 @@
# loads, by sending compressed difference of the pages
#
# @rdma-pin-all: Controls whether or not the entire VM memory footprint is
# mlock()'d on demand or all at once. Refer to docs/rdma.txt for usage.
# Disabled by default. (since 2.0)
# mlock()'d on demand or all at once. Refer to docs/rdma.txt for usage.
# Disabled by default. (since 2.0)
#
# @zero-blocks: During storage migration encode blocks of zeroes efficiently. This
# essentially saves 1MB of zeroes per block on the wire. Enabling requires
# source and target VM to support this feature. To enable it is sufficient
# to enable the capability on the source VM. The feature is disabled by
# default. (since 1.6)
# essentially saves 1MB of zeroes per block on the wire. Enabling requires
# source and target VM to support this feature. To enable it is sufficient
# to enable the capability on the source VM. The feature is disabled by
# default. (since 1.6)
#
# @compress: Use multiple compression threads to accelerate live migration.
# This feature can help to reduce the migration traffic, by sending
# compressed pages. Please note that if compress and xbzrle are both
# on, compress only takes effect in the ram bulk stage, after that,
# it will be disabled and only xbzrle takes effect, this can help to
# minimize migration traffic. The feature is disabled by default.
# (since 2.4 )
# This feature can help to reduce the migration traffic, by sending
# compressed pages. Please note that if compress and xbzrle are both
# on, compress only takes effect in the ram bulk stage, after that,
# it will be disabled and only xbzrle takes effect, this can help to
# minimize migration traffic. The feature is disabled by default.
# (since 2.4 )
#
# @events: generate events for each migration state change
# (since 2.4 )
#
# @auto-converge: If enabled, QEMU will automatically throttle down the guest
# to speed up convergence of RAM migration. (since 1.6)
# to speed up convergence of RAM migration. (since 1.6)
#
# @postcopy-ram: Start executing on the migration target before all of RAM has
# been migrated, pulling the remaining pages along as needed. The
# capacity must have the same setting on both source and target
# or migration will not even start. NOTE: If the migration fails during
# postcopy the VM will fail. (since 2.6)
# been migrated, pulling the remaining pages along as needed. The
# capacity must have the same setting on both source and target
# or migration will not even start. NOTE: If the migration fails during
# postcopy the VM will fail. (since 2.6)
#
# @x-colo: If enabled, migration will never end, and the state of the VM on the
# primary side will be migrated continuously to the VM on secondary
# side, this process is called COarse-Grain LOck Stepping (COLO) for
# Non-stop Service. (since 2.8)
# primary side will be migrated continuously to the VM on secondary
# side, this process is called COarse-Grain LOck Stepping (COLO) for
# Non-stop Service. (since 2.8)
#
# @release-ram: if enabled, qemu will free the migrated ram pages on the source
# during postcopy-ram migration. (since 2.9)
# during postcopy-ram migration. (since 2.9)
#
# @block: If enabled, QEMU will also migrate the contents of all block
# devices. Default is disabled. A possible alternative uses
# mirror jobs to a builtin NBD server on the destination, which
# offers more flexibility.
# (Since 2.10)
# devices. Default is disabled. A possible alternative uses
# mirror jobs to a builtin NBD server on the destination, which
# offers more flexibility.
# (Since 2.10)
#
# @return-path: If enabled, migration will use the return path even
# for precopy. (since 2.10)
#
# @pause-before-switchover: Pause outgoing migration before serialising device
# state and before disabling block IO (since 2.11)
# state and before disabling block IO (since 2.11)
#
# @multifd: Use more than one fd for migration (since 4.0)
#
@ -410,11 +410,11 @@
# (since 2.12)
#
# @postcopy-blocktime: Calculate downtime for postcopy live migration
# (since 3.0)
# (since 3.0)
#
# @late-block-activate: If enabled, the destination will not activate block
# devices (and thus take locks) immediately at the end of migration.
# (since 3.0)
# devices (and thus take locks) immediately at the end of migration.
# (since 3.0)
#
# @x-ignore-shared: If enabled, QEMU will not migrate shared memory (since 4.0)
#
@ -494,24 +494,24 @@
# Migration parameters enumeration
#
# @announce-initial: Initial delay (in milliseconds) before sending the first
# announce (Since 4.0)
# announce (Since 4.0)
#
# @announce-max: Maximum delay (in milliseconds) between packets in the
# announcement (Since 4.0)
# announcement (Since 4.0)
#
# @announce-rounds: Number of self-announce packets sent after migration
# (Since 4.0)
# (Since 4.0)
#
# @announce-step: Increase in delay (in milliseconds) between subsequent
# packets in the announcement (Since 4.0)
# packets in the announcement (Since 4.0)
#
# @compress-level: Set the compression level to be used in live migration,
# the compression level is an integer between 0 and 9, where 0 means
# no compression, 1 means the best compression speed, and 9 means best
# compression ratio which will consume more CPU.
# the compression level is an integer between 0 and 9, where 0 means
# no compression, 1 means the best compression speed, and 9 means best
# compression ratio which will consume more CPU.
#
# @compress-threads: Set compression thread count to be used in live migration,
# the compression thread count is an integer between 1 and 255.
# the compression thread count is an integer between 1 and 255.
#
# @compress-wait-thread: Controls behavior when all compression threads are
# currently busy. If true (default), wait for a free
@ -519,10 +519,10 @@
# send the page uncompressed. (Since 3.1)
#
# @decompress-threads: Set decompression thread count to be used in live
# migration, the decompression thread count is an integer between 1
# and 255. Usually, decompression is at least 4 times as fast as
# compression, so set the decompress-threads to the number about 1/4
# of compress-threads is adequate.
# migration, the decompression thread count is an integer between 1
# and 255. Usually, decompression is at least 4 times as fast as
# compression, so set the decompress-threads to the number about 1/4
# of compress-threads is adequate.
#
# @cpu-throttle-initial: Initial percentage of time guest cpus are throttled
# when migration auto-converge is activated. The
@ -560,14 +560,14 @@
# downtime in milliseconds (Since 2.8)
#
# @x-checkpoint-delay: The delay time (in ms) between two COLO checkpoints in
# periodic mode. (Since 2.8)
# periodic mode. (Since 2.8)
#
# @block-incremental: Affects how much storage is migrated when the
# block migration capability is enabled. When false, the entire
# storage backing chain is migrated into a flattened image at
# the destination; when true, only the active qcow2 layer is
# migrated and the destination must already have access to the
# same backing chain as was used on the source. (since 2.10)
# block migration capability is enabled. When false, the entire
# storage backing chain is migrated into a flattened image at
# the destination; when true, only the active qcow2 layer is
# migrated and the destination must already have access to the
# same backing chain as was used on the source. (since 2.10)
#
# @multifd-channels: Number of channels used to migrate data in
# parallel. This is the same number that the
@ -580,8 +580,8 @@
# (Since 2.11)
#
# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
# Defaults to 0 (unlimited). In bytes per second.
# (Since 3.0)
# Defaults to 0 (unlimited). In bytes per second.
# (Since 3.0)
#
# @max-cpu-throttle: maximum cpu throttle percentage.
# Defaults to 99. (Since 3.1)
@ -604,16 +604,16 @@
# @MigrateSetParameters:
#
# @announce-initial: Initial delay (in milliseconds) before sending the first
# announce (Since 4.0)
# announce (Since 4.0)
#
# @announce-max: Maximum delay (in milliseconds) between packets in the
# announcement (Since 4.0)
# announcement (Since 4.0)
#
# @announce-rounds: Number of self-announce packets sent after migration
# (Since 4.0)
# (Since 4.0)
#
# @announce-step: Increase in delay (in milliseconds) between subsequent
# packets in the announcement (Since 4.0)
# packets in the announcement (Since 4.0)
#
# @compress-level: compression level
#
@ -665,11 +665,11 @@
# @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8)
#
# @block-incremental: Affects how much storage is migrated when the
# block migration capability is enabled. When false, the entire
# storage backing chain is migrated into a flattened image at
# the destination; when true, only the active qcow2 layer is
# migrated and the destination must already have access to the
# same backing chain as was used on the source. (since 2.10)
# block migration capability is enabled. When false, the entire
# storage backing chain is migrated into a flattened image at
# the destination; when true, only the active qcow2 layer is
# migrated and the destination must already have access to the
# same backing chain as was used on the source. (since 2.10)
#
# @multifd-channels: Number of channels used to migrate data in
# parallel. This is the same number that the
@ -682,8 +682,8 @@
# (Since 2.11)
#
# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
# Defaults to 0 (unlimited). In bytes per second.
# (Since 3.0)
# Defaults to 0 (unlimited). In bytes per second.
# (Since 3.0)
#
# @max-cpu-throttle: maximum cpu throttle percentage.
# The default value is 99. (Since 3.1)
@ -713,7 +713,7 @@
'*multifd-channels': 'int',
'*xbzrle-cache-size': 'size',
'*max-postcopy-bandwidth': 'size',
'*max-cpu-throttle': 'int' } }
'*max-cpu-throttle': 'int' } }
##
# @migrate-set-parameters:
@ -737,16 +737,16 @@
# The optional members aren't actually optional.
#
# @announce-initial: Initial delay (in milliseconds) before sending the
# first announce (Since 4.0)
# first announce (Since 4.0)
#
# @announce-max: Maximum delay (in milliseconds) between packets in the
# announcement (Since 4.0)
# announcement (Since 4.0)
#
# @announce-rounds: Number of self-announce packets sent after migration
# (Since 4.0)
# (Since 4.0)
#
# @announce-step: Increase in delay (in milliseconds) between subsequent
# packets in the announcement (Since 4.0)
# packets in the announcement (Since 4.0)
#
# @compress-level: compression level
#
@ -799,11 +799,11 @@
# @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8)
#
# @block-incremental: Affects how much storage is migrated when the
# block migration capability is enabled. When false, the entire
# storage backing chain is migrated into a flattened image at
# the destination; when true, only the active qcow2 layer is
# migrated and the destination must already have access to the
# same backing chain as was used on the source. (since 2.10)
# block migration capability is enabled. When false, the entire
# storage backing chain is migrated into a flattened image at
# the destination; when true, only the active qcow2 layer is
# migrated and the destination must already have access to the
# same backing chain as was used on the source. (since 2.10)
#
# @multifd-channels: Number of channels used to migrate data in
# parallel. This is the same number that the
@ -816,12 +816,12 @@
# (Since 2.11)
#
# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
# Defaults to 0 (unlimited). In bytes per second.
# (Since 3.0)
# Defaults to 0 (unlimited). In bytes per second.
# (Since 3.0)
#
# @max-cpu-throttle: maximum cpu throttle percentage.
# Defaults to 99.
# (Since 3.1)
# (Since 3.1)
#
# Since: 2.4
##
@ -845,7 +845,7 @@
'*block-incremental': 'bool' ,
'*multifd-channels': 'uint8',
'*xbzrle-cache-size': 'size',
'*max-postcopy-bandwidth': 'size',
'*max-postcopy-bandwidth': 'size',
'*max-cpu-throttle':'uint8'} }
##
@ -1047,8 +1047,8 @@
# The reason for a COLO exit.
#
# @none: failover has never happened. This state does not occur
# in the COLO_EXIT event, and is only visible in the result of
# query-colo-status.
# in the COLO_EXIT event, and is only visible in the result of
# query-colo-status.
#
# @request: COLO exit is due to an external request.
#
@ -1281,11 +1281,11 @@
# of the VM are not saved by this command.
#
# @filename: the file to save the state of the devices to as binary
# data. See xen-save-devices-state.txt for a description of the binary
# format.
# data. See xen-save-devices-state.txt for a description of the binary
# format.
#
# @live: Optional argument to ask QEMU to treat this command as part of a live
# migration. Default to true. (since 2.11)
# migration. Default to true. (since 2.11)
#
# Returns: Nothing on success
#

8
qapi/misc-target.json
View File

@ -230,14 +230,14 @@
# QEMU/KVM software version, but also decided by the hardware that
# the program is running upon.
#
# @version: version of GIC to be described. Currently, only 2 and 3
# are supported.
# @version: version of GIC to be described. Currently, only 2 and 3
# are supported.
#
# @emulated: whether current QEMU/hardware supports emulated GIC
# device in user space.
#
# @kernel: whether current QEMU/hardware supports hardware
# accelerated GIC device in kernel.
# @kernel: whether current QEMU/hardware supports hardware
# accelerated GIC device in kernel.
#
# Since: 2.6
##

166
qapi/misc.json
View File

@ -14,11 +14,11 @@
#
# Arguments:
#
# @enable: An optional list of QMPCapability values to enable. The
# client must not enable any capability that is not
# mentioned in the QMP greeting message. If the field is not
# provided, it means no QMP capabilities will be enabled.
# (since 2.12)
# @enable: An optional list of QMPCapability values to enable. The
# client must not enable any capability that is not
# mentioned in the QMP greeting message. If the field is not
# provided, it means no QMP capabilities will be enabled.
# (since 2.12)
#
# Example:
#
@ -27,11 +27,11 @@
# <- { "return": {} }
#
# Notes: This command is valid exactly when first connecting: it must be
# issued before any other command will be accepted, and will fail once the
# monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
# issued before any other command will be accepted, and will fail once the
# monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
#
# The QMP client needs to explicitly enable QMP capabilities, otherwise
# all the QMP capabilities will be turned off by default.
# The QMP client needs to explicitly enable QMP capabilities, otherwise
# all the QMP capabilities will be turned off by default.
#
# Since: 0.13
#
@ -46,8 +46,8 @@
# Enumeration of capabilities to be advertised during initial client
# connection, used for agreeing on particular QMP extension behaviors.
#
# @oob: QMP ability to support out-of-band requests.
# (Please refer to qmp-spec.txt for more information on OOB)
# @oob: QMP ability to support out-of-band requests.
# (Please refer to qmp-spec.txt for more information on OOB)
#
# Since: 2.12
#
@ -60,11 +60,11 @@
#
# A three-part version number.
#
# @major: The major version number.
# @major: The major version number.
#
# @minor: The minor version number.
# @minor: The minor version number.
#
# @micro: The micro version number.
# @micro: The micro version number.
#
# Since: 2.4
##
@ -77,16 +77,16 @@
#
# A description of QEMU's version.
#
# @qemu: The version of QEMU. By current convention, a micro
# version of 50 signifies a development branch. A micro version
# greater than or equal to 90 signifies a release candidate for
# the next minor version. A micro version of less than 50
# signifies a stable release.
# @qemu: The version of QEMU. By current convention, a micro
# version of 50 signifies a development branch. A micro version
# greater than or equal to 90 signifies a release candidate for
# the next minor version. A micro version of less than 50
# signifies a stable release.
#
# @package: QEMU will always set this field to an empty string. Downstream
# versions of QEMU should set this to a non-empty string. The
# exact format depends on the downstream however it highly
# recommended that a unique name is used.
# @package: QEMU will always set this field to an empty string. Downstream
# versions of QEMU should set this to a non-empty string. The
# exact format depends on the downstream however it highly
# recommended that a unique name is used.
#
# Since: 0.14.0
##
@ -98,7 +98,7 @@
#
# Returns the current version of QEMU.
#
# Returns: A @VersionInfo object describing the current version of QEMU.
# Returns: A @VersionInfo object describing the current version of QEMU.
#
# Since: 0.14.0
#
@ -163,17 +163,29 @@
##
# @LostTickPolicy:
#
# Policy for handling lost ticks in timer devices.
# Policy for handling lost ticks in timer devices. Ticks end up getting
# lost when, for example, the guest is paused.
#
# @discard: throw away the missed tick(s) and continue with future injection
# normally. Guest time may be delayed, unless the OS has explicit
# handling of lost ticks
# @discard: throw away the missed ticks and continue with future injection
# normally. The guest OS will see the timer jump ahead by a
# potentially quite significant amount all at once, as if the
# intervening chunk of time had simply not existed; needless to
# say, such a sudden jump can easily confuse a guest OS which is
# not specifically prepared to deal with it. Assuming the guest
# OS can deal correctly with the time jump, the time in the guest
# and in the host should now match.
#
# @delay: continue to deliver ticks at the normal rate. Guest time will be
# delayed due to the late tick
# @delay: continue to deliver ticks at the normal rate. The guest OS will
# not notice anything is amiss, as from its point of view time will
# have continued to flow normally. The time in the guest should now
# be behind the time in the host by exactly the amount of time during
# which ticks have been missed.
#
# @slew: deliver ticks at a higher rate to catch up with the missed tick. The
# guest time should not be delayed once catchup is complete.
# @slew: deliver ticks at a higher rate to catch up with the missed ticks.
# The guest OS will not notice anything is amiss, as from its point
# of view time will have continued to flow normally. Once the timer
# has managed to catch up with all the missing ticks, the time in
# the guest and in the host should match.
#
# Since: 2.0
##
@ -321,7 +333,7 @@
# Since: 1.2.0
#
# Note: This command is deprecated, because its output doesn't reflect
# compile-time configuration. Use query-qmp-schema instead.
# compile-time configuration. Use query-qmp-schema instead.
#
# Example:
#
@ -375,8 +387,8 @@
# Returns a list of information about each iothread.
#
# Note: this list excludes the QEMU main loop thread, which is not declared
# using the -object iothread command-line option. It is always the main thread
# of the process.
# using the -object iothread command-line option. It is always the main thread
# of the process.
#
# Returns: a list of @IOThreadInfo for each iothread
#
@ -418,12 +430,10 @@
#
# Return information about the balloon device.
#
# Returns: @BalloonInfo on success
#
# If the balloon driver is enabled but not functional because the KVM
# kernel module cannot support it, KvmMissingCap
#
# If no balloon device is present, DeviceNotActive
# Returns: - @BalloonInfo on success
# - If the balloon driver is enabled but not functional because the KVM
# kernel module cannot support it, KvmMissingCap
# - If no balloon device is present, DeviceNotActive
#
# Since: 0.14.0
#
@ -480,8 +490,8 @@
#
# @bar: the index of the Base Address Register for this region
#
# @type: 'io' if the region is a PIO region
# 'memory' if the region is a MMIO region
# @type: - 'io' if the region is a PIO region
# - 'memory' if the region is a MMIO region
#
# @size: memory size
#
@ -624,9 +634,9 @@
# Return information about the PCI bus topology of the guest.
#
# Returns: a list of @PciInfo for each PCI bus. Each bus is
# represented by a json-object, which has a key with a json-array of
# all PCI devices attached to it. Each device is represented by a
# json-object.
# represented by a json-object, which has a key with a json-array of
# all PCI devices attached to it. Each device is represented by a
# json-object.
#
# Since: 0.14.0
#
@ -788,10 +798,10 @@
#
# Since: 0.14.0
#
# Notes: This function will succeed even if the guest is already in the stopped
# state. In "inmigrate" state, it will ensure that the guest
# remains paused once migration finishes, as if the -S option was
# passed on the command line.
# Notes: This function will succeed even if the guest is already in the stopped
# state. In "inmigrate" state, it will ensure that the guest
# remains paused once migration finishes, as if the -S option was
# passed on the command line.
#
# Example:
#
@ -847,7 +857,7 @@
# @filename: the file to save the memory to as binary data
#
# @cpu-index: the index of the virtual CPU to use for translating the
# virtual address (defaults to CPU 0)
# virtual address (defaults to CPU 0)
#
# Returns: Nothing on success
#
@ -905,11 +915,11 @@
#
# Returns: If successful, nothing
#
# Notes: This command will succeed if the guest is currently running. It
# will also succeed if the guest is in the "inmigrate" state; in
# this case, the effect of the command is to make sure the guest
# starts once migration finishes, removing the effect of the -S
# command line option if it was passed.
# Notes: This command will succeed if the guest is currently running. It
# will also succeed if the guest is in the "inmigrate" state; in
# this case, the effect of the command is to make sure the guest
# starts once migration finishes, removing the effect of the -S
# command line option if it was passed.
#
# Example:
#
@ -955,7 +965,7 @@
# Returns: nothing.
#
# Note: prior to 4.0, this command does nothing in case the guest
# isn't suspended.
# isn't suspended.
#
# Example:
#
@ -992,10 +1002,10 @@
#
# @value: the target size of the balloon in bytes
#
# Returns: Nothing on success
# If the balloon driver is enabled but not functional because the KVM
# Returns: - Nothing on success
# - If the balloon driver is enabled but not functional because the KVM
# kernel module cannot support it, KvmMissingCap
# If no balloon device is present, DeviceNotActive
# - If no balloon device is present, DeviceNotActive
#
# Notes: This command just issues a request to the guest. When it returns,
# the balloon size may not have changed. A guest can change the balloon
@ -1069,18 +1079,18 @@
# change password command. Otherwise, this specifies a new server URI
# address to listen to for VNC connections.
#
# @arg: If @device is a block device, then this is an optional format to open
# the device with.
# If @device is 'vnc' and @target is 'password', this is the new VNC
# password to set. See change-vnc-password for additional notes.
# @arg: If @device is a block device, then this is an optional format to open
# the device with.
# If @device is 'vnc' and @target is 'password', this is the new VNC
# password to set. See change-vnc-password for additional notes.
#
# Returns: Nothing on success.
# If @device is not a valid block device, DeviceNotFound
# Returns: - Nothing on success.
# - If @device is not a valid block device, DeviceNotFound
#
# Notes: This interface is deprecated, and it is strongly recommended that you
# avoid using it. For changing block devices, use
# blockdev-change-medium; for changing VNC parameters, use
# change-vnc-password.
# Notes: This interface is deprecated, and it is strongly recommended that you
# avoid using it. For changing block devices, use
# blockdev-change-medium; for changing VNC parameters, use
# change-vnc-password.
#
# Since: 0.14.0
#
@ -1225,11 +1235,9 @@
#
# @opaque: A free-form string that can be used to describe the fd.
#
# Returns: @AddfdInfo on success
#
# If file descriptor was not received, FdNotSupplied
#
# If @fdset-id is a negative value, InvalidParameterValue
# Returns: - @AddfdInfo on success
# - If file descriptor was not received, FdNotSupplied
# - If @fdset-id is a negative value, InvalidParameterValue
#
# Notes: The list of fd sets is shared by all monitor connections.
#
@ -1257,8 +1265,8 @@
#
# @fd: The file descriptor that is to be removed.
#
# Returns: Nothing on success
# If @fdset-id or @fd is not found, FdNotFound
# Returns: - Nothing on success
# - If @fdset-id or @fd is not found, FdNotFound
#
# Since: 1.2.0
#
@ -1719,8 +1727,8 @@
# of the VM are not loaded by this command.
#
# @filename: the file to load the state of the devices from as binary
# data. See xen-save-devices-state.txt for a description of the binary
# format.
# data. See xen-save-devices-state.txt for a description of the binary
# format.
#
# Since: 2.7
#

26
qapi/net.json
View File

@ -47,9 +47,9 @@
# Additional arguments depend on the type.
#
# TODO: This command effectively bypasses QAPI completely due to its
# "additional arguments" business. It shouldn't have been added to
# the schema in this form. It should be qapified properly, or
# replaced by a properly qapified command.
# "additional arguments" business. It shouldn't have been added to
# the schema in this form. It should be qapified properly, or
# replaced by a properly qapified command.
#
# Since: 0.14.0
#
@ -213,7 +213,7 @@
# @fd: file descriptor of an already opened tap
#
# @fds: multiple file descriptors of already opened multiqueue capable
# tap
# tap
#
# @script: script to initialize the interface
#
@ -232,14 +232,14 @@
# @vhostfd: file descriptor of an already opened vhost net device
#
# @vhostfds: file descriptors of multiple already opened vhost net
# devices
# devices
#
# @vhostforce: vhost on for non-MSIX virtio guests
#
# @queues: number of queues to be created for multiqueue capable tap
#
# @poll-us: maximum number of microseconds that could
# be spent on busy polling for tap (since 2.7)
# be spent on busy polling for tap (since 2.7)
#
# Since: 1.2
##
@ -446,8 +446,6 @@
# Available netdev drivers.
#
# Since: 2.7
#
# 'dump': dropped in 2.12
##
{ 'enum': 'NetClientDriver',
'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde',
@ -464,7 +462,7 @@
#
# Since: 1.2
#
# 'l2tpv3' - since 2.1
# 'l2tpv3' - since 2.1
##
{ 'union': 'Netdev',
'base': { 'id': 'str', 'type': 'NetClientDriver' },
@ -493,8 +491,6 @@
# @opts: device type specific properties (legacy)
#
# Since: 1.2
#
# 'vlan': dropped in 3.0
##
{ 'struct': 'NetLegacy',
'data': {
@ -691,7 +687,7 @@
# Parameters for self-announce timers
#
# @initial: Initial delay (in ms) before sending the first GARP/RARP
# announcement
# announcement
#
# @max: Maximum delay (in ms) between GARP/RARP announcement packets
#
@ -700,11 +696,11 @@
# @step: Delay increase (in ms) after each self-announcement attempt
#
# @interfaces: An optional list of interface names, which restricts the
# announcement to the listed interfaces. (Since 4.1)
# announcement to the listed interfaces. (Since 4.1)
#
# @id: A name to be used to identify an instance of announce-timers
# and to allow it to modified later. Not for use as
# part of the migration parameters. (Since 4.1)
# and to allow it to modified later. Not for use as
# part of the migration parameters. (Since 4.1)
#
# Since: 4.0
##

10
qapi/qdev.json
View File

@ -19,8 +19,8 @@
# Returns: a list of ObjectPropertyInfo describing a devices properties
#
# Note: objects can create properties at runtime, for example to describe
# links between different devices and/or objects. These properties
# are not included in the output of this command.
# links between different devices and/or objects. These properties
# are not included in the output of this command.
#
# Since: 1.2
##
@ -58,9 +58,9 @@
# <- { "return": {} }
#
# TODO: This command effectively bypasses QAPI completely due to its
# "additional arguments" business. It shouldn't have been added to
# the schema in this form. It should be qapified properly, or
# replaced by a properly qapified command.
# "additional arguments" business. It shouldn't have been added to
# the schema in this form. It should be qapified properly, or
# replaced by a properly qapified command.
#
# Since: 0.13
##

4
qapi/qom.json
View File

@ -189,8 +189,8 @@
# @typename: the type name of an object
#
# Note: objects can create properties at runtime, for example to describe
# links between different devices and/or objects. These properties
# are not included in the output of this command.
# links between different devices and/or objects. These properties
# are not included in the output of this command.
#
# Returns: a list of ObjectPropertyInfo describing object properties
#

12
qapi/rocker.json
View File

@ -140,7 +140,7 @@
# @ip-dst: IP header destination address
#
# Note: optional members may or may not appear in the flow key
# depending if they're relevant to the flow key.
# depending if they're relevant to the flow key.
#
# Since: 2.4
##
@ -170,7 +170,7 @@
# @ip-tos: IP header TOS field
#
# Note: optional members may or may not appear in the flow mask
# depending if they're relevant to the flow mask.
# depending if they're relevant to the flow mask.
#
# Since: 2.4
##
@ -197,7 +197,7 @@
# @out-pport: physical output port
#
# Note: optional members may or may not appear in the flow action
# depending if they're relevant to the flow action.
# depending if they're relevant to the flow action.
#
# Since: 2.4
##
@ -235,7 +235,7 @@
# @name: switch name
#
# @tbl-id: flow table ID. If tbl-id is not specified, returns
# flow information for all tables.
# flow information for all tables.
#
# Returns: rocker OF-DPA flow information
#
@ -291,7 +291,7 @@
# @ttl-check: perform TTL check
#
# Note: optional members may or may not appear in the group depending
# if they're relevant to the group type.
# if they're relevant to the group type.
#
# Since: 2.4
##
@ -311,7 +311,7 @@
# @name: switch name
#
# @type: group type. If type is not specified, returns
# group information for all group types.
# group information for all group types.
#
# Returns: rocker OF-DPA group information
#

34
qapi/run-state.json
View File

@ -15,16 +15,16 @@
# @finish-migrate: guest is paused to finish the migration process
#
# @inmigrate: guest is paused waiting for an incoming migration. Note
# that this state does not tell whether the machine will start at the
# end of the migration. This depends on the command-line -S option and
# any invocation of 'stop' or 'cont' that has happened since QEMU was
# started.
# that this state does not tell whether the machine will start at the
# end of the migration. This depends on the command-line -S option and
# any invocation of 'stop' or 'cont' that has happened since QEMU was
# started.
#
# @internal-error: An internal error that prevents further guest execution
# has occurred
# has occurred
#
# @io-error: the last IOP has failed and the device is configured to pause
# on I/O errors
# on I/O errors
#
# @paused: guest has been paused via the 'stop' command
#
@ -85,8 +85,8 @@
# @guest-panic: Guest panicked, and command line turns that into a shutdown
#
# @subsystem-reset: Partial guest reset that does not trigger QMP events and
# ignores --no-reboot. This is useful for sanitizing
# hypercalls on s390 that are used during kexec/kdump/boot
# ignores --no-reboot. This is useful for sanitizing
# hypercalls on s390 that are used during kexec/kdump/boot
#
##
{ 'enum': 'ShutdownCause',
@ -140,13 +140,13 @@
# about to exit.
#
# @guest: If true, the shutdown was triggered by a guest request (such as
# a guest-initiated ACPI shutdown request or other hardware-specific action)
# rather than a host request (such as sending qemu a SIGINT). (since 2.10)
# a guest-initiated ACPI shutdown request or other hardware-specific action)
# rather than a host request (such as sending qemu a SIGINT). (since 2.10)
#
# @reason: The @ShutdownCause which resulted in the SHUTDOWN. (since 4.0)
#
# Note: If the command-line option "-no-shutdown" has been specified, qemu will
# not exit, and a STOP event will eventually follow the SHUTDOWN event
# not exit, and a STOP event will eventually follow the SHUTDOWN event
#
# Since: 0.12.0
#
@ -180,9 +180,9 @@
# Emitted when the virtual machine is reset
#
# @guest: If true, the reset was triggered by a guest request (such as
# a guest-initiated ACPI reboot request or other hardware-specific action)
# rather than a host request (such as the QMP command system_reset).
# (since 2.10)
# a guest-initiated ACPI reboot request or other hardware-specific action)
# rather than a host request (such as the QMP command system_reset).
# (since 2.10)
#
# @reason: The @ShutdownCause of the RESET. (since 4.0)
#
@ -283,7 +283,7 @@
# @action: action that has been taken
#
# Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is
# followed respectively by the RESET, SHUTDOWN, or STOP events
# followed respectively by the RESET, SHUTDOWN, or STOP events
#
# Note: This event is rate-limited.
#
@ -441,12 +441,12 @@
# @disabled-wait: the CPU has entered a disabled wait state
#
# @extint-loop: clock comparator or cpu timer interrupt with new PSW enabled
# for external interrupts
# for external interrupts
#
# @pgmint-loop: program interrupt with BAD new PSW
#
# @opint-loop: operation exception interrupt with invalid code at the program
# interrupt new PSW
# interrupt new PSW
#
# Since: 2.12
##

8
qapi/sockets.json
View File

@ -89,7 +89,7 @@
# @port: port
#
# Note: string types are used to allow for possible future hostname or
# service resolution support.
# service resolution support.
#
# Since: 2.8
##
@ -104,9 +104,9 @@
# Captures the address of a socket, which could also be a named file descriptor
#
# Note: This type is deprecated in favor of SocketAddress. The
# difference between SocketAddressLegacy and SocketAddress is that the
# latter is a flat union rather than a simple union. Flat is nicer
# because it avoids nesting on the wire, i.e. that form has fewer {}.
# difference between SocketAddressLegacy and SocketAddress is that the
# latter is a flat union rather than a simple union. Flat is nicer
# because it avoids nesting on the wire, i.e. that form has fewer {}.
#
# Since: 1.3

4
qapi/tpm.json
View File

@ -96,8 +96,8 @@
#
# A union referencing different TPM backend types' configuration options
#
# @type: 'passthrough' The configuration options for the TPM passthrough type
# 'emulator' The configuration options for TPM emulator backend type
# @type: - 'passthrough' The configuration options for the TPM passthrough type
# - 'emulator' The configuration options for TPM emulator backend type
#
# Since: 1.5
##

15
qapi/trace.json
View File

@ -52,14 +52,15 @@
#
# Returns: a list of @TraceEventInfo for the matching events
#
# An event is returned if:
# - its name matches the @name pattern, and
# - if @vcpu is given, the event has the "vcpu" property.
# An event is returned if:
#
# Therefore, if @vcpu is given, the operation will only match per-vCPU events,
# returning their state on the specified vCPU. Special case: if @name is an
# exact match, @vcpu is given and the event does not have the "vcpu" property,
# an error is returned.
# - its name matches the @name pattern, and
# - if @vcpu is given, the event has the "vcpu" property.
#
# Therefore, if @vcpu is given, the operation will only match per-vCPU events,
# returning their state on the specified vCPU. Special case: if @name is an
# exact match, @vcpu is given and the event does not have the "vcpu" property,
# an error is returned.
#
# Since: 2.2
#

4
qapi/transaction.json
View File

@ -132,8 +132,8 @@
# Errors depend on the operations of the transaction
#
# Note: The transaction aborts on the first failure. Therefore, there will be
# information on only one failed operation returned in an error condition, and
# subsequent actions will not have been attempted.
# information on only one failed operation returned in an error condition, and
# subsequent actions will not have been attempted.
#
# Since: 1.1
#

117
qapi/ui.json
View File

@ -12,19 +12,19 @@
#
# Sets the password of a remote display session.
#
# @protocol: `vnc' to modify the VNC server password
# `spice' to modify the Spice server password
# @protocol: - 'vnc' to modify the VNC server password
# - 'spice' to modify the Spice server password
#
# @password: the new password
#
# @connected: how to handle existing clients when changing the
# password. If nothing is specified, defaults to `keep'
# `fail' to fail the command if clients are connected
# `disconnect' to disconnect existing clients
# `keep' to maintain existing clients
# password. If nothing is specified, defaults to 'keep'
# 'fail' to fail the command if clients are connected
# 'disconnect' to disconnect existing clients
# 'keep' to maintain existing clients
#
# Returns: Nothing on success
# If Spice is not enabled, DeviceNotFound
# Returns: - Nothing on success
# - If Spice is not enabled, DeviceNotFound
#
# Since: 0.14.0
#
@ -43,16 +43,17 @@
#
# Expire the password of a remote display server.
#
# @protocol: the name of the remote display protocol `vnc' or `spice'
# @protocol: the name of the remote display protocol 'vnc' or 'spice'
#
# @time: when to expire the password.
# `now' to expire the password immediately
# `never' to cancel password expiration
# `+INT' where INT is the number of seconds from now (integer)
# `INT' where INT is the absolute time in seconds
#
# Returns: Nothing on success
# If @protocol is `spice' and Spice is not active, DeviceNotFound
# - 'now' to expire the password immediately
# - 'never' to cancel password expiration
# - '+INT' where INT is the number of seconds from now (integer)
# - 'INT' where INT is the absolute time in seconds
#
# Returns: - Nothing on success
# - If @protocol is 'spice' and Spice is not active, DeviceNotFound
#
# Since: 0.14.0
#
@ -201,9 +202,10 @@
# @tls-port: The SPICE server's TLS port number.
#
# @auth: the current authentication type used by the server
# 'none' if no authentication is being used
# 'spice' uses SASL or direct TLS authentication, depending on command
# line options
#
# - 'none' if no authentication is being used
# - 'spice' uses SASL or direct TLS authentication, depending on command
# line options
#
# @mouse-mode: The mode in which the mouse cursor is displayed currently. Can
# be determined by the client or the server, or unknown if spice
@ -433,27 +435,28 @@
# @host: The hostname the VNC server is bound to. This depends on
# the name resolution on the host and may be an IP address.
#
# @family: 'ipv6' if the host is listening for IPv6 connections
# 'ipv4' if the host is listening for IPv4 connections
# 'unix' if the host is listening on a unix domain socket
# 'unknown' otherwise
# @family: - 'ipv6' if the host is listening for IPv6 connections
# - 'ipv4' if the host is listening for IPv4 connections
# - 'unix' if the host is listening on a unix domain socket
# - 'unknown' otherwise
#
# @service: The service name of the server's port. This may depends
# on the host system's service database so symbolic names should not
# be relied on.
#
# @auth: the current authentication type used by the server
# 'none' if no authentication is being used
# 'vnc' if VNC authentication is being used
# 'vencrypt+plain' if VEncrypt is used with plain text authentication
# 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication
# 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication
# 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth
# 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
# 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
# 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth
# 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
# 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth
#
# - 'none' if no authentication is being used
# - 'vnc' if VNC authentication is being used
# - 'vencrypt+plain' if VEncrypt is used with plain text authentication
# - 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication
# - 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication
# - 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth
# - 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
# - 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
# - 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth
# - 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
# - 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth
#
# @clients: a list of @VncClientInfo of all currently connected clients
#
@ -591,12 +594,12 @@
#
# Change the VNC server password.
#
# @password: the new password to use with VNC authentication
# @password: the new password to use with VNC authentication
#
# Since: 1.1
#
# Notes: An empty password in this command will set the password to the empty
# string. Existing clients are unaffected by executing this command.
# Notes: An empty password in this command will set the password to the empty
# string. Existing clients are unaffected by executing this command.
##
{ 'command': 'change-vnc-password',
'data': { 'password': 'str' },
@ -612,7 +615,7 @@
# @client: client information
#
# Note: This event is emitted before any authentication takes place, thus
# the authentication ID is not provided
# the authentication ID is not provided
#
# Since: 0.13.0
#
@ -776,7 +779,6 @@
# @ac_forward: since 2.10
# @ac_refresh: since 2.10
# @ac_bookmarks: since 2.10
# altgr, altgr_r: dropped in 2.10
#
# @muhenkan: since 2.12
# @katakanahiragana: since 2.12
@ -840,8 +842,8 @@
# @hold-time: time to delay key up events, milliseconds. Defaults
# to 100
#
# Returns: Nothing on success
# If key is unknown or redundant, InvalidParameter
# Returns: - Nothing on success
# - If key is unknown or redundant, InvalidParameter
#
# Since: 1.3.0
#
@ -915,9 +917,9 @@
#
# Pointer motion input event.
#
# @axis: Which axis is referenced by @value.
# @value: Pointer position. For absolute coordinates the
# valid range is 0 -> 0x7ffff
# @axis: Which axis is referenced by @value.
# @value: Pointer position. For absolute coordinates the
# valid range is 0 -> 0x7ffff
#
# Since: 2.0
##
@ -931,10 +933,11 @@
# Input event union.
#
# @type: the input type, one of:
# - 'key': Input event of Keyboard
# - 'btn': Input event of pointer buttons
# - 'rel': Input event of relative pointer motion
# - 'abs': Input event of absolute pointer motion
#
# - 'key': Input event of Keyboard
# - 'btn': Input event of pointer buttons
# - 'rel': Input event of relative pointer motion
# - 'abs': Input event of absolute pointer motion
#
# Since: 2.0
##
@ -949,13 +952,6 @@
#
# Send input event(s) to guest.
#
# @device: display device to send event(s) to.
# @head: head to send event(s) to, in case the
# display device supports multiple scanouts.
# @events: List of InputEvent union.
#
# Returns: Nothing on success.
#
# The @device and @head parameters can be used to send the input event
# to specific input devices in case (a) multiple input devices of the
# same kind are added to the virtual machine and (b) you have
@ -967,12 +963,19 @@
# are admissible, but devices with input routing config take
# precedence.
#
# @device: display device to send event(s) to.
# @head: head to send event(s) to, in case the
# display device supports multiple scanouts.
# @events: List of InputEvent union.
#
# Returns: Nothing on success.
#
# Since: 2.6
#
# Note: The consoles are visible in the qom tree, under
# /backend/console[$index]. They have a device link and head property,
# so it is possible to map which console belongs to which device and
# display.
# /backend/console[$index]. They have a device link and head property,
# so it is possible to map which console belongs to which device and
# display.
#
# Example:
#

156
qga/qapi-schema.json
View File

@ -416,7 +416,7 @@
# Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
#
# Note: This may fail to properly report the current state as a result of
# some other guest processes having issued an fs freeze/thaw.
# some other guest processes having issued an fs freeze/thaw.
#
# Since: 0.15.0
##
@ -431,13 +431,13 @@
# unfreeze.
#
# Note: On Windows, the command is implemented with the help of a
# Volume Shadow-copy Service DLL helper. The frozen state is limited
# for up to 10 seconds by VSS.
# Volume Shadow-copy Service DLL helper. The frozen state is limited
# for up to 10 seconds by VSS.
#
# Returns: Number of file systems currently frozen. On error, all filesystems
# will be thawed. If no filesystems are frozen as a result of this call,
# then @guest-fsfreeze-status will remain "thawed" and calling
# @guest-fsfreeze-thaw is not necessary.
# will be thawed. If no filesystems are frozen as a result of this call,
# then @guest-fsfreeze-status will remain "thawed" and calling
# @guest-fsfreeze-thaw is not necessary.
#
# Since: 0.15.0
##
@ -455,7 +455,7 @@
# Invalid mount points are ignored.
#
# Returns: Number of file systems currently frozen. On error, all filesystems
# will be thawed.
# will be thawed.
#
# Since: 2.2
##
@ -510,13 +510,12 @@
#
# Discard (or "trim") blocks which are not in use by the filesystem.
#
# @minimum:
# Minimum contiguous free range to discard, in bytes. Free ranges
# smaller than this may be ignored (this is a hint and the guest
# may not respect it). By increasing this value, the fstrim
# operation will complete more quickly for filesystems with badly
# fragmented free space, although not all blocks will be discarded.
# The default value is zero, meaning "discard every free block".
# @minimum: Minimum contiguous free range to discard, in bytes. Free ranges
# smaller than this may be ignored (this is a hint and the guest
# may not respect it). By increasing this value, the fstrim
# operation will complete more quickly for filesystems with badly
# fragmented free space, although not all blocks will be discarded.
# The default value is zero, meaning "discard every free block".
#
# Returns: A @GuestFilesystemTrimResponse which contains the
# status of all trimmed paths. (since 2.4)
@ -546,7 +545,8 @@
# (or set its status to "shutdown") due to other reasons.
#
# The following errors may be returned:
# If suspend to disk is not supported, Unsupported
#
# - If suspend to disk is not supported, Unsupported
#
# Notes: It's strongly recommended to issue the guest-sync command before
# sending commands when the guest resumes
@ -575,12 +575,14 @@
#
# This command does NOT return a response on success. There are two options
# to check for success:
# 1. Wait for the SUSPEND QMP event from QEMU
# 2. Issue the query-status QMP command to confirm the VM status is
# "suspended"
#
# 1. Wait for the SUSPEND QMP event from QEMU
# 2. Issue the query-status QMP command to confirm the VM status is
# "suspended"
#
# The following errors may be returned:
# If suspend to ram is not supported, Unsupported
#
# - If suspend to ram is not supported, Unsupported
#
# Notes: It's strongly recommended to issue the guest-sync command before
# sending commands when the guest resumes
@ -607,12 +609,14 @@
#
# This command does NOT return a response on success. There are two options
# to check for success:
# 1. Wait for the SUSPEND QMP event from QEMU
# 2. Issue the query-status QMP command to confirm the VM status is
# "suspended"
#
# 1. Wait for the SUSPEND QMP event from QEMU
# 2. Issue the query-status QMP command to confirm the VM status is
# "suspended"
#
# The following errors may be returned:
# If hybrid suspend is not supported, Unsupported
#
# - If hybrid suspend is not supported, Unsupported
#
# Notes: It's strongly recommended to issue the guest-sync command before
# sending commands when the guest resumes
@ -693,7 +697,7 @@
# @ip-addresses: List of addresses assigned to @name
#
# @statistics: various statistic counters related to @name
# (since 2.11)
# (since 2.11)
#
# Since: 1.1
##
@ -743,7 +747,7 @@
# This is a read-only operation.
#
# Returns: The list of all VCPUs the guest knows about. Each VCPU is put on the
# list exactly once, but their order is unspecified.
# list exactly once, but their order is unspecified.
#
# Since: 1.5
##
@ -767,18 +771,22 @@
# Returns: The length of the initial sublist that has been successfully
# processed. The guest agent maximizes this value. Possible cases:
#
# - 0: if the @vcpus list was empty on input. Guest state
# has not been changed. Otherwise,
# - Error: processing the first node of @vcpus failed for the
# reason returned. Guest state has not been changed.
# Otherwise,
# - < length(@vcpus): more than zero initial nodes have been processed,
# but not the entire @vcpus list. Guest state has
# changed accordingly. To retrieve the error
# (assuming it persists), repeat the call with the
# successfully processed initial sublist removed.
# Otherwise,
# - length(@vcpus): call successful.
# - 0:
# if the @vcpus list was empty on input. Guest state
# has not been changed. Otherwise,
# - Error:
# processing the first node of @vcpus failed for the
# reason returned. Guest state has not been changed.
# Otherwise,
# - < length(@vcpus):
# more than zero initial nodes have been processed,
# but not the entire @vcpus list. Guest state has
# changed accordingly. To retrieve the error
# (assuming it persists), repeat the call with the
# successfully processed initial sublist removed.
# Otherwise,
# - length(@vcpus):
# call successful.
#
# Since: 1.5
##
@ -809,7 +817,7 @@
# @sas: Win serial-attaches SCSI bus type
# @mmc: Win multimedia card (MMC) bus type
# @virtual: Win virtual bus type
# @file-backed virtual: Win file-backed bus type
# @file-backed-virtual: Win file-backed bus type
#
# Since: 2.2; 'Unknown' and all entries below since 2.4
##
@ -937,8 +945,8 @@
# This is a read-only operation.
#
# Returns: The list of all memory blocks the guest knows about.
# Each memory block is put on the list exactly once, but their order
# is unspecified.
# Each memory block is put on the list exactly once, but their order
# is unspecified.
#
# Since: 2.3
##
@ -971,9 +979,9 @@
# @response: the result of memory block operation.
#
# @error-code: the error number.
# When memory block operation fails, we assign the value of
# 'errno' to this member, it indicates what goes wrong.
# When the operation succeeds, it will be omitted.
# When memory block operation fails, we assign the value of
# 'errno' to this member, it indicates what goes wrong.
# When the operation succeeds, it will be omitted.
#
# Since: 2.3
##
@ -1040,15 +1048,15 @@
# @exited: true if process has already terminated.
# @exitcode: process exit code if it was normally terminated.
# @signal: signal number (linux) or unhandled exception code
# (windows) if the process was abnormally terminated.
# (windows) if the process was abnormally terminated.
# @out-data: base64-encoded stdout of the process
# @err-data: base64-encoded stderr of the process
# Note: @out-data and @err-data are present only
# if 'capture-output' was specified for 'guest-exec'
# Note: @out-data and @err-data are present only
# if 'capture-output' was specified for 'guest-exec'
# @out-truncated: true if stdout was not fully captured
# due to size limitation.
# due to size limitation.
# @err-truncated: true if stderr was not fully captured
# due to size limitation.
# due to size limitation.
#
# Since: 2.5
##
@ -1131,8 +1139,8 @@
##
# @GuestUser:
# @user: Username
# @domain: Logon domain (windows only)
# @user: Username
# @domain: Logon domain (windows only)
# @login-time: Time of login of this user on the computer. If multiple
# instances of the user are logged in, the earliest login time is
# reported. The value is in fractional seconds since epoch time.
@ -1156,10 +1164,10 @@
##
# @GuestTimezone:
#
# @zone: Timezone name. These values may differ depending on guest/OS and
# should only be used for informational purposes.
# @offset: Offset to UTC in seconds, negative numbers for time zones west of
# GMT, positive numbers for east
# @zone: Timezone name. These values may differ depending on guest/OS and
# should only be used for informational purposes.
# @offset: Offset to UTC in seconds, negative numbers for time zones west of
# GMT, positive numbers for east
#
# Since: 2.10
##
@ -1182,35 +1190,35 @@
# @GuestOSInfo:
#
# @kernel-release:
# * POSIX: release field returned by uname(2)
# * Windows: build number of the OS
# * POSIX: release field returned by uname(2)
# * Windows: build number of the OS
# @kernel-version:
# * POSIX: version field returned by uname(2)
# * Windows: version number of the OS
# * POSIX: version field returned by uname(2)
# * Windows: version number of the OS
# @machine:
# * POSIX: machine field returned by uname(2)
# * Windows: one of x86, x86_64, arm, ia64
# * POSIX: machine field returned by uname(2)
# * Windows: one of x86, x86_64, arm, ia64
# @id:
# * POSIX: as defined by os-release(5)
# * Windows: contains string "mswindows"
# * POSIX: as defined by os-release(5)
# * Windows: contains string "mswindows"
# @name:
# * POSIX: as defined by os-release(5)
# * Windows: contains string "Microsoft Windows"
# * POSIX: as defined by os-release(5)
# * Windows: contains string "Microsoft Windows"
# @pretty-name:
# * POSIX: as defined by os-release(5)
# * Windows: product name, e.g. "Microsoft Windows 10 Enterprise"
# * POSIX: as defined by os-release(5)
# * Windows: product name, e.g. "Microsoft Windows 10 Enterprise"
# @version:
# * POSIX: as defined by os-release(5)
# * Windows: long version string, e.g. "Microsoft Windows Server 2008"
# * POSIX: as defined by os-release(5)
# * Windows: long version string, e.g. "Microsoft Windows Server 2008"
# @version-id:
# * POSIX: as defined by os-release(5)
# * Windows: short version identifier, e.g. "7" or "20012r2"
# * POSIX: as defined by os-release(5)
# * Windows: short version identifier, e.g. "7" or "20012r2"
# @variant:
# * POSIX: as defined by os-release(5)
# * Windows: contains string "server" or "client"
# * POSIX: as defined by os-release(5)
# * Windows: contains string "server" or "client"
# @variant-id:
# * POSIX: as defined by os-release(5)
# * Windows: contains string "server" or "client"
# * POSIX: as defined by os-release(5)
# * Windows: contains string "server" or "client"
#
# Notes:
#