OpenE2K
/
qemu-e2k
13
4
Fork 0
Code Issues 4 Pull Requests Projects 2 Releases Activity

QAPI patches patches for 2023-05-09 

-----BEGIN PGP SIGNATURE-----
 
 iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmRbUEYSHGFybWJydUBy
 ZWRoYXQuY29tAAoJEDhwtADrkYZTmzEP/3pDpVxpP7xXLevl2vFqkFyHEjc0L3N4
 x//ljgQojAdM6WU3e0qqOfp/NE2ktUg5D3z+QNiVP1/xXv/dtMGATdG+X9AZs0US
 XnhdicYdBng8bGuhlNuNY8QJ/I4ALwUR44LVOYibVohv2RVYWBapGiHowpyTyABq
 sFSHrj/cgvTMUn53yp7veZTo6rWG6RU/D5uUTOMsvKeAoHoOXMyBxV01SCt84t/J
 pcelINcriP6cQVzgfm1B39UNa0IxinGxEx/IIaxz5Ju66G05HTs4CsBFAF6/0QI/
 3YerGWPt9fF6+qYNn21Gg9CL1fHHppNqTXkcuTeGn/Ohg53bosktti5Ysn73vtpR
 GWsJr6M4KQ1SwEbZIiFZCS3A4VTbRcr7WkXets39pcpxGDlNisi+zfV95kNo09xR
 hxi8SuWgb2OfQpVs/71eunp+PM1ZQsODurcy4x0/rlYJfhk53kQSMRtlfy5Cn6uY
 +weWUgygBSWG/w0qanWWK5TF1DNlRKzbix6cmMuGGKcpyF7EMWE1kqmjmmu7CQvM
 a3aPTqGtUt0LeqBQIhmeq/jEwd3vxQa1R85gd0/0sWxEMHkPXVfVoaryiaWAykye
 7r+c8o/41c44zs8YxdZrz72su9fqKC/TeVf5soU46ZucmH8D6f7QHy+s1ec2PEjY
 l6cRIXTXHeQe
 =j6cJ
 -----END PGP SIGNATURE-----

Merge tag 'pull-qapi-2023-05-09-v2' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2023-05-09

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmRbUEYSHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTmzEP/3pDpVxpP7xXLevl2vFqkFyHEjc0L3N4
# x//ljgQojAdM6WU3e0qqOfp/NE2ktUg5D3z+QNiVP1/xXv/dtMGATdG+X9AZs0US
# XnhdicYdBng8bGuhlNuNY8QJ/I4ALwUR44LVOYibVohv2RVYWBapGiHowpyTyABq
# sFSHrj/cgvTMUn53yp7veZTo6rWG6RU/D5uUTOMsvKeAoHoOXMyBxV01SCt84t/J
# pcelINcriP6cQVzgfm1B39UNa0IxinGxEx/IIaxz5Ju66G05HTs4CsBFAF6/0QI/
# 3YerGWPt9fF6+qYNn21Gg9CL1fHHppNqTXkcuTeGn/Ohg53bosktti5Ysn73vtpR
# GWsJr6M4KQ1SwEbZIiFZCS3A4VTbRcr7WkXets39pcpxGDlNisi+zfV95kNo09xR
# hxi8SuWgb2OfQpVs/71eunp+PM1ZQsODurcy4x0/rlYJfhk53kQSMRtlfy5Cn6uY
# +weWUgygBSWG/w0qanWWK5TF1DNlRKzbix6cmMuGGKcpyF7EMWE1kqmjmmu7CQvM
# a3aPTqGtUt0LeqBQIhmeq/jEwd3vxQa1R85gd0/0sWxEMHkPXVfVoaryiaWAykye
# 7r+c8o/41c44zs8YxdZrz72su9fqKC/TeVf5soU46ZucmH8D6f7QHy+s1ec2PEjY
# l6cRIXTXHeQe
# =j6cJ
# -----END PGP SIGNATURE-----
# gpg: Signature made Wed 10 May 2023 09:05:26 AM BST
# gpg:                using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg:                issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [undefined]
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>" [undefined]
# gpg: WARNING: This key is not certified with a trusted signature!
# gpg:          There is no indication that the signature belongs to the owner.
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* tag 'pull-qapi-2023-05-09-v2' of https://repo.or.cz/qemu/armbru:
  qapi: Reformat doc comments to conform to current conventions
  qga/qapi-schema: Reformat doc comments to conform to current conventions
  docs/devel/qapi-code-gen: Update doc comment conventions
  qapi: Section parameter @indent is no longer used, drop
  qapi: Relax doc string @name: description indentation rules
  qapi: Rewrite parsing of doc comment section symbols and tags
  qapi: Fix argument description indentation stripping
  tests/qapi-schema/doc-good: Improve argument description tests
  tests/qapi-schema/doc-good: Improve a comment
  qapi/dump: Indent bulleted lists consistently
  qapi: Tidy up a slightly awkward TODO comment
  sphinx/qapidoc: Do not emit TODO sections into user manuals
  Revert "qapi: BlockExportRemoveMode: move comments to TODO"
  meson: Fix to make QAPI generator output depend on main.py
  qapi: Fix crash on stray double quote character
  docs/devel/qapi-code-gen: Turn FIXME admonitions into comments
  docs/devel/qapi-code-gen: Clean up use of quotes a bit

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
This commit is contained in:
Richard Henderson 2023-05-10 13:11:29 +01:00
parent b2896c1b09 a937b6aa73
commit 568992e344
48 changed files with 4837 additions and 4378 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
docs/devel/qapi-code-gen.rst
View File

@ -947,6 +947,11 @@ Example::
# <- get that
##
For legibility, wrap text paragraphs so every line is at most 70
characters long.
Separate sentences with two spaces.
Definition documentation
~~~~~~~~~~~~~~~~~~~~~~~~
@ -963,57 +968,46 @@ commands and events), member (for structs and unions), branch (for
alternates), or value (for enums), a description of each feature (if
any), and finally optional tagged sections.
The description of an argument or feature 'name' starts with
'\@name:'. The description text can start on the line following the
'\@name:', in which case it must not be indented at all. It can also
start on the same line as the '\@name:'. In this case if it spans
multiple lines then second and subsequent lines must be indented to
line up with the first character of the first line of the
description::
Descriptions start with '\@name:'. The description text should be
indented like this::
# @argone:
# This is a two line description
# in the first style.
#
# @argtwo: This is a two line description
# in the second style.
# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
# do eiusmod tempor incididunt ut labore et dolore magna aliqua.
The number of spaces between the ':' and the text is not significant.
.. FIXME The parser accepts these things in almost any order.
.. admonition:: FIXME
The parser accepts these things in almost any order.
.. admonition:: FIXME
union branches should be described, too.
.. FIXME union branches should be described, too.
Extensions added after the definition was first released carry a
'(since x.y.z)' comment.
"(since x.y.z)" comment.
The feature descriptions must be preceded by a line "Features:", like
this::
# Features:
#
# @feature: Description text
A tagged section starts with one of the following words:
"Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
The section ends with the start of a new section.
The text of a section can start on a new line, in
which case it must not be indented at all. It can also start
on the same line as the 'Note:', 'Returns:', etc tag. In this
case if it spans multiple lines then second and subsequent
lines must be indented to match the first, in the same way as
multiline argument descriptions.
The second and subsequent lines of sections other than
"Example"/"Examples" should be indented like this::
A 'Since: x.y.z' tagged section lists the release that introduced the
# Note: Ut enim ad minim veniam, quis nostrud exercitation ullamco
# laboris nisi ut aliquip ex ea commodo consequat.
#
# Duis aute irure dolor in reprehenderit in voluptate velit esse
# cillum dolore eu fugiat nulla pariatur.
A "Since: x.y.z" tagged section lists the release that introduced the
definition.
An 'Example' or 'Examples' section is automatically rendered
entirely as literal fixed-width text. In other sections,
the text is formatted, and rST markup can be used.
An "Example" or "Examples" section is rendered entirely
as literal fixed-width text. "TODO" sections are not rendered at all
(they are for developers, not users of QMP). In other sections, the
text is formatted, and rST markup can be used.
For example::
@ -1023,7 +1017,7 @@ For example::
# Statistics of a virtual block device or a block backing device.
#
# @device: If the stats are for a virtual block device, the name
# corresponding to the virtual block device.
# corresponding to the virtual block device.
#
# @node-name: The node name of the device. (since 2.3)
#
@ -1040,8 +1034,8 @@ For example::
#
# Query the @BlockStats for all virtual block devices.
#
# @query-nodes: If true, the command will query all the
# block nodes ... explain, explain ... (since 2.3)
# @query-nodes: If true, the command will query all the block nodes
# ... explain, explain ... (since 2.3)
#
# Returns: A list of @BlockStats for each virtual block devices.
#
@ -1078,10 +1072,14 @@ Indentation matters. Bad example::
# @none: None (no memory side cache in this proximity domain,
# or cache associativity unknown)
# (since 5.0)
The description is parsed as a definition list with term "None (no
memory side cache in this proximity domain," and definition "or cache
associativity unknown)".
The last line's de-indent is wrong. The second and subsequent lines
need to line up with each other, like this::
# @none: None (no memory side cache in this proximity domain,
# or cache associativity unknown)
# (since 5.0)
Section tags are case-sensitive and end with a colon. Good example::

3
docs/sphinx/qapidoc.py
View File

@ -268,6 +268,9 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
"""Return list of doctree nodes for additional sections"""
nodelist = []
for section in doc.sections:
if section.name and section.name == 'TODO':
# Hide TODO: sections
continue
snode = self._make_section(section.name)
if section.name and section.name.startswith('Example'):
snode += self._nodes_for_example(section.text)

2
meson.build
View File

@ -2838,12 +2838,12 @@ qapi_gen_depends = [ meson.current_source_dir() / 'scripts/qapi/__init__.py',
meson.current_source_dir() / 'scripts/qapi/expr.py',
meson.current_source_dir() / 'scripts/qapi/gen.py',
meson.current_source_dir() / 'scripts/qapi/introspect.py',
meson.current_source_dir() / 'scripts/qapi/main.py',
meson.current_source_dir() / 'scripts/qapi/parser.py',
meson.current_source_dir() / 'scripts/qapi/schema.py',
meson.current_source_dir() / 'scripts/qapi/source.py',
meson.current_source_dir() / 'scripts/qapi/types.py',
meson.current_source_dir() / 'scripts/qapi/visit.py',
meson.current_source_dir() / 'scripts/qapi/common.py',
meson.current_source_dir() / 'scripts/qapi-gen.py'
]

50
qapi/acpi.json
View File

@ -14,18 +14,19 @@
#
# Specify an ACPI table on the command line to load.
#
# At most one of @file and @data can be specified. The list of files specified
# by any one of them is loaded and concatenated in order. If both are omitted,
# @data is implied.
# At most one of @file and @data can be specified. The list of files
# specified by any one of them is loaded and concatenated in order.
# If both are omitted, @data is implied.
#
# Other fields / optargs can be used to override fields of the generic ACPI
# table header; refer to the ACPI specification 5.0, section 5.2.6 System
# Description Table Header. If a header field is not overridden, then the
# corresponding value from the concatenated blob is used (in case of @file), or
# it is filled in with a hard-coded value (in case of @data).
# Other fields / optargs can be used to override fields of the generic
# ACPI table header; refer to the ACPI specification 5.0, section
# 5.2.6 System Description Table Header. If a header field is not
# overridden, then the corresponding value from the concatenated blob
# is used (in case of @file), or it is filled in with a hard-coded
# value (in case of @data).
#
# String fields are copied into the matching ACPI member from lowest address
# upwards, and silently truncated / NUL-padded to length.
# String fields are copied into the matching ACPI member from lowest
# address upwards, and silently truncated / NUL-padded to length.
#
# @sig: table signature / identifier (4 bytes)
#
@ -38,20 +39,20 @@
# @oem_rev: OEM-supplied revision number (4 bytes)
#
# @asl_compiler_id: identifier of the utility that created the table
# (4 bytes)
# (4 bytes)
#
# @asl_compiler_rev: revision number of the utility that created the
# table (4 bytes)
# table (4 bytes)
#
# @file: colon (:) separated list of pathnames to load and
# concatenate as table data. The resultant binary blob is expected to
# have an ACPI table header. At least one file is required. This field
# excludes @data.
# @file: colon (:) separated list of pathnames to load and concatenate
# as table data. The resultant binary blob is expected to have an
# ACPI table header. At least one file is required. This field
# excludes @data.
#
# @data: colon (:) separated list of pathnames to load and
# concatenate as table data. The resultant binary blob must not have an
# ACPI table header. At least one file is required. This field excludes
# @file.
# @data: colon (:) separated list of pathnames to load and concatenate
# as table data. The resultant binary blob must not have an ACPI
# table header. At least one file is required. This field
# excludes @file.
#
# Since: 1.5
##
@ -71,6 +72,7 @@
# @ACPISlotType:
#
# @DIMM: memory slot
#
# @CPU: logical CPU slot (since 2.7)
##
{ 'enum': 'ACPISlotType', 'data': [ 'DIMM', 'CPU' ] }
@ -78,9 +80,9 @@
##
# @ACPIOSTInfo:
#
# OSPM Status Indication for a device
# For description of possible values of @source and @status fields
# see "_OST (OSPM Status Indication)" chapter of ACPI5.0 spec.
# OSPM Status Indication for a device For description of possible
# values of @source and @status fields see "_OST (OSPM Status
# Indication)" chapter of ACPI5.0 spec.
#
# @device: device ID associated with slot
#
@ -117,7 +119,6 @@
# { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
# { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
# ]}
#
##
{ 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] }
@ -136,7 +137,6 @@
# "data": { "info": { "device": "d1", "slot": "0",
# "slot-type": "DIMM", "source": 1, "status": 0 } },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
#
##
{ 'event': 'ACPI_DEVICE_OST',
'data': { 'info': 'ACPIOSTInfo' } }

93
qapi/audio.json
View File

@ -16,24 +16,24 @@
# General audio backend options that are used for both playback and
# recording.
#
# @mixing-engine: use QEMU's mixing engine to mix all streams inside QEMU and
# convert audio formats when not supported by the backend. When
# set to off, fixed-settings must be also off (default on,
# since 4.2)
# @mixing-engine: use QEMU's mixing engine to mix all streams inside
# QEMU and convert audio formats when not supported by the
# backend. When set to off, fixed-settings must be also off
# (default on, since 4.2)
#
# @fixed-settings: use fixed settings for host input/output. When off,
# frequency, channels and format must not be
# specified (default true)
# @fixed-settings: use fixed settings for host input/output. When
# off, frequency, channels and format must not be specified
# (default true)
#
# @frequency: frequency to use when using fixed settings
# (default 44100)
# @frequency: frequency to use when using fixed settings (default
# 44100)
#
# @channels: number of channels when using fixed settings (default 2)
#
# @voices: number of voices to use (default 1)
#
# @format: sample format to use when using fixed settings
# (default s16)
# @format: sample format to use when using fixed settings (default
# s16)
#
# @buffer-length: the buffer length in microseconds
#
@ -76,7 +76,7 @@
# @period-length: the period length in microseconds
#
# @try-poll: attempt to use poll mode, falling back to non-polling
# access on failure (default true)
# access on failure (default true)
#
# Since: 4.0
##
@ -131,8 +131,8 @@
##
# @AudiodevCoreaudioPerDirectionOptions:
#
# Options of the Core Audio backend that are used for both playback and
# recording.
# Options of the Core Audio backend that are used for both playback
# and recording.
#
# @buffer-count: number of buffers
#
@ -168,8 +168,8 @@
#
# @out: options of the playback stream
#
# @latency: add extra latency to playback in microseconds
# (default 10000)
# @latency: add extra latency to playback in microseconds (default
# 10000)
#
# Since: 4.0
##
@ -185,21 +185,22 @@
# Options of the JACK backend that are used for both playback and
# recording.
#
# @server-name: select from among several possible concurrent server instances
# (default: environment variable $JACK_DEFAULT_SERVER if set, else "default")
# @server-name: select from among several possible concurrent server
# instances (default: environment variable $JACK_DEFAULT_SERVER if
# set, else "default")
#
# @client-name: the client name to use. The server will modify this name to
# create a unique variant, if needed unless @exact-name is true (default: the
# guest's name)
# @client-name: the client name to use. The server will modify this
# name to create a unique variant, if needed unless @exact-name is
# true (default: the guest's name)
#
# @connect-ports: if set, a regular expression of JACK client port name(s) to
# monitor for and automatically connect to
# @connect-ports: if set, a regular expression of JACK client port
# name(s) to monitor for and automatically connect to
#
# @start-server: start a jack server process if one is not already present
# (default: false)
# @start-server: start a jack server process if one is not already
# present (default: false)
#
# @exact-name: use the exact name requested otherwise JACK automatically
# generates a unique one, if needed (default: false)
# @exact-name: use the exact name requested otherwise JACK
# automatically generates a unique one, if needed (default: false)
#
# Since: 5.1
##
@ -239,7 +240,7 @@
# @buffer-count: number of buffers
#
# @try-poll: attempt to use poll mode, falling back to non-polling
# access on failure (default true)
# access on failure (default true)
#
# Since: 4.0
##
@ -260,15 +261,15 @@
# @out: options of the playback stream
#
# @try-mmap: try using memory-mapped access, falling back to
# non-memory-mapped access on failure (default true)
# non-memory-mapped access on failure (default true)
#
# @exclusive: open device in exclusive mode (vmix won't work)
# (default false)
# @exclusive: open device in exclusive mode (vmix won't work) (default
# false)
#
# @dsp-policy: set the timing policy of the device (between 0 and 10,
# where smaller number means smaller latency but higher
# CPU usage) or -1 to use fragment mode (option ignored
# on some platforms) (default 5)
# where smaller number means smaller latency but higher CPU usage)
# or -1 to use fragment mode (option ignored on some platforms)
# (default 5)
#
# Since: 4.0
##
@ -283,18 +284,18 @@
##
# @AudiodevPaPerDirectionOptions:
#
# Options of the Pulseaudio backend that are used for both playback and
# recording.
# Options of the Pulseaudio backend that are used for both playback
# and recording.
#
# @name: name of the sink/source to use
#
# @stream-name: name of the PulseAudio stream created by qemu. Can be
# used to identify the stream in PulseAudio when you
# create multiple PulseAudio devices or run multiple qemu
# instances (default: audiodev's id, since 4.2)
# used to identify the stream in PulseAudio when you create
# multiple PulseAudio devices or run multiple qemu instances
# (default: audiodev's id, since 4.2)
#
# @latency: latency you want PulseAudio to achieve in microseconds
# (default 15000)
# (default 15000)
#
# Since: 4.0
##
@ -333,12 +334,12 @@
# @name: name of the sink/source to use
#
# @stream-name: name of the Pipewire stream created by qemu. Can be
# used to identify the stream in Pipewire when you
# create multiple Pipewire devices or run multiple qemu
# instances (default: audiodev's id)
# used to identify the stream in Pipewire when you create multiple
# Pipewire devices or run multiple qemu instances (default:
# audiodev's id)
#
# @latency: latency you want Pipewire to achieve in microseconds
# (default 46000)
# (default 46000)
#
# Since: 8.1
##
@ -472,7 +473,8 @@
#
# @driver: the backend driver to use
#
# @timer-period: timer period (in microseconds, 0: use lowest possible)
# @timer-period: timer period (in microseconds, 0: use lowest
# possible)
#
# Since: 4.0
##
@ -516,7 +518,6 @@
# Returns: array of @Audiodev
#
# Since: 8.0
#
##
{ 'command': 'query-audiodevs',
'returns': ['Audiodev'] }

29
qapi/authz.json
View File

@ -11,6 +11,7 @@
# The authorization policy result
#
# @deny: deny access
#
# @allow: allow access
#
# Since: 4.0
@ -25,6 +26,7 @@
# The authorization policy match format
#
# @exact: an exact string match
#
# @glob: string with ? and * shell wildcard support
#
# Since: 4.0
@ -39,7 +41,9 @@
# A single authorization rule.
#
# @match: a string or glob to match against a user identity
#
# @policy: the result to return if @match evaluates to true
#
# @format: the format of the @match rule (default 'exact')
#
# Since: 4.0
@ -54,7 +58,8 @@
#
# Properties for authz-list objects.
#
# @policy: Default policy to apply when no rule matches (default: deny)
# @policy: Default policy to apply when no rule matches (default:
# deny)
#
# @rules: Authorization rules based on matching user
#
@ -69,14 +74,14 @@
#
# Properties for authz-listfile objects.
#
# @filename: File name to load the configuration from. The file must
# contain valid JSON for AuthZListProperties.
# @filename: File name to load the configuration from. The file must
# contain valid JSON for AuthZListProperties.
#
# @refresh: If true, inotify is used to monitor the file, automatically
# reloading changes. If an error occurs during reloading, all
# authorizations will fail until the file is next successfully
# loaded. (default: true if the binary was built with
# CONFIG_INOTIFY1, false otherwise)
# @refresh: If true, inotify is used to monitor the file,
# automatically reloading changes. If an error occurs during
# reloading, all authorizations will fail until the file is next
# successfully loaded. (default: true if the binary was built
# with CONFIG_INOTIFY1, false otherwise)
#
# Since: 4.0
##
@ -101,10 +106,10 @@
#
# Properties for authz-simple objects.
#
# @identity: Identifies the allowed user. Its format depends on the network
# service that authorization object is associated with. For
# authorizing based on TLS x509 certificates, the identity must be
# the x509 distinguished name.
# @identity: Identifies the allowed user. Its format depends on the
# network service that authorization object is associated with.
# For authorizing based on TLS x509 certificates, the identity
# must be the x509 distinguished name.
#
# Since: 4.0
##

2801
qapi/block-core.json
View File

File diff suppressed because it is too large Load Diff

244
qapi/block-export.json
View File

@ -11,20 +11,24 @@
##
# @NbdServerOptions:
#
# Keep this type consistent with the nbd-server-start arguments. The only
# intended difference is using SocketAddress instead of SocketAddressLegacy.
# Keep this type consistent with the nbd-server-start arguments. The
# only intended difference is using SocketAddress instead of
# SocketAddressLegacy.
#
# @addr: Address on which to listen.
#
# @tls-creds: ID of the TLS credentials object (since 2.6).
#
# @tls-authz: ID of the QAuthZ authorization object used to validate
# the client's x509 distinguished name. This object is
# is only resolved at time of use, so can be deleted and
# recreated on the fly while the NBD server is active.
# If missing, it will default to denying access (since 4.0).
# @max-connections: The maximum number of connections to allow at the same
# time, 0 for unlimited. Setting this to 1 also stops
# the server from advertising multiple client support
# (since 5.2; default: 0)
# the client's x509 distinguished name. This object is is only
# resolved at time of use, so can be deleted and recreated on the
# fly while the NBD server is active. If missing, it will default
# to denying access (since 4.0).
#
# @max-connections: The maximum number of connections to allow at the
# same time, 0 for unlimited. Setting this to 1 also stops the
# server from advertising multiple client support (since 5.2;
# default: 0)
#
# Since: 4.2
##
@ -38,24 +42,28 @@
# @nbd-server-start:
#
# Start an NBD server listening on the given host and port. Block
# devices can then be exported using @nbd-server-add. The NBD
# server will present them as named exports; for example, another
# QEMU instance could refer to them as "nbd:HOST:PORT:exportname=NAME".
# devices can then be exported using @nbd-server-add. The NBD server
# will present them as named exports; for example, another QEMU
# instance could refer to them as "nbd:HOST:PORT:exportname=NAME".
#
# Keep this type consistent with the NbdServerOptions type. The only intended
# difference is using SocketAddressLegacy instead of SocketAddress.
# Keep this type consistent with the NbdServerOptions type. The only
# intended difference is using SocketAddressLegacy instead of
# SocketAddress.
#
# @addr: Address on which to listen.
#
# @tls-creds: ID of the TLS credentials object (since 2.6).
#
# @tls-authz: ID of the QAuthZ authorization object used to validate
# the client's x509 distinguished name. This object is
# is only resolved at time of use, so can be deleted and
# recreated on the fly while the NBD server is active.
# If missing, it will default to denying access (since 4.0).
# @max-connections: The maximum number of connections to allow at the same
# time, 0 for unlimited. Setting this to 1 also stops
# the server from advertising multiple client support
# (since 5.2; default: 0).
# the client's x509 distinguished name. This object is is only
# resolved at time of use, so can be deleted and recreated on the
# fly while the NBD server is active. If missing, it will default
# to denying access (since 4.0).
#
# @max-connections: The maximum number of connections to allow at the
# same time, 0 for unlimited. Setting this to 1 also stops the
# server from advertising multiple client support (since 5.2;
# default: 0).
#
# Returns: error if the server is already running.
#
@ -71,14 +79,14 @@
##
# @BlockExportOptionsNbdBase:
#
# An NBD block export (common options shared between nbd-server-add and
# the NBD branch of block-export-add).
# An NBD block export (common options shared between nbd-server-add
# and the NBD branch of block-export-add).
#
# @name: Export name. If unspecified, the @device parameter is used as the
# export name. (Since 2.12)
# @name: Export name. If unspecified, the @device parameter is used
# as the export name. (Since 2.12)
#
# @description: Free-form description of the export, up to 4096 bytes.
# (Since 5.0)
# (Since 5.0)
#
# Since: 5.0
##
@ -92,15 +100,15 @@
# block-export-add).
#
# @bitmaps: Also export each of the named dirty bitmaps reachable from
# @device, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
# the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect
# each bitmap.
# Since 7.1 bitmap may be specified by node/name pair.
# @device, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
# the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect
# each bitmap. Since 7.1 bitmap may be specified by node/name
# pair.
#
# @allocation-depth: Also export the allocation depth map for @device, so
# the NBD client can use NBD_OPT_SET_META_CONTEXT with
# the metadata context name "qemu:allocation-depth" to
# inspect allocation details. (since 5.2)
# @allocation-depth: Also export the allocation depth map for @device,
# so the NBD client can use NBD_OPT_SET_META_CONTEXT with the
# metadata context name "qemu:allocation-depth" to inspect
# allocation details. (since 5.2)
#
# Since: 5.2
##
@ -114,12 +122,15 @@
#
# A vhost-user-blk block export.
#
# @addr: The vhost-user socket on which to listen. Both 'unix' and 'fd'
# SocketAddress types are supported. Passed fds must be UNIX domain
# sockets.
# @logical-block-size: Logical block size in bytes. Defaults to 512 bytes.
# @num-queues: Number of request virtqueues. Must be greater than 0. Defaults
# to 1.
# @addr: The vhost-user socket on which to listen. Both 'unix' and
# 'fd' SocketAddress types are supported. Passed fds must be UNIX
# domain sockets.
#
# @logical-block-size: Logical block size in bytes. Defaults to 512
# bytes.
#
# @num-queues: Number of request virtqueues. Must be greater than 0.
# Defaults to 1.
#
# Since: 5.2
##
@ -138,7 +149,7 @@
# @on: Pass allow_other as a mount option.
#
# @auto: Try mounting with allow_other first, and if that fails, retry
# without allow_other.
# without allow_other.
#
# Since: 6.1
##
@ -151,24 +162,21 @@
# Options for exporting a block graph node on some (file) mountpoint
# as a raw image.
#
# @mountpoint: Path on which to export the block device via FUSE.
# This must point to an existing regular file.
# @mountpoint: Path on which to export the block device via FUSE. This
# must point to an existing regular file.
#
# @growable: Whether writes beyond the EOF should grow the block node
# accordingly. (default: false)
# accordingly. (default: false)
#
# @allow-other: If this is off, only qemu's user is allowed access to
# this export. That cannot be changed even with chmod or
# chown.
# Enabling this option will allow other users access to
# the export with the FUSE mount option "allow_other".
# Note that using allow_other as a non-root user requires
# user_allow_other to be enabled in the global fuse.conf
# configuration file.
# In auto mode (the default), the FUSE export driver will
# first attempt to mount the export with allow_other, and
# if that fails, try again without.
# (since 6.1; default: auto)
# this export. That cannot be changed even with chmod or chown.
# Enabling this option will allow other users access to the export
# with the FUSE mount option "allow_other". Note that using
# allow_other as a non-root user requires user_allow_other to be
# enabled in the global fuse.conf configuration file. In auto
# mode (the default), the FUSE export driver will first attempt to
# mount the export with allow_other, and if that fails, try again
# without. (since 6.1; default: auto)
#
# Since: 6.0
##
@ -184,11 +192,16 @@
# A vduse-blk block export.
#
# @name: the name of VDUSE device (must be unique across the host).
# @num-queues: the number of virtqueues. Defaults to 1.
# @queue-size: the size of virtqueue. Defaults to 256.
# @logical-block-size: Logical block size in bytes. Range [512, PAGE_SIZE]
# and must be power of 2. Defaults to 512 bytes.
# @serial: the serial number of virtio block device. Defaults to empty string.
#
# @num-queues: the number of virtqueues. Defaults to 1.
#
# @queue-size: the size of virtqueue. Defaults to 256.
#
# @logical-block-size: Logical block size in bytes. Range [512,
# PAGE_SIZE] and must be power of 2. Defaults to 512 bytes.
#
# @serial: the serial number of virtio block device. Defaults to
# empty string.
#
# Since: 7.1
##
@ -206,13 +219,13 @@
#
# @device: The device name or node name of the node to be exported
#
# @writable: Whether clients should be able to write to the device via the
# NBD connection (default false).
# @writable: Whether clients should be able to write to the device via
# the NBD connection (default false).
#
# @bitmap: Also export a single dirty bitmap reachable from @device, so the
# NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata
# context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap
# (since 4.0).
# @bitmap: Also export a single dirty bitmap reachable from @device,
# so the NBD client can use NBD_OPT_SET_META_CONTEXT with the
# metadata context name "qemu:dirty-bitmap:BITMAP" to inspect the
# bitmap (since 4.0).
#
# Since: 5.0
##
@ -226,13 +239,16 @@
#
# Export a block node to QEMU's embedded NBD server.
#
# The export name will be used as the id for the resulting block export.
# The export name will be used as the id for the resulting block
# export.
#
# Features:
# @deprecated: This command is deprecated. Use @block-export-add instead.
#
# Returns: error if the server is not running, or export with the same name
# already exists.
# @deprecated: This command is deprecated. Use @block-export-add
# instead.
#
# Returns: error if the server is not running, or export with the same
# name already exists.
#
# Since: 1.3
##
@ -245,17 +261,18 @@
#
# Mode for removing a block export.
#
# @safe: Remove export if there are no existing connections, fail otherwise.
# @safe: Remove export if there are no existing connections, fail
# otherwise.
#
# @hard: Drop all connections immediately and remove export.
#
# TODO: Potential additional modes to be added in the future:
# 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.
# hide: Just hide export from new clients, leave existing connections
# as is. Remove export after all clients are disconnected.
#
# soft: Hide export from new clients, answer with ESHUTDOWN for all further
# requests from existing clients.
# soft: Hide export from new clients, answer with ESHUTDOWN for all
# further requests from existing clients.
#
# Since: 2.12
##
@ -268,17 +285,19 @@
#
# @name: Block export id.
#
# @mode: Mode of command operation. See @BlockExportRemoveMode description.
# Default is 'safe'.
# @mode: Mode of command operation. See @BlockExportRemoveMode
# description. Default is 'safe'.
#
# Features:
# @deprecated: This command is deprecated. Use @block-export-del instead.
#
# @deprecated: This command is deprecated. Use @block-export-del
# instead.
#
# Returns: error if
#
# - the server is not running
# - export is not found
# - mode is 'safe' and there are existing connections
# - the server is not running
# - export is not found
# - mode is 'safe' and there are existing connections
#
# Since: 2.12
##
@ -290,8 +309,8 @@
##
# @nbd-server-stop:
#
# Stop QEMU's embedded NBD server, and unregister all devices previously
# added via @nbd-server-add.
# Stop QEMU's embedded NBD server, and unregister all devices
# previously added via @nbd-server-add.
#
# Since: 1.3
##
@ -304,8 +323,11 @@
# An enumeration of block export types
#
# @nbd: NBD export
#
# @vhost-user-blk: vhost-user-blk export (since 5.2)
#
# @fuse: FUSE export (since: 6.0)
#
# @vduse-blk: vduse-blk export (since 7.1)
#
# Since: 4.2
@ -320,28 +342,31 @@
##
# @BlockExportOptions:
#
# Describes a block export, i.e. how single node should be exported on an
# external interface.
# Describes a block export, i.e. how single node should be exported on
# an external interface.
#
# @id: A unique identifier for the block export (across all export types)
# @id: A unique identifier for the block export (across all export
# types)
#
# @node-name: The node name of the block node to be exported (since: 5.2)
# @node-name: The node name of the block node to be exported
# (since: 5.2)
#
# @writable: True if clients should be able to write to the export
# (default false)
# (default false)
#
# @writethrough: If true, caches are flushed after every write request to the
# export before completion is signalled. (since: 5.2;
# default: false)
# @writethrough: If true, caches are flushed after every write request
# to the export before completion is signalled. (since: 5.2;
# default: false)
#
# @iothread: The name of the iothread object where the export will run. The
# default is to use the thread currently associated with the
# block node. (since: 5.2)
# @iothread: The name of the iothread object where the export will
# run. The default is to use the thread currently associated with
# the block node. (since: 5.2)
#
# @fixed-iothread: True prevents the block node from being moved to another
# thread while the export is active. If true and @iothread is
# given, export creation fails if the block node cannot be
# moved to the iothread. The default is false. (since: 5.2)
# @fixed-iothread: True prevents the block node from being moved to
# another thread while the export is active. If true and
# @iothread is given, export creation fails if the block node
# cannot be moved to the iothread. The default is false.
# (since: 5.2)
#
# Since: 4.2
##
@ -378,17 +403,17 @@
##
# @block-export-del:
#
# Request to remove a block export. This drops the user's reference to the
# export, but the export may still stay around after this command returns until
# the shutdown of the export has completed.
# Request to remove a block export. This drops the user's reference
# to the export, but the export may still stay around after this
# command returns until the shutdown of the export has completed.
#
# @id: Block export id.
#
# @mode: Mode of command operation. See @BlockExportRemoveMode description.
# Default is 'safe'.
# @mode: Mode of command operation. See @BlockExportRemoveMode
# description. Default is 'safe'.
#
# Returns: Error if the export is not found or @mode is 'safe' and the export
# is still in use (e.g. by existing client connections)
# Returns: Error if the export is not found or @mode is 'safe' and the
# export is still in use (e.g. by existing client connections)
#
# Since: 5.2
##
@ -420,8 +445,7 @@
# @node-name: The node name of the block node that is exported
#
# @shutting-down: True if the export is shutting down (e.g. after a
# block-export-del command, but before the shutdown has
# completed)
# block-export-del command, but before the shutdown has completed)
#
# Since: 5.2
##

214
qapi/block.json
View File

@ -19,26 +19,26 @@
# translate logical CHS to physical; instead, they will use logical
# block addressing.
#
# @auto: If cylinder/heads/sizes are passed, choose between none and LBA
# depending on the size of the disk. If they are not passed,
# choose none if QEMU can guess that the disk had 16 or fewer
# heads, large if QEMU can guess that the disk had 131072 or
# fewer tracks across all heads (i.e. cylinders*heads<131072),
# otherwise LBA.
# @auto: If cylinder/heads/sizes are passed, choose between none and
# LBA depending on the size of the disk. If they are not passed,
# choose none if QEMU can guess that the disk had 16 or fewer
# heads, large if QEMU can guess that the disk had 131072 or fewer
# tracks across all heads (i.e. cylinders*heads<131072), otherwise
# LBA.
#
# @none: The physical disk geometry is equal to the logical geometry.
#
# @lba: Assume 63 sectors per track and one of 16, 32, 64, 128 or 255
# heads (if fewer than 255 are enough to cover the whole disk
# with 1024 cylinders/head). The number of cylinders/head is
# then computed based on the number of sectors and heads.
# heads (if fewer than 255 are enough to cover the whole disk with
# 1024 cylinders/head). The number of cylinders/head is then
# computed based on the number of sectors and heads.
#
# @large: The number of cylinders per head is scaled down to 1024
# by correspondingly scaling up the number of heads.
# @large: The number of cylinders per head is scaled down to 1024 by
# correspondingly scaling up the number of heads.
#
# @rechs: Same as @large, but first convert a 16-head geometry to
# 15-head, by proportionally scaling up the number of
# cylinders/head.
# 15-head, by proportionally scaling up the number of
# cylinders/head.
#
# Since: 2.0
##
@ -51,9 +51,13 @@
# Type of Floppy drive to be emulated by the Floppy Disk Controller.
#
# @144: 1.44MB 3.5" drive
#
# @288: 2.88MB 3.5" drive
#
# @120: 1.2MB 5.25" drive
#
# @none: No drive connected
#
# @auto: Automatically determined by inserted media at boot
#
# Since: 2.6
@ -68,8 +72,8 @@
#
# @id: the identifier of the persistent reservation manager
#
# @connected: true if the persistent reservation manager is connected to
# the underlying storage or helper
# @connected: true if the persistent reservation manager is connected
# to the underlying storage or helper
#
# Since: 3.0
##
@ -79,9 +83,11 @@
##
# @query-pr-managers:
#
# Returns a list of information about each persistent reservation manager.
# Returns a list of information about each persistent reservation
# manager.
#
# Returns: a list of @PRManagerInfo for each persistent reservation manager
# Returns: a list of @PRManagerInfo for each persistent reservation
# manager
#
# Since: 3.0
##
@ -98,13 +104,15 @@
# @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.
# If not specified, the default value is false.
#
# Features:
#
# @deprecated: Member @device is deprecated. Use @id instead.
#
# 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: Ejecting a device with no media results in success
#
@ -123,32 +131,33 @@
##
# @blockdev-open-tray:
#
# Opens a block device's tray. If there is a block driver state tree inserted as
# a medium, it will become inaccessible to the guest (but it will remain
# associated to the block device, so closing the tray will make it accessible
# again).
# Opens a block device's tray. If there is a block driver state tree
# inserted as a medium, it will become inaccessible to the guest (but
# it will remain associated to the block device, so closing the tray
# will make it accessible again).
#
# If the tray was already open before, this will be a no-op.
#
# Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in
# which no such event will be generated, these include:
# Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There
# are cases in which no such event will be generated, these include:
#
# - if the guest has locked the tray, @force is false and the guest does not
# respond to the eject request
# - if the BlockBackend denoted by @device does not have a guest device attached
# to it
# - if the guest has locked the tray, @force is false and the guest
# does not respond to the eject request
# - if the BlockBackend denoted by @device does not have a guest
# device attached to it
# - if the guest device does not have an actual tray
#
# @device: Block device name
#
# @id: The name or QOM path of the guest device (since: 2.8)
#
# @force: if false (the default), an eject request will be sent to
# the guest if it has locked the tray (and the tray will not be opened
# immediately); if true, the tray will be opened regardless of whether
# it is locked
# @force: if false (the default), an eject request will be sent to the
# guest if it has locked the tray (and the tray will not be opened
# immediately); if true, the tray will be opened regardless of
# whether it is locked
#
# Features:
#
# @deprecated: Member @device is deprecated. Use @id instead.
#
# Since: 2.5
@ -166,7 +175,6 @@
# "tray-open": true } }
#
# <- { "return": {} }
#
##
{ 'command': 'blockdev-open-tray',
'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
@ -176,9 +184,9 @@
##
# @blockdev-close-tray:
#
# Closes a block device's tray. If there is a block driver state tree associated
# with the block device (which is currently ejected), that tree will be loaded
# as the medium.
# Closes a block device's tray. If there is a block driver state tree
# associated with the block device (which is currently ejected), that
# tree will be loaded as the medium.
#
# If the tray was already closed before, this will be a no-op.
#
@ -187,6 +195,7 @@
# @id: The name or QOM path of the guest device (since: 2.8)
#
# Features:
#
# @deprecated: Member @device is deprecated. Use @id instead.
#
# Since: 2.5
@ -204,7 +213,6 @@
# "tray-open": false } }
#
# <- { "return": {} }
#
##
{ 'command': 'blockdev-close-tray',
'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
@ -213,11 +221,12 @@
##
# @blockdev-remove-medium:
#
# Removes a medium (a block driver state tree) from a block device. That block
# device's tray must currently be open (unless there is no attached guest
# device).
# Removes a medium (a block driver state tree) from a block device.
# That block device's tray must currently be open (unless there is no
# attached guest device).
#
# If the tray is open and there is no medium inserted, this will be a no-op.
# If the tray is open and there is no medium inserted, this will be a
# no-op.
#
# @id: The name or QOM path of the guest device
#
@ -247,7 +256,6 @@
# "arguments": { "id": "ide0-1-0" } }
#
# <- { "return": {} }
#
##
{ 'command': 'blockdev-remove-medium',
'data': { 'id': 'str' } }
@ -255,9 +263,9 @@
##
# @blockdev-insert-medium:
#
# Inserts a medium (a block driver state tree) into a block device. That block
# device's tray must currently be open (unless there is no attached guest
# device) and there must be no medium inserted already.
# Inserts a medium (a block driver state tree) into a block device.
# That block device's tray must currently be open (unless there is no
# attached guest device) and there must be no medium inserted already.
#
# @id: The name or QOM path of the guest device
#
@ -280,7 +288,6 @@
# "node-name": "node0" } }
#
# <- { "return": {} }
#
##
{ 'command': 'blockdev-insert-medium',
'data': { 'id': 'str',
@ -306,30 +313,32 @@
##
# @blockdev-change-medium:
#
# Changes the medium inserted into a block device by ejecting the current medium
# and loading a new image file which is inserted as the new medium (this command
# combines blockdev-open-tray, blockdev-remove-medium, blockdev-insert-medium
# and blockdev-close-tray).
# Changes the medium inserted into a block device by ejecting the
# current medium and loading a new image file which is inserted as the
# new medium (this command combines blockdev-open-tray,
# blockdev-remove-medium, blockdev-insert-medium and
# blockdev-close-tray).
#
# @device: Block device name
#
# @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)
#
# @filename: filename of the new image to be loaded
#
# @format: format to open the new image with (defaults to
# the probed format)
# @format: format to open the new image with (defaults to the probed
# format)
#
# @read-only-mode: change the read-only mode of the device; defaults
# to 'retain'
# to 'retain'
#
# @force: if false (the default), an eject request through blockdev-open-tray
# will be sent to the guest if it has locked the tray (and the tray
# will not be opened immediately); if true, the tray will be opened
# regardless of whether it is locked. (since 7.1)
# @force: if false (the default), an eject request through
# blockdev-open-tray will be sent to the guest if it has locked
# the tray (and the tray will not be opened immediately); if true,
# the tray will be opened regardless of whether it is locked.
# (since 7.1)
#
# Features:
#
# @deprecated: Member @device is deprecated. Use @id instead.
#
# Since: 2.5
@ -363,7 +372,6 @@
# "read-only-mode": "read-only" } }
#
# <- { "return": {} }
#
##
{ 'command': 'blockdev-change-medium',
'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
@ -376,16 +384,17 @@
##
# @DEVICE_TRAY_MOVED:
#
# Emitted whenever the tray of a removable device is moved by the guest or by
# HMP/QMP commands
# Emitted whenever the tray of a removable device is moved by the
# guest or by HMP/QMP commands
#
# @device: Block device name. This is always present for compatibility
# reasons, but it can be empty ("") if the image does not
# have a device name associated.
# @device: Block device name. This is always present for
# compatibility reasons, but it can be empty ("") if the image
# does not have a device name associated.
#
# @id: The name or QOM path of the guest device (since 2.8)
#
# @tray-open: true if the tray has been opened or false if it has been closed
# @tray-open: true if the tray has been opened or false if it has been
# closed
#
# Since: 1.1
#
@ -397,7 +406,6 @@
# "tray-open": true
# },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
#
##
{ 'event': 'DEVICE_TRAY_MOVED',
'data': { 'device': 'str', 'id': 'str', 'tray-open': 'bool' } }
@ -421,7 +429,6 @@
# "connected": true
# },
# "timestamp": { "seconds": 1519840375, "microseconds": 450486 } }
#
##
{ 'event': 'PR_MANAGER_STATUS_CHANGED',
'data': { 'id': 'str', 'connected': 'bool' } }
@ -436,24 +443,25 @@
#
# If two or more devices are members of the same group, the limits
# will apply to the combined I/O of the whole group in a round-robin
# fashion. Therefore, setting new I/O limits to a device will affect
# fashion. Therefore, setting new I/O limits to a device will affect
# the whole group.
#
# The name of the group can be specified using the 'group' parameter.
# If the parameter is unset, it is assumed to be the current group of
# that device. If it's not in any group yet, the name of the device
# that device. If it's not in any group yet, the name of the device
# will be used as the name for its group.
#
# The 'group' parameter can also be used to move a device to a
# different group. In this case the limits specified in the parameters
# will be applied to the new group only.
# different group. In this case the limits specified in the
# parameters will be applied to the new group only.
#
# I/O limits can be disabled by setting all of them to 0. In this case
# the device will be removed from its group and the rest of its
# members will not be affected. The 'group' parameter is ignored.
# members will not be affected. The 'group' parameter is ignored.
#
# 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
#
# Since: 1.1
#
@ -504,37 +512,40 @@
#
# Manage read, write and flush latency histograms for the device.
#
# If only @id parameter is specified, remove all present latency histograms
# for the device. Otherwise, add/reset some of (or all) latency histograms.
# If only @id parameter is specified, remove all present latency
# histograms for the device. Otherwise, add/reset some of (or all)
# latency histograms.
#
# @id: The name or QOM path of the guest device.
#
# @boundaries: list of interval boundary values (see description in
# BlockLatencyHistogramInfo definition). If specified, all
# latency histograms are removed, and empty ones created for all
# io types with intervals corresponding to @boundaries (except for
# io types, for which specific boundaries are set through the
# following parameters).
# BlockLatencyHistogramInfo definition). If specified, all latency
# histograms are removed, and empty ones created for all io types
# with intervals corresponding to @boundaries (except for io
# types, for which specific boundaries are set through the
# following parameters).
#
# @boundaries-read: list of interval boundary values for read latency
# histogram. If specified, old read latency histogram is
# removed, and empty one created with intervals
# corresponding to @boundaries-read. The parameter has higher
# priority then @boundaries.
# histogram. If specified, old read latency histogram is removed,
# and empty one created with intervals corresponding to
# @boundaries-read. The parameter has higher priority then
# @boundaries.
#
# @boundaries-write: list of interval boundary values for write latency
# histogram.
# @boundaries-write: list of interval boundary values for write
# latency histogram.
#
# @boundaries-flush: list of interval boundary values for flush latency
# histogram.
# @boundaries-flush: list of interval boundary values for flush
# latency histogram.
#
# Returns: error if device is not found or any boundary arrays are invalid.
# Returns: error if device is not found or any boundary arrays are
# invalid.
#
# Since: 4.0
#
# Example:
# set new histograms for all io types with intervals
# [0, 10), [10, 50), [50, 100), [100, +inf):
#
# set new histograms for all io types with intervals [0, 10), [10,
# 50), [50, 100), [100, +inf):
#
# -> { "execute": "block-latency-histogram-set",
# "arguments": { "id": "drive0",
@ -542,8 +553,9 @@
# <- { "return": {} }
#
# Example:
# set new histogram only for write, other histograms will remain
# not changed (or not created):
#
# set new histogram only for write, other histograms will remain not
# changed (or not created):
#
# -> { "execute": "block-latency-histogram-set",
# "arguments": { "id": "drive0",
@ -551,9 +563,10 @@
# <- { "return": {} }
#
# Example:
# set new histograms with the following intervals:
# read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
# write: [0, 1000), [1000, 5000), [5000, +inf)
#
# set new histograms with the following intervals: read, flush: [0,
# 10), [10, 50), [50, 100), [100, +inf) write: [0, 1000), [1000,
# 5000), [5000, +inf)
#
# -> { "execute": "block-latency-histogram-set",
# "arguments": { "id": "drive0",
@ -562,6 +575,7 @@
# <- { "return": {} }
#
# Example:
#
# remove all latency histograms:
#
# -> { "execute": "block-latency-histogram-set",

134
qapi/char.json
View File

@ -17,12 +17,12 @@
#
# @filename: the filename of the character device
#
# @frontend-open: shows whether the frontend device attached to this backend
# (eg. with the chardev=... option) is in open or closed state
# (since 2.1)
# @frontend-open: shows whether the frontend device attached to this
# backend (eg. with the chardev=... option) is in open or closed
# state (since 2.1)
#
# Notes: @filename is encoded using the QEMU command line character device
# encoding. See the QEMU man page for details.
# Notes: @filename is encoded using the QEMU command line character
# device encoding. See the QEMU man page for details.
#
# Since: 0.14
##
@ -62,7 +62,6 @@
# }
# ]
# }
#
##
{ 'command': 'query-chardev', 'returns': ['ChardevInfo'],
'allow-preconfig': true }
@ -106,7 +105,6 @@
# }
# ]
# }
#
##
{ 'command': 'query-chardev-backends', 'returns': ['ChardevBackendInfo'] }
@ -135,11 +133,11 @@
#
# @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
# - data itself is always Unicode regardless of format, like
# any other string.
# - base64: data must be base64 encoded text. Its binary decoding
# gets written.
# - utf8: data's UTF-8 encoding is written
# - data itself is always Unicode regardless of format, like any
# other string.
#
# Returns: Nothing on success
#
@ -152,7 +150,6 @@
# "data": "abcdefgh",
# "format": "utf8" } }
# <- { "return": {} }
#
##
{ 'command': 'ringbuf-write',
'data': { 'device': 'str',
@ -170,14 +167,13 @@
#
# @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
# sequences, NUL characters, after the ring buffer lost
# data, and when reading stops because the size limit is
# reached.
# - The return value is always Unicode regardless of format,
# like any other string.
# - 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
# sequences, NUL characters, after the ring buffer lost data,
# and when reading stops because the size limit is reached.
# - The return value is always Unicode regardless of format, like
# any other string.
#
# Returns: data read from the device
#
@ -190,7 +186,6 @@
# "size": 1000,
# "format": "utf8" } }
# <- { "return": "abcdefgh" }
#
##
{ 'command': 'ringbuf-read',
'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'},
@ -202,8 +197,9 @@
# Configuration shared across all chardev backends
#
# @logfile: The name of a logfile to save output
# @logappend: true to append instead of truncate
# (default to false to truncate)
#
# @logappend: true to append instead of truncate (default to false to
# truncate)
#
# Since: 2.6
##
@ -217,9 +213,11 @@
# Configuration info for file chardevs.
#
# @in: The name of the input file
#
# @out: The name of the output file
# @append: Open the file in append mode (default false to
# truncate) (Since 2.6)
#
# @append: Open the file in append mode (default false to truncate)
# (Since 2.6)
#
# Since: 1.4
##
@ -234,8 +232,8 @@
#
# Configuration info for device and pipe chardevs.
#
# @device: The name of the special file for the device,
# i.e. /dev/ttyS0 on Unix or COM1: on Windows
# @device: The name of the special file for the device, i.e.
# /dev/ttyS0 on Unix or COM1: on Windows
#
# Since: 1.4
##
@ -248,29 +246,36 @@
#
# Configuration info for (stream) socket chardevs.
#
# @addr: socket address to listen on (server=true)
# or connect to (server=false)
# @addr: socket address to listen on (server=true) or connect to
# (server=false)
#
# @tls-creds: the ID of the TLS credentials object (since 2.6)
#
# @tls-authz: the ID of the QAuthZ authorization object against which
# the client's x509 distinguished name will be validated. This
# object is only resolved at time of use, so can be deleted
# and recreated on the fly while the chardev server is active.
# If missing, it will default to denying access (since 4.0)
# the client's x509 distinguished name will be validated. This
# object is only resolved at time of use, so can be deleted and
# recreated on the fly while the chardev server is active. If
# missing, it will default to denying access (since 4.0)
#
# @server: create server socket (default: true)
# @wait: wait for incoming connection on server
# sockets (default: false).
# Silently ignored with server: false. This use is deprecated.
#
# @wait: wait for incoming connection on server sockets (default:
# false). Silently ignored with server: false. This use is
# deprecated.
#
# @nodelay: set TCP_NODELAY socket option (default: false)
# @telnet: enable telnet protocol on server
# sockets (default: false)
# @tn3270: enable tn3270 protocol on server
# sockets (default: false) (Since: 2.10)
# @websocket: enable websocket protocol on server
# 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)
#
# @telnet: enable telnet protocol on server sockets (default: false)
#
# @tn3270: enable tn3270 protocol on server sockets (default: false)
# (Since: 2.10)
#
# @websocket: enable websocket protocol on server 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)
#
# Since: 1.4
##
@ -293,6 +298,7 @@
# Configuration info for datagram socket chardevs.
#
# @remote: remote address
#
# @local: local address
#
# Since: 1.5
@ -320,8 +326,8 @@
#
# Configuration info for stdio chardevs.
#
# @signal: Allow signals (such as SIGINT triggered by ^C)
# be delivered to qemu. Default: true.
# @signal: Allow signals (such as SIGINT triggered by ^C) be delivered
# to qemu. Default: true.
#
# Since: 1.5
##
@ -377,8 +383,11 @@
# Configuration info for virtual console chardevs.
#
# @width: console width, in pixels
#
# @height: console height, in pixels
#
# @cols: console width, in chars
#
# @rows: console height, in chars
#
# Since: 1.5
@ -409,6 +418,7 @@
# Configuration info for qemu vdagent implementation.
#
# @mouse: enable/disable mouse, default is enabled.
#
# @clipboard: enable/disable clipboard, default is disabled.
#
# Since: 6.1
@ -423,20 +433,35 @@
# @ChardevBackendKind:
#
# @pipe: Since 1.5
#
# @udp: Since 1.5
#
# @mux: Since 1.5
#
# @msmouse: Since 1.5
#
# @wctablet: Since 2.9
#
# @braille: Since 1.5
#
# @testdev: Since 2.2
#
# @stdio: Since 1.5
#
# @console: Since 1.5
#
# @spicevmc: Since 1.5
#
# @spiceport: Since 1.5
#
# @qemu-vdagent: Since 6.1
#
# @dbus: Since 7.0
#
# @vc: v1.5
#
# @ringbuf: Since 1.6
#
# @memory: Since 1.5
#
# Since: 1.4
@ -617,8 +642,8 @@
#
# Return info about the chardev backend just created.
#
# @pty: name of the slave pseudoterminal device, present if
# and only if a chardev of type 'pty' was created
# @pty: name of the slave pseudoterminal device, present if and only
# if a chardev of type 'pty' was created
#
# Since: 1.4
##
@ -631,6 +656,7 @@
# Add a character device backend
#
# @id: the chardev's ID, must be unique
#
# @backend: backend type and parameters
#
# Returns: ChardevReturn.
@ -654,7 +680,6 @@
# "arguments" : { "id" : "baz",
# "backend" : { "type" : "pty", "data" : {} } } }
# <- { "return": { "pty" : "/dev/pty/42" } }
#
##
{ 'command': 'chardev-add',
'data': { 'id': 'str',
@ -667,6 +692,7 @@
# Change a character device backend
#
# @id: the chardev's ID, must exist
#
# @backend: new backend type and parameters
#
# Returns: ChardevReturn.
@ -695,7 +721,6 @@
# "server" : true,
# "wait" : false }}}}
# <- {"return": {}}
#
##
{ 'command': 'chardev-change',
'data': { 'id': 'str',
@ -717,7 +742,6 @@
#
# -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
# <- { "return": {} }
#
##
{ 'command': 'chardev-remove',
'data': { 'id': 'str' } }
@ -737,7 +761,6 @@
#
# -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
# <- { "return": {} }
#
##
{ 'command': 'chardev-send-break',
'data': { 'id': 'str' } }
@ -760,7 +783,6 @@
# <- { "event": "VSERPORT_CHANGE",
# "data": { "id": "channel0", "open": true },
# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
#
##
{ 'event': 'VSERPORT_CHANGE',
'data': { 'id': 'str',

19
qapi/common.json
View File

@ -70,6 +70,7 @@
# has a different meaning.
#
# @s: the string value
#
# @n: no string value
#
# Since: 2.10
@ -155,11 +156,11 @@
#
# @preferred: set the preferred host nodes for allocation
#
# @bind: a strict policy that restricts memory allocation to the
# host nodes specified
# @bind: a strict policy that restricts memory allocation to the host
# nodes specified
#
# @interleave: memory allocations are interleaved across the set
# of host nodes specified
# @interleave: memory allocations are interleaved across the set of
# host nodes specified
#
# Since: 2.1
##
@ -169,17 +170,17 @@
##
# @NetFilterDirection:
#
# Indicates whether a netfilter is attached to a netdev's transmit queue or
# receive queue or both.
# Indicates whether a netfilter is attached to a netdev's transmit
# queue or receive queue or both.
#
# @all: the filter is attached both to the receive and the transmit
# queue of the netdev (default).
# queue of the netdev (default).
#
# @rx: the filter is attached to the receive queue of the netdev,
# where it will receive packets sent to the netdev.
# where it will receive packets sent to the netdev.
#
# @tx: the filter is attached to the transmit queue of the netdev,
# where it will receive packets sent by the netdev.
# where it will receive packets sent by the netdev.
#
# Since: 2.5
##

13
qapi/compat.json
View File

@ -11,7 +11,9 @@
# Policy for handling "funny" input.
#
# @accept: Accept silently
#
# @reject: Reject with an error
#
# @crash: abort() the process
#
# Since: 6.0
@ -25,6 +27,7 @@
# Policy for handling "funny" output.
#
# @accept: Pass on unchanged
#
# @hide: Filter out
#
# Since: 6.0
@ -47,11 +50,15 @@
# enumeration values. They behave the same as with policy @accept.
#
# @deprecated-input: how to handle deprecated input (default 'accept')
# @deprecated-output: how to handle deprecated output (default 'accept')
#
# @deprecated-output: how to handle deprecated output (default
# 'accept')
#
# @unstable-input: how to handle unstable input (default 'accept')
# (since 6.2)
# (since 6.2)
#
# @unstable-output: how to handle unstable output (default 'accept')
# (since 6.2)
# (since 6.2)
#
# Since: 6.0
##

59
qapi/control.json
View File

@ -14,10 +14,9 @@
# 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)
# 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:
#
@ -25,12 +24,14 @@
# "arguments": { "enable": [ "oob" ] } }
# <- { "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)
# 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)
#
# 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
##
@ -44,8 +45,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
##
@ -73,16 +74,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
##
@ -94,7 +95,8 @@
#
# 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
#
@ -111,7 +113,6 @@
# "package":""
# }
# }
#
##
{ 'command': 'query-version', 'returns': 'VersionInfo',
'allow-preconfig': true }
@ -150,8 +151,8 @@
# ]
# }
#
# Note: This example has been shortened as the real response is too long.
#
# Note: This example has been shortened as the real response is too
# long.
##
{ 'command': 'query-commands', 'returns': ['CommandInfo'],
'allow-preconfig': true }
@ -159,10 +160,10 @@
##
# @quit:
#
# This command will cause the QEMU process to exit gracefully. While every
# attempt is made to send the QMP response before terminating, this is not
# guaranteed. When using this interface, a premature EOF would not be
# unexpected.
# This command will cause the QEMU process to exit gracefully. While
# every attempt is made to send the QMP response before terminating,
# this is not guaranteed. When using this interface, a premature EOF
# would not be unexpected.
#
# Since: 0.14
#
@ -195,7 +196,7 @@
# @id: Name of the monitor
#
# @mode: Selects the monitor mode (default: readline in the system
# emulator, control in qemu-storage-daemon)
# emulator, control in qemu-storage-daemon)
#
# @pretty: Enables pretty printing (QMP only)
#

261
qapi/crypto.json
View File

@ -11,8 +11,7 @@
#
# The type of network endpoint that will be using the credentials.
# Most types of credential require different setup / structures
# depending on whether they will be used in a server versus a
# client.
# depending on whether they will be used in a server versus a client.
#
# @client: the network endpoint is acting as the client
#
@ -29,7 +28,9 @@
#
# The data format that the secret is provided in
#
# @raw: raw bytes. When encoded in JSON only valid UTF-8 sequences can be used
# @raw: raw bytes. When encoded in JSON only valid UTF-8 sequences
# can be used
#
# @base64: arbitrary base64 encoded binary data
#
# Since: 2.6
@ -44,11 +45,17 @@
# The supported algorithms for computing content digests
#
# @md5: MD5. Should not be used in any new code, legacy compat only
#
# @sha1: SHA-1. Should not be used in any new code, legacy compat only
#
# @sha224: SHA-224. (since 2.7)
#
# @sha256: SHA-256. Current recommended strong hash.
#
# @sha384: SHA-384. (since 2.7)
#
# @sha512: SHA-512. (since 2.7)
#
# @ripemd160: RIPEMD-160. (since 2.7)
#
# Since: 2.6
@ -63,16 +70,28 @@
# The supported algorithms for content encryption ciphers
#
# @aes-128: AES with 128 bit / 16 byte keys
#
# @aes-192: AES with 192 bit / 24 byte keys
#
# @aes-256: AES with 256 bit / 32 byte keys
# @des: DES with 56 bit / 8 byte keys. Do not use except in VNC. (since 6.1)
#
# @des: DES with 56 bit / 8 byte keys. Do not use except in VNC.
# (since 6.1)
#
# @3des: 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
#
# @cast5-128: Cast5 with 128 bit / 16 byte keys
#
# @serpent-128: Serpent with 128 bit / 16 byte keys
#
# @serpent-192: Serpent with 192 bit / 24 byte keys
#
# @serpent-256: Serpent with 256 bit / 32 byte keys
#
# @twofish-128: Twofish with 128 bit / 16 byte keys
#
# @twofish-192: Twofish with 192 bit / 24 byte keys
#
# @twofish-256: Twofish with 256 bit / 32 byte keys
#
# Since: 2.6
@ -91,8 +110,11 @@
# The supported modes for content encryption ciphers
#
# @ecb: Electronic Code Book
#
# @cbc: Cipher Block Chaining
#
# @xts: XEX with tweaked code book and ciphertext stealing
#
# @ctr: Counter (Since 2.8)
#
# Since: 2.6
@ -104,15 +126,17 @@
##
# @QCryptoIVGenAlgorithm:
#
# The supported algorithms for generating initialization
# vectors for full disk encryption. The 'plain' generator
# should not be used for disks with sector numbers larger
# than 2^32, except where compatibility with pre-existing
# Linux dm-crypt volumes is required.
# The supported algorithms for generating initialization vectors for
# full disk encryption. The 'plain' generator should not be used for
# disks with sector numbers larger than 2^32, except where
# compatibility with pre-existing Linux dm-crypt volumes is required.
#
# @plain: 64-bit sector number truncated to 32-bits
#
# @plain64: 64-bit sector number
# @essiv: 64-bit sector number encrypted with a hash of the encryption key
#
# @essiv: 64-bit sector number encrypted with a hash of the encryption
# key
#
# Since: 2.6
##
@ -125,9 +149,10 @@
#
# The supported full disk encryption formats
#
# @qcow: QCow/QCow2 built-in AES-CBC encryption. Use only
# for liberating data from old images.
# @luks: LUKS encryption format. Recommended for new images
# @qcow: QCow/QCow2 built-in AES-CBC encryption. Use only for
# liberating data from old images.
#
# @luks: LUKS encryption format. Recommended for new images
#
# Since: 2.6
##
@ -138,8 +163,7 @@
##
# @QCryptoBlockOptionsBase:
#
# The common options that apply to all full disk
# encryption formats
# The common options that apply to all full disk encryption formats
#
# @format: the encryption format
#
@ -154,8 +178,8 @@
# The options that apply to QCow/QCow2 AES-CBC encryption format
#
# @key-secret: the ID of a QCryptoSecret object providing the
# decryption key. Mandatory except when probing image for
# metadata only.
# decryption key. Mandatory except when probing image for
# metadata only.
#
# Since: 2.6
##
@ -168,8 +192,8 @@
# The options that apply to LUKS encryption format
#
# @key-secret: the ID of a QCryptoSecret object providing the
# decryption key. Mandatory except when probing image for
# metadata only.
# decryption key. Mandatory except when probing image for
# metadata only.
#
# Since: 2.6
##
@ -181,19 +205,23 @@
#
# The options that apply to LUKS encryption format initialization
#
# @cipher-alg: the cipher algorithm for data encryption
# Currently defaults to 'aes-256'.
# @cipher-mode: the cipher mode for data encryption
# Currently defaults to 'xts'
# @ivgen-alg: the initialization vector generator
# Currently defaults to 'plain64'
# @ivgen-hash-alg: the initialization vector generator hash
# Currently defaults to 'sha256'
# @hash-alg: the master key hash algorithm
# Currently defaults to 'sha256'
# @iter-time: number of milliseconds to spend in
# PBKDF passphrase processing. Currently defaults
# to 2000. (since 2.8)
# @cipher-alg: the cipher algorithm for data encryption Currently
# defaults to 'aes-256'.
#
# @cipher-mode: the cipher mode for data encryption Currently defaults
# to 'xts'
#
# @ivgen-alg: the initialization vector generator Currently defaults
# to 'plain64'
#
# @ivgen-hash-alg: the initialization vector generator hash Currently
# defaults to 'sha256'
#
# @hash-alg: the master key hash algorithm Currently defaults to
# 'sha256'
#
# @iter-time: number of milliseconds to spend in PBKDF passphrase
# processing. Currently defaults to 2000. (since 2.8)
#
# Since: 2.6
##
@ -209,8 +237,8 @@
##
# @QCryptoBlockOpenOptions:
#
# The options that are available for all encryption formats
# when opening an existing volume
# The options that are available for all encryption formats when
# opening an existing volume
#
# Since: 2.6
##
@ -223,8 +251,8 @@
##
# @QCryptoBlockCreateOptions:
#
# The options that are available for all encryption formats
# when initializing a new volume
# The options that are available for all encryption formats when
# initializing a new volume
#
# Since: 2.6
##
@ -237,8 +265,8 @@
##
# @QCryptoBlockInfoBase:
#
# The common information that applies to all full disk
# encryption formats
# The common information that applies to all full disk encryption
# formats
#
# @format: the encryption format
#
@ -250,12 +278,14 @@
##
# @QCryptoBlockInfoLUKSSlot:
#
# Information about the LUKS block encryption key
# slot options
# Information about the LUKS block encryption key slot options
#
# @active: whether the key slot is currently in use
#
# @key-offset: offset to the key material in bytes
#
# @iters: number of PBKDF2 iterations for key material
#
# @stripes: number of stripes for splitting key material
#
# Since: 2.7
@ -272,13 +302,21 @@
# Information about the LUKS block encryption options
#
# @cipher-alg: the cipher algorithm for data encryption
#
# @cipher-mode: the cipher mode for data encryption
#
# @ivgen-alg: the initialization vector generator
#
# @ivgen-hash-alg: the initialization vector generator hash
#
# @hash-alg: the master key hash algorithm
#
# @payload-offset: offset to the payload data in bytes
#
# @master-key-iters: number of PBKDF2 iterations for key material
#
# @uuid: unique identifier for the volume
#
# @slots: information about each key slot
#
# Since: 2.7
@ -312,7 +350,9 @@
# Defines state of keyslots that are affected by the update
#
# @active: The slots contain the given password and marked as active
# @inactive: The slots are erased (contain garbage) and marked as inactive
#
# @inactive: The slots are erased (contain garbage) and marked as
# inactive
#
# Since: 5.1
##
@ -322,35 +362,34 @@
##
# @QCryptoBlockAmendOptionsLUKS:
#
# This struct defines the update parameters that activate/de-activate set
# of keyslots
# This struct defines the update parameters that activate/de-activate
# set of keyslots
#
# @state: the desired state of the keyslots
#
# @new-secret: The ID of a QCryptoSecret object providing the password to be
# written into added active keyslots
# @new-secret: The ID of a QCryptoSecret object providing the password
# to be written into added active keyslots
#
# @old-secret: Optional (for deactivation only)
# If given will deactivate all keyslots that
# match password located in QCryptoSecret with this ID
# @old-secret: Optional (for deactivation only) If given will
# deactivate all keyslots that match password located in
# QCryptoSecret with this ID
#
# @iter-time: Optional (for activation only)
# Number of milliseconds to spend in
# PBKDF passphrase processing for the newly activated keyslot.
# Currently defaults to 2000.
# @iter-time: Optional (for activation only) Number of milliseconds to
# spend in PBKDF passphrase processing for the newly activated
# keyslot. Currently defaults to 2000.
#
# @keyslot: Optional. ID of the keyslot to activate/deactivate.
# For keyslot activation, keyslot should not be active already
# (this is unsafe to update an active keyslot),
# but possible if 'force' parameter is given.
# If keyslot is not given, first free keyslot will be written.
# @keyslot: Optional. ID of the keyslot to activate/deactivate. For
# keyslot activation, keyslot should not be active already (this
# is unsafe to update an active keyslot), but possible if 'force'
# parameter is given. If keyslot is not given, first free keyslot
# will be written.
#
# For keyslot deactivation, this parameter specifies the exact
# keyslot to deactivate
# For keyslot deactivation, this parameter specifies the exact
# keyslot to deactivate
#
# @secret: Optional. The ID of a QCryptoSecret object providing the
# password to use to retrieve current master key.
# Defaults to the same secret that was used to open the image
# @secret: Optional. The ID of a QCryptoSecret object providing the
# password to use to retrieve current master key. Defaults to the
# same secret that was used to open the image
#
# Since: 5.1
##
@ -365,8 +404,8 @@
##
# @QCryptoBlockAmendOptions:
#
# The options that are available for all encryption formats
# when amending encryption settings
# The options that are available for all encryption formats when
# amending encryption settings
#
# Since: 5.1
##
@ -381,22 +420,27 @@
#
# Properties for objects of classes derived from secret-common.
#
# @loaded: if true, the secret is loaded immediately when applying this option
# and will probably fail when processing the next option. Don't use;
# only provided for compatibility. (default: false)
# @loaded: if true, the secret is loaded immediately when applying
# this option and will probably fail when processing the next
# option. Don't use; only provided for compatibility.
# (default: false)
#
# @format: the data format that the secret is provided in (default: raw)
# @format: the data format that the secret is provided in
# (default: raw)
#
# @keyid: the name of another secret that should be used to decrypt the
# provided data. If not present, the data is assumed to be unencrypted.
# @keyid: the name of another secret that should be used to decrypt
# the provided data. If not present, the data is assumed to be
# unencrypted.
#
# @iv: the random initialization vector used for encryption of this particular
# secret. Should be a base64 encrypted string of the 16-byte IV. Mandatory
# if @keyid is given. Ignored if @keyid is absent.
# @iv: the random initialization vector used for encryption of this
# particular secret. Should be a base64 encrypted string of the
# 16-byte IV. Mandatory if @keyid is given. Ignored if @keyid is
# absent.
#
# Features:
# @deprecated: Member @loaded is deprecated. Setting true doesn't make sense,
# and false is already the default.
#
# @deprecated: Member @loaded is deprecated. Setting true doesn't
# make sense, and false is already the default.
#
# Since: 2.6
##
@ -443,16 +487,17 @@
# Properties for objects of classes derived from tls-creds.
#
# @verify-peer: if true the peer credentials will be verified once the
# handshake is completed. This is a no-op for anonymous
# credentials. (default: true)
# handshake is completed. This is a no-op for anonymous
# credentials. (default: true)
#
# @dir: the path of the directory that contains the credential files
#
# @endpoint: whether the QEMU network backend that uses the credentials will be
# acting as a client or as a server (default: client)
# @endpoint: whether the QEMU network backend that uses the
# credentials will be acting as a client or as a server
# (default: client)
#
# @priority: a gnutls priority string as described at
# https://gnutls.org/manual/html_node/Priority-Strings.html
# https://gnutls.org/manual/html_node/Priority-Strings.html
#
# Since: 2.5
##
@ -467,13 +512,15 @@
#
# Properties for tls-creds-anon objects.
#
# @loaded: if true, the credentials are loaded immediately when applying this
# option and will ignore options that are processed later. Don't use;
# only provided for compatibility. (default: false)
# @loaded: if true, the credentials are loaded immediately when
# applying this option and will ignore options that are processed
# later. Don't use; only provided for compatibility.
# (default: false)
#
# Features:
# @deprecated: Member @loaded is deprecated. Setting true doesn't make sense,
# and false is already the default.
#
# @deprecated: Member @loaded is deprecated. Setting true doesn't
# make sense, and false is already the default.
#
# Since: 2.5
##
@ -486,17 +533,19 @@
#
# Properties for tls-creds-psk objects.
#
# @loaded: if true, the credentials are loaded immediately when applying this
# option and will ignore options that are processed later. Don't use;
# only provided for compatibility. (default: false)
# @loaded: if true, the credentials are loaded immediately when
# applying this option and will ignore options that are processed
# later. Don't use; only provided for compatibility.
# (default: false)
#
# @username: the username which will be sent to the server. For clients only.
# If absent, "qemu" is sent and the property will read back as an
# empty string.
# @username: the username which will be sent to the server. For
# clients only. If absent, "qemu" is sent and the property will
# read back as an empty string.
#
# Features:
# @deprecated: Member @loaded is deprecated. Setting true doesn't make sense,
# and false is already the default.
#
# @deprecated: Member @loaded is deprecated. Setting true doesn't
# make sense, and false is already the default.
#
# Since: 3.0
##
@ -510,22 +559,24 @@
#
# Properties for tls-creds-x509 objects.
#
# @loaded: if true, the credentials are loaded immediately when applying this
# option and will ignore options that are processed later. Don't use;
# only provided for compatibility. (default: false)
# @loaded: if true, the credentials are loaded immediately when
# applying this option and will ignore options that are processed
# later. Don't use; only provided for compatibility.
# (default: false)
#
# @sanity-check: if true, perform some sanity checks before using the
# credentials (default: true)
# credentials (default: true)
#
# @passwordid: For the server-key.pem and client-key.pem files which contain
# sensitive private keys, it is possible to use an encrypted
# version by providing the @passwordid parameter. This provides
# the ID of a previously created secret object containing the
# password for decryption.
# @passwordid: For the server-key.pem and client-key.pem files which
# contain sensitive private keys, it is possible to use an
# encrypted version by providing the @passwordid parameter. This
# provides the ID of a previously created secret object containing
# the password for decryption.
#
# Features:
# @deprecated: Member @loaded is deprecated. Setting true doesn't make sense,
# and false is already the default.
#
# @deprecated: Member @loaded is deprecated. Setting true doesn't
# make sense, and false is already the default.
#
# Since: 2.5
##
@ -564,6 +615,7 @@
# The padding algorithm for RSA.
#
# @raw: no padding used
#
# @pkcs1: pkcs1#v1.5
#
# Since: 7.1
@ -578,6 +630,7 @@
# Specific parameters for RSA algorithm.
#
# @hash-alg: QCryptoHashAlgorithm
#
# @padding-alg: QCryptoRSAPaddingAlgorithm
#
# Since: 7.1

3
qapi/cryptodev.json
View File

@ -14,6 +14,7 @@
# The supported algorithm types of a crypto device.
#
# @sym: symmetric encryption
#
# @asym: asymmetric Encryption
#
# Since: 8.0
@ -39,7 +40,9 @@
# The crypto device backend type
#
# @builtin: the QEMU builtin support
#
# @vhost-user: vhost-user
#
# @lkcf: Linux kernel cryptographic framework
#
# Since: 8.0

74
qapi/cxl.json
View File

@ -8,26 +8,45 @@
##
# @CxlUncorErrorType:
#
# Type of uncorrectable CXL error to inject. These errors are reported via
# an AER uncorrectable internal error with additional information logged at
# the CXL device.
# Type of uncorrectable CXL error to inject. These errors are
# reported via an AER uncorrectable internal error with additional
# information logged at the CXL device.
#
# @cache-data-parity: Data error such as data parity or data ECC error
# CXL.cache
#
# @cache-address-parity: Address parity or other errors associated
# with the address field on CXL.cache
#
# @cache-be-parity: Byte enable parity or other byte enable errors on
# CXL.cache
#
# @cache-data-parity: Data error such as data parity or data ECC error CXL.cache
# @cache-address-parity: Address parity or other errors associated with the
# address field on CXL.cache
# @cache-be-parity: Byte enable parity or other byte enable errors on CXL.cache
# @cache-data-ecc: ECC error on CXL.cache
# @mem-data-parity: Data error such as data parity or data ECC error on CXL.mem
# @mem-address-parity: Address parity or other errors associated with the
# address field on CXL.mem
# @mem-be-parity: Byte enable parity or other byte enable errors on CXL.mem.
#
# @mem-data-parity: Data error such as data parity or data ECC error
# on CXL.mem
#
# @mem-address-parity: Address parity or other errors associated with
# the address field on CXL.mem
#
# @mem-be-parity: Byte enable parity or other byte enable errors on
# CXL.mem.
#
# @mem-data-ecc: Data ECC error on CXL.mem.
#
# @reinit-threshold: REINIT threshold hit.
#
# @rsvd-encoding: Received unrecognized encoding.
#
# @poison-received: Received poison from the peer.
# @receiver-overflow: Buffer overflows (first 3 bits of header log indicate which)
#
# @receiver-overflow: Buffer overflows (first 3 bits of header log
# indicate which)
#
# @internal: Component specific error
#
# @cxl-ide-tx: Integrity and data encryption tx error.
#
# @cxl-ide-rx: Integrity and data encryption rx error.
#
# Since: 8.0
@ -58,6 +77,7 @@
# Record of a single error including header log.
#
# @type: Type of error
#
# @header: 16 DWORD of header.
#
# Since: 8.0
@ -72,10 +92,11 @@
##
# @cxl-inject-uncorrectable-errors:
#
# Command to allow injection of multiple errors in one go. This allows testing
# of multiple header log handling in the OS.
# Command to allow injection of multiple errors in one go. This
# allows testing of multiple header log handling in the OS.
#
# @path: CXL Type 3 device canonical QOM path
#
# @errors: Errors to inject
#
# Since: 8.0
@ -90,10 +111,16 @@
# Type of CXL correctable error to inject
#
# @cache-data-ecc: Data ECC error on CXL.cache
#
# @mem-data-ecc: Data ECC error on CXL.mem
# @crc-threshold: Component specific and applicable to 68 byte Flit mode only.
#
# @crc-threshold: Component specific and applicable to 68 byte Flit
# mode only.
#
# @cache-poison-received: Received poison from a peer on CXL.cache.
#
# @mem-poison-received: Received poison from a peer on CXL.mem
#
# @physical: Received error indication from the physical layer.
#
# Since: 8.0
@ -111,18 +138,17 @@
##
# @cxl-inject-correctable-error:
#
# Command to inject a single correctable error. Multiple error injection
# of this error type is not interesting as there is no associated header log.
# These errors are reported via AER as a correctable internal error, with
# additional detail available from the CXL device.
# Command to inject a single correctable error. Multiple error
# injection of this error type is not interesting as there is no
# associated header log. These errors are reported via AER as a
# correctable internal error, with additional detail available from
# the CXL device.
#
# @path: CXL Type 3 device canonical QOM path
#
# @type: Type of error.
#
# Since: 8.0
##
{ 'command': 'cxl-inject-correctable-error',
'data': { 'path': 'str',
'type': 'CxlCorErrorType'
}
}
{'command': 'cxl-inject-correctable-error',
'data': {'path': 'str', 'type': 'CxlCorErrorType'}}

78
qapi/dump.json
View File

@ -21,8 +21,8 @@
#
# @kdump-snappy: kdump-compressed format with snappy-compressed
#
# @win-dmp: Windows full crashdump format,
# can be used instead of ELF converting (since 2.13)
# @win-dmp: Windows full crashdump format, can be used instead of ELF
# converting (since 2.13)
#
# Since: 2.0
##
@ -32,47 +32,47 @@
##
# @dump-guest-memory:
#
# Dump guest's memory to vmcore. It is a synchronous operation that can take
# very long depending on the amount of guest memory.
# Dump guest's memory to vmcore. It is a synchronous operation that
# can take very long depending on the amount of guest memory.
#
# @paging: if true, do paging to get guest's memory mapping. This allows
# using gdb to process the core file.
# @paging: if true, do paging to get guest's memory mapping. This
# allows 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.
# 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.
#
# Also, paging=true has the following limitations:
# Also, paging=true has the following limitations:
#
# 1. The guest may be in a catastrophic state or can have corrupted
# memory, which cannot be trusted
# 2. The guest can be in real-mode even if paging is enabled. For
# example, the guest uses ACPI to sleep, and ACPI sleep state
# goes in real-mode
# 3. Currently only supported on i386 and x86_64.
# 1. The guest may be in a catastrophic state or can have
# corrupted memory, which cannot be trusted
# 2. The guest can be in real-mode even if paging is enabled. For
# example, the guest uses ACPI to sleep, and ACPI sleep state
# goes in real-mode
# 3. Currently only supported on i386 and x86_64.
#
# @protocol: the filename or file descriptor of the vmcore. The supported
# protocols are:
# @protocol: the filename or file descriptor of the vmcore. The
# supported protocols are:
#
# 1. file: the protocol starts with "file:", and the following
# string is the file's path.
# 2. fd: the protocol starts with "fd:", and the following string
# is the fd's name.
# 1. file: the protocol starts with "file:", and the following
# string is the file's path.
# 2. fd: the protocol starts with "fd:", and the following string
# is the fd's name.
#
# @detach: if true, QMP will return immediately rather than
# waiting for the dump to finish. The user can track progress
# using "query-dump". (since 2.6).
# @detach: if true, QMP will return immediately rather than waiting
# for the dump to finish. The user can track progress using
# "query-dump". (since 2.6).
#
# @begin: if specified, the starting physical address.
#
# @length: if specified, the memory size, in bytes. If you don't
# want to dump all guest's memory, please specify the start @begin
# and @length
# @length: if specified, the memory size, in bytes. If you don't want
# to dump all guest's memory, please specify the start @begin and
# @length
#
# @format: if specified, the format of guest memory dump. But non-elf
# format is conflict with paging and filter, ie. @paging, @begin and
# @length is not allowed to be specified with non-elf @format at the
# same time (since 2.0)
# @format: if specified, the format of guest memory dump. But non-elf
# format is conflict with paging and filter, ie. @paging, @begin
# and @length is not allowed to be specified with non-elf @format
# at the same time (since 2.0)
#
# Note: All boolean arguments default to false
#
@ -85,7 +85,6 @@
# -> { "execute": "dump-guest-memory",
# "arguments": { "paging": false, "protocol": "fd:dump" } }
# <- { "return": {} }
#
##
{ 'command': 'dump-guest-memory',
'data': { 'paging': 'bool', 'protocol': 'str', '*detach': 'bool',
@ -142,7 +141,6 @@
# -> { "execute": "query-dump" }
# <- { "return": { "status": "active", "completed": 1024000,
# "total": 2048000 } }
#
##
{ 'command': 'query-dump', 'returns': 'DumpQueryResult' }
@ -153,9 +151,9 @@
#
# @result: final dump status
#
# @error: human-readable error string that provides
# hint on why dump failed. Only presents on failure. The
# user should not try to interpret the error string.
# @error: human-readable error string that provides hint on why dump
# failed. Only presents on failure. The user should not try to
# interpret the error string.
#
# Since: 2.6
#
@ -165,7 +163,6 @@
# "data": { "result": { "total": 1090650112, "status": "completed",
# "completed": 1090650112 } },
# "timestamp": { "seconds": 1648244171, "microseconds": 950316 } }
#
##
{ 'event': 'DUMP_COMPLETED' ,
'data': { 'result': 'DumpQueryResult', '*error': 'str' } }
@ -186,8 +183,8 @@
#
# Returns the available formats for dump-guest-memory
#
# Returns: A @DumpGuestMemoryCapability object listing available formats for
# dump-guest-memory
# Returns: A @DumpGuestMemoryCapability object listing available
# formats for dump-guest-memory
#
# Since: 2.0
#
@ -196,7 +193,6 @@
# -> { "execute": "query-dump-guest-memory-capability" }
# <- { "return": { "formats":
# ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } }
#
##
{ 'command': 'query-dump-guest-memory-capability',
'returns': 'DumpGuestMemoryCapability' }

6
qapi/error.json
View File

@ -10,8 +10,8 @@
#
# QEMU error classes
#
# @GenericError: this is used for errors that don't require a specific error
# class. This should be the default case for most errors
# @GenericError: this is used for errors that don't require a specific
# error class. This should be the default case for most errors
#
# @CommandNotFound: the requested command has not been found
#
@ -20,7 +20,7 @@
# @DeviceNotFound: the requested device has not been found
#
# @KVMMissingCap: the requested operation can't be fulfilled because a
# required KVM capability is missing
# required KVM capability is missing
#
# Since: 1.2
##

89
qapi/introspect.json
View File

@ -35,15 +35,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
##
@ -80,20 +80,18 @@
##
# @SchemaInfo:
#
# @name: the entity's name, inherited from @base.
# The SchemaInfo is always referenced by this name.
# Commands and events have the name defined in the QAPI schema.
# Unlike command and event names, type names are not part of
# the wire ABI. Consequently, type names are meaningless
# strings here, although they are still guaranteed unique
# regardless of @meta-type.
# @name: the entity's name, inherited from @base. The SchemaInfo is
# always referenced by this name. Commands and events have the
# name defined in the QAPI schema. Unlike command and event
# names, type names are not part of the wire ABI. Consequently,
# type names are meaningless strings here, although they are still
# guaranteed unique regardless of @meta-type.
#
# @meta-type: the entity's meta type, inherited from @base.
#
# @features: names of features associated with the entity, in no
# particular order.
# (since 4.1 for object types, 4.2 for commands, 5.0 for
# the rest)
# particular order. (since 4.1 for object types, 4.2 for
# commands, 5.0 for the rest)
#
# Additional members depend on the value of @meta-type.
#
@ -142,13 +140,15 @@
#
# Additional SchemaInfo members for meta-type 'enum'.
#
# @members: the enum type's members, in no particular order
# (since 6.2).
# @members: the enum type's members, in no particular order (since
# 6.2).
#
# @values: the enumeration type's member names, in no particular order.
# Redundant with @members. Just for backward compatibility.
# @values: the enumeration type's member names, in no particular
# order. Redundant with @members. Just for backward
# compatibility.
#
# Features:
#
# @deprecated: Member @values is deprecated. Use @members instead.
#
# Values of this type are JSON string on the wire.
@ -168,7 +168,7 @@
# @name: the member's name, as defined in the QAPI schema.
#
# @features: names of features associated with the member, in no
# particular order.
# particular order.
#
# Since: 6.2
##
@ -194,16 +194,16 @@
#
# Additional SchemaInfo members for meta-type 'object'.
#
# @members: the object type's (non-variant) members, in no particular order.
# @members: the object type's (non-variant) members, in no particular
# order.
#
# @tag: the name of the member serving as type tag.
# An element of @members with this name must exist.
# @tag: the name of the member serving as type tag. An element of
# @members with this name must exist.
#
# @variants: variant members, i.e. additional members that
# depend on the type tag's value. Present exactly when
# @tag is present. The variants are in no particular order,
# and may even differ from the order of the values of the
# enum type of the @tag.
# @variants: variant members, i.e. additional members that depend on
# the type tag's value. Present exactly when @tag is present.
# The variants are in no particular order, and may even differ
# from the order of the values of the enum type of the @tag.
#
# Values of this type are JSON object on the wire.
#
@ -223,16 +223,14 @@
#
# @type: the name of the member's type.
#
# @default: default when used as command parameter.
# If absent, the parameter is mandatory.
# If present, the value must be null. The parameter is
# optional, and behavior when it's missing is not specified
# here.
# Future extension: if present and non-null, the parameter
# is optional, and defaults to this value.
# @default: default when used as command parameter. If absent, the
# parameter is mandatory. If present, the value must be null.
# The parameter is optional, and behavior when it's missing is not
# specified here. Future extension: if present and non-null, the
# parameter is optional, and defaults to this value.
#
# @features: names of features associated with the member, in no
# particular order. (since 5.0)
# particular order. (since 5.0)
#
# Since: 2.5
##
@ -249,7 +247,7 @@
# @case: a value of the type tag.
#
# @type: the name of the object type that provides the variant members
# when the type tag has value @case.
# when the type tag has value @case.
#
# Since: 2.5
##
@ -261,9 +259,9 @@
#
# Additional SchemaInfo members for meta-type 'alternate'.
#
# @members: the alternate type's members, in no particular order.
# The members' wire encoding is distinct, see
# docs/devel/qapi-code-gen.txt section Alternate types.
# @members: the alternate type's members, in no particular order. The
# members' wire encoding is distinct, see
# docs/devel/qapi-code-gen.txt section Alternate types.
#
# On the wire, this can be any of the members.
#
@ -290,14 +288,15 @@
# Additional SchemaInfo members for meta-type 'command'.
#
# @arg-type: the name of the object type that provides the command's
# parameters.
# parameters.
#
# @ret-type: the name of the command's result type.
#
# @allow-oob: whether the command allows out-of-band execution,
# defaults to false (Since: 2.12)
# defaults to false (Since: 2.12)
#
# TODO: @success-response (currently irrelevant, because it's QGA, not QMP)
# TODO: @success-response (currently irrelevant, because it's QGA, not
# QMP)
#
# Since: 2.5
##
@ -311,7 +310,7 @@
# Additional SchemaInfo members for meta-type 'event'.
#
# @arg-type: the name of the object type that provides the event's
# parameters.
# parameters.
#
# Since: 2.5
##

139
qapi/job.json
View File

@ -20,13 +20,17 @@
#
# @create: image creation job type, see "blockdev-create" (since 3.0)
#
# @amend: image options amend job type, see "x-blockdev-amend" (since 5.1)
# @amend: image options amend job type, see "x-blockdev-amend" (since
# 5.1)
#
# @snapshot-load: snapshot load job type, see "snapshot-load" (since 6.0)
# @snapshot-load: snapshot load job type, see "snapshot-load" (since
# 6.0)
#
# @snapshot-save: snapshot save job type, see "snapshot-save" (since 6.0)
# @snapshot-save: snapshot save job type, see "snapshot-save" (since
# 6.0)
#
# @snapshot-delete: snapshot delete job type, see "snapshot-delete" (since 6.0)
# @snapshot-delete: snapshot delete job type, see "snapshot-delete"
# (since 6.0)
#
# Since: 1.7
##
@ -39,41 +43,42 @@
#
# Indicates the present state of a given job in its lifetime.
#
# @undefined: Erroneous, default state. Should not ever be visible.
# @undefined: Erroneous, default state. Should not ever be visible.
#
# @created: The job has been created, but not yet started.
#
# @running: The job is currently running.
#
# @paused: The job is running, but paused. The pause may be requested by
# either the QMP user or by internal processes.
# @paused: The job is running, but paused. The pause may be requested
# by either the QMP user or by internal processes.
#
# @ready: The job is running, but is ready for the user to signal completion.
# This is used for long-running jobs like mirror that are designed to
# run indefinitely.
# @ready: The job is running, but is ready for the user to signal
# completion. This is used for long-running jobs like mirror that
# are designed to run indefinitely.
#
# @standby: The job is ready, but paused. This is nearly identical to @paused.
# The job may return to @ready or otherwise be canceled.
# @standby: The job is ready, but paused. This is nearly identical to
# @paused. The job may return to @ready or otherwise be canceled.
#
# @waiting: The job is waiting for other jobs in the transaction to converge
# to the waiting state. This status will likely not be visible for
# the last job in a transaction.
# @waiting: The job is waiting for other jobs in the transaction to
# converge to the waiting state. This status will likely not be
# visible for the last job in a transaction.
#
# @pending: The job has finished its work, but has finalization steps that it
# needs to make prior to completing. These changes will require
# manual intervention via @job-finalize if auto-finalize was set to
# false. These pending changes may still fail.
# @pending: The job has finished its work, but has finalization steps
# that it needs to make prior to completing. These changes will
# require manual intervention via @job-finalize if auto-finalize
# was set to false. These pending changes may still fail.
#
# @aborting: The job is in the process of being aborted, and will finish with
# an error. The job will afterwards report that it is @concluded.
# This status may not be visible to the management process.
# @aborting: The job is in the process of being aborted, and will
# finish with an error. The job will afterwards report that it is
# @concluded. This status may not be visible to the management
# process.
#
# @concluded: The job has finished all work. If auto-dismiss was set to false,
# the job will remain in the query list until it is dismissed via
# @job-dismiss.
# @concluded: The job has finished all work. If auto-dismiss was set
# to false, the job will remain in the query list until it is
# dismissed via @job-dismiss.
#
# @null: The job is in the process of being dismantled. This state should not
# ever be visible externally.
# @null: The job is in the process of being dismantled. This state
# should not ever be visible externally.
#
# Since: 2.12
##
@ -112,6 +117,7 @@
# Emitted when a job transitions to a different status.
#
# @id: The job identifier
#
# @status: The new job status
#
# Since: 3.0
@ -125,12 +131,12 @@
#
# Pause an active job.
#
# This command returns immediately after marking the active job for pausing.
# Pausing an already paused job is an error.
# This command returns immediately after marking the active job for
# pausing. Pausing an already paused job is an error.
#
# The job will pause as soon as possible, which means transitioning into the
# PAUSED state if it was RUNNING, or into STANDBY if it was READY. The
# corresponding JOB_STATUS_CHANGE event will be emitted.
# The job will pause as soon as possible, which means transitioning
# into the PAUSED state if it was RUNNING, or into STANDBY if it was
# READY. The corresponding JOB_STATUS_CHANGE event will be emitted.
#
# Cancelling a paused job automatically resumes it.
#
@ -145,8 +151,8 @@
#
# Resume a paused job.
#
# This command returns immediately after resuming a paused job. Resuming an
# already running job is an error.
# This command returns immediately after resuming a paused job.
# Resuming an already running job is an error.
#
# @id: The job identifier.
#
@ -161,11 +167,11 @@
# This command returns immediately after marking the active job for
# cancellation.
#
# The job will cancel as soon as possible and then emit a JOB_STATUS_CHANGE
# event. Usually, the status will change to ABORTING, but it is possible that
# a job successfully completes (e.g. because it was almost done and there was
# no opportunity to cancel earlier than completing the job) and transitions to
# PENDING instead.
# The job will cancel as soon as possible and then emit a
# JOB_STATUS_CHANGE event. Usually, the status will change to
# ABORTING, but it is possible that a job successfully completes (e.g.
# because it was almost done and there was no opportunity to cancel
# earlier than completing the job) and transitions to PENDING instead.
#
# @id: The job identifier.
#
@ -187,12 +193,14 @@
##
# @job-dismiss:
#
# Deletes a job that is in the CONCLUDED state. This command only needs to be
# run explicitly for jobs that don't have automatic dismiss enabled.
# Deletes a job that is in the CONCLUDED state. This command only
# needs to be run explicitly for jobs that don't have automatic
# dismiss enabled.
#
# This command will refuse to operate on any job that has not yet reached its
# terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of JOB_READY
# event, job-cancel or job-complete will still need to be used as appropriate.
# This command will refuse to operate on any job that has not yet
# reached its terminal state, JOB_STATUS_CONCLUDED. For jobs that make
# use of JOB_READY event, job-cancel or job-complete will still need
# to be used as appropriate.
#
# @id: The job identifier.
#
@ -203,16 +211,17 @@
##
# @job-finalize:
#
# Instructs all jobs in a transaction (or a single job if it is not part of any
# transaction) to finalize any graph changes and do any necessary cleanup. This
# command requires that all involved jobs are in the PENDING state.
# Instructs all jobs in a transaction (or a single job if it is not
# part of any transaction) to finalize any graph changes and do any
# necessary cleanup. This command requires that all involved jobs are
# in the PENDING state.
#
# For jobs in a transaction, instructing one job to finalize will force
# ALL jobs in the transaction to finalize, so it is only necessary to instruct
# a single member job to finalize.
# For jobs in a transaction, instructing one job to finalize will
# force ALL jobs in the transaction to finalize, so it is only
# necessary to instruct a single member job to finalize.
#
# @id: The identifier of any job in the transaction, or of a job that is not
# part of any transaction.
# @id: The identifier of any job in the transaction, or of a job that
# is not part of any transaction.
#
# Since: 3.0
##
@ -229,22 +238,22 @@
#
# @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
##

303
qapi/machine-target.json
View File

@ -9,12 +9,13 @@
#
# Virtual CPU model.
#
# A CPU model consists of the name of a CPU definition, to which
# delta changes are applied (e.g. features added/removed). Most magic values
# A CPU model consists of the name of a CPU definition, to which delta
# changes are applied (e.g. features added/removed). Most magic values
# that an architecture might require should be hidden behind the name.
# However, if required, architectures can expose relevant properties.
#
# @name: the name of the CPU definition the model is based on
#
# @props: a dictionary of QOM properties to be applied
#
# Since: 2.8
@ -28,26 +29,28 @@
#
# An enumeration of CPU model expansion types.
#
# @static: Expand to a static CPU model, a combination of a static base
# model name and property delta changes. As the static base model will
# never change, the expanded CPU model will be the same, independent of
# QEMU version, machine type, machine options, and accelerator options.
# Therefore, the resulting model can be used by tooling without having
# to specify a compatibility machine - e.g. when displaying the "host"
# model. The @static CPU models are migration-safe.
# @full: Expand all properties. The produced model is not guaranteed to be
# migration-safe, but allows tooling to get an insight and work with
# model details.
# @static: Expand to a static CPU model, a combination of a static
# base model name and property delta changes. As the static base
# model will never change, the expanded CPU model will be the
# same, independent of QEMU version, machine type, machine
# options, and accelerator options. Therefore, the resulting
# model can be used by tooling without having to specify a
# compatibility machine - e.g. when displaying the "host" model.
# The @static CPU models are migration-safe.
#
# 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).
# @full: Expand all properties. The produced model is not guaranteed
# to be migration-safe, but allows tooling to get an insight and
# work with 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).
#
# Since: 2.8
##
@ -57,20 +60,22 @@
##
# @CpuModelCompareResult:
#
# An enumeration of CPU model comparison results. The result is usually
# calculated using e.g. CPU features or CPU generations.
# An enumeration of CPU model comparison results. The result is
# usually calculated using e.g. CPU features or CPU generations.
#
# @incompatible: If model A is incompatible to model B, model A is not
# guaranteed to run where model B runs and the other way around.
# guaranteed to run where model B runs and the other way around.
#
# @identical: If model A is identical to model B, model A is guaranteed to run
# where model B runs and the other way around.
# @identical: If model A is identical to model B, model A is
# guaranteed to run where model B runs and the other way around.
#
# @superset: If model A is a superset of model B, model B is guaranteed to run
# where model A runs. There are no guarantees about the other way.
# @superset: If model A is a superset of model B, model B is
# guaranteed to run where model A runs. There are no guarantees
# about the other way.
#
# @subset: If model A is a subset of model B, model A is guaranteed to run
# where model B runs. There are no guarantees about the other way.
# @subset: If model A is a subset of model B, model A is guaranteed to
# run where model B runs. There are no guarantees about the other
# way.
#
# Since: 2.8
##
@ -96,15 +101,16 @@
# The result of a CPU model comparison.
#
# @result: The result of the compare operation.
# @responsible-properties: List of properties that led to the comparison result
# not being identical.
#
# @responsible-properties: List of properties that led to the
# comparison result not being identical.
#
# @responsible-properties is a list of QOM property names that led to
# both CPUs not being detected as identical. For identical models, this
# list is empty.
# If a QOM property is read-only, that means there's no known way to make the
# CPU models identical. If the special property name "type" is included, the
# models are by definition not identical and cannot be made identical.
# both CPUs not being detected as identical. For identical models,
# this list is empty. If a QOM property is read-only, that means
# there's no known way to make the CPU models identical. If the
# special property name "type" is included, the models are by
# definition not identical and cannot be made identical.
#
# Since: 2.8
##
@ -117,38 +123,42 @@
# @query-cpu-model-comparison:
#
# Compares two CPU models, returning how they compare in a specific
# configuration. The results indicates how both models compare regarding
# runnability. This result can be used by tooling to make decisions if a
# certain CPU model will run in a certain configuration or if a compatible
# CPU model has to be created by baselining.
# configuration. The results indicates how both models compare
# regarding runnability. This result can be used by tooling to make
# decisions if a certain CPU model will run in a certain configuration
# or if a compatible CPU model has to be created by baselining.
#
# Usually, a CPU model is compared against the maximum possible CPU model
# of a certain configuration (e.g. the "host" model for KVM). If that CPU
# model is identical or a subset, it will run in that configuration.
# Usually, a CPU model is compared against the maximum possible CPU
# model of a certain configuration (e.g. the "host" model for KVM).
# If that CPU model is identical or a subset, it will run in that
# configuration.
#
# The result returned by this command may be affected by:
#
# * QEMU version: CPU models may look different depending on the QEMU version.
# (Except for CPU models reported as "static" in query-cpu-definitions.)
# * machine-type: CPU model may look different depending on the machine-type.
# (Except for CPU models reported as "static" in query-cpu-definitions.)
# * machine options (including accelerator): in some architectures, CPU models
# may look different depending on machine and accelerator options. (Except for
# CPU models reported as "static" in query-cpu-definitions.)
# * "-cpu" arguments and global properties: arguments to the -cpu option and
# global properties may affect expansion of CPU models. Using
# query-cpu-model-expansion while using these is not advised.
# * QEMU version: CPU models may look different depending on the QEMU
# version. (Except for CPU models reported as "static" in
# query-cpu-definitions.)
# * machine-type: CPU model may look different depending on the
# machine-type. (Except for CPU models reported as "static" in
# query-cpu-definitions.)
# * machine options (including accelerator): in some architectures,
# CPU models may look different depending on machine and accelerator
# options. (Except for CPU models reported as "static" in
# query-cpu-definitions.)
# * "-cpu" arguments and global properties: arguments to the -cpu
# option and global properties may affect expansion of CPU models.
# Using query-cpu-model-expansion while using these is not advised.
#
# Some architectures may not support comparing CPU models. s390x supports
# comparing CPU models.
# Some architectures may not support comparing CPU models. s390x
# supports comparing CPU models.
#
# Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU models is
# not supported, if a model cannot be used, if a model contains
# an unknown cpu definition name, unknown properties or properties
# with wrong types.
# Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU
# models is not supported, if a model cannot be used, if a model
# contains an unknown cpu definition name, unknown properties or
# properties 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
##
@ -160,38 +170,42 @@
##
# @query-cpu-model-baseline:
#
# Baseline two CPU models, creating a compatible third model. The created
# model will always be a static, migration-safe CPU model (see "static"
# CPU model expansion for details).
# Baseline two CPU models, creating a compatible third model. The
# created model will always be a static, migration-safe CPU model (see
# "static" CPU model expansion for details).
#
# This interface can be used by tooling to create a compatible CPU model out
# two CPU models. The created CPU model will be identical to or a subset of
# both CPU models when comparing them. Therefore, the created CPU model is
# guaranteed to run where the given CPU models run.
# This interface can be used by tooling to create a compatible CPU
# model out two CPU models. The created CPU model will be identical
# to or a subset of both CPU models when comparing them. Therefore,
# the created CPU model is guaranteed to run where the given CPU
# models run.
#
# The result returned by this command may be affected by:
#
# * QEMU version: CPU models may look different depending on the QEMU version.
# (Except for CPU models reported as "static" in query-cpu-definitions.)
# * machine-type: CPU model may look different depending on the machine-type.
# (Except for CPU models reported as "static" in query-cpu-definitions.)
# * machine options (including accelerator): in some architectures, CPU models
# may look different depending on machine and accelerator options. (Except for
# CPU models reported as "static" in query-cpu-definitions.)
# * "-cpu" arguments and global properties: arguments to the -cpu option and
# global properties may affect expansion of CPU models. Using
# query-cpu-model-expansion while using these is not advised.
# * QEMU version: CPU models may look different depending on the QEMU
# version. (Except for CPU models reported as "static" in
# query-cpu-definitions.)
# * machine-type: CPU model may look different depending on the
# machine-type. (Except for CPU models reported as "static" in
# query-cpu-definitions.)
# * machine options (including accelerator): in some architectures,
# CPU models may look different depending on machine and accelerator
# options. (Except for CPU models reported as "static" in
# query-cpu-definitions.)
# * "-cpu" arguments and global properties: arguments to the -cpu
# option and global properties may affect expansion of CPU models.
# Using query-cpu-model-expansion while using these is not advised.
#
# Some architectures may not support baselining CPU models. s390x supports
# baselining CPU models.
# Some architectures may not support baselining CPU models. s390x
# supports baselining CPU models.
#
# Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU models is
# not supported, if a model cannot be used, if a model contains
# an unknown cpu definition name, unknown properties or properties
# with wrong types.
# Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU
# models is not supported, if a model cannot be used, if a model
# contains an unknown cpu definition name, unknown properties or
# properties 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
##
@ -219,33 +233,37 @@
##
# @query-cpu-model-expansion:
#
# Expands a given CPU model (or a combination of CPU model + additional options)
# to different granularities, allowing tooling to get an understanding what a
# specific CPU model looks like in QEMU under a certain configuration.
# Expands a given CPU model (or a combination of CPU model +
# additional options) to different granularities, allowing tooling to
# get an understanding what a specific CPU model looks like in QEMU
# under a certain configuration.
#
# This interface can be used to query the "host" CPU model.
#
# The data returned by this command may be affected by:
#
# * QEMU version: CPU models may look different depending on the QEMU version.
# (Except for CPU models reported as "static" in query-cpu-definitions.)
# * machine-type: CPU model may look different depending on the machine-type.
# (Except for CPU models reported as "static" in query-cpu-definitions.)
# * machine options (including accelerator): in some architectures, CPU models
# may look different depending on machine and accelerator options. (Except for
# CPU models reported as "static" in query-cpu-definitions.)
# * "-cpu" arguments and global properties: arguments to the -cpu option and
# global properties may affect expansion of CPU models. Using
# query-cpu-model-expansion while using these is not advised.
# * QEMU version: CPU models may look different depending on the QEMU
# version. (Except for CPU models reported as "static" in
# query-cpu-definitions.)
# * machine-type: CPU model may look different depending on the
# machine-type. (Except for CPU models reported as "static" in
# query-cpu-definitions.)
# * machine options (including accelerator): in some architectures,
# CPU models may look different depending on machine and accelerator
# options. (Except for CPU models reported as "static" in
# query-cpu-definitions.)
# * "-cpu" arguments and global properties: arguments to the -cpu
# option and global properties may affect expansion of CPU models.
# Using query-cpu-model-expansion while using these is not advised.
#
# Some architectures may not support all expansion types. s390x supports
# "full" and "static". Arm only supports "full".
# Some architectures may not support all expansion types. s390x
# supports "full" and "static". Arm only supports "full".
#
# Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU models is
# not supported, if the model cannot be expanded, if the model contains
# an unknown CPU definition name, unknown properties or properties
# with a wrong type. Also returns an error if an expansion type is
# not supported.
# Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU
# models is not supported, if the model cannot be expanded, if the
# model contains an unknown CPU definition name, unknown
# properties or properties with a wrong type. Also returns an
# error if an expansion type is not supported.
#
# Since: 2.8
##
@ -265,49 +283,48 @@
# @name: the name of the CPU definition
#
# @migration-safe: whether a CPU definition can be safely used for
# migration in combination with a QEMU compatibility machine
# when migrating between different QEMU versions and between
# hosts with different sets of (hardware or software)
# capabilities. If not provided, information is not available
# and callers should not assume the CPU definition to be
# migration-safe. (since 2.8)
# migration in combination with a QEMU compatibility machine when
# migrating between different QEMU versions and between hosts with
# different sets of (hardware or software) capabilities. If not
# provided, information is not available and callers should not
# assume the CPU definition to be migration-safe. (since 2.8)
#
# @static: whether a CPU definition is static and will not change depending on
# QEMU version, machine type, machine options and accelerator options.
# A static model is always migration-safe. (since 2.8)
# @static: whether a CPU definition is static and will not change
# depending on QEMU version, machine type, machine options and
# accelerator options. A static model is always migration-safe.
# (since 2.8)
#
# @unavailable-features: List of properties that prevent
# the CPU model from running in the current
# host. (since 2.8)
# @typename: Type name that can be used as argument to @device-list-properties,
# to introspect properties configurable using -cpu or -global.
# (since 2.9)
# @unavailable-features: List of properties that prevent the CPU model
# from running in the current host. (since 2.8)
#
# @alias-of: Name of CPU model this model is an alias for. The target of the
# CPU model alias may change depending on the machine type.
# Management software is supposed to translate CPU model aliases
# in the VM configuration, because aliases may stop being
# migration-safe in the future (since 4.1)
# @typename: Type name that can be used as argument to
# @device-list-properties, to introspect properties configurable
# using -cpu or -global. (since 2.9)
#
# @deprecated: If true, this CPU model is deprecated and may be removed in
# in some future version of QEMU according to the QEMU deprecation
# policy. (since 5.2)
# @alias-of: Name of CPU model this model is an alias for. The target
# of the CPU model alias may change depending on the machine type.
# Management software is supposed to translate CPU model aliases
# in the VM configuration, because aliases may stop being
# migration-safe in the future (since 4.1)
#
# @unavailable-features is a list of QOM property names that
# represent CPU model attributes that prevent the CPU from running.
# If the QOM property is read-only, that means there's no known
# way to make the CPU model run in the current host. Implementations
# that choose not to provide specific information return the
# property name "type".
# If the property is read-write, it means that it MAY be possible
# to run the CPU model in the current host if that property is
# changed. Management software can use it as hints to suggest or
# choose an alternative for the user, or just to generate meaningful
# error messages explaining why the CPU model can't be used.
# If @unavailable-features is an empty list, the CPU model is
# runnable using the current host and machine-type.
# If @unavailable-features is not present, runnability
# information for the CPU is not available.
# @deprecated: If true, this CPU model is deprecated and may be
# removed in in some future version of QEMU according to the QEMU
# deprecation policy. (since 5.2)
#
# @unavailable-features is a list of QOM property names that represent
# CPU model attributes that prevent the CPU from running. If the QOM
# property is read-only, that means there's no known way to make the
# CPU model run in the current host. Implementations that choose not
# to provide specific information return the property name "type". If
# the property is read-write, it means that it MAY be possible to run
# the CPU model in the current host if that property is changed.
# Management software can use it as hints to suggest or choose an
# alternative for the user, or just to generate meaningful error
# messages explaining why the CPU model can't be used. If
# @unavailable-features is an empty list, the CPU model is runnable
# using the current host and machine-type. If @unavailable-features
# is not present, runnability information for the CPU is not
# available.
#
# Since: 1.2
##

389
qapi/machine.json
View File

@ -14,17 +14,18 @@
# @SysEmuTarget:
#
# The comprehensive enumeration of QEMU system emulation ("softmmu")
# targets. Run "./configure --help" in the project root directory, and
# look for the \*-softmmu targets near the "--target-list" option. The
# individual target constants are not documented here, for the time
# being.
# targets. Run "./configure --help" in the project root directory,
# and look for the \*-softmmu targets near the "--target-list" option.
# The individual target constants are not documented here, for the
# time being.
#
# @rx: since 5.0
#
# @avr: since 5.1
#
# Notes: The resulting QMP strings can be appended to the "qemu-system-"
# prefix to produce the corresponding QEMU executable name. This
# is true even for "qemu-system-x86_64".
# Notes: The resulting QMP strings can be appended to the
# "qemu-system-" prefix to produce the corresponding QEMU
# executable name. This is true even for "qemu-system-x86_64".
#
# Since: 3.0
##
@ -39,8 +40,8 @@
##
# @CpuS390State:
#
# An enumeration of cpu states that can be assumed by a virtual
# S390 CPU
# An enumeration of cpu states that can be assumed by a virtual S390
# CPU
#
# Since: 2.12
##
@ -71,10 +72,10 @@
# @thread-id: ID of the underlying host thread
#
# @props: properties describing to which node/socket/core/thread
# virtual CPU belongs to, provided if supported by board
# virtual CPU belongs to, provided if supported by board
#
# @target: the QEMU system emulation target, which determines which
# additional fields will be listed (since 3.0)
# additional fields will be listed (since 3.0)
#
# Since: 2.12
##
@ -139,21 +140,22 @@
# @is-default: whether the machine is default
#
# @cpu-max: maximum number of CPUs supported by the machine type
# (since 1.5)
# (since 1.5)
#
# @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7)
#
# @numa-mem-supported: true if '-numa node,mem' option is supported by
# the machine type and false otherwise (since 4.1)
# the machine type and false otherwise (since 4.1)
#
# @deprecated: if true, the machine type is deprecated and may be removed
# in future versions of QEMU according to the QEMU deprecation
# policy (since 4.1)
# @deprecated: if true, the machine type is deprecated and may be
# removed in future versions of QEMU according to the QEMU
# deprecation policy (since 4.1)
#
# @default-cpu-type: default CPU model typename if none is requested via
# the -cpu argument. (since 4.2)
# @default-cpu-type: default CPU model typename if none is requested
# via the -cpu argument. (since 4.2)
#
# @default-ram-id: the default ID of initial RAM memory backend (since 5.2)
# @default-ram-id: the default ID of initial RAM memory backend (since
# 5.2)
#
# @acpi: machine type supports ACPI (since 8.0)
#
@ -183,7 +185,7 @@
# Information describing the running machine parameters.
#
# @wakeup-suspend-support: true if the machine supports wake up from
# suspend
# suspend
#
# Since: 4.0
##
@ -233,7 +235,8 @@
#
# Since: 0.14
#
# Notes: If no UUID was specified for the guest, a null UUID is returned.
# Notes: If no UUID was specified for the guest, a null UUID is
# returned.
##
{ 'struct': 'UuidInfo', 'data': {'UUID': 'str'} }
@ -250,7 +253,6 @@
#
# -> { "execute": "query-uuid" }
# <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
#
##
{ 'command': 'query-uuid', 'returns': 'UuidInfo', 'allow-preconfig': true }
@ -285,7 +287,6 @@
#
# -> { "execute": "system_reset" }
# <- { "return": {} }
#
##
{ 'command': 'system_reset' }
@ -297,67 +298,65 @@
# Since: 0.14
#
# Notes: A guest may or may not respond to this command. This command
# returning does not indicate that a guest has accepted the request or
# that it has shut down. Many guests will respond to this command by
# prompting the user in some way.
# returning does not indicate that a guest has accepted the
# request or that it has shut down. Many guests will respond to
# this command by prompting the user in some way.
#
# Example:
#
# -> { "execute": "system_powerdown" }
# <- { "return": {} }
#
##
{ 'command': 'system_powerdown' }
##
# @system_wakeup:
#
# Wake up guest from suspend. If the guest has wake-up from suspend
# Wake up guest from suspend. If the guest has wake-up from suspend
# support enabled (wakeup-suspend-support flag from
# query-current-machine), wake-up guest from suspend if the guest is
# in SUSPENDED state. Return an error otherwise.
# in SUSPENDED state. Return an error otherwise.
#
# Since: 1.1
#
# Returns: nothing.
#
# Note: prior to 4.0, this command does nothing in case the guest
# isn't suspended.
# isn't suspended.
#
# Example:
#
# -> { "execute": "system_wakeup" }
# <- { "return": {} }
#
##
{ 'command': 'system_wakeup' }
##
# @LostTickPolicy:
#
# Policy for handling lost ticks in timer devices. Ticks end up getting
# lost when, for example, the guest is paused.
# 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 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.
# @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. 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.
# @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 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.
# @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
##
@ -367,20 +366,21 @@
##
# @inject-nmi:
#
# Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all CPUs (ppc64).
# The command fails when the guest doesn't support injecting.
# Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or
# all CPUs (ppc64). The command fails when the guest doesn't support
# injecting.
#
# Returns: If successful, nothing
#
# Since: 0.14
#
# Note: prior to 2.1, this command was only supported for x86 and s390 VMs
# Note: prior to 2.1, this command was only supported for x86 and s390
# VMs
#
# Example:
#
# -> { "execute": "inject-nmi" }
# <- { "return": {} }
#
##
{ 'command': 'inject-nmi' }
@ -410,7 +410,6 @@
#
# -> { "execute": "query-kvm" }
# <- { "return": { "enabled": true, "present": true } }
#
##
{ 'command': 'query-kvm', 'returns': 'KvmInfo' }
@ -435,7 +434,7 @@
##
# @NumaOptions:
#
# A discriminated record of NUMA options. (for OptsVisitor)
# A discriminated record of NUMA options. (for OptsVisitor)
#
# Since: 2.1
##
@ -452,26 +451,25 @@
##
# @NumaNodeOptions:
#
# Create a guest NUMA node. (for OptsVisitor)
# Create a guest NUMA node. (for OptsVisitor)
#
# @nodeid: NUMA node ID (increase by 1 from 0 if omitted)
#
# @cpus: VCPUs belonging to this node (assign VCPUS round-robin
# if omitted)
# @cpus: VCPUs belonging to this node (assign VCPUS round-robin if
# omitted)
#
# @mem: memory size of this node; mutually exclusive with @memdev.
# Equally divide total memory among nodes if both @mem and @memdev are
# omitted.
# Equally divide total memory among nodes if both @mem and @memdev
# are omitted.
#
# @memdev: memory backend object. If specified for one node,
# it must be specified for all nodes.
# @memdev: memory backend object. If specified for one node, it must
# be specified for all nodes.
#
# @initiator: defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145,
# points to the nodeid which has the memory controller
# responsible for this NUMA node. This field provides
# additional information as to the initiator node that
# is closest (as in directly attached) to this node, and
# therefore has the best performance (since 5.0)
# @initiator: defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145, points
# to the nodeid which has the memory controller responsible for
# this NUMA node. This field provides additional information as
# to the initiator node that is closest (as in directly attached)
# to this node, and therefore has the best performance (since 5.0)
#
# Since: 2.1
##
@ -492,9 +490,9 @@
#
# @dst: destination NUMA node.
#
# @val: NUMA distance from source node to destination node.
# When a node is unreachable from another node, set the distance
# between them to 255.
# @val: NUMA distance from source node to destination node. When a
# node is unreachable from another node, set the distance between
# them to 255.
#
# Since: 2.10
##
@ -509,13 +507,15 @@
#
# Create a CXL Fixed Memory Window
#
# @size: Size of the Fixed Memory Window in bytes. Must be a multiple
# of 256MiB.
# @size: Size of the Fixed Memory Window in bytes. Must be a multiple
# of 256MiB.
#
# @interleave-granularity: Number of contiguous bytes for which
# accesses will go to a given interleave target.
# Accepted values [256, 512, 1k, 2k, 4k, 8k, 16k]
# @targets: Target root bridge IDs from -device ...,id=<ID> for each root
# bridge.
# accesses will go to a given interleave target. Accepted values
# [256, 512, 1k, 2k, 4k, 8k, 16k]
#
# @targets: Target root bridge IDs from -device ...,id=<ID> for each
# root bridge.
#
# Since: 7.1
##
@ -553,10 +553,11 @@
#
# Information about a X86 CPU feature word
#
# @cpuid-input-eax: Input EAX value for CPUID instruction for that feature word
# @cpuid-input-eax: Input EAX value for CPUID instruction for that
# feature word
#
# @cpuid-input-ecx: Input ECX value for CPUID instruction for that
# feature word
# feature word
#
# @cpuid-register: Output register containing the feature bits
#
@ -573,7 +574,8 @@
##
# @DummyForceArrays:
#
# Not used by QMP; hack to let us use X86CPUFeatureWordInfoList internally
# Not used by QMP; hack to let us use X86CPUFeatureWordInfoList
# internally
#
# Since: 2.5
##
@ -583,8 +585,8 @@
##
# @NumaCpuOptions:
#
# Option "-numa cpu" overrides default cpu to node mapping.
# It accepts the same set of cpu properties as returned by
# Option "-numa cpu" overrides default cpu to node mapping. It
# accepts the same set of cpu properties as returned by
# query-hotpluggable-cpus[].props, where node-id could be used to
# override default node mapping.
#
@ -619,11 +621,11 @@
##
# @HmatLBDataType:
#
# Data type in the System Locality Latency and Bandwidth
# Information Structure of HMAT (Heterogeneous Memory Attribute Table)
# Data type in the System Locality Latency and Bandwidth Information
# Structure of HMAT (Heterogeneous Memory Attribute Table)
#
# For more information about @HmatLBDataType, see chapter
# 5.2.27.4: Table 5-146: Field "Data Type" of ACPI 6.3 spec.
# For more information about @HmatLBDataType, see chapter 5.2.27.4:
# Table 5-146: Field "Data Type" of ACPI 6.3 spec.
#
# @access-latency: access latency (nanoseconds)
#
@ -646,28 +648,27 @@
##
# @NumaHmatLBOptions:
#
# Set the system locality latency and bandwidth information
# between Initiator and Target proximity Domains.
# Set the system locality latency and bandwidth information between
# Initiator and Target proximity Domains.
#
# For more information about @NumaHmatLBOptions, see chapter
# 5.2.27.4: Table 5-146 of ACPI 6.3 spec.
# For more information about @NumaHmatLBOptions, see chapter 5.2.27.4:
# Table 5-146 of ACPI 6.3 spec.
#
# @initiator: the Initiator Proximity Domain.
#
# @target: the Target Proximity Domain.
#
# @hierarchy: the Memory Hierarchy. Indicates the performance
# of memory or side cache.
# @hierarchy: the Memory Hierarchy. Indicates the performance of
# memory or side cache.
#
# @data-type: presents the type of data, access/read/write
# latency or hit latency.
# @data-type: presents the type of data, access/read/write latency or
# hit latency.
#
# @latency: the value of latency from @initiator to @target
# proximity domain, the latency unit is "ns(nanosecond)".
# @latency: the value of latency from @initiator to @target proximity
# domain, the latency unit is "ns(nanosecond)".
#
# @bandwidth: the value of bandwidth between @initiator and @target
# proximity domain, the bandwidth unit is
# "Bytes per second".
# proximity domain, the bandwidth unit is "Bytes per second".
#
# Since: 5.0
##
@ -689,8 +690,8 @@
# For more information of @HmatCacheAssociativity, see chapter
# 5.2.27.5: Table 5-147 of ACPI 6.3 spec.
#
# @none: None (no memory side cache in this proximity domain,
# or cache associativity unknown)
# @none: None (no memory side cache in this proximity domain, or cache
# associativity unknown)
#
# @direct: Direct Mapped
#
@ -704,14 +705,14 @@
##
# @HmatCacheWritePolicy:
#
# Cache write policy in the Memory Side Cache Information Structure
# of HMAT
# Cache write policy in the Memory Side Cache Information Structure of
# HMAT
#
# For more information of @HmatCacheWritePolicy, see chapter
# 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
# For more information of @HmatCacheWritePolicy, see chapter 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)
# @none: None (no memory side cache in this proximity domain, or cache
# write policy unknown)
#
# @write-back: Write Back (WB)
#
@ -727,8 +728,8 @@
#
# Set the memory side cache information for a given memory domain.
#
# For more information of @NumaHmatCacheOptions, see chapter
# 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
# For more information of @NumaHmatCacheOptions, see chapter 5.2.27.5:
# Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
#
# @node-id: the memory proximity domain to which the memory belongs.
#
@ -737,7 +738,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.
#
@ -766,7 +767,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
#
@ -781,7 +782,6 @@
# "size": 100,
# "filename": "/tmp/virtual-mem-dump" } }
# <- { "return": {} }
#
##
{ 'command': 'memsave',
'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} }
@ -810,7 +810,6 @@
# "size": 100,
# "filename": "/tmp/physical-mem-dump" } }
# <- { "return": {} }
#
##
{ 'command': 'pmemsave',
'data': {'val': 'int', 'size': 'int', 'filename': 'str'} }
@ -832,11 +831,11 @@
#
# @share: whether memory is private to QEMU or shared (since 6.1)
#
# @reserve: whether swap space (or huge pages) was reserved if applicable.
# This corresponds to the user configuration and not the actual
# behavior implemented in the OS to perform the reservation.
# For example, Linux will never reserve swap space for shared
# file mappings. (since 6.1)
# @reserve: whether swap space (or huge pages) was reserved if
# applicable. This corresponds to the user configuration and not
# the actual behavior implemented in the OS to perform the
# reservation. For example, Linux will never reserve swap space
# for shared file mappings. (since 6.1)
#
# @host-nodes: host nodes for its memory policy
#
@ -890,29 +889,34 @@
# }
# ]
# }
#
##
{ 'command': 'query-memdev', 'returns': ['Memdev'], 'allow-preconfig': true }
##
# @CpuInstanceProperties:
#
# List of properties to be used for hotplugging a CPU instance,
# it should be passed by management with device_add command when
# a CPU is being hotplugged.
# List of properties to be used for hotplugging a CPU instance, it
# should be passed by management with device_add command when a CPU is
# being hotplugged.
#
# @node-id: NUMA node ID the CPU belongs to
#
# @socket-id: socket number within node/board the CPU belongs to
#
# @die-id: die number within socket the CPU belongs to (since 4.1)
# @cluster-id: cluster number within die the CPU belongs to (since 7.1)
#
# @cluster-id: cluster number within die the CPU belongs to (since
# 7.1)
#
# @core-id: core number within cluster the CPU belongs to
#
# @thread-id: thread number within core the CPU belongs to
#
# Note: currently there are 6 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.
# Note: currently there are 6 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.
#
# Since: 2.7
##
@ -930,10 +934,14 @@
# @HotpluggableCPU:
#
# @type: CPU object type for usage with device_add command
#
# @props: list of properties to be used for hotplugging CPU
# @vcpus-count: number of logical VCPU threads @HotpluggableCPU provides
# @qom-path: link to existing CPU object if CPU is present or
# omitted if CPU is not present.
#
# @vcpus-count: number of logical VCPU threads @HotpluggableCPU
# provides
#
# @qom-path: link to existing CPU object if CPU is present or omitted
# if CPU is not present.
#
# Since: 2.7
##
@ -956,7 +964,8 @@
#
# Examples:
#
# For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
# For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu
# POWER8:
#
# -> { "execute": "query-hotpluggable-cpus" }
# <- {"return": [
@ -981,8 +990,8 @@
# }
# ]}
#
# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
# (Since: 2.11):
# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu
# qemu (Since: 2.11):
#
# -> { "execute": "query-hotpluggable-cpus" }
# <- {"return": [
@ -996,7 +1005,6 @@
# "props": { "core-id": 0 }
# }
# ]}
#
##
{ 'command': 'query-hotpluggable-cpus', 'returns': ['HotpluggableCPU'],
'allow-preconfig': true }
@ -1004,9 +1012,8 @@
##
# @set-numa-node:
#
# Runtime equivalent of '-numa' CLI option, available at
# preconfigure stage to configure numa mapping before initializing
# machine.
# Runtime equivalent of '-numa' CLI option, available at preconfigure
# stage to configure numa mapping before initializing machine.
#
# Since: 3.0
##
@ -1020,21 +1027,22 @@
#
# Request the balloon driver to change its balloon size.
#
# @value: the target logical size of the VM in bytes.
# We can deduce the size of the balloon using this formula:
# @value: the target logical size of the VM in bytes. We can deduce
# the size of the balloon using this formula:
#
# logical_vm_size = vm_ram_size - balloon_size
# logical_vm_size = vm_ram_size - balloon_size
#
# From it we have: balloon_size = vm_ram_size - @value
# From it we have: balloon_size = vm_ram_size - @value
#
# 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
# 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
#
# 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
# size independent of this command.
# 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 size independent of this command.
#
# Since: 0.14
#
@ -1044,7 +1052,6 @@
# <- { "return": {} }
#
# With a 2.5GiB guest this command inflated the ballon to 3GiB.
#
##
{ 'command': 'balloon', 'data': {'value': 'int'} }
@ -1053,8 +1060,8 @@
#
# Information about the guest balloon device.
#
# @actual: the logical size of the VM in bytes
# Formula used: logical_vm_size = vm_ram_size - balloon_size
# @actual: the logical size of the VM in bytes Formula used:
# logical_vm_size = vm_ram_size - balloon_size
#
# Since: 0.14
##
@ -1065,10 +1072,11 @@
#
# 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
#
@ -1079,18 +1087,18 @@
# "actual": 1073741824
# }
# }
#
##
{ 'command': 'query-balloon', 'returns': 'BalloonInfo' }
##
# @BALLOON_CHANGE:
#
# Emitted when the guest changes the actual BALLOON level. This value is
# equivalent to the @actual field return by the 'query-balloon' command
# Emitted when the guest changes the actual BALLOON level. This value
# is equivalent to the @actual field return by the 'query-balloon'
# command
#
# @actual: the logical size of the VM in bytes
# Formula used: logical_vm_size = vm_ram_size - balloon_size
# @actual: the logical size of the VM in bytes Formula used:
# logical_vm_size = vm_ram_size - balloon_size
#
# Note: this event is rate-limited.
#
@ -1101,7 +1109,6 @@
# <- { "event": "BALLOON_CHANGE",
# "data": { "actual": 944766976 },
# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
#
##
{ 'event': 'BALLOON_CHANGE',
'data': { 'actual': 'int' } }
@ -1112,11 +1119,11 @@
# Actual memory information in bytes.
#
# @base-memory: size of "base" memory specified with command line
# option -m.
# option -m.
#
# @plugged-memory: size of memory that can be hot-unplugged. This field
# is omitted if target doesn't support memory hotplug
# (i.e. CONFIG_MEM_DEVICE not defined at build time).
# @plugged-memory: size of memory that can be hot-unplugged. This
# field is omitted if target doesn't support memory hotplug (i.e.
# CONFIG_MEM_DEVICE not defined at build time).
#
# Since: 2.11
##
@ -1126,8 +1133,8 @@
##
# @query-memory-size-summary:
#
# Return the amount of initially allocated and present hotpluggable (if
# enabled) memory in bytes.
# Return the amount of initially allocated and present hotpluggable
# (if enabled) memory in bytes.
#
# Example:
#
@ -1157,7 +1164,8 @@
#
# @hotplugged: true if device was hotplugged
#
# @hotpluggable: true if device if could be added/removed while machine is running
# @hotpluggable: true if device if could be added/removed while
# machine is running
#
# Since: 2.1
##
@ -1374,16 +1382,15 @@
# "slot": 0},
# "type": "dimm"
# } ] }
#
##
{ 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] }
##
# @MEMORY_DEVICE_SIZE_CHANGE:
#
# Emitted when the size of a memory device changes. Only emitted for memory
# devices that can actually change the size (e.g., virtio-mem due to guest
# action).
# Emitted when the size of a memory device changes. Only emitted for
# memory devices that can actually change the size (e.g., virtio-mem
# due to guest action).
#
# @id: device's ID
#
@ -1401,7 +1408,6 @@
# "data": { "id": "vm0", "size": 1073741824,
# "qom-path": "/machine/unattached/device[2]" },
# "timestamp": { "seconds": 1588168529, "microseconds": 201316 } }
#
##
{ 'event': 'MEMORY_DEVICE_SIZE_CHANGE',
'data': { '*id': 'str', 'size': 'size', 'qom-path' : 'str'} }
@ -1416,8 +1422,9 @@
# @msg: Informative message
#
# Features:
# @deprecated: This event is deprecated. Use @DEVICE_UNPLUG_GUEST_ERROR
# instead.
#
# @deprecated: This event is deprecated. Use
# @DEVICE_UNPLUG_GUEST_ERROR instead.
#
# Since: 2.4
#
@ -1428,7 +1435,6 @@
# "msg": "acpi: device unplug for unsupported device"
# },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
#
##
{ 'event': 'MEM_UNPLUG_ERROR',
'data': { 'device': 'str', 'msg': 'str' },
@ -1445,13 +1451,15 @@
#
# @menu: Whether to show a boot menu
#
# @splash: The name of the file to be passed to the firmware as logo picture, if @menu is true.
# @splash: The name of the file to be passed to the firmware as logo
# picture, if @menu is true.
#
# @splash-time: How long to show the logo picture, in milliseconds
#
# @reboot-timeout: Timeout before guest reboots after boot fails
#
# @strict: Whether to attempt booting from devices not included in the boot order
# @strict: Whether to attempt booting from devices not included in the
# boot order
#
# Since: 7.1
##
@ -1467,8 +1475,8 @@
##
# @SMPConfiguration:
#
# Schema for CPU topology configuration. A missing value lets
# QEMU figure out a suitable value based on the ones that are provided.
# Schema for CPU topology configuration. A missing value lets QEMU
# figure out a suitable value based on the ones that are provided.
#
# @cpus: number of virtual CPUs in the virtual machine
#
@ -1476,13 +1484,15 @@
#
# @dies: number of dies per socket in the CPU topology
#
# @clusters: number of clusters per die in the CPU topology (since 7.0)
# @clusters: number of clusters per die in the CPU topology (since
# 7.0)
#
# @cores: number of cores per cluster in the CPU topology
#
# @threads: number of threads per core in the CPU topology
#
# @maxcpus: maximum number of hotpluggable virtual CPUs in the virtual machine
# @maxcpus: maximum number of hotpluggable virtual CPUs in the virtual
# machine
#
# Since: 6.1
##
@ -1501,6 +1511,7 @@
# Query interrupt statistics
#
# Features:
#
# @unstable: This command is meant for debugging.
#
# Returns: interrupt statistics
@ -1517,6 +1528,7 @@
# Query TCG compiler statistics
#
# Features:
#
# @unstable: This command is meant for debugging.
#
# Returns: TCG compiler statistics
@ -1534,6 +1546,7 @@
# Query NUMA topology information
#
# Features:
#
# @unstable: This command is meant for debugging.
#
# Returns: topology information
@ -1550,6 +1563,7 @@
# Query TCG opcode counters
#
# Features:
#
# @unstable: This command is meant for debugging.
#
# Returns: TCG opcode counters
@ -1567,6 +1581,7 @@
# Query TCG profiling information
#
# Features:
#
# @unstable: This command is meant for debugging.
#
# Returns: profile information
@ -1584,6 +1599,7 @@
# Query system ramblock information
#
# Features:
#
# @unstable: This command is meant for debugging.
#
# Returns: system ramblock information
@ -1600,6 +1616,7 @@
# Query RDMA state
#
# Features:
#
# @unstable: This command is meant for debugging.
#
# Returns: RDMA state
@ -1616,6 +1633,7 @@
# Query information on the registered ROMS
#
# Features:
#
# @unstable: This command is meant for debugging.
#
# Returns: registered ROMs
@ -1632,6 +1650,7 @@
# Query information on the USB devices
#
# Features:
#
# @unstable: This command is meant for debugging.
#
# Returns: USB device information
@ -1682,10 +1701,10 @@
# Since: 7.2
#
# Example:
#
# -> { "execute": "dumpdtb" }
# "arguments": { "filename": "fdt.dtb" } }
# <- { "return": {} }
#
##
{ 'command': 'dumpdtb',
'data': { 'filename': 'str' },

1120
qapi/migration.json
View File

File diff suppressed because it is too large Load Diff

67
qapi/misc-target.json
View File

@ -5,10 +5,9 @@
##
# @rtc-reset-reinjection:
#
# This command will reset the RTC interrupt reinjection backlog.
# Can be used if another mechanism to synchronize guest time
# is in effect, for example QEMU guest agent's guest-set-time
# command.
# This command will reset the RTC interrupt reinjection backlog. Can
# be used if another mechanism to synchronize guest time is in effect,
# for example QEMU guest agent's guest-set-time command.
#
# Since: 2.1
#
@ -16,7 +15,6 @@
#
# -> { "execute": "rtc-reset-reinjection" }
# <- { "return": {} }
#
##
{ 'command': 'rtc-reset-reinjection',
'if': 'TARGET_I386' }
@ -28,17 +26,19 @@
#
# @uninit: The guest is uninitialized.
#
# @launch-update: The guest is currently being launched; plaintext data and
# register state is being imported.
# @launch-update: The guest is currently being launched; plaintext
# data and register state is being imported.
#
# @launch-secret: The guest is currently being launched; ciphertext data
# is being imported.
# @launch-secret: The guest is currently being launched; ciphertext
# data is being imported.
#
# @running: The guest is fully launched or migrated in.
#
# @send-update: The guest is currently being migrated out to another machine.
# @send-update: The guest is currently being migrated out to another
# machine.
#
# @receive-update: The guest is currently being migrated from another machine.
# @receive-update: The guest is currently being migrated from another
# machine.
#
# Since: 2.12
##
@ -95,7 +95,6 @@
# <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
# "build-id" : 0, "policy" : 0, "state" : "running",
# "handle" : 1 } }
#
##
{ 'command': 'query-sev', 'returns': 'SevInfo',
'if': 'TARGET_I386' }
@ -125,7 +124,6 @@
#
# -> { "execute": "query-sev-launch-measure" }
# <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
#
##
{ 'command': 'query-sev-launch-measure', 'returns': 'SevLaunchMeasureInfo',
'if': 'TARGET_I386' }
@ -133,8 +131,8 @@
##
# @SevCapability:
#
# The struct describes capability for a Secure Encrypted Virtualization
# feature.
# The struct describes capability for a Secure Encrypted
# Virtualization feature.
#
# @pdh: Platform Diffie-Hellman key (base64 encoded)
#
@ -144,8 +142,8 @@
#
# @cbitpos: C-bit location in page table entry
#
# @reduced-phys-bits: Number of physical Address bit reduction when SEV is
# enabled
# @reduced-phys-bits: Number of physical Address bit reduction when
# SEV is enabled
#
# Since: 2.12
##
@ -160,8 +158,8 @@
##
# @query-sev-capabilities:
#
# This command is used to get the SEV capabilities, and is supported on AMD
# X86 platforms only.
# This command is used to get the SEV capabilities, and is supported
# on AMD X86 platforms only.
#
# Returns: SevCapability objects.
#
@ -173,7 +171,6 @@
# <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
# "cpu0-id": "2lvmGwo+...61iEinw==",
# "cbitpos": 47, "reduced-phys-bits": 1}}
#
##
{ 'command': 'query-sev-capabilities', 'returns': 'SevCapability',
'if': 'TARGET_I386' }
@ -216,7 +213,7 @@
# supported on AMD X86 platforms only.
#
# @mnonce: a random 16 bytes value encoded in base64 (it will be
# included in report)
# included in report)
#
# Returns: SevAttestationReport objects.
#
@ -227,7 +224,6 @@
# -> { "execute" : "query-sev-attestation-report",
# "arguments": { "mnonce": "aaaaaaa" } }
# <- { "return" : { "data": "aaaaaaaabbbddddd"} }
#
##
{ 'command': 'query-sev-attestation-report',
'data': { 'mnonce': 'str' },
@ -250,7 +246,6 @@
# -> { "execute": "dump-skeys",
# "arguments": { "filename": "/tmp/skeys" } }
# <- { "return": {} }
#
##
{ 'command': 'dump-skeys',
'data': { 'filename': 'str' },
@ -260,18 +255,18 @@
# @GICCapability:
#
# The struct describes capability for a specific GIC (Generic
# Interrupt Controller) version. These bits are not only decided by
# QEMU/KVM software version, but also decided by the hardware that
# the program is running upon.
# Interrupt Controller) version. These bits are not only decided by
# 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.
# 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
##
@ -284,7 +279,7 @@
##
# @query-gic-capabilities:
#
# This command is ARM-only. It will return a list of GICCapability
# This command is ARM-only. It will return a list of GICCapability
# objects that describe its capability bits.
#
# Returns: a list of GICCapability objects.
@ -296,7 +291,6 @@
# -> { "execute": "query-gic-capabilities" }
# <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
# { "version": 3, "emulated": false, "kernel": true } ] }
#
##
{ 'command': 'query-gic-capabilities', 'returns': ['GICCapability'],
'if': 'TARGET_ARM' }
@ -357,7 +351,6 @@
# "flc": true,
# "sections": [{"node": 0, "size": 67108864},
# {"node": 1, "size": 29360128}]} }
#
##
{ 'command': 'query-sgx', 'returns': 'SGXInfo', 'if': 'TARGET_I386' }
@ -377,7 +370,6 @@
# "flc": true,
# "section" : [{"node": 0, "size": 67108864},
# {"node": 1, "size": 29360128}]} }
#
##
{ 'command': 'query-sgx-capabilities', 'returns': 'SGXInfo', 'if': 'TARGET_I386' }
@ -470,7 +462,6 @@
# }
# ]
# }
#
##
{ 'command': 'xen-event-list',
'returns': ['EvtchnInfo'],
@ -483,7 +474,8 @@
#
# @port: The port number
#
# Returns: - Nothing on success.
# Returns:
# - Nothing on success.
#
# Since: 8.0
#
@ -491,7 +483,6 @@
#
# -> { "execute": "xen-event-inject", "arguments": { "port": 1 } }
# <- { "return": { } }
#
##
{ 'command': 'xen-event-inject',
'data': { 'port': 'uint32' },

180
qapi/misc.json
View File

@ -11,22 +11,22 @@
##
# @add_client:
#
# Allow client connections for VNC, Spice and socket based
# character devices to be passed in to QEMU via SCM_RIGHTS.
# Allow client connections for VNC, Spice and socket based character
# devices to be passed in to QEMU via SCM_RIGHTS.
#
# If the FD associated with @fdname is not a socket, the command will fail and
# the FD will be closed.
# If the FD associated with @fdname is not a socket, the command will
# fail and the FD will be closed.
#
# @protocol: protocol name. Valid names are "vnc", "spice", "@dbus-display" or
# the name of a character device (eg. from -chardev id=XXXX)
# @protocol: protocol name. Valid names are "vnc", "spice",
# "@dbus-display" or the name of a character device (eg. from
# -chardev id=XXXX)
#
# @fdname: file descriptor name previously passed via 'getfd' command
#
# @skipauth: whether to skip authentication. Only applies
# to "vnc" and "spice" protocols
# @skipauth: whether to skip authentication. Only applies to "vnc"
# and "spice" protocols
#
# @tls: whether to perform TLS. Only applies to the "spice"
# protocol
# @tls: whether to perform TLS. Only applies to the "spice" protocol
#
# Returns: nothing on success.
#
@ -37,7 +37,6 @@
# -> { "execute": "add_client", "arguments": { "protocol": "vnc",
# "fdname": "myclient" } }
# <- { "return": {} }
#
##
{ 'command': 'add_client',
'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
@ -67,7 +66,6 @@
#
# -> { "execute": "query-name" }
# <- { "return": { "name": "qemu-name" } }
#
##
{ 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true }
@ -80,17 +78,17 @@
#
# @thread-id: ID of the underlying host thread
#
# @poll-max-ns: maximum polling time in ns, 0 means polling is disabled
# (since 2.9)
# @poll-max-ns: maximum polling time in ns, 0 means polling is
# disabled (since 2.9)
#
# @poll-grow: how many ns will be added to polling time, 0 means that it's not
# configured (since 2.9)
# @poll-grow: how many ns will be added to polling time, 0 means that
# it's not configured (since 2.9)
#
# @poll-shrink: how many ns will be removed from polling time, 0 means that
# it's not configured (since 2.9)
# @poll-shrink: how many ns will be removed from polling time, 0 means
# that it's not configured (since 2.9)
#
# @aio-max-batch: maximum number of requests in a batch for the AIO engine,
# 0 means that the engine will use its default (since 6.1)
# @aio-max-batch: maximum number of requests in a batch for the AIO
# engine, 0 means that the engine will use its default (since 6.1)
#
# Since: 2.0
##
@ -107,9 +105,9 @@
#
# 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.
# 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.
#
# Returns: a list of @IOThreadInfo for each iothread
#
@ -129,7 +127,6 @@
# }
# ]
# }
#
##
{ 'command': 'query-iothreads', 'returns': ['IOThreadInfo'],
'allow-preconfig': true }
@ -141,16 +138,15 @@
#
# Since: 0.14
#
# 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:
#
# -> { "execute": "stop" }
# <- { "return": {} }
#
##
{ 'command': 'stop' }
@ -163,17 +159,16 @@
#
# 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:
#
# -> { "execute": "cont" }
# <- { "return": {} }
#
##
{ 'command': 'cont' }
@ -182,13 +177,14 @@
#
# Exit from "preconfig" state
#
# This command makes QEMU exit the preconfig state and proceed with
# VM initialization using configuration data provided on the command line
# and via the QMP monitor during the preconfig state. The command is only
# available during the preconfig state (i.e. when the --preconfig command
# line option was in use).
# This command makes QEMU exit the preconfig state and proceed with VM
# initialization using configuration data provided on the command line
# and via the QMP monitor during the preconfig state. The command is
# only available during the preconfig state (i.e. when the --preconfig
# command line option was in use).
#
# Features:
#
# @unstable: This command is experimental.
#
# Since: 3.0
@ -199,7 +195,6 @@
#
# -> { "execute": "x-exit-preconfig" }
# <- { "return": {} }
#
##
{ 'command': 'x-exit-preconfig', 'allow-preconfig': true,
'features': [ 'unstable' ] }
@ -214,35 +209,33 @@
# @cpu-index: The CPU to use for commands that require an implicit CPU
#
# Features:
#
# @savevm-monitor-nodes: If present, HMP command savevm only snapshots
# monitor-owned nodes if they have no parents.
# This allows the use of 'savevm' with
# -blockdev. (since 4.2)
# monitor-owned nodes if they have no parents. This allows the
# use of 'savevm' with -blockdev. (since 4.2)
#
# Returns: the output of the command as a string
#
# Since: 0.14
#
# Notes: This command only exists as a stop-gap. Its use is highly
# discouraged. The semantics of this command are not
# guaranteed: this means that command names, arguments and
# responses can change or be removed at ANY time. Applications
# that rely on long term stability guarantees should NOT
# use this command.
# discouraged. The semantics of this command are not guaranteed:
# this means that command names, arguments and responses can
# change or be removed at ANY time. Applications that rely on
# long term stability guarantees should NOT use this command.
#
# Known limitations:
# Known limitations:
#
# * This command is stateless, this means that commands that depend
# on state information (such as getfd) might not work
# * This command is stateless, this means that commands that
# depend on state information (such as getfd) might not work
#
# * Commands that prompt the user for data don't currently work
# * Commands that prompt the user for data don't currently work
#
# Example:
#
# -> { "execute": "human-monitor-command",
# "arguments": { "command-line": "info kvm" } }
# <- { "return": "kvm support: enabled\r\n" }
#
##
{ 'command': 'human-monitor-command',
'data': {'command-line': 'str', '*cpu-index': 'int'},
@ -260,18 +253,16 @@
#
# Since: 0.14
#
# Notes: If @fdname already exists, the file descriptor assigned to
# it will be closed and replaced by the received file
# descriptor.
# Notes: If @fdname already exists, the file descriptor assigned to it
# will be closed and replaced by the received file descriptor.
#
# The 'closefd' command can be used to explicitly close the
# file descriptor when it is no longer needed.
# The 'closefd' command can be used to explicitly close the file
# descriptor when it is no longer needed.
#
# Example:
#
# -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
# <- { "return": {} }
#
##
{ 'command': 'getfd', 'data': {'fdname': 'str'}, 'if': 'CONFIG_POSIX' }
@ -291,18 +282,16 @@
#
# Since: 8.0
#
# Notes: If @fdname already exists, the file descriptor assigned to
# it will be closed and replaced by the received file
# descriptor.
# Notes: If @fdname already exists, the file descriptor assigned to it
# will be closed and replaced by the received file descriptor.
#
# The 'closefd' command can be used to explicitly close the
# file descriptor when it is no longer needed.
# The 'closefd' command can be used to explicitly close the file
# descriptor when it is no longer needed.
#
# Example:
#
# -> { "execute": "get-win32-socket", "arguments": { "info": "abcd123..", fdname": "skclient" } }
# <- { "return": {} }
#
##
{ 'command': 'get-win32-socket', 'data': {'info': 'str', 'fdname': 'str'}, 'if': 'CONFIG_WIN32' }
@ -321,7 +310,6 @@
#
# -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
# <- { "return": {} }
#
##
{ 'command': 'closefd', 'data': {'fdname': 'str'} }
@ -332,8 +320,8 @@
#
# @fdset-id: The ID of the fd set that @fd was added to.
#
# @fd: The file descriptor that was received via SCM rights and
# added to the fd set.
# @fd: The file descriptor that was received via SCM rights and added
# to the fd set.
#
# Since: 1.2
##
@ -348,13 +336,14 @@
#
# @opaque: A free-form string that can be used to describe the fd.
#
# Returns: - @AddfdInfo on success
# - If file descriptor was not received, GenericError
# - If @fdset-id is a negative value, GenericError
# Returns:
# - @AddfdInfo on success
# - If file descriptor was not received, GenericError
# - If @fdset-id is a negative value, GenericError
#
# Notes: The list of fd sets is shared by all monitor connections.
#
# If @fdset-id is not specified, a new fd set will be created.
# If @fdset-id is not specified, a new fd set will be created.
#
# Since: 1.2
#
@ -362,7 +351,6 @@
#
# -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
# <- { "return": { "fdset-id": 1, "fd": 3 } }
#
##
{ 'command': 'add-fd',
'data': { '*fdset-id': 'int',
@ -378,21 +366,21 @@
#
# @fd: The file descriptor that is to be removed.
#
# Returns: - Nothing on success
# - If @fdset-id or @fd is not found, GenericError
# Returns:
# - Nothing on success
# - If @fdset-id or @fd is not found, GenericError
#
# Since: 1.2
#
# Notes: The list of fd sets is shared by all monitor connections.
#
# If @fd is not specified, all file descriptors in @fdset-id
# will be removed.
# If @fd is not specified, all file descriptors in @fdset-id will be
# removed.
#
# Example:
#
# -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
# <- { "return": {} }
#
##
{ 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
@ -465,7 +453,6 @@
# }
# ]
# }
#
##
{ 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
@ -481,7 +468,7 @@
# @number: accepts a number
#
# @size: accepts a number followed by an optional suffix (K)ilo,
# (M)ega, (G)iga, (T)era
# (M)ega, (G)iga, (T)era
#
# Since: 1.5
##
@ -512,7 +499,8 @@
##
# @CommandLineOptionInfo:
#
# Details about a command line option, including its list of parameter details
# Details about a command line option, including its list of parameter
# details
#
# @option: option name
#
@ -530,8 +518,9 @@
#
# @option: option name
#
# Returns: list of @CommandLineOptionInfo for all options (or for the given
# @option). Returns an error if the given @option doesn't exist.
# Returns: list of @CommandLineOptionInfo for all options (or for the
# given @option). Returns an error if the given @option doesn't
# exist.
#
# Since: 1.5
#
@ -555,26 +544,25 @@
# }
# ]
# }
#
##
{'command': 'query-command-line-options',
'data': { '*option': 'str' },
'data': {'*option': 'str'},
'returns': ['CommandLineOptionInfo'],
'allow-preconfig': true }
'allow-preconfig': true}
##
# @RTC_CHANGE:
#
# Emitted when the guest changes the RTC time.
#
# @offset: offset in seconds between base RTC clock (as specified
# by -rtc base), and new RTC clock value
# @offset: offset in seconds between base RTC clock (as specified by
# -rtc base), and new RTC clock value
#
# @qom-path: path to the RTC object in the QOM tree
#
# Note: This event is rate-limited.
# It is not guaranteed that the RTC in the system implements
# this event, or even that the system has an RTC at all.
# Note: This event is rate-limited. It is not guaranteed that the RTC
# in the system implements this event, or even that the system has
# an RTC at all.
#
# Since: 0.13
#
@ -593,10 +581,11 @@
# Emitted when the client of a TYPE_VFIO_USER_SERVER closes the
# communication channel
#
# @vfu-id: ID of the TYPE_VFIO_USER_SERVER object. It is the last component
# of @vfu-qom-path referenced below
# @vfu-id: ID of the TYPE_VFIO_USER_SERVER object. It is the last
# component of @vfu-qom-path referenced below
#
# @vfu-qom-path: path to the TYPE_VFIO_USER_SERVER object in the QOM tree
# @vfu-qom-path: path to the TYPE_VFIO_USER_SERVER object in the QOM
# tree
#
# @dev-id: ID of attached PCI device
#
@ -612,7 +601,6 @@
# "dev-id": "sas1",
# "dev-qom-path": "/machine/peripheral/sas1" },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
#
##
{ 'event': 'VFU_CLIENT_HANGUP',
'data': { 'vfu-id': 'str', 'vfu-qom-path': 'str',

260
qapi/net.json
View File

@ -18,21 +18,20 @@
#
# @up: true to set the link status to be up
#
# Returns: Nothing on success
# If @name is not a valid network device, DeviceNotFound
# Returns: Nothing on success If @name is not a valid network device,
# DeviceNotFound
#
# Since: 0.14
#
# Notes: Not all network adapters support setting link status. This command
# will succeed even if the network adapter does not support link status
# notification.
# Notes: Not all network adapters support setting link status. This
# command will succeed even if the network adapter does not
# support link status notification.
#
# Example:
#
# -> { "execute": "set_link",
# "arguments": { "name": "e1000.0", "up": false } }
# <- { "return": {} }
#
##
{ 'command': 'set_link', 'data': {'name': 'str', 'up': 'bool'} }
@ -45,8 +44,8 @@
#
# Since: 0.14
#
# Returns: Nothing on success
# If @type is not a valid network backend, DeviceNotFound
# Returns: Nothing on success If @type is not a valid network backend,
# DeviceNotFound
#
# Example:
#
@ -54,7 +53,6 @@
# "arguments": { "type": "user", "id": "netdev1",
# "dnssearch": [ { "str": "example.org" } ] } }
# <- { "return": {} }
#
##
{ 'command': 'netdev_add', 'data': 'Netdev', 'boxed': true,
'allow-preconfig': true }
@ -66,8 +64,8 @@
#
# @id: the name of the network backend to remove
#
# Returns: Nothing on success
# If @id is not a valid network backend, DeviceNotFound
# Returns: Nothing on success If @id is not a valid network backend,
# DeviceNotFound
#
# Since: 0.14
#
@ -75,7 +73,6 @@
#
# -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
# <- { "return": {} }
#
##
{ 'command': 'netdev_del', 'data': {'id': 'str'},
'allow-preconfig': true }
@ -108,25 +105,23 @@
##
# @NetdevUserOptions:
#
# Use the user mode network stack which requires no administrator privilege to
# run.
# Use the user mode network stack which requires no administrator
# privilege to run.
#
# @hostname: client hostname reported by the builtin DHCP server
#
# @restrict: isolate the guest from the host
#
# @ipv4: whether to support IPv4, default true for enabled
# (since 2.6)
# @ipv4: whether to support IPv4, default true for enabled (since 2.6)
#
# @ipv6: whether to support IPv6, default true for enabled
# (since 2.6)
# @ipv6: whether to support IPv6, default true for enabled (since 2.6)
#
# @ip: legacy parameter, use net= instead
#
# @net: IP network address that the guest will see, in the
# form addr[/netmask] The netmask is optional, and can be
# either in the form a.b.c.d or as a number of valid top-most
# bits. Default is 10.0.2.0/24.
# @net: IP network address that the guest will see, in the form
# addr[/netmask] The netmask is optional, and can be either in the
# form a.b.c.d or as a number of valid top-most bits. Default is
# 10.0.2.0/24.
#
# @host: guest-visible address of the host
#
@ -135,34 +130,34 @@
# @bootfile: BOOTP filename, for use with tftp=
#
# @dhcpstart: the first of the 16 IPs the built-in DHCP server can
# assign
# assign
#
# @dns: guest-visible address of the virtual nameserver
#
# @dnssearch: list of DNS suffixes to search, passed as DHCP option
# to the guest
# @dnssearch: list of DNS suffixes to search, passed as DHCP option to
# the guest
#
# @domainname: guest-visible domain name of the virtual nameserver
# (since 3.0)
# (since 3.0)
#
# @ipv6-prefix: IPv6 network prefix (default is fec0::) (since
# 2.6). The network prefix is given in the usual
# hexadecimal IPv6 address notation.
# @ipv6-prefix: IPv6 network prefix (default is fec0::) (since 2.6).
# The network prefix is given in the usual hexadecimal IPv6
# address notation.
#
# @ipv6-prefixlen: IPv6 network prefix length (default is 64)
# (since 2.6)
# @ipv6-prefixlen: IPv6 network prefix length (default is 64) (since
# 2.6)
#
# @ipv6-host: guest-visible IPv6 address of the host (since 2.6)
#
# @ipv6-dns: guest-visible IPv6 address of the virtual
# nameserver (since 2.6)
# @ipv6-dns: guest-visible IPv6 address of the virtual nameserver
# (since 2.6)
#
# @smb: root directory of the built-in SMB server
#
# @smbserver: IP address of the built-in SMB server
#
# @hostfwd: redirect incoming TCP or UDP host connections to guest
# endpoints
# endpoints
#
# @guestfwd: forward guest TCP connections
#
@ -205,7 +200,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
#
@ -215,7 +210,7 @@
#
# @helper: command to execute to configure bridge
#
# @sndbuf: send buffer limit. Understands [TGMKkb] suffixes.
# @sndbuf: send buffer limit. Understands [TGMKkb] suffixes.
#
# @vnet_hdr: enable the IFF_VNET_HDR flag on the tap interface
#
@ -224,14 +219,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)
# @poll-us: maximum number of microseconds that could be spent on busy
# polling for tap (since 2.7)
#
# Since: 1.2
##
@ -303,9 +298,8 @@
#
# @counter: have sequence counter
#
# @pincounter: pin sequence counter to zero -
# workaround for buggy implementations or
# networks with packet reorder
# @pincounter: pin sequence counter to zero - workaround for buggy
# implementations or networks with packet reorder
#
# @txcookie: 32 or 64 bit transmit cookie
#
@ -313,11 +307,11 @@
#
# @txsession: 32 bit transmit session
#
# @rxsession: 32 bit receive session - if not specified
# set to the same value as transmit
# @rxsession: 32 bit receive session - if not specified set to the
# same value as transmit
#
# @offset: additional offset - allows the insertion of
# additional application-specific data before the packet payload
# @offset: additional offset - allows the insertion of additional
# application-specific data before the packet payload
#
# Since: 2.1
##
@ -382,7 +376,9 @@
# Connect two or more net clients through a software hub.
#
# @hubid: hub identifier number
# @netdev: used to connect hub to a netdev instead of a device (since 2.12)
#
# @netdev: used to connect hub to a netdev instead of a device (since
# 2.12)
#
# Since: 1.2
##
@ -396,12 +392,12 @@
#
# Connect a client to a netmap-enabled NIC or to a VALE switch port
#
# @ifname: Either the name of an existing network interface supported by
# netmap, or the name of a VALE port (created on the fly).
# A VALE port name is in the form 'valeXXX:YYY', where XXX and
# YYY are non-negative integers. XXX identifies a switch and
# YYY identifies a port of the switch. VALE ports having the
# same XXX are therefore connected to the same switch.
# @ifname: Either the name of an existing network interface supported
# by netmap, or the name of a VALE port (created on the fly). A
# VALE port name is in the form 'valeXXX:YYY', where XXX and YYY
# are non-negative integers. XXX identifies a switch and YYY
# identifies a port of the switch. VALE ports having the same XXX
# are therefore connected to the same switch.
#
# @devname: path of the netmap device (default: '/dev/netmap').
#
@ -422,7 +418,7 @@
# @vhostforce: vhost on for non-MSIX virtio guests (default: false).
#
# @queues: number of queues to be created for multiqueue vhost-user
# (default: 1) (Since 2.5)
# (default: 1) (Since 2.5)
#
# Since: 2.1
##
@ -437,21 +433,21 @@
#
# Vhost-vdpa network backend
#
# vDPA device is a device that uses a datapath which complies with the virtio
# specifications with a vendor specific control path.
# vDPA device is a device that uses a datapath which complies with the
# virtio specifications with a vendor specific control path.
#
# @vhostdev: path of vhost-vdpa device
# (default:'/dev/vhost-vdpa-0')
# @vhostdev: path of vhost-vdpa device (default:'/dev/vhost-vdpa-0')
#
# @vhostfd: file descriptor of an already opened vhost vdpa device
#
# @queues: number of queues to be created for multiqueue vhost-vdpa
# (default: 1)
# (default: 1)
#
# @x-svq: Start device with (experimental) shadow virtqueue. (Since 7.1)
# (default: false)
# @x-svq: Start device with (experimental) shadow virtqueue. (Since
# 7.1) (default: false)
#
# Features:
#
# @unstable: Member @x-svq is experimental.
#
# Since: 5.1
@ -472,31 +468,28 @@
# interfaces that are in host mode and also with the host.
#
# @start-address: The starting IPv4 address to use for the interface.
# Must be in the private IP range (RFC 1918). Must be
# specified along with @end-address and @subnet-mask.
# This address is used as the gateway address. The
# subsequent address up to and including end-address are
# placed in the DHCP pool.
# Must be in the private IP range (RFC 1918). Must be specified
# along with @end-address and @subnet-mask. This address is used
# as the gateway address. The subsequent address up to and
# including end-address are placed in the DHCP pool.
#
# @end-address: The DHCP IPv4 range end address to use for the
# interface. Must be in the private IP range (RFC 1918).
# Must be specified along with @start-address and
# @subnet-mask.
# interface. Must be in the private IP range (RFC 1918). Must be
# specified along with @start-address and @subnet-mask.
#
# @subnet-mask: The IPv4 subnet mask to use on the interface. Must
# be specified along with @start-address and @subnet-mask.
# @subnet-mask: The IPv4 subnet mask to use on the interface. Must be
# specified along with @start-address and @subnet-mask.
#
# @isolated: Enable isolation for this interface. Interface isolation
# ensures that vmnet interface is not able to communicate
# with any other vmnet interfaces. Only communication with
# host is allowed. Requires at least macOS Big Sur 11.0.
# @isolated: Enable isolation for this interface. Interface isolation
# ensures that vmnet interface is not able to communicate with any
# other vmnet interfaces. Only communication with host is
# allowed. Requires at least macOS Big Sur 11.0.
#
# @net-uuid: The identifier (UUID) to uniquely identify the isolated
# network vmnet interface should be added to. If
# set, no DHCP service is provided for this interface and
# network communication is allowed only with other interfaces
# added to this network identified by the UUID. Requires
# at least macOS Big Sur 11.0.
# network vmnet interface should be added to. If set, no DHCP
# service is provided for this interface and network communication
# is allowed only with other interfaces added to this network
# identified by the UUID. Requires at least macOS Big Sur 11.0.
#
# Since: 7.1
##
@ -515,34 +508,33 @@
# vmnet (shared mode) network backend.
#
# Allows traffic originating from the vmnet interface to reach the
# Internet through a network address translator (NAT).
# The vmnet interface can communicate with the host and with
# other shared mode interfaces on the same subnet. If no DHCP
# settings, subnet mask and IPv6 prefix specified, the interface can
# communicate with any of other interfaces in shared mode.
# Internet through a network address translator (NAT). The vmnet
# interface can communicate with the host and with other shared mode
# interfaces on the same subnet. If no DHCP settings, subnet mask and
# IPv6 prefix specified, the interface can communicate with any of
# other interfaces in shared mode.
#
# @start-address: The starting IPv4 address to use for the interface.
# Must be in the private IP range (RFC 1918). Must be
# specified along with @end-address and @subnet-mask.
# This address is used as the gateway address. The
# subsequent address up to and including end-address are
# placed in the DHCP pool.
# Must be in the private IP range (RFC 1918). Must be specified
# along with @end-address and @subnet-mask. This address is used
# as the gateway address. The subsequent address up to and
# including end-address are placed in the DHCP pool.
#
# @end-address: The DHCP IPv4 range end address to use for the
# interface. Must be in the private IP range (RFC 1918).
# Must be specified along with @start-address and @subnet-mask.
# interface. Must be in the private IP range (RFC 1918). Must be
# specified along with @start-address and @subnet-mask.
#
# @subnet-mask: The IPv4 subnet mask to use on the interface. Must
# be specified along with @start-address and @subnet-mask.
# @subnet-mask: The IPv4 subnet mask to use on the interface. Must be
# specified along with @start-address and @subnet-mask.
#
# @isolated: Enable isolation for this interface. Interface isolation
# ensures that vmnet interface is not able to communicate
# with any other vmnet interfaces. Only communication with
# host is allowed. Requires at least macOS Big Sur 11.0.
# @isolated: Enable isolation for this interface. Interface isolation
# ensures that vmnet interface is not able to communicate with any
# other vmnet interfaces. Only communication with host is
# allowed. Requires at least macOS Big Sur 11.0.
#
# @nat66-prefix: The IPv6 prefix to use into guest network. Must be a
# unique local address i.e. start with fd00::/8 and have
# length of 64.
# @nat66-prefix: The IPv6 prefix to use into guest network. Must be a
# unique local address i.e. start with fd00::/8 and have length of
# 64.
#
# Since: 7.1
##
@ -564,10 +556,10 @@
#
# @ifname: The name of the physical interface to be bridged.
#
# @isolated: Enable isolation for this interface. Interface isolation
# ensures that vmnet interface is not able to communicate
# with any other vmnet interfaces. Only communication with
# host is allowed. Requires at least macOS Big Sur 11.0.
# @isolated: Enable isolation for this interface. Interface isolation
# ensures that vmnet interface is not able to communicate with any
# other vmnet interfaces. Only communication with host is
# allowed. Requires at least macOS Big Sur 11.0.
#
# Since: 7.1
##
@ -582,13 +574,14 @@
#
# Configuration info for stream socket netdev
#
# @addr: socket address to listen on (server=true)
# or connect to (server=false)
# @addr: socket address to listen on (server=true) or connect to
# (server=false)
#
# @server: create server socket (default: false)
# @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 8.0)
#
# @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 8.0)
#
# Only SocketAddress types 'unix', 'inet' and 'fd' are supported.
#
@ -606,13 +599,14 @@
# Configuration info for datagram socket netdev.
#
# @remote: remote address
#
# @local: local address
#
# Only SocketAddress types 'unix', 'inet' and 'fd' are supported.
#
# If remote address is present and it's a multicast address, local address
# is optional. Otherwise local address is required and remote address is
# optional.
# If remote address is present and it's a multicast address, local
# address is optional. Otherwise local address is required and remote
# address is optional.
#
# .. table:: Valid parameters combination table
# :widths: auto
@ -764,9 +758,9 @@
# @name: net client name
#
# Returns: list of @RxFilterInfo for all NICs (or for the given NIC).
# Returns an error if the given @name doesn't exist, or given
# NIC doesn't support rx-filter querying, or given net client
# isn't a NIC.
# Returns an error if the given @name doesn't exist, or given NIC
# doesn't support rx-filter querying, or given net client isn't a
# NIC.
#
# Since: 1.6
#
@ -798,7 +792,6 @@
# }
# ]
# }
#
##
{ 'command': 'query-rx-filter',
'data': { '*name': 'str' },
@ -807,8 +800,8 @@
##
# @NIC_RX_FILTER_CHANGED:
#
# Emitted once until the 'query-rx-filter' command is executed, the first event
# will always be emitted
# Emitted once until the 'query-rx-filter' command is executed, the
# first event will always be emitted
#
# @name: net client name
#
@ -822,7 +815,6 @@
# "data": { "name": "vnet0",
# "path": "/machine/peripheral/vnet0/virtio-backend" },
# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
#
##
{ 'event': 'NIC_RX_FILTER_CHANGED',
'data': { '*name': 'str', 'path': 'str' } }
@ -833,7 +825,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
#
@ -841,12 +833,12 @@
#
# @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)
# @interfaces: An optional list of interface names, which restricts
# the 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
##
@ -862,8 +854,9 @@
##
# @announce-self:
#
# Trigger generation of broadcast RARP frames to update network switches.
# This can be useful when network bonds fail-over the active slave.
# Trigger generation of broadcast RARP frames to update network
# switches. This can be useful when network bonds fail-over the
# active slave.
#
# Example:
#
@ -881,9 +874,10 @@
##
# @FAILOVER_NEGOTIATED:
#
# Emitted when VIRTIO_NET_F_STANDBY was enabled during feature negotiation.
# Failover primary devices which were hidden (not hotplugged when requested)
# before will now be hotplugged by the virtio-net standby device.
# Emitted when VIRTIO_NET_F_STANDBY was enabled during feature
# negotiation. Failover primary devices which were hidden (not
# hotplugged when requested) before will now be hotplugged by the
# virtio-net standby device.
#
# @device-id: QEMU device id of the unplugged device
#
@ -894,7 +888,6 @@
# <- { "event": "FAILOVER_NEGOTIATED",
# "data": { "device-id": "net1" },
# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
#
##
{ 'event': 'FAILOVER_NEGOTIATED',
'data': {'device-id': 'str'} }
@ -905,6 +898,7 @@
# Emitted when the netdev stream backend is connected
#
# @netdev-id: QEMU netdev id that is connected
#
# @addr: The destination address
#
# Since: 7.2
@ -921,7 +915,6 @@
# "data": { "netdev-id": "netdev0",
# "addr": { "path": "/tmp/qemu0", "type": "unix" } },
# "timestamp": { "seconds": 1666269706, "microseconds": 413651 } }
#
##
{ 'event': 'NETDEV_STREAM_CONNECTED',
'data': { 'netdev-id': 'str',
@ -941,7 +934,6 @@
# <- { 'event': 'NETDEV_STREAM_DISCONNECTED',
# 'data': {'netdev-id': 'netdev0'},
# 'timestamp': {'seconds': 1663330937, 'microseconds': 526695} }
#
##
{ 'event': 'NETDEV_STREAM_DISCONNECTED',
'data': { 'netdev-id': 'str' } }

35
qapi/pci.json
View File

@ -29,8 +29,9 @@
#
# @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
#
@ -49,21 +50,21 @@
#
# Information about a bus of a PCI Bridge device
#
# @number: primary bus interface number. This should be the number of the
# bus the device resides on.
# @number: primary bus interface number. This should be the number of
# the bus the device resides on.
#
# @secondary: secondary bus interface number. This is the number of the
# main bus for the bridge
# @secondary: secondary bus interface number. This is the number of
# the main bus for the bridge
#
# @subordinate: This is the highest number bus that resides below the
# bridge.
# bridge.
#
# @io_range: The PIO range for all devices on this bridge
#
# @memory_range: The MMIO range for all devices on this bridge
#
# @prefetchable_range: The range of prefetchable MMIO for all devices on
# this bridge
# @prefetchable_range: The range of prefetchable MMIO for all devices
# on this bridge
#
# Since: 2.4
##
@ -145,8 +146,8 @@
#
# @regions: a list of the PCI I/O regions associated with the device
#
# Notes: the contents of @class_info.desc are not stable and should only be
# treated as informational.
# Notes: the contents of @class_info.desc are not stable and should
# only be treated as informational.
#
# Since: 0.14
##
@ -174,10 +175,10 @@
#
# 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.
# 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.
#
# Since: 0.14
#
@ -310,7 +311,7 @@
# ]
# }
#
# Note: This example has been shortened as the real response is too long.
#
# Note: This example has been shortened as the real response is too
# long.
##
{ 'command': 'query-pci', 'returns': ['PciInfo'] }

25
qapi/qapi-schema.json
View File

@ -5,17 +5,20 @@
#
# This document describes all commands currently supported by QMP.
#
# Most of the time their usage is exactly the same as in the user Monitor, this
# means that any other document which also describe commands (the manpage,
# QEMU's manual, etc) can and should be consulted.
# Most of the time their usage is exactly the same as in the user
# Monitor, this means that any other document which also describe
# commands (the manpage, QEMU's manual, etc) can and should be
# consulted.
#
# QMP has two types of commands: regular and query commands. Regular commands
# usually change the Virtual Machine's state someway, while query commands just
# return information. The sections below are divided accordingly.
# QMP has two types of commands: regular and query commands. Regular
# commands usually change the Virtual Machine's state someway, while
# query commands just return information. The sections below are
# divided accordingly.
#
# It's important to observe that all communication examples are formatted in
# a reader-friendly way, so that they're easier to understand. However, in real
# protocol usage, they're emitted as a single line.
# It's important to observe that all communication examples are
# formatted in a reader-friendly way, so that they're easier to
# understand. However, in real protocol usage, they're emitted as a
# single line.
#
# Also, the following notation is used to denote data flow:
#
@ -26,8 +29,8 @@
# -> data issued by the Client
# <- Server data response
#
# Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for
# detailed information on the Server command and response formats.
# Please, refer to the QMP specification (docs/interop/qmp-spec.txt)
# for detailed information on the Server command and response formats.
##
{ 'include': 'pragma.json' }

63
qapi/qdev.json
View File

@ -17,11 +17,12 @@
#
# @typename: the type name of a device
#
# Returns: a list of ObjectPropertyInfo describing a devices properties
# 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.
# 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.
#
# Since: 1.2
##
@ -41,12 +42,14 @@
# @id: the device's ID, must be unique
#
# Features:
# @json-cli: If present, the "-device" command line option supports JSON
# syntax with a structure identical to the arguments of this
# command.
# @json-cli-hotplug: If present, the "-device" command line option supports JSON
# syntax without the reference counting leak that broke
# hot-unplug
#
# @json-cli: If present, the "-device" command line option supports
# JSON syntax with a structure identical to the arguments of this
# command.
#
# @json-cli-hotplug: If present, the "-device" command line option
# supports JSON syntax without the reference counting leak that
# broke hot-unplug
#
# Notes:
#
@ -68,9 +71,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
##
@ -86,17 +89,18 @@
#
# @id: the device's ID or QOM path
#
# Returns: Nothing on success
# If @id is not a valid device, DeviceNotFound
# Returns: Nothing on success If @id is not a valid device,
# DeviceNotFound
#
# Notes: When this command completes, the device may not be removed from the
# guest. Hot removal is an operation that requires guest cooperation.
# This command merely requests that the guest begin the hot removal
# process. Completion of the device removal process is signaled with a
# DEVICE_DELETED event. Guest reset will automatically complete removal
# for all devices. If a guest-side error in the hot removal process is
# detected, the device will not be removed and a DEVICE_UNPLUG_GUEST_ERROR
# event is sent. Some errors cannot be detected.
# Notes: When this command completes, the device may not be removed
# from the guest. Hot removal is an operation that requires guest
# cooperation. This command merely requests that the guest begin
# the hot removal process. Completion of the device removal
# process is signaled with a DEVICE_DELETED event. Guest reset
# will automatically complete removal for all devices. If a
# guest-side error in the hot removal process is detected, the
# device will not be removed and a DEVICE_UNPLUG_GUEST_ERROR event
# is sent. Some errors cannot be detected.
#
# Since: 0.14
#
@ -109,16 +113,16 @@
# -> { "execute": "device_del",
# "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
# <- { "return": {} }
#
##
{ 'command': 'device_del', 'data': {'id': 'str'} }
##
# @DEVICE_DELETED:
#
# Emitted whenever the device removal completion is acknowledged by the guest.
# At this point, it's safe to reuse the specified device ID. Device removal can
# be initiated by the guest or by HMP/QMP commands.
# Emitted whenever the device removal completion is acknowledged by
# the guest. At this point, it's safe to reuse the specified device
# ID. Device removal can be initiated by the guest or by HMP/QMP
# commands.
#
# @device: the device's ID if it has one
#
@ -132,7 +136,6 @@
# "data": { "device": "virtio-net-pci-0",
# "path": "/machine/peripheral/virtio-net-pci-0" },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
#
##
{ 'event': 'DEVICE_DELETED',
'data': { '*device': 'str', 'path': 'str' } }
@ -140,7 +143,8 @@
##
# @DEVICE_UNPLUG_GUEST_ERROR:
#
# Emitted when a device hot unplug fails due to a guest reported error.
# Emitted when a device hot unplug fails due to a guest reported
# error.
#
# @device: the device's ID if it has one
#
@ -154,7 +158,6 @@
# "data": { "device": "core1",
# "path": "/machine/peripheral/core1" },
# "timestamp": { "seconds": 1615570772, "microseconds": 202844 } }
#
##
{ 'event': 'DEVICE_UNPLUG_GUEST_ERROR',
'data': { '*device': 'str', 'path': 'str' } }

404
qapi/qom.json
View File

@ -18,17 +18,20 @@
#
# @name: the name of the property
#
# @type: the type of the property. This will typically come in one of four
# forms:
# @type: the type of the property. This will typically come in one of
# four forms:
#
# 1) A primitive type such as 'u8', 'u16', 'bool', 'str', or 'double'.
# These types are mapped to the appropriate JSON type.
# 1) A primitive type such as 'u8', 'u16', 'bool', 'str', or
# 'double'. These types are mapped to the appropriate JSON
# type.
#
# 2) A child type in the form 'child<subtype>' where subtype is a qdev
# device type name. Child properties create the composition tree.
# 2) A child type in the form 'child<subtype>' where subtype is a
# qdev device type name. Child properties create the
# composition tree.
#
# 3) A link type in the form 'link<subtype>' where subtype is a qdev
# device type name. Link properties form the device model graph.
# 3) A link type in the form 'link<subtype>' where subtype is a
# qdev device type name. Link properties form the device model
# graph.
#
# @description: if specified, the description of the property.
#
@ -45,14 +48,14 @@
##
# @qom-list:
#
# This command will list any properties of a object given a path in the object
# model.
# This command will list any properties of a object given a path in
# the object model.
#
# @path: the path within the object model. See @qom-get for a description of
# this parameter.
# @path: the path within the object model. See @qom-get for a
# description of this parameter.
#
# Returns: a list of @ObjectPropertyInfo that describe the properties of the
# object.
# Returns: a list of @ObjectPropertyInfo that describe the properties
# of the object.
#
# Since: 1.2
#
@ -64,7 +67,6 @@
# { "name": "parallel0", "type": "child<chardev-vc>" },
# { "name": "serial0", "type": "child<chardev-vc>" },
# { "name": "mon0", "type": "child<chardev-stdio>" } ] }
#
##
{ 'command': 'qom-list',
'data': { 'path': 'str' },
@ -74,32 +76,31 @@
##
# @qom-get:
#
# This command will get a property from a object model path and return the
# value.
# This command will get a property from a object model path and return
# the value.
#
# @path: The path within the object model. There are two forms of supported
# paths--absolute and partial paths.
# @path: The path within the object model. There are two forms of
# supported paths--absolute and partial paths.
#
# Absolute paths are derived from the root object and can follow child<>
# or link<> properties. Since they can follow link<> properties, they
# can be arbitrarily long. Absolute paths look like absolute filenames
# and are prefixed with a leading slash.
# Absolute paths are derived from the root object and can follow
# child<> or link<> properties. Since they can follow link<>
# properties, they can be arbitrarily long. Absolute paths look
# like absolute filenames and are prefixed with a leading slash.
#
# Partial paths look like relative filenames. They do not begin
# with a prefix. The matching rules for partial paths are subtle but
# designed to make specifying objects easy. At each level of the
# composition tree, the partial path is matched as an absolute path.
# The first match is not returned. At least two matches are searched
# for. A successful result is only returned if only one match is
# found. If more than one match is found, a flag is return to
# indicate that the match was ambiguous.
# Partial paths look like relative filenames. They do not begin
# with a prefix. The matching rules for partial paths are subtle
# but designed to make specifying objects easy. At each level of
# the composition tree, the partial path is matched as an absolute
# path. The first match is not returned. At least two matches
# are searched for. A successful result is only returned if only
# one match is found. If more than one match is found, a flag is
# return to indicate that the match was ambiguous.
#
# @property: The property name to read
#
# Returns: The property value. The type depends on the property
# type. child<> and link<> properties are returned as #str
# pathnames. All integer property types (u8, u16, etc) are
# returned as #int.
# Returns: The property value. The type depends on the property type.
# child<> and link<> properties are returned as #str pathnames.
# All integer property types (u8, u16, etc) are returned as #int.
#
# Since: 1.2
#
@ -118,7 +119,6 @@
# "arguments": { "path": "unattached/sysbus",
# "property": "type" } }
# <- { "return": "System" }
#
##
{ 'command': 'qom-get',
'data': { 'path': 'str', 'property': 'str' },
@ -134,8 +134,8 @@
#
# @property: the property name to set
#
# @value: a value who's type is appropriate for the property type. See @qom-get
# for a description of type mapping.
# @value: a value who's type is appropriate for the property type.
# See @qom-get for a description of type mapping.
#
# Since: 1.2
#
@ -146,7 +146,6 @@
# "property": "graphics",
# "value": false } }
# <- { "return": {} }
#
##
{ 'command': 'qom-set',
'data': { 'path': 'str', 'property': 'str', 'value': 'any' },
@ -160,7 +159,7 @@
# @name: the type name found in the search
#
# @abstract: the type is abstract and can't be directly instantiated.
# Omitted if false. (since 2.10)
# Omitted if false. (since 2.10)
#
# @parent: Name of parent type, if any (since 2.10)
#
@ -174,11 +173,13 @@
#
# This command will return a list of types given search parameters
#
# @implements: if specified, only return types that implement this type name
# @implements: if specified, only return types that implement this
# type name
#
# @abstract: if true, include abstract types in the results
#
# Returns: a list of @ObjectTypeInfo or an empty list if no results are found
# Returns: a list of @ObjectTypeInfo or an empty list if no results
# are found
#
# Since: 1.1
##
@ -194,9 +195,9 @@
#
# @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.
# 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.
#
# Returns: a list of ObjectPropertyInfo describing object properties
#
@ -214,7 +215,8 @@
#
# @if: interface name of the host system CAN bus to connect to
#
# @canbus: object ID of the can-bus object to connect to the host interface
# @canbus: object ID of the can-bus object to connect to the host
# interface
#
# Since: 2.12
##
@ -227,34 +229,35 @@
#
# Properties for colo-compare objects.
#
# @primary_in: name of the character device backend to use for the primary
# input (incoming packets are redirected to @outdev)
# @primary_in: name of the character device backend to use for the
# primary input (incoming packets are redirected to @outdev)
#
# @secondary_in: name of the character device backend to use for secondary
# input (incoming packets are only compared to the input on
# @primary_in and then dropped)
# @secondary_in: name of the character device backend to use for
# secondary input (incoming packets are only compared to the input
# on @primary_in and then dropped)
#
# @outdev: name of the character device backend to use for output
#
# @iothread: name of the iothread to run in
#
# @notify_dev: name of the character device backend to be used to communicate
# with the remote colo-frame (only for Xen COLO)
# @notify_dev: name of the character device backend to be used to
# communicate with the remote colo-frame (only for Xen COLO)
#
# @compare_timeout: the maximum time to hold a packet from @primary_in for
# comparison with an incoming packet on @secondary_in in
# milliseconds (default: 3000)
# @compare_timeout: the maximum time to hold a packet from @primary_in
# for comparison with an incoming packet on @secondary_in in
# milliseconds (default: 3000)
#
# @expired_scan_cycle: the interval at which colo-compare checks whether
# packets from @primary have timed out, in milliseconds
# (default: 3000)
# @expired_scan_cycle: the interval at which colo-compare checks
# whether packets from @primary have timed out, in milliseconds
# (default: 3000)
#
# @max_queue_size: the maximum number of packets to keep in the queue for
# comparing with incoming packets from @secondary_in. If the
# queue is full and additional packets are received, the
# additional packets are dropped. (default: 1024)
# @max_queue_size: the maximum number of packets to keep in the queue
# for comparing with incoming packets from @secondary_in. If the
# queue is full and additional packets are received, the
# additional packets are dropped. (default: 1024)
#
# @vnet_hdr_support: if true, vnet header support is enabled (default: false)
# @vnet_hdr_support: if true, vnet header support is enabled
# (default: false)
#
# Since: 2.8
##
@ -272,11 +275,12 @@
##
# @CryptodevBackendProperties:
#
# Properties for cryptodev-backend and cryptodev-backend-builtin objects.
# Properties for cryptodev-backend and cryptodev-backend-builtin
# objects.
#
# @queues: the number of queues for the cryptodev backend. Ignored for
# cryptodev-backend and must be 1 for cryptodev-backend-builtin.
# (default: 1)
# @queues: the number of queues for the cryptodev backend. Ignored
# for cryptodev-backend and must be 1 for
# cryptodev-backend-builtin. (default: 1)
#
# @throttle-bps: limit total bytes per second (Since 8.0)
#
@ -294,8 +298,8 @@
#
# Properties for cryptodev-vhost-user objects.
#
# @chardev: the name of a Unix domain socket character device that connects to
# the vhost-user server
# @chardev: the name of a Unix domain socket character device that
# connects to the vhost-user server
#
# Since: 2.12
##
@ -310,8 +314,8 @@
#
# @addr: the name of the DBus bus to connect to
#
# @id-list: a comma separated list of DBus IDs of helpers whose data should be
# included in the VM state on migration
# @id-list: a comma separated list of DBus IDs of helpers whose data
# should be included in the VM state on migration
#
# Since: 5.0
##
@ -322,7 +326,8 @@
##
# @NetfilterInsert:
#
# Indicates where to insert a netfilter relative to a given other filter.
# Indicates where to insert a netfilter relative to a given other
# filter.
#
# @before: insert before the specified filter
#
@ -342,20 +347,20 @@
#
# @queue: indicates which queue(s) to filter (default: all)
#
# @status: indicates whether the filter is enabled ("on") or disabled ("off")
# (default: "on")
# @status: indicates whether the filter is enabled ("on") or disabled
# ("off") (default: "on")
#
# @position: specifies where the filter should be inserted in the filter list.
# "head" means the filter is inserted at the head of the filter list,
# before any existing filters.
# "tail" means the filter is inserted at the tail of the filter list,
# behind any existing filters (default).
# "id=<id>" means the filter is inserted before or behind the filter
# specified by <id>, depending on the @insert property.
# (default: "tail")
# @position: specifies where the filter should be inserted in the
# filter list. "head" means the filter is inserted at the head of
# the filter list, before any existing filters. "tail" means the
# filter is inserted at the tail of the filter list, behind any
# existing filters (default). "id=<id>" means the filter is
# inserted before or behind the filter specified by <id>,
# depending on the @insert property. (default: "tail")
#
# @insert: where to insert the filter relative to the filter given in @position.
# Ignored if @position is "head" or "tail". (default: behind)
# @insert: where to insert the filter relative to the filter given in
# @position. Ignored if @position is "head" or "tail".
# (default: behind)
#
# Since: 2.5
##
@ -371,8 +376,9 @@
#
# Properties for filter-buffer objects.
#
# @interval: a non-zero interval in microseconds. All packets arriving in the
# given interval are delayed until the end of the interval.
# @interval: a non-zero interval in microseconds. All packets
# arriving in the given interval are delayed until the end of the
# interval.
#
# Since: 2.5
##
@ -387,7 +393,8 @@
#
# @file: the filename where the dumped packets should be stored
#
# @maxlen: maximum number of bytes in a packet that are stored (default: 65536)
# @maxlen: maximum number of bytes in a packet that are stored
# (default: 65536)
#
# Since: 2.5
##
@ -401,10 +408,11 @@
#
# Properties for filter-mirror objects.
#
# @outdev: the name of a character device backend to which all incoming packets
# are mirrored
# @outdev: the name of a character device backend to which all
# incoming packets are mirrored
#
# @vnet_hdr_support: if true, vnet header support is enabled (default: false)
# @vnet_hdr_support: if true, vnet header support is enabled
# (default: false)
#
# Since: 2.6
##
@ -418,16 +426,17 @@
#
# Properties for filter-redirector objects.
#
# At least one of @indev or @outdev must be present. If both are present, they
# must not refer to the same character device backend.
# At least one of @indev or @outdev must be present. If both are
# present, they must not refer to the same character device backend.
#
# @indev: the name of a character device backend from which packets are
# received and redirected to the filtered network device
# @indev: the name of a character device backend from which packets
# are received and redirected to the filtered network device
#
# @outdev: the name of a character device backend to which all incoming packets
# are redirected
# @outdev: the name of a character device backend to which all
# incoming packets are redirected
#
# @vnet_hdr_support: if true, vnet header support is enabled (default: false)
# @vnet_hdr_support: if true, vnet header support is enabled
# (default: false)
#
# Since: 2.6
##
@ -442,7 +451,8 @@
#
# Properties for filter-rewriter objects.
#
# @vnet_hdr_support: if true, vnet header support is enabled (default: false)
# @vnet_hdr_support: if true, vnet header support is enabled
# (default: false)
#
# Since: 2.8
##
@ -455,17 +465,18 @@
#
# Properties for input-barrier objects.
#
# @name: the screen name as declared in the screens section of barrier.conf
# @name: the screen name as declared in the screens section of
# barrier.conf
#
# @server: hostname of the Barrier server (default: "localhost")
#
# @port: TCP port of the Barrier server (default: "24800")
#
# @x-origin: x coordinate of the leftmost pixel on the guest screen
# (default: "0")
# (default: "0")
#
# @y-origin: y coordinate of the topmost pixel on the guest screen
# (default: "0")
# (default: "0")
#
# @width: the width of secondary screen in pixels (default: "1920")
#
@ -489,13 +500,13 @@
#
# @evdev: the path of the host evdev device to use
#
# @grab_all: if true, grab is toggled for all devices (e.g. both keyboard and
# mouse) instead of just one device (default: false)
# @grab_all: if true, grab is toggled for all devices (e.g. both
# keyboard and mouse) instead of just one device (default: false)
#
# @repeat: enables auto-repeat events (default: false)
#
# @grab-toggle: the key or key combination that toggles device grab
# (default: ctrl-ctrl)
# (default: ctrl-ctrl)
#
# Since: 2.6
##
@ -510,15 +521,15 @@
#
# Common properties for event loops
#
# @aio-max-batch: maximum number of requests in a batch for the AIO engine,
# 0 means that the engine will use its default.
# (default: 0)
# @aio-max-batch: maximum number of requests in a batch for the AIO
# engine, 0 means that the engine will use its default.
# (default: 0)
#
# @thread-pool-min: minimum number of threads reserved in the thread pool
# (default:0)
# @thread-pool-min: minimum number of threads reserved in the thread
# pool (default:0)
#
# @thread-pool-max: maximum number of threads the thread pool can contain
# (default:64)
# @thread-pool-max: maximum number of threads the thread pool can
# contain (default:64)
#
# Since: 7.1
##
@ -532,17 +543,17 @@
#
# Properties for iothread objects.
#
# @poll-max-ns: the maximum number of nanoseconds to busy wait for events.
# 0 means polling is disabled (default: 32768 on POSIX hosts,
# 0 otherwise)
# @poll-max-ns: the maximum number of nanoseconds to busy wait for
# events. 0 means polling is disabled (default: 32768 on POSIX
# hosts, 0 otherwise)
#
# @poll-grow: the multiplier used to increase the polling time when the
# algorithm detects it is missing events due to not polling long
# enough. 0 selects a default behaviour (default: 0)
# @poll-grow: the multiplier used to increase the polling time when
# the algorithm detects it is missing events due to not polling
# long enough. 0 selects a default behaviour (default: 0)
#
# @poll-shrink: the divisor used to decrease the polling time when the
# algorithm detects it is spending too long polling without
# encountering events. 0 selects a default behaviour (default: 0)
# algorithm detects it is spending too long polling without
# encountering events. 0 selects a default behaviour (default: 0)
#
# The @aio-max-batch option is available since 6.1.
#
@ -570,11 +581,11 @@
#
# Properties for objects of classes derived from memory-backend.
#
# @merge: if true, mark the memory as mergeable (default depends on the machine
# type)
# @merge: if true, mark the memory as mergeable (default depends on
# the machine type)
#
# @dump: if true, include the memory in core dumps (default depends on the
# machine type)
# @dump: if true, include the memory in core dumps (default depends on
# the machine type)
#
# @host-nodes: the list of NUMA host nodes to bind the memory to
#
@ -582,31 +593,31 @@
#
# @prealloc: if true, preallocate memory (default: false)
#
# @prealloc-threads: number of CPU threads to use for prealloc (default: 1)
# @prealloc-threads: number of CPU threads to use for prealloc
# (default: 1)
#
# @prealloc-context: thread context to use for creation of preallocation threads
# (default: none) (since 7.2)
# @prealloc-context: thread context to use for creation of
# preallocation threads (default: none) (since 7.2)
#
# @share: if false, the memory is private to QEMU; if true, it is shared
# (default: false)
# @share: if false, the memory is private to QEMU; if true, it is
# shared (default: false)
#
# @reserve: if true, reserve swap space (or huge pages) if applicable
# (default: true) (since 6.1)
# (default: true) (since 6.1)
#
# @size: size of the memory region in bytes
#
# @x-use-canonical-path-for-ramblock-id: if true, the canonical path is used
# for ramblock-id. Disable this for 4.0
# machine types or older to allow
# migration with newer QEMU versions.
# (default: false generally,
# but true for machine types <= 4.0)
# @x-use-canonical-path-for-ramblock-id: if true, the canonical path
# is used for ramblock-id. Disable this for 4.0 machine types or
# older to allow migration with newer QEMU versions.
# (default: false generally, but true for machine types <= 4.0)
#
# Note: prealloc=true and reserve=false cannot be set at the same time. With
# reserve=true, the behavior depends on the operating system: for example,
# Linux will not reserve swap space for shared file mappings --
# "not applicable". In contrast, reserve=false will bail out if it cannot
# be configured accordingly.
# Note: prealloc=true and reserve=false cannot be set at the same
# time. With reserve=true, the behavior depends on the operating
# system: for example, Linux will not reserve swap space for
# shared file mappings -- "not applicable". In contrast,
# reserve=false will bail out if it cannot be configured
# accordingly.
#
# Since: 2.1
##
@ -628,27 +639,29 @@
#
# Properties for memory-backend-file objects.
#
# @align: the base address alignment when QEMU mmap(2)s @mem-path. Some
# backend stores specified by @mem-path require an alignment different
# than the default one used by QEMU, e.g. the device DAX /dev/dax0.0
# requires 2M alignment rather than 4K. In such cases, users can
# specify the required alignment via this option.
# 0 selects a default alignment (currently the page size). (default: 0)
# @align: the base address alignment when QEMU mmap(2)s @mem-path.
# Some backend stores specified by @mem-path require an alignment
# different than the default one used by QEMU, e.g. the device DAX
# /dev/dax0.0 requires 2M alignment rather than 4K. In such cases,
# users can specify the required alignment via this option. 0
# selects a default alignment (currently the page size).
# (default: 0)
#
# @discard-data: if true, the file contents can be destroyed when QEMU exits,
# to avoid unnecessarily flushing data to the backing file. Note
# that @discard-data is only an optimization, and QEMU might
# not discard file contents if it aborts unexpectedly or is
# terminated using SIGKILL. (default: false)
# @discard-data: if true, the file contents can be destroyed when QEMU
# exits, to avoid unnecessarily flushing data to the backing file.
# Note that @discard-data is only an optimization, and QEMU might
# not discard file contents if it aborts unexpectedly or is
# terminated using SIGKILL. (default: false)
#
# @mem-path: the path to either a shared memory or huge page filesystem mount
# @mem-path: the path to either a shared memory or huge page
# filesystem mount
#
# @pmem: specifies whether the backing file specified by @mem-path is in
# host persistent memory that can be accessed using the SNIA NVM
# programming model (e.g. Intel NVDIMM).
# @pmem: specifies whether the backing file specified by @mem-path is
# in host persistent memory that can be accessed using the SNIA
# NVM programming model (e.g. Intel NVDIMM).
#
# @readonly: if true, the backing file is opened read-only; if false, it is
# opened read-write. (default: false)
# @readonly: if true, the backing file is opened read-only; if false,
# it is opened read-write. (default: false)
#
# Since: 2.1
##
@ -667,16 +680,16 @@
#
# The @share boolean option is true by default with memfd.
#
# @hugetlb: if true, the file to be created resides in the hugetlbfs filesystem
# (default: false)
# @hugetlb: if true, the file to be created resides in the hugetlbfs
# filesystem (default: false)
#
# @hugetlbsize: the hugetlb page size on systems that support multiple hugetlb
# page sizes (it must be a power of 2 value supported by the
# system). 0 selects a default page size. This option is ignored
# if @hugetlb is false. (default: 0)
# @hugetlbsize: the hugetlb page size on systems that support multiple
# hugetlb page sizes (it must be a power of 2 value supported by
# the system). 0 selects a default page size. This option is
# ignored if @hugetlb is false. (default: 0)
#
# @seal: if true, create a sealed-file, which will block further resizing of
# the memory (default: true)
# @seal: if true, create a sealed-file, which will block further
# resizing of the memory (default: true)
#
# Since: 2.12
##
@ -708,7 +721,8 @@
#
# Properties for pr-manager-helper objects.
#
# @path: the path to a Unix domain socket for connecting to the external helper
# @path: the path to a Unix domain socket for connecting to the
# external helper
#
# Since: 2.11
##
@ -737,7 +751,8 @@
#
# @fd: file descriptor name previously passed via 'getfd' command
#
# @devid: the id of the device to be associated with the file descriptor
# @devid: the id of the device to be associated with the file
# descriptor
#
# Since: 6.0
##
@ -763,13 +778,15 @@
#
# Properties for objects of classes derived from rng.
#
# @opened: if true, the device is opened immediately when applying this option
# and will probably fail when processing the next option. Don't use;
# only provided for compatibility. (default: false)
# @opened: if true, the device is opened immediately when applying
# this option and will probably fail when processing the next
# option. Don't use; only provided for compatibility.
# (default: false)
#
# Features:
# @deprecated: Member @opened is deprecated. Setting true doesn't make sense,
# and false is already the default.
#
# @deprecated: Member @opened is deprecated. Setting true doesn't
# make sense, and false is already the default.
#
# Since: 1.3
##
@ -781,8 +798,8 @@
#
# Properties for rng-egd objects.
#
# @chardev: the name of a character device backend that provides the connection
# to the RNG daemon
# @chardev: the name of a character device backend that provides the
# connection to the RNG daemon
#
# Since: 1.3
##
@ -795,8 +812,8 @@
#
# Properties for rng-random objects.
#
# @filename: the filename of the device on the host to obtain entropy from
# (default: "/dev/urandom")
# @filename: the filename of the device on the host to obtain entropy
# from (default: "/dev/urandom")
#
# Since: 1.3
##
@ -822,11 +839,11 @@
# @cbitpos: C-bit location in page table entry (default: 0)
#
# @reduced-phys-bits: number of bits in physical addresses that become
# unavailable when SEV is enabled
# unavailable when SEV is enabled
#
# @kernel-hashes: if true, add hashes of kernel/initrd/cmdline to a
# designated guest firmware page for measured boot
# with -kernel (default: false) (since 6.2)
# designated guest firmware page for measured boot with -kernel
# (default: false) (since 6.2)
#
# Since: 2.12
##
@ -845,15 +862,15 @@
#
# Properties for thread context objects.
#
# @cpu-affinity: the list of host CPU numbers used as CPU affinity for all
# threads created in the thread context (default: QEMU main
# thread CPU affinity)
# @cpu-affinity: the list of host CPU numbers used as CPU affinity for
# all threads created in the thread context (default: QEMU main
# thread CPU affinity)
#
# @node-affinity: the list of host node numbers that will be resolved to a
# list of host CPU numbers used as CPU affinity. This is a
# shortcut for specifying the list of host CPU numbers
# belonging to the host nodes manually by setting
# @cpu-affinity. (default: QEMU main thread affinity)
# @node-affinity: the list of host node numbers that will be resolved
# to a list of host CPU numbers used as CPU affinity. This is a
# shortcut for specifying the list of host CPU numbers belonging
# to the host nodes manually by setting @cpu-affinity.
# (default: QEMU main thread affinity)
#
# Since: 7.2
##
@ -866,6 +883,7 @@
# @ObjectType:
#
# Features:
#
# @unstable: Member @x-remote-object is experimental.
#
# Since: 6.0
@ -998,8 +1016,8 @@
#
# Create a QOM object.
#
# Returns: Nothing on success
# Error if @qom-type is not a valid class name
# Returns: Nothing on success Error if @qom-type is not a valid class
# name
#
# Since: 2.0
#
@ -1009,7 +1027,6 @@
# "arguments": { "qom-type": "rng-random", "id": "rng1",
# "filename": "/dev/hwrng" } }
# <- { "return": {} }
#
##
{ 'command': 'object-add', 'data': 'ObjectOptions', 'boxed': true,
'allow-preconfig': true }
@ -1021,8 +1038,8 @@
#
# @id: the name of the QOM object to remove
#
# Returns: Nothing on success
# Error if @id is not a valid id for a QOM object
# Returns: Nothing on success Error if @id is not a valid id for a QOM
# object
#
# Since: 2.0
#
@ -1030,7 +1047,6 @@
#
# -> { "execute": "object-del", "arguments": { "id": "rng1" } }
# <- { "return": {} }
#
##
{ 'command': 'object-del', 'data': {'id': 'str'},
'allow-preconfig': true }

1
qapi/rdma.json
View File

@ -30,7 +30,6 @@
# "interface-id": 15880512517475447892,
# "gid-status": true,
# "subnet-prefix": 33022}}
#
##
{ 'event': 'RDMA_GID_STATUS_CHANGED',
'data': { 'netdev' : 'str',

48
qapi/replay.json
View File

@ -13,13 +13,13 @@
#
# Mode of the replay subsystem.
#
# @none: normal execution mode. Replay or record are not enabled.
# @none: normal execution mode. Replay or record are not enabled.
#
# @record: record mode. All non-deterministic data is written into the
# replay log.
# @record: record mode. All non-deterministic data is written into
# the replay log.
#
# @play: replay mode. Non-deterministic data required for system execution
# is read from the log.
# @play: replay mode. Non-deterministic data required for system
# execution is read from the log.
#
# Since: 2.5
##
@ -33,9 +33,8 @@
#
# @mode: current mode.
#
# @filename: name of the record/replay log file.
# It is present only in record or replay modes, when the log
# is recorded or replayed.
# @filename: name of the record/replay log file. It is present only
# in record or replay modes, when the log is recorded or replayed.
#
# @icount: current number of executed instructions.
#
@ -47,9 +46,9 @@
##
# @query-replay:
#
# Retrieve the record/replay information.
# It includes current instruction count which may be used for
# @replay-break and @replay-seek commands.
# Retrieve the record/replay information. It includes current
# instruction count which may be used for @replay-break and
# @replay-seek commands.
#
# Returns: record/replay information.
#
@ -59,7 +58,6 @@
#
# -> { "execute": "query-replay" }
# <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } }
#
##
{ 'command': 'query-replay',
'returns': 'ReplayInfo' }
@ -67,12 +65,12 @@
##
# @replay-break:
#
# Set replay breakpoint at instruction count @icount.
# Execution stops when the specified instruction is reached.
# There can be at most one breakpoint. When breakpoint is set, any prior
# one is removed. The breakpoint may be set only in replay mode and only
# "in the future", i.e. at instruction counts greater than the current one.
# The current instruction count can be observed with @query-replay.
# Set replay breakpoint at instruction count @icount. Execution stops
# when the specified instruction is reached. There can be at most one
# breakpoint. When breakpoint is set, any prior one is removed. The
# breakpoint may be set only in replay mode and only "in the future",
# i.e. at instruction counts greater than the current one. The
# current instruction count can be observed with @query-replay.
#
# @icount: instruction count to stop at
#
@ -82,15 +80,14 @@
#
# -> { "execute": "replay-break", "arguments": { "icount": 220414 } }
# <- { "return": {} }
#
##
{ 'command': 'replay-break', 'data': { 'icount': 'int' } }
##
# @replay-delete-break:
#
# Remove replay breakpoint which was set with @replay-break.
# The command is ignored when there are no replay breakpoints.
# Remove replay breakpoint which was set with @replay-break. The
# command is ignored when there are no replay breakpoints.
#
# Since: 5.2
#
@ -98,7 +95,6 @@
#
# -> { "execute": "replay-delete-break" }
# <- { "return": {} }
#
##
{ 'command': 'replay-delete-break' }
@ -106,11 +102,11 @@
# @replay-seek:
#
# Automatically proceed to the instruction count @icount, when
# replaying the execution. The command automatically loads nearest
# replaying the execution. The command automatically loads nearest
# snapshot and replays the execution to find the desired instruction.
# When there is no preceding snapshot or the execution is not replayed,
# then the command fails.
# icount for the reference may be obtained with @query-replay command.
# When there is no preceding snapshot or the execution is not
# replayed, then the command fails. icount for the reference may be
# obtained with @query-replay command.
#
# @icount: target instruction count
#

20
qapi/rocker.json
View File

@ -34,7 +34,6 @@
#
# -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
# <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
#
##
{ 'command': 'query-rocker',
'data': { 'name': 'str' },
@ -107,7 +106,6 @@
# {"duplex": "full", "enabled": true, "name": "sw1.2",
# "autoneg": "off", "link-up": true, "speed": 10000}
# ]}
#
##
{ 'command': 'query-rocker-ports',
'data': { 'name': 'str' },
@ -141,7 +139,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
##
@ -171,7 +169,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
##
@ -198,7 +196,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,8 +233,8 @@
#
# @name: switch name
#
# @tbl-id: flow table ID. If tbl-id is not specified, returns
# flow information for all tables.
# @tbl-id: flow table ID. If tbl-id is not specified, returns flow
# information for all tables.
#
# Returns: rocker OF-DPA flow information
#
@ -254,7 +252,6 @@
# },
# {...more...},
# ]}
#
##
{ 'command': 'query-rocker-of-dpa-flows',
'data': { 'name': 'str', '*tbl-id': 'uint32' },
@ -292,7 +289,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,8 +308,8 @@
#
# @name: switch name
#
# @type: group type. If type is not specified, returns
# group information for all group types.
# @type: group type. If type is not specified, returns group
# information for all group types.
#
# Returns: rocker OF-DPA group information
#
@ -335,7 +332,6 @@
# "pport": 0, "vlan-id": 3840,
# "pop-vlan": 1, "id": 251658240}
# ]}
#
##
{ 'command': 'query-rocker-of-dpa-groups',
'data': { 'name': 'str', '*type': 'uint8' },

227
qapi/run-state.json
View File

@ -16,16 +16,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
# @internal-error: An internal error that prevents further guest
# execution has occurred
#
# @io-error: the last IOP has failed and the device is configured to pause
# on I/O errors
# @io-error: the last IOP has failed and the device is configured to
# pause on I/O errors
#
# @paused: guest has been paused via the 'stop' command
#
@ -43,13 +43,15 @@
#
# @suspended: guest is suspended (ACPI S3)
#
# @watchdog: the watchdog action is configured to pause and has been triggered
# @watchdog: the watchdog action is configured to pause and has been
# triggered
#
# @guest-panicked: guest has been panicked as a result of guest OS panic
# @guest-panicked: guest has been panicked as a result of guest OS
# panic
#
# @colo: guest is paused to save/restore VM state under colo checkpoint,
# VM can not get into this state unless colo capability is enabled
# for migration. (since 2.8)
# @colo: guest is paused to save/restore VM state under colo
# checkpoint, VM can not get into this state unless colo
# capability is enabled for migration. (since 2.8)
##
{ 'enum': 'RunState',
'data': [ 'debug', 'inmigrate', 'internal-error', 'io-error', 'paused',
@ -75,21 +77,21 @@
# @host-ui: Reaction to a UI event, like window close
#
# @guest-shutdown: Guest shutdown/suspend request, via ACPI or other
# hardware-specific means
# hardware-specific means
#
# @guest-reset: Guest reset request, and command line turns that into
# a shutdown
# a shutdown
#
# @guest-panic: Guest panicked, and command line turns that into a shutdown
# @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
# @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
#
# @snapshot-load: A snapshot is being loaded by the record & replay
# subsystem. This value is used only within QEMU. It
# doesn't occur in QMP. (since 7.2)
#
# subsystem. This value is used only within QEMU. It doesn't
# occur in QMP. (since 7.2)
##
{ 'enum': 'ShutdownCause',
# Beware, shutdown_caused_by_guest() depends on enumeration order
@ -104,19 +106,21 @@
#
# @running: true if all VCPUs are runnable, false if not runnable
#
# @singlestep: true if using TCG with one guest instruction
# per translation block
# @singlestep: true if using TCG with one guest instruction per
# translation block
#
# @status: the virtual machine @RunState
#
# Features:
# @deprecated: Member 'singlestep' is deprecated (with no replacement).
#
# @deprecated: Member 'singlestep' is deprecated (with no
# replacement).
#
# Since: 0.14
#
# Notes: @singlestep is enabled on the command line with
# '-accel tcg,one-insn-per-tb=on', or with the HMP
# 'one-insn-per-tb' command.
# Notes: @singlestep is enabled on the command line with '-accel
# tcg,one-insn-per-tb=on', or with the HMP 'one-insn-per-tb'
# command.
##
{ 'struct': 'StatusInfo',
'data': {'running': 'bool',
@ -138,7 +142,6 @@
# <- { "return": { "running": true,
# "singlestep": false,
# "status": "running" } }
#
##
{ 'command': 'query-status', 'returns': 'StatusInfo',
'allow-preconfig': true }
@ -146,17 +149,20 @@
##
# @SHUTDOWN:
#
# Emitted when the virtual machine has shut down, indicating that qemu is
# about to exit.
# Emitted when the virtual machine has shut down, indicating that qemu
# is 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)
# @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)
#
# @reason: The @ShutdownCause which resulted in the SHUTDOWN. (since 4.0)
# @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
# 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
#
# Since: 0.12
#
@ -165,15 +171,14 @@
# <- { "event": "SHUTDOWN",
# "data": { "guest": true, "reason": "guest-shutdown" },
# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
#
##
{ 'event': 'SHUTDOWN', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } }
##
# @POWERDOWN:
#
# Emitted when the virtual machine is powered down through the power control
# system, such as via ACPI.
# Emitted when the virtual machine is powered down through the power
# control system, such as via ACPI.
#
# Since: 0.12
#
@ -181,7 +186,6 @@
#
# <- { "event": "POWERDOWN",
# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
#
##
{ 'event': 'POWERDOWN' }
@ -191,9 +195,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)
#
@ -204,7 +208,6 @@
# <- { "event": "RESET",
# "data": { "guest": false, "reason": "guest-reset" },
# "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
#
##
{ 'event': 'RESET', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } }
@ -219,7 +222,6 @@
#
# <- { "event": "STOP",
# "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
#
##
{ 'event': 'STOP' }
@ -234,15 +236,14 @@
#
# <- { "event": "RESUME",
# "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
#
##
{ 'event': 'RESUME' }
##
# @SUSPEND:
#
# Emitted when guest enters a hardware suspension state, for example, S3 state,
# which is sometimes called standby state
# Emitted when guest enters a hardware suspension state, for example,
# S3 state, which is sometimes called standby state
#
# Since: 1.1
#
@ -250,17 +251,18 @@
#
# <- { "event": "SUSPEND",
# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
#
##
{ 'event': 'SUSPEND' }
##
# @SUSPEND_DISK:
#
# Emitted when guest enters a hardware suspension state with data saved on
# disk, for example, S4 state, which is sometimes called hibernate state
# Emitted when guest enters a hardware suspension state with data
# saved on disk, for example, S4 state, which is sometimes called
# hibernate state
#
# Note: QEMU shuts down (similar to event @SHUTDOWN) when entering this state
# Note: QEMU shuts down (similar to event @SHUTDOWN) when entering
# this state
#
# Since: 1.2
#
@ -274,7 +276,8 @@
##
# @WAKEUP:
#
# Emitted when the guest has woken up from suspend state and is running
# Emitted when the guest has woken up from suspend state and is
# running
#
# Since: 1.1
#
@ -282,7 +285,6 @@
#
# <- { "event": "WAKEUP",
# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
#
##
{ 'event': 'WAKEUP' }
@ -293,8 +295,9 @@
#
# @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
# Note: If action is "reset", "shutdown", or "pause" the WATCHDOG
# event is followed respectively by the RESET, SHUTDOWN, or STOP
# events
#
# Note: This event is rate-limited.
#
@ -305,7 +308,6 @@
# <- { "event": "WATCHDOG",
# "data": { "action": "reset" },
# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
#
##
{ 'event': 'WATCHDOG',
'data': { 'action': 'WatchdogAction' } }
@ -313,13 +315,13 @@
##
# @WatchdogAction:
#
# An enumeration of the actions taken when the watchdog device's timer is
# expired
# An enumeration of the actions taken when the watchdog device's timer
# is expired
#
# @reset: system resets
#
# @shutdown: system shutdown, note that it is similar to @powerdown, which
# tries to set to system status and notify guest
# @shutdown: system shutdown, note that it is similar to @powerdown,
# which tries to set to system status and notify guest
#
# @poweroff: system poweroff, the emulator program exits
#
@ -329,8 +331,8 @@
#
# @none: nothing is done
#
# @inject-nmi: a non-maskable interrupt is injected into the first VCPU (all
# VCPUS on x86) (since 2.4)
# @inject-nmi: a non-maskable interrupt is injected into the first
# VCPU (all VCPUS on x86) (since 2.4)
#
# Since: 2.1
##
@ -345,7 +347,8 @@
#
# @reset: Reset the VM
#
# @shutdown: Shutdown the VM and exit, according to the shutdown action
# @shutdown: Shutdown the VM and exit, according to the shutdown
# action
#
# Since: 6.0
##
@ -373,10 +376,11 @@
#
# @pause: Pause the VM
#
# @shutdown: Shutdown the VM and exit, according to the shutdown action
# @shutdown: Shutdown the VM and exit, according to the shutdown
# action
#
# @exit-failure: Shutdown the VM and exit with nonzero status
# (since 7.1)
# @exit-failure: Shutdown the VM and exit with nonzero status (since
# 7.1)
#
# Since: 6.0
##
@ -395,8 +399,8 @@
##
# @set-action:
#
# Set the actions that will be taken by the emulator in response to guest
# events.
# Set the actions that will be taken by the emulator in response to
# guest events.
#
# @reboot: @RebootAction action taken on guest reboot.
#
@ -404,7 +408,8 @@
#
# @panic: @PanicAction action taken on guest panic.
#
# @watchdog: @WatchdogAction action taken when watchdog timer expires .
# @watchdog: @WatchdogAction action taken when watchdog timer expires
# .
#
# Returns: Nothing on success.
#
@ -442,7 +447,6 @@
# <- { "event": "GUEST_PANICKED",
# "data": { "action": "pause" },
# "timestamp": { "seconds": 1648245231, "microseconds": 900001 } }
#
##
{ 'event': 'GUEST_PANICKED',
'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }
@ -463,7 +467,6 @@
# <- { "event": "GUEST_CRASHLOADED",
# "data": { "action": "run" },
# "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }
#
##
{ 'event': 'GUEST_CRASHLOADED',
'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }
@ -510,8 +513,8 @@
{'union': 'GuestPanicInformation',
'base': {'type': 'GuestPanicInformationType'},
'discriminator': 'type',
'data': { 'hyper-v': 'GuestPanicInformationHyperV',
's390': 'GuestPanicInformationS390' } }
'data': {'hyper-v': 'GuestPanicInformationHyperV',
's390': 'GuestPanicInformationS390'}}
##
# @GuestPanicInformationHyperV:
@ -521,11 +524,11 @@
# Since: 2.9
##
{'struct': 'GuestPanicInformationHyperV',
'data': { 'arg1': 'uint64',
'arg2': 'uint64',
'arg3': 'uint64',
'arg4': 'uint64',
'arg5': 'uint64' } }
'data': {'arg1': 'uint64',
'arg2': 'uint64',
'arg3': 'uint64',
'arg4': 'uint64',
'arg5': 'uint64'}}
##
# @S390CrashReason:
@ -536,13 +539,13 @@
#
# @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
# @extint-loop: clock comparator or cpu timer interrupt with new PSW
# enabled 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
# @opint-loop: operation exception interrupt with invalid code at the
# program interrupt new PSW
#
# Since: 2.12
##
@ -559,17 +562,20 @@
# S390 specific guest panic information (PSW)
#
# @core: core id of the CPU that crashed
#
# @psw-mask: control fields of guest PSW
#
# @psw-addr: guest instruction address
#
# @reason: guest crash reason
#
# Since: 2.12
##
{'struct': 'GuestPanicInformationS390',
'data': { 'core': 'uint32',
'psw-mask': 'uint64',
'psw-addr': 'uint64',
'reason': 'S390CrashReason' } }
'data': {'core': 'uint32',
'psw-mask': 'uint64',
'psw-addr': 'uint64',
'reason': 'S390CrashReason'}}
##
# @MEMORY_FAILURE:
@ -578,9 +584,11 @@
#
# @recipient: recipient is defined as @MemoryFailureRecipient.
#
# @action: action that has been taken. action is defined as @MemoryFailureAction.
# @action: action that has been taken. action is defined as
# @MemoryFailureAction.
#
# @flags: flags for MemoryFailureAction. action is defined as @MemoryFailureFlags.
# @flags: flags for MemoryFailureAction. action is defined as
# @MemoryFailureFlags.
#
# Since: 5.2
#
@ -592,7 +600,6 @@
# "flags": { "action-required": false,
# "recursive": false } },
# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
#
##
{ 'event': 'MEMORY_FAILURE',
'data': { 'recipient': 'MemoryFailureRecipient',
@ -604,8 +611,8 @@
#
# Hardware memory failure occurs, handled by recipient.
#
# @hypervisor: memory failure at QEMU process address space.
# (none guest memory, but used by QEMU itself).
# @hypervisor: memory failure at QEMU process address space. (none
# guest memory, but used by QEMU itself).
#
# @guest: memory failure at guest memory,
#
@ -620,19 +627,20 @@
#
# Actions taken by QEMU in response to a hardware memory failure.
#
# @ignore: the memory failure could be ignored. This will only be the case
# for action-optional failures.
# @ignore: the memory failure could be ignored. This will only be the
# case for action-optional failures.
#
# @inject: memory failure occurred in guest memory, the guest enabled MCE
# handling mechanism, and QEMU could inject the MCE into the guest
# successfully.
# @inject: memory failure occurred in guest memory, the guest enabled
# MCE handling mechanism, and QEMU could inject the MCE into the
# guest successfully.
#
# @fatal: the failure is unrecoverable. This occurs for action-required
# failures if the recipient is the hypervisor; QEMU will exit.
# @fatal: the failure is unrecoverable. This occurs for
# action-required failures if the recipient is the hypervisor;
# QEMU will exit.
#
# @reset: the failure is unrecoverable but confined to the guest. This
# occurs if the recipient is a guest guest which is not ready
# to handle memory failures.
# @reset: the failure is unrecoverable but confined to the guest.
# This occurs if the recipient is a guest guest which is not ready
# to handle memory failures.
#
# Since: 5.2
##
@ -648,10 +656,10 @@
# Additional information on memory failures.
#
# @action-required: whether a memory failure event is action-required
# or action-optional (e.g. a failure during memory scrub).
# or action-optional (e.g. a failure during memory scrub).
#
# @recursive: whether the failure occurred while the previous
# failure was still in progress.
# @recursive: whether the failure occurred while the previous failure
# was still in progress.
#
# Since: 5.2
##
@ -664,10 +672,11 @@
#
# An enumeration of the options specified when enabling notify VM exit
#
# @run: enable the feature, do nothing and continue if the notify VM exit happens.
# @run: enable the feature, do nothing and continue if the notify VM
# exit happens.
#
# @internal-error: enable the feature, raise a internal error if the notify
# VM exit happens.
# @internal-error: enable the feature, raise a internal error if the
# notify VM exit happens.
#
# @disable: disable the feature.
#

50
qapi/sockets.json
View File

@ -41,21 +41,24 @@
##
# @InetSocketAddress:
#
# Captures a socket address or address range in the Internet namespace.
# Captures a socket address or address range in the Internet
# namespace.
#
# @numeric: true if the host/port are guaranteed to be numeric,
# false if name resolution should be attempted. Defaults to false.
# (Since 2.9)
# @numeric: true if the host/port are guaranteed to be numeric, false
# if name resolution should be attempted. Defaults to false.
# (Since 2.9)
#
# @to: If present, this is range of possible addresses, with port
# between @port and @to.
# between @port and @to.
#
# @ipv4: whether to accept IPv4 addresses, default try both IPv4 and IPv6
# @ipv4: whether to accept IPv4 addresses, default try both IPv4 and
# IPv6
#
# @ipv6: whether to accept IPv6 addresses, default try both IPv4 and IPv6
# @ipv6: whether to accept IPv6 addresses, default try both IPv4 and
# IPv6
#
# @keep-alive: enable keep-alive when connecting to this socket. Not supported
# for passive sockets. (Since 4.2)
# @keep-alive: enable keep-alive when connecting to this socket. Not
# supported for passive sockets. (Since 4.2)
#
# @mptcp: enable multi-path TCP. (Since 6.1)
#
@ -77,12 +80,14 @@
# Captures a socket address in the local ("Unix socket") namespace.
#
# @path: filesystem path to use
#
# @abstract: if true, this is a Linux abstract socket address. @path
# will be prefixed by a null byte, and optionally padded
# with null bytes. Defaults to false. (Since 5.1)
# will be prefixed by a null byte, and optionally padded with null
# bytes. Defaults to false. (Since 5.1)
#
# @tight: if false, pad an abstract socket address with enough null
# bytes to make it fill struct sockaddr_un member sun_path.
# Defaults to true. (Since 5.1)
# bytes to make it fill struct sockaddr_un member sun_path.
# Defaults to true. (Since 5.1)
#
# Since: 1.3
##
@ -98,10 +103,11 @@
# Captures a socket address in the vsock namespace.
#
# @cid: unique host identifier
#
# @port: port
#
# Note: string types are used to allow for possible future hostname or
# service resolution support.
# service resolution support.
#
# Since: 2.8
##
@ -145,11 +151,12 @@
##
# @SocketAddressLegacy:
#
# Captures the address of a socket, which could also be a named file descriptor
# 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 has fewer {} on the wire.
# difference between SocketAddressLegacy and SocketAddress is that
# the latter has fewer {} on the wire.
#
# Since: 1.3
##
@ -173,10 +180,11 @@
#
# @vsock: VMCI address
#
# @fd: decimal is for file descriptor number, otherwise a file descriptor name.
# Named file descriptors are permitted in monitor commands, in combination
# with the 'getfd' command. Decimal file descriptors are permitted at
# startup or other contexts where no monitor context is active.
# @fd: decimal is for file descriptor number, otherwise a file
# descriptor name. Named file descriptors are permitted in
# monitor commands, in combination with the 'getfd' command.
# Decimal file descriptors are permitted at startup or other
# contexts where no monitor context is active.
#
# Since: 2.9
##

83
qapi/stats.json
View File

@ -18,11 +18,15 @@
# Enumeration of statistics types
#
# @cumulative: stat is cumulative; value can only increase.
#
# @instant: stat is instantaneous; value can increase or decrease.
#
# @peak: stat is the peak value; value can only increase.
#
# @linear-histogram: stat is a linear histogram.
#
# @log2-histogram: stat is a logarithmic histogram, with one bucket
# for each power of two.
# for each power of two.
#
# Since: 7.1
##
@ -36,8 +40,11 @@
# Enumeration of unit of measurement for statistics
#
# @bytes: stat reported in bytes.
#
# @seconds: stat reported in seconds.
#
# @cycles: stat reported in clock cycles.
#
# @boolean: stat is a boolean value.
#
# Since: 7.1
@ -64,8 +71,8 @@
#
# The kinds of objects on which one can request statistics.
#
# @vm: statistics that apply to the entire virtual machine or
# the entire QEMU process.
# @vm: statistics that apply to the entire virtual machine or the
# entire QEMU process.
#
# @vcpu: statistics that apply to a single virtual CPU.
#
@ -79,10 +86,11 @@
##
# @StatsRequest:
#
# Indicates a set of statistics that should be returned by query-stats.
# Indicates a set of statistics that should be returned by
# query-stats.
#
# @provider: provider for which to return statistics.
#
# @names: statistics to be returned (all if omitted).
#
# Since: 7.1
@ -104,9 +112,9 @@
##
# @StatsFilter:
#
# The arguments to the query-stats command; specifies a target for which to
# request statistics and optionally the required subset of information for
# that target:
# The arguments to the query-stats command; specifies a target for
# which to request statistics and optionally the required subset of
# information for that target:
#
# - which vCPUs to request statistics for
# - which providers to request statistics from
@ -125,6 +133,7 @@
# @StatsValue:
#
# @scalar: single unsigned 64-bit integers.
#
# @list: list of unsigned 64-bit integers (used for histograms).
#
# Since: 7.1
@ -138,6 +147,7 @@
# @Stats:
#
# @name: name of stat.
#
# @value: stat value.
#
# Since: 7.1
@ -152,7 +162,7 @@
# @provider: provider for this set of statistics.
#
# @qom-path: Path to the object for which the statistics are returned,
# if the object is exposed in the QOM tree
# if the object is exposed in the QOM tree
#
# @stats: list of statistics.
#
@ -166,14 +176,14 @@
##
# @query-stats:
#
# Return runtime-collected statistics for objects such as the
# VM or its vCPUs.
# Return runtime-collected statistics for objects such as the VM or
# its vCPUs.
#
# The arguments are a StatsFilter and specify the provider and objects
# to return statistics about.
#
# Returns: a list of StatsResult, one for each provider and object
# (e.g., for each vCPU).
# (e.g., for each vCPU).
#
# Since: 7.1
##
@ -188,24 +198,25 @@
# Schema for a single statistic.
#
# @name: name of the statistic; each element of the schema is uniquely
# identified by a target, a provider (both available in @StatsSchema)
# and the name.
# identified by a target, a provider (both available in
# @StatsSchema) and the name.
#
# @type: kind of statistic.
#
# @unit: basic unit of measure for the statistic; if missing, the statistic
# is a simple number or counter.
# @unit: basic unit of measure for the statistic; if missing, the
# statistic is a simple number or counter.
#
# @base: base for the multiple of @unit in which the statistic is measured.
# Only present if @exponent is non-zero; @base and @exponent together
# form a SI prefix (e.g., _nano-_ for ``base=10`` and ``exponent=-9``)
# or IEC binary prefix (e.g. _kibi-_ for ``base=2`` and ``exponent=10``)
# @base: base for the multiple of @unit in which the statistic is
# measured. Only present if @exponent is non-zero; @base and
# @exponent together form a SI prefix (e.g., _nano-_ for
# ``base=10`` and ``exponent=-9``) or IEC binary prefix (e.g.
# _kibi-_ for ``base=2`` and ``exponent=10``)
#
# @exponent: exponent for the multiple of @unit in which the statistic is
# expressed, or 0 for the basic unit
# @exponent: exponent for the multiple of @unit in which the statistic
# is expressed, or 0 for the basic unit
#
# @bucket-size: Present when @type is "linear-histogram", contains the width
# of each bucket of the histogram.
# @bucket-size: Present when @type is "linear-histogram", contains the
# width of each bucket of the histogram.
#
# Since: 7.1
##
@ -224,7 +235,8 @@
#
# @provider: provider for this set of statistics.
#
# @target: the kind of object that can be queried through the provider.
# @target: the kind of object that can be queried through the
# provider.
#
# @stats: list of statistics.
#
@ -240,16 +252,17 @@
#
# Return the schema for all available runtime-collected statistics.
#
# Note: runtime-collected statistics and their names fall outside QEMU's usual
# deprecation policies. QEMU will try to keep the set of available data
# stable, together with their names, but will not guarantee stability
# at all costs; the same is true of providers that source statistics
# externally, e.g. from Linux. For example, if the same value is being
# tracked with different names on different architectures or by different
# providers, one of them might be renamed. A statistic might go away if
# an algorithm is changed or some code is removed; changing a default
# might cause previously useful statistics to always report 0. Such
# changes, however, are expected to be rare.
# Note: runtime-collected statistics and their names fall outside
# QEMU's usual deprecation policies. QEMU will try to keep the
# set of available data stable, together with their names, but
# will not guarantee stability at all costs; the same is true of
# providers that source statistics externally, e.g. from Linux.
# For example, if the same value is being tracked with different
# names on different architectures or by different providers, one
# of them might be renamed. A statistic might go away if an
# algorithm is changed or some code is removed; changing a default
# might cause previously useful statistics to always report 0.
# Such changes, however, are expected to be rare.
#
# Since: 7.1
##

20
qapi/tpm.json
View File

@ -12,7 +12,9 @@
# An enumeration of TPM models
#
# @tpm-tis: TPM TIS model
#
# @tpm-crb: TPM CRB model (since 2.12)
#
# @tpm-spapr: TPM SPAPR model (since 5.0)
#
# Since: 1.5
@ -33,7 +35,6 @@
#
# -> { "execute": "query-tpm-models" }
# <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] }
#
##
{ 'command': 'query-tpm-models', 'returns': ['TpmModel'],
'if': 'CONFIG_TPM' }
@ -44,6 +45,7 @@
# An enumeration of TPM types
#
# @passthrough: TPM passthrough type
#
# @emulator: Software Emulator TPM type (since 2.11)
#
# Since: 1.5
@ -64,7 +66,6 @@
#
# -> { "execute": "query-tpm-types" }
# <- { "return": [ "passthrough", "emulator" ] }
#
##
{ 'command': 'query-tpm-types', 'returns': ['TpmType'],
'if': 'CONFIG_TPM' }
@ -76,8 +77,8 @@
#
# @path: string describing the path used for accessing the TPM device
#
# @cancel-path: string showing the TPM's sysfs cancel file
# for cancellation of TPM commands while they are executing
# @cancel-path: string showing the TPM's sysfs cancel file for
# cancellation of TPM commands while they are executing
#
# Since: 1.5
##
@ -119,10 +120,14 @@
##
# @TpmTypeOptions:
#
# A union referencing different TPM backend types' configuration options
# 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
##
@ -178,7 +183,6 @@
# }
# ]
# }
#
##
{ 'command': 'query-tpm', 'returns': ['TPMInfo'],
'if': 'CONFIG_TPM' }

34
qapi/trace.json
View File

@ -32,11 +32,13 @@
# Information of a tracing event.
#
# @name: Event name.
#
# @state: Tracing state.
#
# @vcpu: Whether this is a per-vCPU event (since 2.7).
#
# An event is per-vCPU if it has the "vcpu" property in the "trace-events"
# files.
# An event is per-vCPU if it has the "vcpu" property in the
# "trace-events" files.
#
# Since: 2.2
##
@ -49,19 +51,20 @@
# Query the state of events.
#
# @name: Event name pattern (case-sensitive glob).
#
# @vcpu: The vCPU to query (any by default; since 2.7).
#
# Returns: a list of @TraceEventInfo for the matching events
#
# An event is returned if:
# An event is returned if:
#
# - its name matches the @name pattern, and
# - if @vcpu is given, the event has the "vcpu" property.
# - 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.
# 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
#
@ -70,7 +73,6 @@
# -> { "execute": "trace-event-get-state",
# "arguments": { "name": "qemu_memalign" } }
# <- { "return": [ { "name": "qemu_memalign", "state": "disabled", "vcpu": false } ] }
#
##
{ 'command': 'trace-event-get-state',
'data': {'name': 'str', '*vcpu': 'int'},
@ -82,8 +84,11 @@
# Set the dynamic tracing state of events.
#
# @name: Event name pattern (case-sensitive glob).
#
# @enable: Whether to enable tracing.
#
# @ignore-unavailable: Do not match unavailable events with @name.
#
# @vcpu: The vCPU to act upon (all by default; since 2.7).
#
# An event's state is modified if:
@ -91,10 +96,10 @@
# - 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,
# setting 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.
# Therefore, if @vcpu is given, the operation will only match per-vCPU
# events, setting 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
#
@ -103,7 +108,6 @@
# -> { "execute": "trace-event-set-state",
# "arguments": { "name": "qemu_memalign", "enable": true } }
# <- { "return": {} }
#
##
{ 'command': 'trace-event-set-state',
'data': {'name': 'str', 'enable': 'bool', '*ignore-unavailable': 'bool',

87
qapi/transaction.json
View File

@ -23,15 +23,15 @@
#
# An enumeration of Transactional completion modes.
#
# @individual: Do not attempt to cancel any other Actions if any Actions fail
# after the Transaction request succeeds. All Actions that
# can complete successfully will do so without waiting on others.
# This is the default.
# @individual: Do not attempt to cancel any other Actions if any
# Actions fail after the Transaction request succeeds. All
# Actions that can complete successfully will do so without
# waiting on others. This is the default.
#
# @grouped: If any Action fails after the Transaction succeeds, cancel all
# Actions. Actions do not complete until all Actions are ready to
# complete. May be rejected by Actions that do not support this
# completion mode.
# @grouped: If any Action fails after the Transaction succeeds, cancel
# all Actions. Actions do not complete until all Actions are
# ready to complete. May be rejected by Actions that do not
# support this completion mode.
#
# Since: 2.5
##
@ -42,21 +42,33 @@
# @TransactionActionKind:
#
# @abort: Since 1.6
#
# @block-dirty-bitmap-add: Since 2.5
#
# @block-dirty-bitmap-remove: Since 4.2
#
# @block-dirty-bitmap-clear: Since 2.5
#
# @block-dirty-bitmap-enable: Since 4.0
#
# @block-dirty-bitmap-disable: Since 4.0
#
# @block-dirty-bitmap-merge: Since 4.0
#
# @blockdev-backup: Since 2.3
#
# @blockdev-snapshot: Since 2.5
#
# @blockdev-snapshot-internal-sync: Since 1.7
#
# @blockdev-snapshot-sync: since 1.1
#
# @drive-backup: Since 1.6
#
# Features:
#
# @deprecated: Member @drive-backup is deprecated. Use member
# @blockdev-backup instead.
# @blockdev-backup instead.
#
# Since: 1.1
##
@ -172,8 +184,8 @@
# Optional arguments to modify the behavior of a Transaction.
#
# @completion-mode: Controls how jobs launched asynchronously by
# Actions will complete or fail as a group.
# See @ActionCompletionMode for details.
# Actions will complete or fail as a group. See
# @ActionCompletionMode for details.
#
# Since: 2.5
##
@ -186,46 +198,48 @@
##
# @transaction:
#
# Executes a number of transactionable QMP commands atomically. If any
# operation fails, then the entire set of actions will be abandoned and the
# appropriate error returned.
# Executes a number of transactionable QMP commands atomically. If
# any operation fails, then the entire set of actions will be
# abandoned and the appropriate error returned.
#
# For external snapshots, the dictionary contains the device, the file to use for
# the new snapshot, and the format. The default format, if not specified, is
# qcow2.
# For external snapshots, the dictionary contains the device, the file
# to use for the new snapshot, and the format. The default format, if
# not specified, is qcow2.
#
# Each new snapshot defaults to being created by QEMU (wiping any
# contents if the file already exists), but it is also possible to reuse
# an externally-created file. In the latter case, you should ensure that
# the new image file has the same contents as the current one; QEMU cannot
# perform any meaningful check. Typically this is achieved by using the
# current image file as the backing file for the new image.
# contents if the file already exists), but it is also possible to
# reuse an externally-created file. In the latter case, you should
# ensure that the new image file has the same contents as the current
# one; QEMU cannot perform any meaningful check. Typically this is
# achieved by using the current image file as the backing file for the
# new image.
#
# On failure, the original disks pre-snapshot attempt will be used.
#
# For internal snapshots, the dictionary contains the device and the
# snapshot's name. If an internal snapshot matching name already exists,
# the request will be rejected. Only some image formats support it, for
# example, qcow2, and rbd,
# snapshot's name. If an internal snapshot matching name already
# exists, the request will be rejected. Only some image formats
# support it, for example, qcow2, and rbd,
#
# On failure, qemu will try delete the newly created internal snapshot in the
# transaction. When an I/O error occurs during deletion, the user needs to fix
# it later with qemu-img or other command.
# On failure, qemu will try delete the newly created internal snapshot
# in the transaction. When an I/O error occurs during deletion, the
# user needs to fix it later with qemu-img or other command.
#
# @actions: List of @TransactionAction;
# information needed for the respective operations.
# @actions: List of @TransactionAction; information needed for the
# respective operations.
#
# @properties: structure of additional options to control the
# execution of the transaction. See @TransactionProperties
# for additional detail.
# execution of the transaction. See @TransactionProperties for
# additional detail.
#
# Returns: nothing on success
#
# Errors depend on the operations of the transaction
# 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.
# 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.
#
# Since: 1.1
#
@ -249,7 +263,6 @@
# "device": "ide-hd2",
# "name": "snapshot0" } } ] } }
# <- { "return": {} }
#
##
{ 'command': 'transaction',
'data': { 'actions': [ 'TransactionAction' ],

435
qapi/ui.json
View File

@ -22,7 +22,8 @@
##
# @SetPasswordAction:
#
# An action to take on changing a password on a connection with active clients.
# An action to take on changing a password on a connection with active
# clients.
#
# @keep: maintain existing clients
#
@ -40,14 +41,15 @@
#
# Options for set_password.
#
# @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'.
# For VNC, only 'keep' is currently implemented.
# password. If nothing is specified, defaults to 'keep'. For VNC,
# only 'keep' is currently implemented.
#
# Since: 7.0
##
@ -63,8 +65,8 @@
#
# Options for set_password specific to the VNC procotol.
#
# @display: The id of the display where the password should be changed.
# Defaults to the first.
# @display: The id of the display where the password should be
# changed. Defaults to the first.
#
# Since: 7.0
##
@ -76,8 +78,9 @@
#
# Set the password of a remote display server.
#
# Returns: - Nothing on success
# - If Spice is not enabled, DeviceNotFound
# Returns:
# - Nothing on success
# - If Spice is not enabled, DeviceNotFound
#
# Since: 0.14
#
@ -86,7 +89,6 @@
# -> { "execute": "set_password", "arguments": { "protocol": "vnc",
# "password": "secret" } }
# <- { "return": {} }
#
##
{ 'command': 'set_password', 'boxed': true, 'data': 'SetPasswordOptions' }
@ -95,20 +97,22 @@
#
# General options for expire_password.
#
# @protocol: - 'vnc' to modify the VNC server expiration
# - 'spice' to modify the Spice server expiration
# @protocol:
# - 'vnc' to modify the VNC server expiration
# - 'spice' to modify the Spice server expiration
#
# @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
# - '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
#
# Notes: Time is relative to the server and currently there is no way to
# coordinate server time with client time. It is not recommended to
# use the absolute time version of the @time parameter unless you're
# sure you are on the same machine as the QEMU instance.
# Notes: Time is relative to the server and currently there is no way
# to coordinate server time with client time. It is not
# recommended to use the absolute time version of the @time
# parameter unless you're sure you are on the same machine as the
# QEMU instance.
#
# Since: 7.0
##
@ -123,8 +127,8 @@
#
# Options for expire_password specific to the VNC procotol.
#
# @display: The id of the display where the expiration should be changed.
# Defaults to the first.
# @display: The id of the display where the expiration should be
# changed. Defaults to the first.
#
# Since: 7.0
##
@ -136,8 +140,10 @@
#
# Expire the password of a remote display server.
#
# Returns: - Nothing on success
# - If @protocol is 'spice' and Spice is not active, DeviceNotFound
# Returns:
# - Nothing on success
# - If @protocol is 'spice' and Spice is not active,
# DeviceNotFound
#
# Since: 0.14
#
@ -146,7 +152,6 @@
# -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
# "time": "+60" } }
# <- { "return": {} }
#
##
{ 'command': 'expire_password', 'boxed': true, 'data': 'ExpirePasswordOptions' }
@ -171,14 +176,16 @@
#
# @filename: the path of a new file to store the image
#
# @device: ID of the display device that should be dumped. If this parameter
# is missing, the primary display will be used. (Since 2.12)
# @device: ID of the display device that should be dumped. If this
# parameter is missing, the primary display will be used. (Since
# 2.12)
#
# @head: head to use in case the device supports multiple heads. If this
# parameter is missing, head #0 will be used. Also note that the head
# can only be specified in conjunction with the device ID. (Since 2.12)
# @head: head to use in case the device supports multiple heads. If
# this parameter is missing, head #0 will be used. Also note that
# the head can only be specified in conjunction with the device
# ID. (Since 2.12)
#
# @format: image format for screendump. (default: ppm) (Since 7.1)
# @format: image format for screendump. (default: ppm) (Since 7.1)
#
# Returns: Nothing on success
#
@ -189,7 +196,6 @@
# -> { "execute": "screendump",
# "arguments": { "filename": "/tmp/image" } }
# <- { "return": {} }
#
##
{ 'command': 'screendump',
'data': {'filename': 'str', '*device': 'str', '*head': 'int',
@ -238,16 +244,16 @@
#
# Information about a SPICE client channel.
#
# @connection-id: SPICE connection id number. All channels with the same id
# belong to the same SPICE session.
# @connection-id: SPICE connection id number. All channels with the
# same id belong to the same SPICE session.
#
# @channel-type: SPICE channel type number. "1" is the main control
# channel, filter for this one if you want to track spice
# sessions only
# channel, filter for this one if you want to track spice sessions
# only
#
# @channel-id: SPICE channel ID number. Usually "0", might be different when
# multiple channels of the same type exist, such as multiple
# display channels in a multihead setup
# @channel-id: SPICE channel ID number. Usually "0", might be
# different when multiple channels of the same type exist, such as
# multiple display channels in a multihead setup
#
# @tls: true if the channel is encrypted, false otherwise.
#
@ -268,8 +274,8 @@
#
# @server: Mouse cursor position is determined by the server.
#
# @unknown: No information is available about mouse mode used by
# the spice server.
# @unknown: No information is available about mouse mode used by the
# spice server.
#
# Note: spice/enums.h has a SpiceMouseMode already, hence the name.
#
@ -287,10 +293,10 @@
# @enabled: true if the SPICE server is enabled, false otherwise
#
# @migrated: true if the last guest migration completed and spice
# migration had completed as well. false otherwise. (since 1.4)
# migration had completed as well. false otherwise. (since 1.4)
#
# @host: The hostname the SPICE server is bound to. This depends on
# the name resolution on the host and may be an IP address.
# the name resolution on the host and may be an IP address.
#
# @port: The SPICE server's port number.
#
@ -300,13 +306,14 @@
#
# @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
# server doesn't provide this information. (since: 1.1)
# @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 server doesn't provide this information.
# (since: 1.1)
#
# @channels: a list of @SpiceChannel for each active spice channel
#
@ -361,7 +368,6 @@
# ]
# }
# }
#
##
{ 'command': 'query-spice', 'returns': 'SpiceInfo',
'if': 'CONFIG_SPICE' }
@ -385,7 +391,6 @@
# "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
# "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
# }}
#
##
{ 'event': 'SPICE_CONNECTED',
'data': { 'server': 'SpiceBasicInfo',
@ -395,8 +400,8 @@
##
# @SPICE_INITIALIZED:
#
# Emitted after initial handshake and authentication takes place (if any)
# and the SPICE channel is up and running
# Emitted after initial handshake and authentication takes place (if
# any) and the SPICE channel is up and running
#
# @server: server information
#
@ -414,7 +419,6 @@
# "connection-id": 1804289383, "host": "127.0.0.1",
# "channel-id": 0, "tls": true}
# }}
#
##
{ 'event': 'SPICE_INITIALIZED',
'data': { 'server': 'SpiceServerInfo',
@ -440,7 +444,6 @@
# "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
# "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
# }}
#
##
{ 'event': 'SPICE_DISCONNECTED',
'data': { 'server': 'SpiceBasicInfo',
@ -458,7 +461,6 @@
#
# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
# "event": "SPICE_MIGRATE_COMPLETED" }
#
##
{ 'event': 'SPICE_MIGRATE_COMPLETED',
'if': 'CONFIG_SPICE' }
@ -474,9 +476,9 @@
#
# @host: IP address
#
# @service: The service name of the vnc port. This may depend on the host
# system's service database so symbolic names should not be relied
# on.
# @service: The service name of the vnc port. This may depend on the
# host system's service database so symbolic names should not be
# relied on.
#
# @family: address family
#
@ -496,8 +498,8 @@
#
# The network connection information for server
#
# @auth: authentication method used for
# the plain (non-websocket) VNC server
# @auth: authentication method used for the plain (non-websocket) VNC
# server
#
# Since: 2.1
##
@ -512,10 +514,10 @@
# Information about a connected VNC client.
#
# @x509_dname: If x509 authentication is in use, the Distinguished
# Name of the client.
# Name of the client.
#
# @sasl_username: If SASL authentication is in use, the SASL username
# used for authentication.
# used for authentication.
#
# Since: 0.14
##
@ -531,33 +533,41 @@
#
# @enabled: true if the VNC server is enabled, false otherwise
#
# @host: The hostname the VNC server is bound to. This depends on
# the name resolution on the host and may be an IP address.
# @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.
# 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
# @clients: a list of @VncClientInfo of all currently connected
# clients
#
# Since: 0.14
##
@ -601,8 +611,8 @@
#
# @auth: The current authentication type used by the servers
#
# @vencrypt: The vencrypt sub authentication type used by the
# servers, only specified in case auth == vencrypt.
# @vencrypt: The vencrypt sub authentication type used by the servers,
# only specified in case auth == vencrypt.
#
# Since: 2.9
##
@ -620,17 +630,18 @@
# @id: vnc server name.
#
# @server: A list of @VncBasincInfo describing all listening sockets.
# The list can be empty (in case the vnc server is disabled).
# It also may have multiple entries: normal + websocket,
# possibly also ipv4 + ipv6 in the future.
# The list can be empty (in case the vnc server is disabled). It
# also may have multiple entries: normal + websocket, possibly
# also ipv4 + ipv6 in the future.
#
# @clients: A list of @VncClientInfo of all currently connected clients.
# The list can be empty, for obvious reasons.
# @clients: A list of @VncClientInfo of all currently connected
# clients. The list can be empty, for obvious reasons.
#
# @auth: The current authentication type used by the non-websockets servers
# @auth: The current authentication type used by the non-websockets
# servers
#
# @vencrypt: The vencrypt authentication type used by the servers,
# only specified in case auth == vencrypt.
# only specified in case auth == vencrypt.
#
# @display: The display device the vnc server is linked to.
#
@ -673,7 +684,6 @@
# ]
# }
# }
#
##
{ 'command': 'query-vnc', 'returns': 'VncInfo',
'if': 'CONFIG_VNC' }
@ -698,8 +708,9 @@
#
# 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' },
@ -714,8 +725,8 @@
#
# @client: client information
#
# Note: This event is emitted before any authentication takes place, thus
# the authentication ID is not provided
# Note: This event is emitted before any authentication takes place,
# thus the authentication ID is not provided
#
# Since: 0.13
#
@ -728,7 +739,6 @@
# "client": { "family": "ipv4", "service": "58425",
# "host": "127.0.0.1", "websocket": false } },
# "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
#
##
{ 'event': 'VNC_CONNECTED',
'data': { 'server': 'VncServerInfo',
@ -738,8 +748,8 @@
##
# @VNC_INITIALIZED:
#
# Emitted after authentication takes place (if any) and the VNC session is
# made active
# Emitted after authentication takes place (if any) and the VNC
# session is made active
#
# @server: server information
#
@ -756,7 +766,6 @@
# "client": { "family": "ipv4", "service": "46089", "websocket": false,
# "host": "127.0.0.1", "sasl_username": "luiz" } },
# "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
#
##
{ 'event': 'VNC_INITIALIZED',
'data': { 'server': 'VncServerInfo',
@ -783,7 +792,6 @@
# "client": { "family": "ipv4", "service": "58425", "websocket": false,
# "host": "127.0.0.1", "sasl_username": "luiz" } },
# "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
#
##
{ 'event': 'VNC_DISCONNECTED',
'data': { 'server': 'VncServerInfo',
@ -805,7 +813,8 @@
#
# @current: true if this device is currently receiving mouse events
#
# @absolute: true if this device supports absolute coordinates as input
# @absolute: true if this device supports absolute coordinates as
# input
#
# Since: 0.14
##
@ -840,7 +849,6 @@
# }
# ]
# }
#
##
{ 'command': 'query-mice', 'returns': ['MouseInfo'] }
@ -852,59 +860,96 @@
# This is used by the @send-key command.
#
# @unmapped: since 2.0
#
# @pause: since 2.0
#
# @ro: since 2.4
#
# @kp_comma: since 2.4
#
# @kp_equals: since 2.6
#
# @power: since 2.6
#
# @hiragana: since 2.9
#
# @henkan: since 2.9
#
# @yen: since 2.9
#
# @sleep: since 2.10
#
# @wake: since 2.10
#
# @audionext: since 2.10
#
# @audioprev: since 2.10
#
# @audiostop: since 2.10
#
# @audioplay: since 2.10
#
# @audiomute: since 2.10
#
# @volumeup: since 2.10
#
# @volumedown: since 2.10
#
# @mediaselect: since 2.10
#
# @mail: since 2.10
#
# @calculator: since 2.10
#
# @computer: since 2.10
#
# @ac_home: since 2.10
#
# @ac_back: since 2.10
#
# @ac_forward: since 2.10
#
# @ac_refresh: since 2.10
#
# @ac_bookmarks: since 2.10
#
# @muhenkan: since 2.12
#
# @katakanahiragana: since 2.12
#
# @lang1: since 6.1
#
# @lang2: since 6.1
#
# @f13: since 8.0
#
# @f14: since 8.0
#
# @f15: since 8.0
#
# @f16: since 8.0
#
# @f17: since 8.0
#
# @f18: since 8.0
#
# @f19: since 8.0
#
# @f20: since 8.0
#
# @f21: since 8.0
#
# @f22: since 8.0
#
# @f23: since 8.0
#
# @f24: since 8.0
#
# 'sysrq' was mistakenly added to hack around the fact that
# the ps2 driver was not generating correct scancodes sequences
# when 'alt+print' was pressed. This flaw is now fixed and the
# 'sysrq' key serves no further purpose. Any further use of
# 'sysrq' will be transparently changed to 'print', so they
# are effectively synonyms.
# 'sysrq' was mistakenly added to hack around the fact that the ps2
# driver was not generating correct scancodes sequences when
# 'alt+print' was pressed. This flaw is now fixed and the 'sysrq' key
# serves no further purpose. Any further use of 'sysrq' will be
# transparently changed to 'print', so they are effectively synonyms.
#
# Since: 1.3
##
@ -976,16 +1021,17 @@
#
# Send keys to guest.
#
# @keys: An array of @KeyValue elements. All @KeyValues in this array are
# simultaneously sent to the guest. A @KeyValue.number value is sent
# directly to the guest, while @KeyValue.qcode must be a valid
# @QKeyCode value
# @keys: An array of @KeyValue elements. All @KeyValues in this array
# are simultaneously sent to the guest. A @KeyValue.number value
# is sent directly to the guest, while @KeyValue.qcode must be a
# valid @QKeyCode value
#
# @hold-time: time to delay key up events, milliseconds. Defaults
# to 100
# @hold-time: time to delay key up events, milliseconds. Defaults to
# 100
#
# Returns: - Nothing on success
# - If key is unknown or redundant, GenericError
# Returns:
# - Nothing on success
# - If key is unknown or redundant, GenericError
#
# Since: 1.3
#
@ -996,7 +1042,6 @@
# { "type": "qcode", "data": "alt" },
# { "type": "qcode", "data": "delete" } ] } }
# <- { "return": {} }
#
##
{ 'command': 'send-key',
'data': { 'keys': ['KeyValue'], '*hold-time': 'int' } }
@ -1032,6 +1077,7 @@
# Keyboard input event.
#
# @key: Which key this event is for.
#
# @down: True for key-down and false for key-up events.
#
# Since: 2.0
@ -1046,6 +1092,7 @@
# Pointer button input event.
#
# @button: Which button this event is for.
#
# @down: True for key-down and false for key-up events.
#
# Since: 2.0
@ -1060,8 +1107,9 @@
# Pointer motion input event.
#
# @axis: Which axis is referenced by @value.
# @value: Pointer position. For absolute coordinates the
# valid range is 0 -> 0x7ffff
#
# @value: Pointer position. For absolute coordinates the valid range
# is 0 -> 0x7ffff
#
# Since: 2.0
##
@ -1108,10 +1156,10 @@
#
# @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
##
@ -1140,8 +1188,10 @@
# precedence.
#
# @device: display device to send event(s) to.
# @head: head to send event(s) to, in case the
# display device supports multiple scanouts.
#
# @head: head to send event(s) to, in case the display device supports
# multiple scanouts.
#
# @events: List of InputEvent union.
#
# Returns: Nothing on success.
@ -1149,9 +1199,9 @@
# 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.
#
# Examples:
#
@ -1188,7 +1238,6 @@
# { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
# { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
# <- { "return": {} }
#
##
{ 'command': 'input-send-event',
'data': { '*device': 'str',
@ -1201,19 +1250,20 @@
# GTK display options.
#
# @grab-on-hover: Grab keyboard input on mouse hover.
#
# @zoom-to-fit: Zoom guest display to fit into the host window. When
# turned off the host window will be resized instead.
# In case the display device can notify the guest on
# window resizes (virtio-gpu) this will default to "on",
# assuming the guest will resize the display to match
# the window size then. Otherwise it defaults to "off".
# (Since 3.1)
# @show-tabs: Display the tab bar for switching between the various graphical
# interfaces (e.g. VGA and virtual console character devices)
# by default.
# (Since 7.1)
# @show-menubar: Display the main window menubar. Defaults to "on".
# (Since 8.0)
# turned off the host window will be resized instead. In case the
# display device can notify the guest on window resizes
# (virtio-gpu) this will default to "on", assuming the guest will
# resize the display to match the window size then. Otherwise it
# defaults to "off". (Since 3.1)
#
# @show-tabs: Display the tab bar for switching between the various
# graphical interfaces (e.g. VGA and virtual console character
# devices) by default. (Since 7.1)
#
# @show-menubar: Display the main window menubar. Defaults to "on".
# (Since 8.0)
#
# Since: 2.12
##
@ -1228,8 +1278,8 @@
#
# EGL headless display options.
#
# @rendernode: Which DRM render node should be used. Default is the first
# available node on the host.
# @rendernode: Which DRM render node should be used. Default is the
# first available node on the host.
#
# Since: 3.1
##
@ -1243,11 +1293,11 @@
#
# @addr: The D-Bus bus address (default to the session bus).
#
# @rendernode: Which DRM render node should be used. Default is the first
# available node on the host.
# @rendernode: Which DRM render node should be used. Default is the
# first available node on the host.
#
# @p2p: Whether to use peer-to-peer connections (accepted through
# @add_client).
# @add_client).
#
# @audiodev: Use the specified DBus audiodev to export audio.
#
@ -1265,10 +1315,13 @@
# Display OpenGL mode.
#
# @off: Disable OpenGL (default).
# @on: Use OpenGL, pick context type automatically.
# Would better be named 'auto' but is called 'on' for backward
# compatibility with bool type.
#
# @on: Use OpenGL, pick context type automatically. Would better be
# named 'auto' but is called 'on' for backward compatibility with
# bool type.
#
# @core: Use OpenGL with Core (desktop) Context.
#
# @es: Use OpenGL with ES (embedded systems) Context.
#
# Since: 3.0
@ -1294,18 +1347,17 @@
# Cocoa display options.
#
# @left-command-key: Enable/disable forwarding of left command key to
# guest. Allows command-tab window switching on the
# host without sending this key to the guest when
# "off". Defaults to "on"
# guest. Allows command-tab window switching on the host without
# sending this key to the guest when "off". Defaults to "on"
#
# @full-grab: Capture all key presses, including system combos. This
# requires accessibility permissions, since it performs
# a global grab on key events. (default: off)
# See https://support.apple.com/en-in/guide/mac-help/mh32356/mac
# @full-grab: Capture all key presses, including system combos. This
# requires accessibility permissions, since it performs a global
# grab on key events. (default: off) See
# https://support.apple.com/en-in/guide/mac-help/mh32356/mac
#
# @swap-opt-cmd: Swap the Option and Command keys so that their key codes match
# their position on non-Mac keyboards and you can use Meta/Super
# and Alt where you expect them. (default: off)
# @swap-opt-cmd: Swap the Option and Command keys so that their key
# codes match their position on non-Mac keyboards and you can use
# Meta/Super and Alt where you expect them. (default: off)
#
# Since: 7.0
##
@ -1331,8 +1383,8 @@
#
# SDL2 display options.
#
# @grab-mod: Modifier keys that should be pressed together with the
# "G" key to release the mouse grab.
# @grab-mod: Modifier keys that should be pressed together with the
# "G" key to release the mouse grab.
#
# Since: 7.1
##
@ -1344,36 +1396,35 @@
#
# Display (user interface) type.
#
# @default: The default user interface, selecting from the first available
# of gtk, sdl, cocoa, and vnc.
# @default: The default user interface, selecting from the first
# available of gtk, sdl, cocoa, and vnc.
#
# @none: No user interface or video output display. The guest will
# still see an emulated graphics card, but its output will not
# be displayed to the QEMU user.
# @none: No user interface or video output display. The guest will
# still see an emulated graphics card, but its output will not be
# displayed to the QEMU user.
#
# @gtk: The GTK user interface.
#
# @sdl: The SDL user interface.
#
# @egl-headless: No user interface, offload GL operations to a local
# DRI device. Graphical display need to be paired with
# VNC or Spice. (Since 3.1)
# DRI device. Graphical display need to be paired with VNC or
# Spice. (Since 3.1)
#
# @curses: Display video output via curses. For graphics device
# models which support a text mode, QEMU can display this
# output using a curses/ncurses interface. Nothing is
# displayed when the graphics device is in graphical mode or
# if the graphics device does not support a text
# mode. Generally only the VGA device models support text
# mode.
# models which support a text mode, QEMU can display this output
# using a curses/ncurses interface. Nothing is displayed when the
# graphics device is in graphical mode or if the graphics device
# does not support a text mode. Generally only the VGA device
# models support text mode.
#
# @cocoa: The Cocoa user interface.
#
# @spice-app: Set up a Spice server and run the default associated
# application to connect to it. The server will redirect
# the serial console and QEMU monitors. (Since 4.0)
# application to connect to it. The server will redirect the
# serial console and QEMU monitors. (Since 4.0)
#
# @dbus: Start a D-Bus service for the display. (Since 7.0)
# @dbus: Start a D-Bus service for the display. (Since 7.0)
#
# Since: 2.12
##
@ -1398,9 +1449,16 @@
# Display (user interface) options.
#
# @type: Which DisplayType qemu should use.
# @full-screen: Start user interface in fullscreen mode (default: off).
# @window-close: Allow to quit qemu with window close button (default: on).
# @show-cursor: Force showing the mouse cursor (default: off). (since: 5.0)
#
# @full-screen: Start user interface in fullscreen mode
# (default: off).
#
# @window-close: Allow to quit qemu with window close button
# (default: on).
#
# @show-cursor: Force showing the mouse cursor (default: off).
# (since: 5.0)
#
# @gl: Enable OpenGL support (default: off).
#
# Since: 2.12
@ -1487,7 +1545,6 @@
# -> { "execute": "display-reload",
# "arguments": { "type": "vnc", "tls-certs": true } }
# <- { "return": {} }
#
##
{ 'command': 'display-reload',
'data': 'DisplayReloadOptions',
@ -1510,9 +1567,9 @@
#
# Specify the VNC reload options.
#
# @addresses: If specified, change set of addresses
# to listen for connections. Addresses configured
# for websockets are not touched.
# @addresses: If specified, change set of addresses to listen for
# connections. Addresses configured for websockets are not
# touched.
#
# Since: 7.1
##
@ -1549,7 +1606,6 @@
# [ { "type": "inet", "host": "0.0.0.0",
# "port": "5901" } ] } }
# <- { "return": {} }
#
##
{ 'command': 'display-update',
'data': 'DisplayUpdateOptions',
@ -1563,9 +1619,13 @@
# once migration finished successfully. Only implemented for SPICE.
#
# @protocol: must be "spice"
#
# @hostname: migration target hostname
#
# @port: spice tcp port for plaintext channels
#
# @tls-port: spice tcp port for tls-secured channels
#
# @cert-subject: server certificate subject
#
# Since: 0.14
@ -1577,7 +1637,6 @@
# "hostname": "virt42.lab.kraxel.org",
# "port": 1234 } }
# <- { "return": {} }
#
##
{ 'command': 'client_migrate_info',
'data': { 'protocol': 'str', 'hostname': 'str', '*port': 'int',

84
qapi/virtio.json
View File

@ -16,7 +16,6 @@
# @name: Name of the VirtIODevice
#
# Since: 7.2
#
##
{ 'struct': 'VirtioInfo',
'data': { 'path': 'str',
@ -28,6 +27,7 @@
# Returns a list of all realized VirtIODevices
#
# Features:
#
# @unstable: This command is meant for debugging.
#
# Returns: List of gathered VirtIODevices
@ -60,9 +60,7 @@
# }
# ]
# }
#
##
{ 'command': 'x-query-virtio',
'returns': [ 'VirtioInfo' ],
'features': [ 'unstable' ] }
@ -70,7 +68,7 @@
##
# @VhostStatus:
#
# Information about a vhost device. This information will only be
# Information about a vhost device. This information will only be
# displayed if the vhost device is active.
#
# @n-mem-sections: vhost_dev n_mem_sections
@ -98,9 +96,7 @@
# @log-size: vhost_dev log_size
#
# Since: 7.2
#
##
{ 'struct': 'VhostStatus',
'data': { 'n-mem-sections': 'int',
'n-tmp-sections': 'int',
@ -119,8 +115,8 @@
# @VirtioStatus:
#
# Full status of the virtio device with most VirtIODevice members.
# Also includes the full status of the corresponding vhost device
# if the vhost device is active.
# Also includes the full status of the corresponding vhost device if
# the vhost device is active.
#
# @name: VirtIODevice name
#
@ -136,8 +132,8 @@
#
# @device-endian: VirtIODevice device_endian
#
# @num-vqs: VirtIODevice virtqueue count. This is the number of active
# virtqueues being used by the VirtIODevice.
# @num-vqs: VirtIODevice virtqueue count. This is the number of
# active virtqueues being used by the VirtIODevice.
#
# @status: VirtIODevice configuration status (VirtioDeviceStatus)
#
@ -163,14 +159,12 @@
#
# @use-guest-notifier-mask: VirtIODevice use_guest_notifier_mask flag
#
# @vhost-dev: Corresponding vhost device info for a given VirtIODevice.
# Present if the given VirtIODevice has an active vhost
# device.
# @vhost-dev: Corresponding vhost device info for a given
# VirtIODevice. Present if the given VirtIODevice has an active
# vhost device.
#
# Since: 7.2
#
##
{ 'struct': 'VirtioStatus',
'data': { 'name': 'str',
'device-id': 'uint16',
@ -202,6 +196,7 @@
# @path: Canonical QOM path of the VirtIODevice
#
# Features:
#
# @unstable: This command is meant for debugging.
#
# Returns: VirtioStatus of the virtio device
@ -433,9 +428,7 @@
# "use-started": true
# }
# }
#
##
{ 'command': 'x-query-virtio-status',
'data': { 'path': 'str' },
'returns': 'VirtioStatus',
@ -448,13 +441,13 @@
# device
#
# @statuses: List of decoded configuration statuses of the virtio
# device
# device
#
# @unknown-statuses: Virtio device statuses bitmap that have not been decoded
# @unknown-statuses: Virtio device statuses bitmap that have not been
# decoded
#
# Since: 7.2
##
{ 'struct': 'VirtioDeviceStatus',
'data': { 'statuses': [ 'str' ],
'*unknown-statuses': 'uint8' } }
@ -466,14 +459,13 @@
# Vhost User device
#
# @protocols: List of decoded vhost user protocol features of a vhost
# user device
# user device
#
# @unknown-protocols: Vhost user device protocol features bitmap that
# have not been decoded
# have not been decoded
#
# Since: 7.2
##
{ 'struct': 'VhostDeviceProtocols',
'data': { 'protocols': [ 'str' ],
'*unknown-protocols': 'uint64' } }
@ -481,20 +473,19 @@
##
# @VirtioDeviceFeatures:
#
# The common fields that apply to most Virtio devices. Some devices
# The common fields that apply to most Virtio devices. Some devices
# may not have their own device-specific features (e.g. virtio-rng).
#
# @transports: List of transport features of the virtio device
#
# @dev-features: List of device-specific features (if the device has
# unique features)
# unique features)
#
# @unknown-dev-features: Virtio device features bitmap that have not
# been decoded
# been decoded
#
# Since: 7.2
##
{ 'struct': 'VirtioDeviceFeatures',
'data': { 'transports': [ 'str' ],
'*dev-features': [ 'str' ],
@ -525,7 +516,7 @@
# @vring-used: VirtQueue vring.used (device area)
#
# @last-avail-idx: VirtQueue last_avail_idx or return of vhost_dev
# vhost_get_vring_base (if vhost active)
# vhost_get_vring_base (if vhost active)
#
# @shadow-avail-idx: VirtQueue shadow_avail_idx
#
@ -536,9 +527,7 @@
# @signalled-used-valid: VirtQueue signalled_used_valid flag
#
# Since: 7.2
#
##
{ 'struct': 'VirtQueueStatus',
'data': { 'name': 'str',
'queue-index': 'uint16',
@ -565,16 +554,17 @@
# @queue: VirtQueue index to examine
#
# Features:
#
# @unstable: This command is meant for debugging.
#
# Returns: VirtQueueStatus of the VirtQueue
#
# Notes: last_avail_idx will not be displayed in the case where
# the selected VirtIODevice has a running vhost device and
# the VirtIODevice VirtQueue index (queue) does not exist for
# the corresponding vhost device vhost_virtqueue. Also,
# shadow_avail_idx will not be displayed in the case where
# the selected VirtIODevice has a running vhost device.
# Notes: last_avail_idx will not be displayed in the case where the
# selected VirtIODevice has a running vhost device and the
# VirtIODevice VirtQueue index (queue) does not exist for the
# corresponding vhost device vhost_virtqueue. Also,
# shadow_avail_idx will not be displayed in the case where the
# selected VirtIODevice has a running vhost device.
#
# Since: 7.2
#
@ -626,9 +616,7 @@
# "vring-num": 128
# }
# }
#
##
{ 'command': 'x-query-virtio-queue-status',
'data': { 'path': 'str', 'queue': 'uint16' },
'returns': 'VirtQueueStatus',
@ -667,9 +655,7 @@
# @used-size: vhost_virtqueue used_size
#
# Since: 7.2
#
##
{ 'struct': 'VirtVhostQueueStatus',
'data': { 'name': 'str',
'kick': 'int',
@ -695,6 +681,7 @@
# @queue: vhost_virtqueue index to examine
#
# Features:
#
# @unstable: This command is meant for debugging.
#
# Returns: VirtVhostQueueStatus of the vhost_virtqueue
@ -748,9 +735,7 @@
# "kick": 0
# }
# }
#
##
{ 'command': 'x-query-virtio-vhost-queue-status',
'data': { 'path': 'str', 'queue': 'uint16' },
'returns': 'VirtVhostQueueStatus',
@ -768,9 +753,7 @@
# @flags: List of descriptor flags
#
# Since: 7.2
#
##
{ 'struct': 'VirtioRingDesc',
'data': { 'addr': 'uint64',
'len': 'uint32',
@ -788,9 +771,7 @@
# @ring: VRingAvail ring[] entry at provided index
#
# Since: 7.2
#
##
{ 'struct': 'VirtioRingAvail',
'data': { 'flags': 'uint16',
'idx': 'uint16',
@ -806,9 +787,7 @@
# @idx: VRingUsed index
#
# Since: 7.2
#
##
{ 'struct': 'VirtioRingUsed',
'data': { 'flags': 'uint16',
'idx': 'uint16' } }
@ -830,9 +809,7 @@
# @used: VRingUsed info
#
# Since: 7.2
#
##
{ 'struct': 'VirtioQueueElement',
'data': { 'name': 'str',
'index': 'uint32',
@ -849,10 +826,11 @@
#
# @queue: VirtQueue index to examine
#
# @index: Index of the element in the queue
# (default: head of the queue)
# @index: Index of the element in the queue (default: head of the
# queue)
#
# Features:
#
# @unstable: This command is meant for debugging.
#
# Returns: VirtioQueueElement information
@ -945,9 +923,7 @@
# }
# }
# }
#
##
{ 'command': 'x-query-virtio-queue-element',
'data': { 'path': 'str', 'queue': 'uint16', '*index': 'uint16' },
'returns': 'VirtioQueueElement',

42
qapi/yank.json
View File

@ -9,7 +9,7 @@
##
# @YankInstanceType:
#
# An enumeration of yank instance types. See @YankInstance for more
# An enumeration of yank instance types. See @YankInstance for more
# information.
#
# Since: 6.0
@ -20,8 +20,8 @@
##
# @YankInstanceBlockNode:
#
# Specifies which block graph node to yank. See @YankInstance for more
# information.
# Specifies which block graph node to yank. See @YankInstance for
# more information.
#
# @node-name: the name of the block graph node
#
@ -33,8 +33,8 @@
##
# @YankInstanceChardev:
#
# Specifies which character device to yank. See @YankInstance for more
# information.
# Specifies which character device to yank. See @YankInstance for
# more information.
#
# @id: the chardev's ID
#
@ -46,21 +46,18 @@
##
# @YankInstance:
#
# A yank instance can be yanked with the @yank qmp command to recover from a
# hanging QEMU.
# A yank instance can be yanked with the @yank qmp command to recover
# from a hanging QEMU.
#
# Currently implemented yank instances:
#
# - nbd block device:
# Yanking it will shut down the connection to the nbd server without
# attempting to reconnect.
# - socket chardev:
# Yanking it will shut down the connected socket.
# - migration:
# Yanking it will shut down all migration connections. Unlike
# @migrate_cancel, it will not notify the migration process, so migration
# will go into @failed state, instead of @cancelled state. @yank should be
# used to recover from hangs.
# - nbd block device: Yanking it will shut down the connection to the
# nbd server without attempting to reconnect.
# - socket chardev: Yanking it will shut down the connected socket.
# - migration: Yanking it will shut down all migration connections.
# Unlike @migrate_cancel, it will not notify the migration process,
# so migration will go into @failed state, instead of @cancelled
# state. @yank should be used to recover from hangs.
#
# Since: 6.0
##
@ -74,13 +71,14 @@
##
# @yank:
#
# Try to recover from hanging QEMU by yanking the specified instances. See
# @YankInstance for more information.
# Try to recover from hanging QEMU by yanking the specified instances.
# See @YankInstance for more information.
#
# Takes a list of @YankInstance as argument.
#
# Returns: - Nothing on success
# - @DeviceNotFound error, if any of the YankInstances doesn't exist
# Returns:
# - Nothing on success
# - @DeviceNotFound error, if any of the YankInstances doesn't exist
#
# Example:
#
@ -101,7 +99,7 @@
##
# @query-yank:
#
# Query yank instances. See @YankInstance for more information.
# Query yank instances. See @YankInstance for more information.
#
# Returns: list of @YankInstance
#

668
qga/qapi-schema.json
View File

File diff suppressed because it is too large Load Diff

141
scripts/qapi/parser.py
View File

@ -346,7 +346,7 @@ class QAPISchemaParser:
elif not self.tok.isspace():
# Show up to next structural, whitespace or quote
# character
match = must_match('[^[\\]{}:,\\s\'"]+',
match = must_match('[^[\\]{}:,\\s\']+',
self.src[self.cursor-1:])
raise QAPIParseError(self, "stray '%s'" % match.group(0))
@ -468,34 +468,39 @@ class QAPIDoc:
class Section:
# pylint: disable=too-few-public-methods
def __init__(self, parser: QAPISchemaParser,
name: Optional[str] = None, indent: int = 0):
name: Optional[str] = None):
# parser, for error messages about indentation
self._parser = parser
# optional section name (argument/member or section name)
self.name = name
# section text without section name
self.text = ''
# the expected indent level of the text of this section
self._indent = indent
# indentation to strip (None means indeterminate)
self._indent = None if self.name else 0
def append(self, line: str) -> None:
# Strip leading spaces corresponding to the expected indent level
# Blank lines are always OK.
line = line.rstrip()
if line:
indent = must_match(r'\s*', line).end()
if indent < self._indent:
if self._indent is None:
# indeterminate indentation
if self.text != '':
# non-blank, non-first line determines indentation
self._indent = indent
elif indent < self._indent:
raise QAPIParseError(
self._parser,
"unexpected de-indent (expected at least %d spaces)" %
self._indent)
line = line[self._indent:]
self.text += line.rstrip() + '\n'
self.text += line + '\n'
class ArgSection(Section):
def __init__(self, parser: QAPISchemaParser,
name: str, indent: int = 0):
super().__init__(parser, name, indent)
name: str):
super().__init__(parser, name)
self.member: Optional['QAPISchemaMember'] = None
def connect(self, member: 'QAPISchemaMember') -> None:
@ -558,12 +563,12 @@ class QAPIDoc:
self._switch_section(QAPIDoc.NullSection(self._parser))
@staticmethod
def _is_section_tag(name: str) -> bool:
return name in ('Returns:', 'Since:',
# those are often singular or plural
'Note:', 'Notes:',
'Example:', 'Examples:',
'TODO:')
def _match_at_name_colon(string: str) -> re.Match:
return re.match(r'@([^:]*): *', string)
@staticmethod
def _match_section_tag(string: str) -> re.Match:
return re.match(r'(Returns|Since|Notes?|Examples?|TODO): *', string)
def _append_body_line(self, line: str) -> None:
"""
@ -579,7 +584,6 @@ class QAPIDoc:
Else, append the line to the current section.
"""
name = line.split(' ', 1)[0]
# FIXME not nice: things like '# @foo:' and '# @foo: ' aren't
# recognized, and get silently treated as ordinary text
if not self.symbol and not self.body.text and line.startswith('@'):
@ -593,12 +597,12 @@ class QAPIDoc:
self._parser, "name required after '@'")
elif self.symbol:
# This is a definition documentation block
if name.startswith('@') and name.endswith(':'):
if self._match_at_name_colon(line):
self._append_line = self._append_args_line
self._append_args_line(line)
elif line == 'Features:':
self._append_line = self._append_features_line
elif self._is_section_tag(name):
elif self._match_section_tag(line):
self._append_line = self._append_various_line
self._append_various_line(line)
else:
@ -619,25 +623,11 @@ class QAPIDoc:
Else, append the line to the current section.
"""
name = line.split(' ', 1)[0]
if name.startswith('@') and name.endswith(':'):
# If line is "@arg: first line of description", find
# the index of 'f', which is the indent we expect for any
# following lines. We then remove the leading "@arg:"
# from line and replace it with spaces so that 'f' has the
# same index as it did in the original line and can be
# handled the same way we will handle following lines.
indent = must_match(r'@\S*:\s*', line).end()
line = line[indent:]
if not line:
# Line was just the "@arg:" header; following lines
# are not indented
indent = 0
else:
line = ' ' * indent + line
self._start_args_section(name[1:-1], indent)
elif self._is_section_tag(name):
match = self._match_at_name_colon(line)
if match:
line = line[match.end():]
self._start_args_section(match.group(1))
elif self._match_section_tag(line):
self._append_line = self._append_various_line
self._append_various_line(line)
return
@ -654,25 +644,11 @@ class QAPIDoc:
self._append_freeform(line)
def _append_features_line(self, line: str) -> None:
name = line.split(' ', 1)[0]
if name.startswith('@') and name.endswith(':'):
# If line is "@arg: first line of description", find
# the index of 'f', which is the indent we expect for any
# following lines. We then remove the leading "@arg:"
# from line and replace it with spaces so that 'f' has the
# same index as it did in the original line and can be
# handled the same way we will handle following lines.
indent = must_match(r'@\S*:\s*', line).end()
line = line[indent:]
if not line:
# Line was just the "@arg:" header; following lines
# are not indented
indent = 0
else:
line = ' ' * indent + line
self._start_features_section(name[1:-1], indent)
elif self._is_section_tag(name):
match = self._match_at_name_colon(line)
if match:
line = line[match.end():]
self._start_features_section(match.group(1))
elif self._match_section_tag(line):
self._append_line = self._append_various_line
self._append_various_line(line)
return
@ -696,36 +672,22 @@ class QAPIDoc:
Else, append the line to the current section.
"""
name = line.split(' ', 1)[0]
if name.startswith('@') and name.endswith(':'):
match = self._match_at_name_colon(line)
if match:
raise QAPIParseError(self._parser,
"'%s' can't follow '%s' section"
% (name, self.sections[0].name))
if self._is_section_tag(name):
# If line is "Section: first line of description", find
# the index of 'f', which is the indent we expect for any
# following lines. We then remove the leading "Section:"
# from line and replace it with spaces so that 'f' has the
# same index as it did in the original line and can be
# handled the same way we will handle following lines.
indent = must_match(r'\S*:\s*', line).end()
line = line[indent:]
if not line:
# Line was just the "Section:" header; following lines
# are not indented
indent = 0
else:
line = ' ' * indent + line
self._start_section(name[:-1], indent)
"'@%s:' can't follow '%s' section"
% (match.group(1), self.sections[0].name))
match = self._match_section_tag(line)
if match:
line = line[match.end():]
self._start_section(match.group(1))
self._append_freeform(line)
def _start_symbol_section(
self,
symbols_dict: Dict[str, 'QAPIDoc.ArgSection'],
name: str,
indent: int) -> None:
name: str) -> None:
# FIXME invalid names other than the empty string aren't flagged
if not name:
raise QAPIParseError(self._parser, "invalid parameter name")
@ -733,27 +695,26 @@ class QAPIDoc:
raise QAPIParseError(self._parser,
"'%s' parameter name duplicated" % name)
assert not self.sections
new_section = QAPIDoc.ArgSection(self._parser, name, indent)
new_section = QAPIDoc.ArgSection(self._parser, name)
self._switch_section(new_section)
symbols_dict[name] = new_section
def _start_args_section(self, name: str, indent: int) -> None:
self._start_symbol_section(self.args, name, indent)
def _start_args_section(self, name: str) -> None:
self._start_symbol_section(self.args, name)
def _start_features_section(self, name: str, indent: int) -> None:
self._start_symbol_section(self.features, name, indent)
def _start_features_section(self, name: str) -> None:
self._start_symbol_section(self.features, name)
def _start_section(self, name: Optional[str] = None,
indent: int = 0) -> None:
def _start_section(self, name: Optional[str] = None) -> None:
if name in ('Returns', 'Since') and self.has_section(name):
raise QAPIParseError(self._parser,
"duplicated '%s' section" % name)
new_section = QAPIDoc.Section(self._parser, name, indent)
new_section = QAPIDoc.Section(self._parser, name)
self._switch_section(new_section)
self.sections.append(new_section)
def _switch_section(self, new_section: 'QAPIDoc.Section') -> None:
text = self._section.text = self._section.text.strip()
text = self._section.text = self._section.text.strip('\n')
# Only the 'body' section is allowed to have an empty body.
# All other sections, including anonymous ones, must have text.

2
tests/qapi-schema/doc-bad-indent.err
View File

@ -1 +1 @@
doc-bad-indent.json:6:1: unexpected de-indent (expected at least 4 spaces)
doc-bad-indent.json:7:1: unexpected de-indent (expected at least 2 spaces)

3
tests/qapi-schema/doc-bad-indent.json
View File

@ -3,6 +3,7 @@
##
# @foo:
# @a: line one
# line two is wrongly indented
# line two
# line three is wrongly indented
##
{ 'command': 'foo', 'data': { 'a': 'int' } }

20
tests/qapi-schema/doc-good.json
View File

@ -54,7 +54,7 @@
##
# @Enum:
#
# @one: The _one_ {and only}
# @one: The _one_ {and only}, description on the same line
#
# Features:
# @enum-feat: Also _one_ {and only}
@ -73,7 +73,8 @@
# @Base:
#
# @base1:
# the first member
# description starts on a new line,
# not indented
##
{ 'struct': 'Base', 'data': { 'base1': 'Enum' },
'if': { 'all': ['IFALL1', 'IFALL2'] } }
@ -83,7 +84,9 @@
#
# A paragraph
#
# Another paragraph (but no @var: line)
# Another paragraph
#
# @var1 is undocumented
#
# Features:
# @variant1-feat: a feature
@ -118,7 +121,8 @@
##
# @Alternate:
#
# @i: an integer
# @i: description starts on the same line
# remainder indented the same
# @b is undocumented
#
# Features:
@ -136,10 +140,12 @@
##
# @cmd:
#
# @arg1: the first argument
# @arg1:
# description starts on a new line,
# indented
#
# @arg2: the second
# argument
# @arg2: description starts on the same line
# remainder indented differently
#
# Features:
# @cmd-feat1: a feature

19
tests/qapi-schema/doc-good.out
View File

@ -104,7 +104,7 @@ doc symbol=Enum
body=
arg=one
The _one_ {and only}
The _one_ {and only}, description on the same line
arg=two
feature=enum-feat
@ -117,12 +117,15 @@ doc symbol=Base
body=
arg=base1
the first member
description starts on a new line,
not indented
doc symbol=Variant1
body=
A paragraph
Another paragraph (but no @var: line)
Another paragraph
@var1 is undocumented
arg=var1
feature=variant1-feat
@ -141,7 +144,8 @@ doc symbol=Alternate
body=
arg=i
an integer
description starts on the same line
remainder indented the same
@b is undocumented
arg=b
@ -154,10 +158,11 @@ doc symbol=cmd
body=
arg=arg1
the first argument
description starts on a new line,
indented
arg=arg2
the second
argument
description starts on the same line
remainder indented differently
arg=arg3
feature=cmd-feat1