mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

QAPI patches patches for 2023-05-09

Browse Source 
-----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
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 # <- get that
## ##
For legibility, wrap text paragraphs so every line is at most 70
characters long.
Separate sentences with two spaces.
Definition documentation 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 alternates), or value (for enums), a description of each feature (if
any), and finally optional tagged sections. any), and finally optional tagged sections.
The description of an argument or feature 'name' starts with Descriptions start with '\@name:'. The description text should be
'\@name:'. The description text can start on the line following the indented like this::
'\@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::
# @argone: # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
# This is a two line description # do eiusmod tempor incididunt ut labore et dolore magna aliqua.
# in the first style.
#
# @argtwo: This is a two line description
# in the second style.
The number of spaces between the ':' and the text is not significant. .. FIXME The parser accepts these things in almost any order.
.. admonition:: FIXME .. FIXME union branches should be described, too.
The parser accepts these things in almost any order.
.. admonition:: FIXME
union branches should be described, too.
Extensions added after the definition was first released carry a 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 The feature descriptions must be preceded by a line "Features:", like
this:: this::
# Features: # Features:
#
# @feature: Description text # @feature: Description text
A tagged section starts with one of the following words: A tagged section starts with one of the following words:
"Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:". "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
The section ends with the start of a new section. The section ends with the start of a new section.
The text of a section can start on a new line, in The second and subsequent lines of sections other than
which case it must not be indented at all. It can also start "Example"/"Examples" should be indented like this::
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.
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. definition.
An 'Example' or 'Examples' section is automatically rendered An "Example" or "Examples" section is rendered entirely
entirely as literal fixed-width text. In other sections, as literal fixed-width text. "TODO" sections are not rendered at all
the text is formatted, and rST markup can be used. (they are for developers, not users of QMP). In other sections, the
text is formatted, and rST markup can be used.
For example:: For example::
@ -1023,7 +1017,7 @@ For example::
# Statistics of a virtual block device or a block backing device. # Statistics of a virtual block device or a block backing device.
# #
# @device: If the stats are for a virtual block device, the name # @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) # @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 the @BlockStats for all virtual block devices.
# #
# @query-nodes: If true, the command will query all the # @query-nodes: If true, the command will query all the block nodes
# block nodes ... explain, explain ... (since 2.3) # ... explain, explain ... (since 2.3)
# #
# Returns: A list of @BlockStats for each virtual block devices. # 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, # @none: None (no memory side cache in this proximity domain,
# or cache associativity unknown) # or cache associativity unknown)
# (since 5.0)
The description is parsed as a definition list with term "None (no The last line's de-indent is wrong. The second and subsequent lines
memory side cache in this proximity domain," and definition "or cache need to line up with each other, like this::
associativity unknown)".
# @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:: 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""" """Return list of doctree nodes for additional sections"""
nodelist = [] nodelist = []
for section in doc.sections: for section in doc.sections:
if section.name and section.name == 'TODO':
# Hide TODO: sections
continue
snode = self._make_section(section.name) snode = self._make_section(section.name)
if section.name and section.name.startswith('Example'): if section.name and section.name.startswith('Example'):
snode += self._nodes_for_example(section.text) 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/expr.py',
meson.current_source_dir() / 'scripts/qapi/gen.py', meson.current_source_dir() / 'scripts/qapi/gen.py',
meson.current_source_dir() / 'scripts/qapi/introspect.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/parser.py',
meson.current_source_dir() / 'scripts/qapi/schema.py', meson.current_source_dir() / 'scripts/qapi/schema.py',
meson.current_source_dir() / 'scripts/qapi/source.py', meson.current_source_dir() / 'scripts/qapi/source.py',
meson.current_source_dir() / 'scripts/qapi/types.py', meson.current_source_dir() / 'scripts/qapi/types.py',
meson.current_source_dir() / 'scripts/qapi/visit.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' 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. # 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 # At most one of @file and @data can be specified. The list of files
# by any one of them is loaded and concatenated in order. If both are omitted, # specified by any one of them is loaded and concatenated in order.
# @data is implied. # If both are omitted, @data is implied.
# #
# Other fields / optargs can be used to override fields of the generic ACPI # Other fields / optargs can be used to override fields of the generic
# table header; refer to the ACPI specification 5.0, section 5.2.6 System # ACPI table header; refer to the ACPI specification 5.0, section
# Description Table Header. If a header field is not overridden, then the # 5.2.6 System Description Table Header. If a header field is not
# corresponding value from the concatenated blob is used (in case of @file), or # overridden, then the corresponding value from the concatenated blob
# it is filled in with a hard-coded value (in case of @data). # 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 # String fields are copied into the matching ACPI member from lowest
# upwards, and silently truncated / NUL-padded to length. # address upwards, and silently truncated / NUL-padded to length.
# #
# @sig: table signature / identifier (4 bytes) # @sig: table signature / identifier (4 bytes)
# #
@ -38,20 +39,20 @@
# @oem_rev: OEM-supplied revision number (4 bytes) # @oem_rev: OEM-supplied revision number (4 bytes)
# #
# @asl_compiler_id: identifier of the utility that created the table # @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 # @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 # @file: colon (:) separated list of pathnames to load and concatenate
# concatenate as table data. The resultant binary blob is expected to # as table data. The resultant binary blob is expected to have an
# have an ACPI table header. At least one file is required. This field # ACPI table header. At least one file is required. This field
# excludes @data. # excludes @data.
# #
# @data: colon (:) separated list of pathnames to load and # @data: colon (:) separated list of pathnames to load and concatenate
# concatenate as table data. The resultant binary blob must not have an # as table data. The resultant binary blob must not have an ACPI
# ACPI table header. At least one file is required. This field excludes # table header. At least one file is required. This field
# @file. # excludes @file.
# #
# Since: 1.5 # Since: 1.5
## ##
@ -71,6 +72,7 @@
# @ACPISlotType: # @ACPISlotType:
# #
# @DIMM: memory slot # @DIMM: memory slot
#
# @CPU: logical CPU slot (since 2.7) # @CPU: logical CPU slot (since 2.7)
## ##
{ 'enum': 'ACPISlotType', 'data': [ 'DIMM', 'CPU' ] } { 'enum': 'ACPISlotType', 'data': [ 'DIMM', 'CPU' ] }
@ -78,9 +80,9 @@
## ##
# @ACPIOSTInfo: # @ACPIOSTInfo:
# #
# OSPM Status Indication for a device # OSPM Status Indication for a device For description of possible
# For description of possible values of @source and @status fields # values of @source and @status fields see "_OST (OSPM Status
# see "_OST (OSPM Status Indication)" chapter of ACPI5.0 spec. # Indication)" chapter of ACPI5.0 spec.
# #
# @device: device ID associated with slot # @device: device ID associated with slot
# #
@ -117,7 +119,6 @@
# { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0}, # { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
# { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0} # { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
# ]} # ]}
#
## ##
{ 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] } { 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] }
@ -136,7 +137,6 @@
# "data": { "info": { "device": "d1", "slot": "0", # "data": { "info": { "device": "d1", "slot": "0",
# "slot-type": "DIMM", "source": 1, "status": 0 } }, # "slot-type": "DIMM", "source": 1, "status": 0 } },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
#
## ##
{ 'event': 'ACPI_DEVICE_OST', { 'event': 'ACPI_DEVICE_OST',
'data': { 'info': 'ACPIOSTInfo' } } 'data': { 'info': 'ACPIOSTInfo' } }

93
qapi/audio.json
View File

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

29
qapi/authz.json
View File

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

214
qapi/block.json
View File

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

134
qapi/char.json
View File

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

19
qapi/common.json
View File

@ -70,6 +70,7 @@
# has a different meaning. # has a different meaning.
# #
# @s: the string value # @s: the string value
#
# @n: no string value # @n: no string value
# #
# Since: 2.10 # Since: 2.10
@ -155,11 +156,11 @@
# #
# @preferred: set the preferred host nodes for allocation # @preferred: set the preferred host nodes for allocation
# #
# @bind: a strict policy that restricts memory allocation to the # @bind: a strict policy that restricts memory allocation to the host
# host nodes specified # nodes specified
# #
# @interleave: memory allocations are interleaved across the set # @interleave: memory allocations are interleaved across the set of
# of host nodes specified # host nodes specified
# #
# Since: 2.1 # Since: 2.1
## ##
@ -169,17 +170,17 @@
## ##
# @NetFilterDirection: # @NetFilterDirection:
# #
# Indicates whether a netfilter is attached to a netdev's transmit queue or # Indicates whether a netfilter is attached to a netdev's transmit
# receive queue or both. # queue or receive queue or both.
# #
# @all: the filter is attached both to the receive and the transmit # @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, # @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, # @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 # Since: 2.5
## ##

13
qapi/compat.json
View File

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

59
qapi/control.json
View File

@ -14,10 +14,9 @@
# Arguments: # Arguments:
# #
# @enable: An optional list of QMPCapability values to enable. The # @enable: An optional list of QMPCapability values to enable. The
# client must not enable any capability that is not # client must not enable any capability that is not mentioned in
# mentioned in the QMP greeting message. If the field is not # the QMP greeting message. If the field is not provided, it
# provided, it means no QMP capabilities will be enabled. # means no QMP capabilities will be enabled. (since 2.12)
# (since 2.12)
# #
# Example: # Example:
# #
@ -25,12 +24,14 @@
# "arguments": { "enable": [ "oob" ] } } # "arguments": { "enable": [ "oob" ] } }
# <- { "return": {} } # <- { "return": {} }
# #
# Notes: This command is valid exactly when first connecting: it must be # Notes: This command is valid exactly when first connecting: it must
# issued before any other command will be accepted, and will fail once the # be issued before any other command will be accepted, and will
# monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt) # 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 # The QMP client needs to explicitly enable QMP capabilities,
# all the QMP capabilities will be turned off by default. # otherwise all the QMP capabilities will be turned off by
# default.
# #
# Since: 0.13 # Since: 0.13
## ##
@ -44,8 +45,8 @@
# Enumeration of capabilities to be advertised during initial client # Enumeration of capabilities to be advertised during initial client
# connection, used for agreeing on particular QMP extension behaviors. # connection, used for agreeing on particular QMP extension behaviors.
# #
# @oob: QMP ability to support out-of-band requests. # @oob: QMP ability to support out-of-band requests. (Please refer to
# (Please refer to qmp-spec.txt for more information on OOB) # qmp-spec.txt for more information on OOB)
# #
# Since: 2.12 # Since: 2.12
## ##
@ -73,16 +74,16 @@
# #
# A description of QEMU's version. # A description of QEMU's version.
# #
# @qemu: The version of QEMU. By current convention, a micro # @qemu: The version of QEMU. By current convention, a micro version
# version of 50 signifies a development branch. A micro version # of 50 signifies a development branch. A micro version greater
# greater than or equal to 90 signifies a release candidate for # than or equal to 90 signifies a release candidate for the next
# the next minor version. A micro version of less than 50 # minor version. A micro version of less than 50 signifies a
# signifies a stable release. # stable release.
# #
# @package: QEMU will always set this field to an empty string. Downstream # @package: QEMU will always set this field to an empty string.
# versions of QEMU should set this to a non-empty string. The # Downstream versions of QEMU should set this to a non-empty
# exact format depends on the downstream however it highly # string. The exact format depends on the downstream however it
# recommended that a unique name is used. # highly recommended that a unique name is used.
# #
# Since: 0.14 # Since: 0.14
## ##
@ -94,7 +95,8 @@
# #
# Returns the current version of QEMU. # 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 # Since: 0.14
# #
@ -111,7 +113,6 @@
# "package":"" # "package":""
# } # }
# } # }
#
## ##
{ 'command': 'query-version', 'returns': 'VersionInfo', { 'command': 'query-version', 'returns': 'VersionInfo',
'allow-preconfig': true } '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'], { 'command': 'query-commands', 'returns': ['CommandInfo'],
'allow-preconfig': true } 'allow-preconfig': true }
@ -159,10 +160,10 @@
## ##
# @quit: # @quit:
# #
# This command will cause the QEMU process to exit gracefully. While every # This command will cause the QEMU process to exit gracefully. While
# attempt is made to send the QMP response before terminating, this is not # every attempt is made to send the QMP response before terminating,
# guaranteed. When using this interface, a premature EOF would not be # this is not guaranteed. When using this interface, a premature EOF
# unexpected. # would not be unexpected.
# #
# Since: 0.14 # Since: 0.14
# #
@ -195,7 +196,7 @@
# @id: Name of the monitor # @id: Name of the monitor
# #
# @mode: Selects the monitor mode (default: readline in the system # @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) # @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. # The type of network endpoint that will be using the credentials.
# Most types of credential require different setup / structures # Most types of credential require different setup / structures
# depending on whether they will be used in a server versus a # depending on whether they will be used in a server versus a client.
# client.
# #
# @client: the network endpoint is acting as the client # @client: the network endpoint is acting as the client
# #
@ -29,7 +28,9 @@
# #
# The data format that the secret is provided in # 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 # @base64: arbitrary base64 encoded binary data
# #
# Since: 2.6 # Since: 2.6
@ -44,11 +45,17 @@
# The supported algorithms for computing content digests # The supported algorithms for computing content digests
# #
# @md5: MD5. Should not be used in any new code, legacy compat only # @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 # @sha1: SHA-1. Should not be used in any new code, legacy compat only
#
# @sha224: SHA-224. (since 2.7) # @sha224: SHA-224. (since 2.7)
#
# @sha256: SHA-256. Current recommended strong hash. # @sha256: SHA-256. Current recommended strong hash.
#
# @sha384: SHA-384. (since 2.7) # @sha384: SHA-384. (since 2.7)
#
# @sha512: SHA-512. (since 2.7) # @sha512: SHA-512. (since 2.7)
#
# @ripemd160: RIPEMD-160. (since 2.7) # @ripemd160: RIPEMD-160. (since 2.7)
# #
# Since: 2.6 # Since: 2.6
@ -63,16 +70,28 @@
# The supported algorithms for content encryption ciphers # The supported algorithms for content encryption ciphers
# #
# @aes-128: AES with 128 bit / 16 byte keys # @aes-128: AES with 128 bit / 16 byte keys
#
# @aes-192: AES with 192 bit / 24 byte keys # @aes-192: AES with 192 bit / 24 byte keys
#
# @aes-256: AES with 256 bit / 32 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) # @3des: 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
#
# @cast5-128: Cast5 with 128 bit / 16 byte keys # @cast5-128: Cast5 with 128 bit / 16 byte keys
#
# @serpent-128: Serpent 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-192: Serpent with 192 bit / 24 byte keys
#
# @serpent-256: Serpent with 256 bit / 32 byte keys # @serpent-256: Serpent with 256 bit / 32 byte keys
#
# @twofish-128: Twofish with 128 bit / 16 byte keys # @twofish-128: Twofish with 128 bit / 16 byte keys
#
# @twofish-192: Twofish with 192 bit / 24 byte keys # @twofish-192: Twofish with 192 bit / 24 byte keys
#
# @twofish-256: Twofish with 256 bit / 32 byte keys # @twofish-256: Twofish with 256 bit / 32 byte keys
# #
# Since: 2.6 # Since: 2.6
@ -91,8 +110,11 @@
# The supported modes for content encryption ciphers # The supported modes for content encryption ciphers
# #
# @ecb: Electronic Code Book # @ecb: Electronic Code Book
#
# @cbc: Cipher Block Chaining # @cbc: Cipher Block Chaining
#
# @xts: XEX with tweaked code book and ciphertext stealing # @xts: XEX with tweaked code book and ciphertext stealing
#
# @ctr: Counter (Since 2.8) # @ctr: Counter (Since 2.8)
# #
# Since: 2.6 # Since: 2.6
@ -104,15 +126,17 @@
## ##
# @QCryptoIVGenAlgorithm: # @QCryptoIVGenAlgorithm:
# #
# The supported algorithms for generating initialization # The supported algorithms for generating initialization vectors for
# vectors for full disk encryption. The 'plain' generator # full disk encryption. The 'plain' generator should not be used for
# should not be used for disks with sector numbers larger # disks with sector numbers larger than 2^32, except where
# than 2^32, except where compatibility with pre-existing # compatibility with pre-existing Linux dm-crypt volumes is required.
# Linux dm-crypt volumes is required.
# #
# @plain: 64-bit sector number truncated to 32-bits # @plain: 64-bit sector number truncated to 32-bits
#
# @plain64: 64-bit sector number # @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 # Since: 2.6
## ##
@ -125,9 +149,10 @@
# #
# The supported full disk encryption formats # The supported full disk encryption formats
# #
# @qcow: QCow/QCow2 built-in AES-CBC encryption. Use only # @qcow: QCow/QCow2 built-in AES-CBC encryption. Use only for
# for liberating data from old images. # liberating data from old images.
# @luks: LUKS encryption format. Recommended for new images #
# @luks: LUKS encryption format. Recommended for new images
# #
# Since: 2.6 # Since: 2.6
## ##
@ -138,8 +163,7 @@
## ##
# @QCryptoBlockOptionsBase: # @QCryptoBlockOptionsBase:
# #
# The common options that apply to all full disk # The common options that apply to all full disk encryption formats
# encryption formats
# #
# @format: the encryption format # @format: the encryption format
# #
@ -154,8 +178,8 @@
# The options that apply to QCow/QCow2 AES-CBC encryption format # The options that apply to QCow/QCow2 AES-CBC encryption format
# #
# @key-secret: the ID of a QCryptoSecret object providing the # @key-secret: the ID of a QCryptoSecret object providing the
# decryption key. Mandatory except when probing image for # decryption key. Mandatory except when probing image for
# metadata only. # metadata only.
# #
# Since: 2.6 # Since: 2.6
## ##
@ -168,8 +192,8 @@
# The options that apply to LUKS encryption format # The options that apply to LUKS encryption format
# #
# @key-secret: the ID of a QCryptoSecret object providing the # @key-secret: the ID of a QCryptoSecret object providing the
# decryption key. Mandatory except when probing image for # decryption key. Mandatory except when probing image for
# metadata only. # metadata only.
# #
# Since: 2.6 # Since: 2.6
## ##
@ -181,19 +205,23 @@
# #
# The options that apply to LUKS encryption format initialization # The options that apply to LUKS encryption format initialization
# #
# @cipher-alg: the cipher algorithm for data encryption # @cipher-alg: the cipher algorithm for data encryption Currently
# Currently defaults to 'aes-256'. # defaults to 'aes-256'.
# @cipher-mode: the cipher mode for data encryption #
# Currently defaults to 'xts' # @cipher-mode: the cipher mode for data encryption Currently defaults
# @ivgen-alg: the initialization vector generator # to 'xts'
# Currently defaults to 'plain64' #
# @ivgen-hash-alg: the initialization vector generator hash # @ivgen-alg: the initialization vector generator Currently defaults
# Currently defaults to 'sha256' # to 'plain64'
# @hash-alg: the master key hash algorithm #
# Currently defaults to 'sha256' # @ivgen-hash-alg: the initialization vector generator hash Currently
# @iter-time: number of milliseconds to spend in # defaults to 'sha256'
# PBKDF passphrase processing. Currently defaults #
# to 2000. (since 2.8) # @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 # Since: 2.6
## ##
@ -209,8 +237,8 @@
## ##
# @QCryptoBlockOpenOptions: # @QCryptoBlockOpenOptions:
# #
# The options that are available for all encryption formats # The options that are available for all encryption formats when
# when opening an existing volume # opening an existing volume
# #
# Since: 2.6 # Since: 2.6
## ##
@ -223,8 +251,8 @@
## ##
# @QCryptoBlockCreateOptions: # @QCryptoBlockCreateOptions:
# #
# The options that are available for all encryption formats # The options that are available for all encryption formats when
# when initializing a new volume # initializing a new volume
# #
# Since: 2.6 # Since: 2.6
## ##
@ -237,8 +265,8 @@
## ##
# @QCryptoBlockInfoBase: # @QCryptoBlockInfoBase:
# #
# The common information that applies to all full disk # The common information that applies to all full disk encryption
# encryption formats # formats
# #
# @format: the encryption format # @format: the encryption format
# #
@ -250,12 +278,14 @@
## ##
# @QCryptoBlockInfoLUKSSlot: # @QCryptoBlockInfoLUKSSlot:
# #
# Information about the LUKS block encryption key # Information about the LUKS block encryption key slot options
# slot options
# #
# @active: whether the key slot is currently in use # @active: whether the key slot is currently in use
#
# @key-offset: offset to the key material in bytes # @key-offset: offset to the key material in bytes
#
# @iters: number of PBKDF2 iterations for key material # @iters: number of PBKDF2 iterations for key material
#
# @stripes: number of stripes for splitting key material # @stripes: number of stripes for splitting key material
# #
# Since: 2.7 # Since: 2.7
@ -272,13 +302,21 @@
# Information about the LUKS block encryption options # Information about the LUKS block encryption options
# #
# @cipher-alg: the cipher algorithm for data encryption # @cipher-alg: the cipher algorithm for data encryption
#
# @cipher-mode: the cipher mode for data encryption # @cipher-mode: the cipher mode for data encryption
#
# @ivgen-alg: the initialization vector generator # @ivgen-alg: the initialization vector generator
#
# @ivgen-hash-alg: the initialization vector generator hash # @ivgen-hash-alg: the initialization vector generator hash
#
# @hash-alg: the master key hash algorithm # @hash-alg: the master key hash algorithm
#
# @payload-offset: offset to the payload data in bytes # @payload-offset: offset to the payload data in bytes
#
# @master-key-iters: number of PBKDF2 iterations for key material # @master-key-iters: number of PBKDF2 iterations for key material
#
# @uuid: unique identifier for the volume # @uuid: unique identifier for the volume
#
# @slots: information about each key slot # @slots: information about each key slot
# #
# Since: 2.7 # Since: 2.7
@ -312,7 +350,9 @@
# Defines state of keyslots that are affected by the update # Defines state of keyslots that are affected by the update
# #
# @active: The slots contain the given password and marked as active # @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 # Since: 5.1
## ##
@ -322,35 +362,34 @@
## ##
# @QCryptoBlockAmendOptionsLUKS: # @QCryptoBlockAmendOptionsLUKS:
# #
# This struct defines the update parameters that activate/de-activate set # This struct defines the update parameters that activate/de-activate
# of keyslots # set of keyslots
# #
# @state: the desired state of the keyslots # @state: the desired state of the keyslots
# #
# @new-secret: The ID of a QCryptoSecret object providing the password to be # @new-secret: The ID of a QCryptoSecret object providing the password
# written into added active keyslots # to be written into added active keyslots
# #
# @old-secret: Optional (for deactivation only) # @old-secret: Optional (for deactivation only) If given will
# If given will deactivate all keyslots that # deactivate all keyslots that match password located in
# match password located in QCryptoSecret with this ID # QCryptoSecret with this ID
# #
# @iter-time: Optional (for activation only) # @iter-time: Optional (for activation only) Number of milliseconds to
# Number of milliseconds to spend in # spend in PBKDF passphrase processing for the newly activated
# PBKDF passphrase processing for the newly activated keyslot. # keyslot. Currently defaults to 2000.
# Currently defaults to 2000.
# #
# @keyslot: Optional. ID of the keyslot to activate/deactivate. # @keyslot: Optional. ID of the keyslot to activate/deactivate. For
# For keyslot activation, keyslot should not be active already # keyslot activation, keyslot should not be active already (this
# (this is unsafe to update an active keyslot), # is unsafe to update an active keyslot), but possible if 'force'
# but possible if 'force' parameter is given. # parameter is given. If keyslot is not given, first free keyslot
# If keyslot is not given, first free keyslot will be written. # will be written.
# #
# For keyslot deactivation, this parameter specifies the exact # For keyslot deactivation, this parameter specifies the exact
# keyslot to deactivate # keyslot to deactivate
# #
# @secret: Optional. The ID of a QCryptoSecret object providing the # @secret: Optional. The ID of a QCryptoSecret object providing the
# password to use to retrieve current master key. # password to use to retrieve current master key. Defaults to the
# Defaults to the same secret that was used to open the image # same secret that was used to open the image
# #
# Since: 5.1 # Since: 5.1
## ##
@ -365,8 +404,8 @@
## ##
# @QCryptoBlockAmendOptions: # @QCryptoBlockAmendOptions:
# #
# The options that are available for all encryption formats # The options that are available for all encryption formats when
# when amending encryption settings # amending encryption settings
# #
# Since: 5.1 # Since: 5.1
## ##
@ -381,22 +420,27 @@
# #
# Properties for objects of classes derived from secret-common. # Properties for objects of classes derived from secret-common.
# #
# @loaded: if true, the secret is loaded immediately when applying this option # @loaded: if true, the secret is loaded immediately when applying
# and will probably fail when processing the next option. Don't use; # this option and will probably fail when processing the next
# only provided for compatibility. (default: false) # 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 # @keyid: the name of another secret that should be used to decrypt
# provided data. If not present, the data is assumed to be unencrypted. # the provided data. If not present, the data is assumed to be
# unencrypted.
# #
# @iv: the random initialization vector used for encryption of this particular # @iv: the random initialization vector used for encryption of this
# secret. Should be a base64 encrypted string of the 16-byte IV. Mandatory # particular secret. Should be a base64 encrypted string of the
# if @keyid is given. Ignored if @keyid is absent. # 16-byte IV. Mandatory if @keyid is given. Ignored if @keyid is
# absent.
# #
# Features: # 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 # Since: 2.6
## ##
@ -443,16 +487,17 @@
# Properties for objects of classes derived from tls-creds. # Properties for objects of classes derived from tls-creds.
# #
# @verify-peer: if true the peer credentials will be verified once the # @verify-peer: if true the peer credentials will be verified once the
# handshake is completed. This is a no-op for anonymous # handshake is completed. This is a no-op for anonymous
# credentials. (default: true) # credentials. (default: true)
# #
# @dir: the path of the directory that contains the credential files # @dir: the path of the directory that contains the credential files
# #
# @endpoint: whether the QEMU network backend that uses the credentials will be # @endpoint: whether the QEMU network backend that uses the
# acting as a client or as a server (default: client) # credentials will be acting as a client or as a server
# (default: client)
# #
# @priority: a gnutls priority string as described at # @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 # Since: 2.5
## ##
@ -467,13 +512,15 @@
# #
# Properties for tls-creds-anon objects. # Properties for tls-creds-anon objects.
# #
# @loaded: if true, the credentials are loaded immediately when applying this # @loaded: if true, the credentials are loaded immediately when
# option and will ignore options that are processed later. Don't use; # applying this option and will ignore options that are processed
# only provided for compatibility. (default: false) # later. Don't use; only provided for compatibility.
# (default: false)
# #
# Features: # 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 # Since: 2.5
## ##
@ -486,17 +533,19 @@
# #
# Properties for tls-creds-psk objects. # Properties for tls-creds-psk objects.
# #
# @loaded: if true, the credentials are loaded immediately when applying this # @loaded: if true, the credentials are loaded immediately when
# option and will ignore options that are processed later. Don't use; # applying this option and will ignore options that are processed
# only provided for compatibility. (default: false) # later. Don't use; only provided for compatibility.
# (default: false)
# #
# @username: the username which will be sent to the server. For clients only. # @username: the username which will be sent to the server. For
# If absent, "qemu" is sent and the property will read back as an # clients only. If absent, "qemu" is sent and the property will
# empty string. # read back as an empty string.
# #
# Features: # 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 # Since: 3.0
## ##
@ -510,22 +559,24 @@
# #
# Properties for tls-creds-x509 objects. # Properties for tls-creds-x509 objects.
# #
# @loaded: if true, the credentials are loaded immediately when applying this # @loaded: if true, the credentials are loaded immediately when
# option and will ignore options that are processed later. Don't use; # applying this option and will ignore options that are processed
# only provided for compatibility. (default: false) # later. Don't use; only provided for compatibility.
# (default: false)
# #
# @sanity-check: if true, perform some sanity checks before using the # @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 # @passwordid: For the server-key.pem and client-key.pem files which
# sensitive private keys, it is possible to use an encrypted # contain sensitive private keys, it is possible to use an
# version by providing the @passwordid parameter. This provides # encrypted version by providing the @passwordid parameter. This
# the ID of a previously created secret object containing the # provides the ID of a previously created secret object containing
# password for decryption. # the password for decryption.
# #
# Features: # 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 # Since: 2.5
## ##
@ -564,6 +615,7 @@
# The padding algorithm for RSA. # The padding algorithm for RSA.
# #
# @raw: no padding used # @raw: no padding used
#
# @pkcs1: pkcs1#v1.5 # @pkcs1: pkcs1#v1.5
# #
# Since: 7.1 # Since: 7.1
@ -578,6 +630,7 @@
# Specific parameters for RSA algorithm. # Specific parameters for RSA algorithm.
# #
# @hash-alg: QCryptoHashAlgorithm # @hash-alg: QCryptoHashAlgorithm
#
# @padding-alg: QCryptoRSAPaddingAlgorithm # @padding-alg: QCryptoRSAPaddingAlgorithm
# #
# Since: 7.1 # Since: 7.1

3
qapi/cryptodev.json
View File

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

74
qapi/cxl.json
View File

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

78
qapi/dump.json
View File

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

6
qapi/error.json
View File

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

89
qapi/introspect.json
View File

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

139
qapi/job.json
View File

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

303
qapi/machine-target.json
View File

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

389
qapi/machine.json
View File

@ -14,17 +14,18 @@
# @SysEmuTarget: # @SysEmuTarget:
# #
# The comprehensive enumeration of QEMU system emulation ("softmmu") # The comprehensive enumeration of QEMU system emulation ("softmmu")
# targets. Run "./configure --help" in the project root directory, and # targets. Run "./configure --help" in the project root directory,
# look for the \*-softmmu targets near the "--target-list" option. The # and look for the \*-softmmu targets near the "--target-list" option.
# individual target constants are not documented here, for the time # The individual target constants are not documented here, for the
# being. # time being.
# #
# @rx: since 5.0 # @rx: since 5.0
#
# @avr: since 5.1 # @avr: since 5.1
# #
# Notes: The resulting QMP strings can be appended to the "qemu-system-" # Notes: The resulting QMP strings can be appended to the
# prefix to produce the corresponding QEMU executable name. This # "qemu-system-" prefix to produce the corresponding QEMU
# is true even for "qemu-system-x86_64". # executable name. This is true even for "qemu-system-x86_64".
# #
# Since: 3.0 # Since: 3.0
## ##
@ -39,8 +40,8 @@
## ##
# @CpuS390State: # @CpuS390State:
# #
# An enumeration of cpu states that can be assumed by a virtual # An enumeration of cpu states that can be assumed by a virtual S390
# S390 CPU # CPU
# #
# Since: 2.12 # Since: 2.12
## ##
@ -71,10 +72,10 @@
# @thread-id: ID of the underlying host thread # @thread-id: ID of the underlying host thread
# #
# @props: properties describing to which node/socket/core/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 # @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 # Since: 2.12
## ##
@ -139,21 +140,22 @@
# @is-default: whether the machine is default # @is-default: whether the machine is default
# #
# @cpu-max: maximum number of CPUs supported by the machine type # @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) # @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7)
# #
# @numa-mem-supported: true if '-numa node,mem' option is supported by # @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 # @deprecated: if true, the machine type is deprecated and may be
# in future versions of QEMU according to the QEMU deprecation # removed in future versions of QEMU according to the QEMU
# policy (since 4.1) # deprecation policy (since 4.1)
# #
# @default-cpu-type: default CPU model typename if none is requested via # @default-cpu-type: default CPU model typename if none is requested
# the -cpu argument. (since 4.2) # 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) # @acpi: machine type supports ACPI (since 8.0)
# #
@ -183,7 +185,7 @@
# Information describing the running machine parameters. # Information describing the running machine parameters.
# #
# @wakeup-suspend-support: true if the machine supports wake up from # @wakeup-suspend-support: true if the machine supports wake up from
# suspend # suspend
# #
# Since: 4.0 # Since: 4.0
## ##
@ -233,7 +235,8 @@
# #
# Since: 0.14 # 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'} } { 'struct': 'UuidInfo', 'data': {'UUID': 'str'} }
@ -250,7 +253,6 @@
# #
# -> { "execute": "query-uuid" } # -> { "execute": "query-uuid" }
# <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } } # <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
#
## ##
{ 'command': 'query-uuid', 'returns': 'UuidInfo', 'allow-preconfig': true } { 'command': 'query-uuid', 'returns': 'UuidInfo', 'allow-preconfig': true }
@ -285,7 +287,6 @@
# #
# -> { "execute": "system_reset" } # -> { "execute": "system_reset" }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'system_reset' } { 'command': 'system_reset' }
@ -297,67 +298,65 @@
# Since: 0.14 # Since: 0.14
# #
# Notes: A guest may or may not respond to this command. This command # 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 # returning does not indicate that a guest has accepted the
# that it has shut down. Many guests will respond to this command by # request or that it has shut down. Many guests will respond to
# prompting the user in some way. # this command by prompting the user in some way.
# #
# Example: # Example:
# #
# -> { "execute": "system_powerdown" } # -> { "execute": "system_powerdown" }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'system_powerdown' } { 'command': 'system_powerdown' }
## ##
# @system_wakeup: # @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 # support enabled (wakeup-suspend-support flag from
# query-current-machine), wake-up guest from suspend if the guest is # 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 # Since: 1.1
# #
# Returns: nothing. # Returns: nothing.
# #
# Note: prior to 4.0, this command does nothing in case the guest # Note: prior to 4.0, this command does nothing in case the guest
# isn't suspended. # isn't suspended.
# #
# Example: # Example:
# #
# -> { "execute": "system_wakeup" } # -> { "execute": "system_wakeup" }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'system_wakeup' } { 'command': 'system_wakeup' }
## ##
# @LostTickPolicy: # @LostTickPolicy:
# #
# Policy for handling lost ticks in timer devices. Ticks end up getting # Policy for handling lost ticks in timer devices. Ticks end up
# lost when, for example, the guest is paused. # getting lost when, for example, the guest is paused.
# #
# @discard: throw away the missed ticks and continue with future injection # @discard: throw away the missed ticks and continue with future
# normally. The guest OS will see the timer jump ahead by a # injection normally. The guest OS will see the timer jump ahead
# potentially quite significant amount all at once, as if the # by a potentially quite significant amount all at once, as if the
# intervening chunk of time had simply not existed; needless to # intervening chunk of time had simply not existed; needless to
# say, such a sudden jump can easily confuse a guest OS which is # say, such a sudden jump can easily confuse a guest OS which is
# not specifically prepared to deal with it. Assuming the guest # not specifically prepared to deal with it. Assuming the guest
# OS can deal correctly with the time jump, the time in the guest # OS can deal correctly with the time jump, the time in the guest
# and in the host should now match. # and in the host should now match.
# #
# @delay: continue to deliver ticks at the normal rate. The guest OS will # @delay: continue to deliver ticks at the normal rate. The guest OS
# not notice anything is amiss, as from its point of view time will # will not notice anything is amiss, as from its point of view
# have continued to flow normally. The time in the guest should now # time will have continued to flow normally. The time in the
# be behind the time in the host by exactly the amount of time during # guest should now be behind the time in the host by exactly the
# which ticks have been missed. # amount of time during which ticks have been missed.
# #
# @slew: deliver ticks at a higher rate to catch up with the missed ticks. # @slew: deliver ticks at a higher rate to catch up with the missed
# The guest OS will not notice anything is amiss, as from its point # ticks. The guest OS will not notice anything is amiss, as from
# of view time will have continued to flow normally. Once the timer # its point of view time will have continued to flow normally.
# has managed to catch up with all the missing ticks, the time in # Once the timer has managed to catch up with all the missing
# the guest and in the host should match. # ticks, the time in the guest and in the host should match.
# #
# Since: 2.0 # Since: 2.0
## ##
@ -367,20 +366,21 @@
## ##
# @inject-nmi: # @inject-nmi:
# #
# Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all CPUs (ppc64). # Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or
# The command fails when the guest doesn't support injecting. # all CPUs (ppc64). The command fails when the guest doesn't support
# injecting.
# #
# Returns: If successful, nothing # Returns: If successful, nothing
# #
# Since: 0.14 # 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: # Example:
# #
# -> { "execute": "inject-nmi" } # -> { "execute": "inject-nmi" }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'inject-nmi' } { 'command': 'inject-nmi' }
@ -410,7 +410,6 @@
# #
# -> { "execute": "query-kvm" } # -> { "execute": "query-kvm" }
# <- { "return": { "enabled": true, "present": true } } # <- { "return": { "enabled": true, "present": true } }
#
## ##
{ 'command': 'query-kvm', 'returns': 'KvmInfo' } { 'command': 'query-kvm', 'returns': 'KvmInfo' }
@ -435,7 +434,7 @@
## ##
# @NumaOptions: # @NumaOptions:
# #
# A discriminated record of NUMA options. (for OptsVisitor) # A discriminated record of NUMA options. (for OptsVisitor)
# #
# Since: 2.1 # Since: 2.1
## ##
@ -452,26 +451,25 @@
## ##
# @NumaNodeOptions: # @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) # @nodeid: NUMA node ID (increase by 1 from 0 if omitted)
# #
# @cpus: VCPUs belonging to this node (assign VCPUS round-robin # @cpus: VCPUs belonging to this node (assign VCPUS round-robin if
# if omitted) # omitted)
# #
# @mem: memory size of this node; mutually exclusive with @memdev. # @mem: memory size of this node; mutually exclusive with @memdev.
# Equally divide total memory among nodes if both @mem and @memdev are # Equally divide total memory among nodes if both @mem and @memdev
# omitted. # are omitted.
# #
# @memdev: memory backend object. If specified for one node, # @memdev: memory backend object. If specified for one node, it must
# it must be specified for all nodes. # be specified for all nodes.
# #
# @initiator: defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145, # @initiator: defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145, points
# points to the nodeid which has the memory controller # to the nodeid which has the memory controller responsible for
# responsible for this NUMA node. This field provides # this NUMA node. This field provides additional information as
# additional information as to the initiator node that # to the initiator node that is closest (as in directly attached)
# is closest (as in directly attached) to this node, and # to this node, and therefore has the best performance (since 5.0)
# therefore has the best performance (since 5.0)
# #
# Since: 2.1 # Since: 2.1
## ##
@ -492,9 +490,9 @@
# #
# @dst: destination NUMA node. # @dst: destination NUMA node.
# #
# @val: NUMA distance from source node to destination node. # @val: NUMA distance from source node to destination node. When a
# When a node is unreachable from another node, set the distance # node is unreachable from another node, set the distance between
# between them to 255. # them to 255.
# #
# Since: 2.10 # Since: 2.10
## ##
@ -509,13 +507,15 @@
# #
# Create a CXL Fixed Memory Window # Create a CXL Fixed Memory Window
# #
# @size: Size of the Fixed Memory Window in bytes. Must be a multiple # @size: Size of the Fixed Memory Window in bytes. Must be a multiple
# of 256MiB. # of 256MiB.
#
# @interleave-granularity: Number of contiguous bytes for which # @interleave-granularity: Number of contiguous bytes for which
# accesses will go to a given interleave target. # accesses will go to a given interleave target. Accepted values
# Accepted values [256, 512, 1k, 2k, 4k, 8k, 16k] # [256, 512, 1k, 2k, 4k, 8k, 16k]
# @targets: Target root bridge IDs from -device ...,id=<ID> for each root #
# bridge. # @targets: Target root bridge IDs from -device ...,id=<ID> for each
# root bridge.
# #
# Since: 7.1 # Since: 7.1
## ##
@ -553,10 +553,11 @@
# #
# Information about a X86 CPU feature word # 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 # @cpuid-input-ecx: Input ECX value for CPUID instruction for that
# feature word # feature word
# #
# @cpuid-register: Output register containing the feature bits # @cpuid-register: Output register containing the feature bits
# #
@ -573,7 +574,8 @@
## ##
# @DummyForceArrays: # @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 # Since: 2.5
## ##
@ -583,8 +585,8 @@
## ##
# @NumaCpuOptions: # @NumaCpuOptions:
# #
# Option "-numa cpu" overrides default cpu to node mapping. # Option "-numa cpu" overrides default cpu to node mapping. It
# It accepts the same set of cpu properties as returned by # accepts the same set of cpu properties as returned by
# query-hotpluggable-cpus[].props, where node-id could be used to # query-hotpluggable-cpus[].props, where node-id could be used to
# override default node mapping. # override default node mapping.
# #
@ -619,11 +621,11 @@
## ##
# @HmatLBDataType: # @HmatLBDataType:
# #
# Data type in the System Locality Latency and Bandwidth # Data type in the System Locality Latency and Bandwidth Information
# Information Structure of HMAT (Heterogeneous Memory Attribute Table) # Structure of HMAT (Heterogeneous Memory Attribute Table)
# #
# For more information about @HmatLBDataType, see chapter # For more information about @HmatLBDataType, see chapter 5.2.27.4:
# 5.2.27.4: Table 5-146: Field "Data Type" of ACPI 6.3 spec. # Table 5-146: Field "Data Type" of ACPI 6.3 spec.
# #
# @access-latency: access latency (nanoseconds) # @access-latency: access latency (nanoseconds)
# #
@ -646,28 +648,27 @@
## ##
# @NumaHmatLBOptions: # @NumaHmatLBOptions:
# #
# Set the system locality latency and bandwidth information # Set the system locality latency and bandwidth information between
# between Initiator and Target proximity Domains. # Initiator and Target proximity Domains.
# #
# For more information about @NumaHmatLBOptions, see chapter # For more information about @NumaHmatLBOptions, see chapter 5.2.27.4:
# 5.2.27.4: Table 5-146 of ACPI 6.3 spec. # Table 5-146 of ACPI 6.3 spec.
# #
# @initiator: the Initiator Proximity Domain. # @initiator: the Initiator Proximity Domain.
# #
# @target: the Target Proximity Domain. # @target: the Target Proximity Domain.
# #
# @hierarchy: the Memory Hierarchy. Indicates the performance # @hierarchy: the Memory Hierarchy. Indicates the performance of
# of memory or side cache. # memory or side cache.
# #
# @data-type: presents the type of data, access/read/write # @data-type: presents the type of data, access/read/write latency or
# latency or hit latency. # hit latency.
# #
# @latency: the value of latency from @initiator to @target # @latency: the value of latency from @initiator to @target proximity
# proximity domain, the latency unit is "ns(nanosecond)". # domain, the latency unit is "ns(nanosecond)".
# #
# @bandwidth: the value of bandwidth between @initiator and @target # @bandwidth: the value of bandwidth between @initiator and @target
# proximity domain, the bandwidth unit is # proximity domain, the bandwidth unit is "Bytes per second".
# "Bytes per second".
# #
# Since: 5.0 # Since: 5.0
## ##
@ -689,8 +690,8 @@
# For more information of @HmatCacheAssociativity, see chapter # For more information of @HmatCacheAssociativity, see chapter
# 5.2.27.5: Table 5-147 of ACPI 6.3 spec. # 5.2.27.5: Table 5-147 of ACPI 6.3 spec.
# #
# @none: None (no memory side cache in this proximity domain, # @none: None (no memory side cache in this proximity domain, or cache
# or cache associativity unknown) # associativity unknown)
# #
# @direct: Direct Mapped # @direct: Direct Mapped
# #
@ -704,14 +705,14 @@
## ##
# @HmatCacheWritePolicy: # @HmatCacheWritePolicy:
# #
# Cache write policy in the Memory Side Cache Information Structure # Cache write policy in the Memory Side Cache Information Structure of
# of HMAT # HMAT
# #
# For more information of @HmatCacheWritePolicy, see chapter # For more information of @HmatCacheWritePolicy, see chapter 5.2.27.5:
# 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec. # Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
# #
# @none: None (no memory side cache in this proximity domain, # @none: None (no memory side cache in this proximity domain, or cache
# or cache write policy unknown) # write policy unknown)
# #
# @write-back: Write Back (WB) # @write-back: Write Back (WB)
# #
@ -727,8 +728,8 @@
# #
# Set the memory side cache information for a given memory domain. # Set the memory side cache information for a given memory domain.
# #
# For more information of @NumaHmatCacheOptions, see chapter # For more information of @NumaHmatCacheOptions, see chapter 5.2.27.5:
# 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec. # Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
# #
# @node-id: the memory proximity domain to which the memory belongs. # @node-id: the memory proximity domain to which the memory belongs.
# #
@ -737,7 +738,7 @@
# @level: the cache level described in this structure. # @level: the cache level described in this structure.
# #
# @associativity: the cache associativity, # @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. # @policy: the write policy, none/write-back/write-through.
# #
@ -766,7 +767,7 @@
# @filename: the file to save the memory to as binary data # @filename: the file to save the memory to as binary data
# #
# @cpu-index: the index of the virtual CPU to use for translating the # @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 # Returns: Nothing on success
# #
@ -781,7 +782,6 @@
# "size": 100, # "size": 100,
# "filename": "/tmp/virtual-mem-dump" } } # "filename": "/tmp/virtual-mem-dump" } }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'memsave', { 'command': 'memsave',
'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} } 'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} }
@ -810,7 +810,6 @@
# "size": 100, # "size": 100,
# "filename": "/tmp/physical-mem-dump" } } # "filename": "/tmp/physical-mem-dump" } }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'pmemsave', { 'command': 'pmemsave',
'data': {'val': 'int', 'size': 'int', 'filename': 'str'} } 'data': {'val': 'int', 'size': 'int', 'filename': 'str'} }
@ -832,11 +831,11 @@
# #
# @share: whether memory is private to QEMU or shared (since 6.1) # @share: whether memory is private to QEMU or shared (since 6.1)
# #
# @reserve: whether swap space (or huge pages) was reserved if applicable. # @reserve: whether swap space (or huge pages) was reserved if
# This corresponds to the user configuration and not the actual # applicable. This corresponds to the user configuration and not
# behavior implemented in the OS to perform the reservation. # the actual behavior implemented in the OS to perform the
# For example, Linux will never reserve swap space for shared # reservation. For example, Linux will never reserve swap space
# file mappings. (since 6.1) # for shared file mappings. (since 6.1)
# #
# @host-nodes: host nodes for its memory policy # @host-nodes: host nodes for its memory policy
# #
@ -890,29 +889,34 @@
# } # }
# ] # ]
# } # }
#
## ##
{ 'command': 'query-memdev', 'returns': ['Memdev'], 'allow-preconfig': true } { 'command': 'query-memdev', 'returns': ['Memdev'], 'allow-preconfig': true }
## ##
# @CpuInstanceProperties: # @CpuInstanceProperties:
# #
# List of properties to be used for hotplugging a CPU instance, # List of properties to be used for hotplugging a CPU instance, it
# it should be passed by management with device_add command when # should be passed by management with device_add command when a CPU is
# a CPU is being hotplugged. # being hotplugged.
# #
# @node-id: NUMA node ID the CPU belongs to # @node-id: NUMA node ID the CPU belongs to
#
# @socket-id: socket number within node/board 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) # @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 # @core-id: core number within cluster the CPU belongs to
#
# @thread-id: thread number within core the CPU belongs to # @thread-id: thread number within core the CPU belongs to
# #
# Note: currently there are 6 properties that could be present # Note: currently there are 6 properties that could be present but
# but management should be prepared to pass through other # management should be prepared to pass through other properties
# properties with device_add command to allow for future # with device_add command to allow for future interface extension.
# interface extension. This also requires the filed names to be kept in # This also requires the filed names to be kept in sync with the
# sync with the properties passed to -device/device_add. # properties passed to -device/device_add.
# #
# Since: 2.7 # Since: 2.7
## ##
@ -930,10 +934,14 @@
# @HotpluggableCPU: # @HotpluggableCPU:
# #
# @type: CPU object type for usage with device_add command # @type: CPU object type for usage with device_add command
#
# @props: list of properties to be used for hotplugging CPU # @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 # @vcpus-count: number of logical VCPU threads @HotpluggableCPU
# omitted if CPU is not present. # provides
#
# @qom-path: link to existing CPU object if CPU is present or omitted
# if CPU is not present.
# #
# Since: 2.7 # Since: 2.7
## ##
@ -956,7 +964,8 @@
# #
# Examples: # 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" } # -> { "execute": "query-hotpluggable-cpus" }
# <- {"return": [ # <- {"return": [
@ -981,8 +990,8 @@
# } # }
# ]} # ]}
# #
# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu # For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu
# (Since: 2.11): # qemu (Since: 2.11):
# #
# -> { "execute": "query-hotpluggable-cpus" } # -> { "execute": "query-hotpluggable-cpus" }
# <- {"return": [ # <- {"return": [
@ -996,7 +1005,6 @@
# "props": { "core-id": 0 } # "props": { "core-id": 0 }
# } # }
# ]} # ]}
#
## ##
{ 'command': 'query-hotpluggable-cpus', 'returns': ['HotpluggableCPU'], { 'command': 'query-hotpluggable-cpus', 'returns': ['HotpluggableCPU'],
'allow-preconfig': true } 'allow-preconfig': true }
@ -1004,9 +1012,8 @@
## ##
# @set-numa-node: # @set-numa-node:
# #
# Runtime equivalent of '-numa' CLI option, available at # Runtime equivalent of '-numa' CLI option, available at preconfigure
# preconfigure stage to configure numa mapping before initializing # stage to configure numa mapping before initializing machine.
# machine.
# #
# Since: 3.0 # Since: 3.0
## ##
@ -1020,21 +1027,22 @@
# #
# Request the balloon driver to change its balloon size. # Request the balloon driver to change its balloon size.
# #
# @value: the target logical size of the VM in bytes. # @value: the target logical size of the VM in bytes. We can deduce
# We can deduce the size of the balloon using this formula: # 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 # Returns:
# - If the balloon driver is enabled but not functional because the KVM # - Nothing on success
# kernel module cannot support it, KVMMissingCap # - If the balloon driver is enabled but not functional because the
# - If no balloon device is present, DeviceNotActive # 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, # Notes: This command just issues a request to the guest. When it
# the balloon size may not have changed. A guest can change the balloon # returns, the balloon size may not have changed. A guest can
# size independent of this command. # change the balloon size independent of this command.
# #
# Since: 0.14 # Since: 0.14
# #
@ -1044,7 +1052,6 @@
# <- { "return": {} } # <- { "return": {} }
# #
# With a 2.5GiB guest this command inflated the ballon to 3GiB. # With a 2.5GiB guest this command inflated the ballon to 3GiB.
#
## ##
{ 'command': 'balloon', 'data': {'value': 'int'} } { 'command': 'balloon', 'data': {'value': 'int'} }
@ -1053,8 +1060,8 @@
# #
# Information about the guest balloon device. # Information about the guest balloon device.
# #
# @actual: the logical size of the VM in bytes # @actual: the logical size of the VM in bytes Formula used:
# Formula used: logical_vm_size = vm_ram_size - balloon_size # logical_vm_size = vm_ram_size - balloon_size
# #
# Since: 0.14 # Since: 0.14
## ##
@ -1065,10 +1072,11 @@
# #
# Return information about the balloon device. # Return information about the balloon device.
# #
# Returns: - @BalloonInfo on success # Returns:
# - If the balloon driver is enabled but not functional because the KVM # - @BalloonInfo on success
# kernel module cannot support it, KVMMissingCap # - If the balloon driver is enabled but not functional because the
# - If no balloon device is present, DeviceNotActive # KVM kernel module cannot support it, KVMMissingCap
# - If no balloon device is present, DeviceNotActive
# #
# Since: 0.14 # Since: 0.14
# #
@ -1079,18 +1087,18 @@
# "actual": 1073741824 # "actual": 1073741824
# } # }
# } # }
#
## ##
{ 'command': 'query-balloon', 'returns': 'BalloonInfo' } { 'command': 'query-balloon', 'returns': 'BalloonInfo' }
## ##
# @BALLOON_CHANGE: # @BALLOON_CHANGE:
# #
# Emitted when the guest changes the actual BALLOON level. This value is # Emitted when the guest changes the actual BALLOON level. This value
# equivalent to the @actual field return by the 'query-balloon' command # is equivalent to the @actual field return by the 'query-balloon'
# command
# #
# @actual: the logical size of the VM in bytes # @actual: the logical size of the VM in bytes Formula used:
# Formula used: logical_vm_size = vm_ram_size - balloon_size # logical_vm_size = vm_ram_size - balloon_size
# #
# Note: this event is rate-limited. # Note: this event is rate-limited.
# #
@ -1101,7 +1109,6 @@
# <- { "event": "BALLOON_CHANGE", # <- { "event": "BALLOON_CHANGE",
# "data": { "actual": 944766976 }, # "data": { "actual": 944766976 },
# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } # "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
#
## ##
{ 'event': 'BALLOON_CHANGE', { 'event': 'BALLOON_CHANGE',
'data': { 'actual': 'int' } } 'data': { 'actual': 'int' } }
@ -1112,11 +1119,11 @@
# Actual memory information in bytes. # Actual memory information in bytes.
# #
# @base-memory: size of "base" memory specified with command line # @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 # @plugged-memory: size of memory that can be hot-unplugged. This
# is omitted if target doesn't support memory hotplug # field is omitted if target doesn't support memory hotplug (i.e.
# (i.e. CONFIG_MEM_DEVICE not defined at build time). # CONFIG_MEM_DEVICE not defined at build time).
# #
# Since: 2.11 # Since: 2.11
## ##
@ -1126,8 +1133,8 @@
## ##
# @query-memory-size-summary: # @query-memory-size-summary:
# #
# Return the amount of initially allocated and present hotpluggable (if # Return the amount of initially allocated and present hotpluggable
# enabled) memory in bytes. # (if enabled) memory in bytes.
# #
# Example: # Example:
# #
@ -1157,7 +1164,8 @@
# #
# @hotplugged: true if device was hotplugged # @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 # Since: 2.1
## ##
@ -1374,16 +1382,15 @@
# "slot": 0}, # "slot": 0},
# "type": "dimm" # "type": "dimm"
# } ] } # } ] }
#
## ##
{ 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] } { 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] }
## ##
# @MEMORY_DEVICE_SIZE_CHANGE: # @MEMORY_DEVICE_SIZE_CHANGE:
# #
# Emitted when the size of a memory device changes. Only emitted for memory # Emitted when the size of a memory device changes. Only emitted for
# devices that can actually change the size (e.g., virtio-mem due to guest # memory devices that can actually change the size (e.g., virtio-mem
# action). # due to guest action).
# #
# @id: device's ID # @id: device's ID
# #
@ -1401,7 +1408,6 @@
# "data": { "id": "vm0", "size": 1073741824, # "data": { "id": "vm0", "size": 1073741824,
# "qom-path": "/machine/unattached/device[2]" }, # "qom-path": "/machine/unattached/device[2]" },
# "timestamp": { "seconds": 1588168529, "microseconds": 201316 } } # "timestamp": { "seconds": 1588168529, "microseconds": 201316 } }
#
## ##
{ 'event': 'MEMORY_DEVICE_SIZE_CHANGE', { 'event': 'MEMORY_DEVICE_SIZE_CHANGE',
'data': { '*id': 'str', 'size': 'size', 'qom-path' : 'str'} } 'data': { '*id': 'str', 'size': 'size', 'qom-path' : 'str'} }
@ -1416,8 +1422,9 @@
# @msg: Informative message # @msg: Informative message
# #
# Features: # 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 # Since: 2.4
# #
@ -1428,7 +1435,6 @@
# "msg": "acpi: device unplug for unsupported device" # "msg": "acpi: device unplug for unsupported device"
# }, # },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
#
## ##
{ 'event': 'MEM_UNPLUG_ERROR', { 'event': 'MEM_UNPLUG_ERROR',
'data': { 'device': 'str', 'msg': 'str' }, 'data': { 'device': 'str', 'msg': 'str' },
@ -1445,13 +1451,15 @@
# #
# @menu: Whether to show a boot menu # @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 # @splash-time: How long to show the logo picture, in milliseconds
# #
# @reboot-timeout: Timeout before guest reboots after boot fails # @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 # Since: 7.1
## ##
@ -1467,8 +1475,8 @@
## ##
# @SMPConfiguration: # @SMPConfiguration:
# #
# Schema for CPU topology configuration. A missing value lets # Schema for CPU topology configuration. A missing value lets QEMU
# QEMU figure out a suitable value based on the ones that are provided. # figure out a suitable value based on the ones that are provided.
# #
# @cpus: number of virtual CPUs in the virtual machine # @cpus: number of virtual CPUs in the virtual machine
# #
@ -1476,13 +1484,15 @@
# #
# @dies: number of dies per socket in the CPU topology # @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 # @cores: number of cores per cluster in the CPU topology
# #
# @threads: number of threads per core 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 # Since: 6.1
## ##
@ -1501,6 +1511,7 @@
# Query interrupt statistics # Query interrupt statistics
# #
# Features: # Features:
#
# @unstable: This command is meant for debugging. # @unstable: This command is meant for debugging.
# #
# Returns: interrupt statistics # Returns: interrupt statistics
@ -1517,6 +1528,7 @@
# Query TCG compiler statistics # Query TCG compiler statistics
# #
# Features: # Features:
#
# @unstable: This command is meant for debugging. # @unstable: This command is meant for debugging.
# #
# Returns: TCG compiler statistics # Returns: TCG compiler statistics
@ -1534,6 +1546,7 @@
# Query NUMA topology information # Query NUMA topology information
# #
# Features: # Features:
#
# @unstable: This command is meant for debugging. # @unstable: This command is meant for debugging.
# #
# Returns: topology information # Returns: topology information
@ -1550,6 +1563,7 @@
# Query TCG opcode counters # Query TCG opcode counters
# #
# Features: # Features:
#
# @unstable: This command is meant for debugging. # @unstable: This command is meant for debugging.
# #
# Returns: TCG opcode counters # Returns: TCG opcode counters
@ -1567,6 +1581,7 @@
# Query TCG profiling information # Query TCG profiling information
# #
# Features: # Features:
#
# @unstable: This command is meant for debugging. # @unstable: This command is meant for debugging.
# #
# Returns: profile information # Returns: profile information
@ -1584,6 +1599,7 @@
# Query system ramblock information # Query system ramblock information
# #
# Features: # Features:
#
# @unstable: This command is meant for debugging. # @unstable: This command is meant for debugging.
# #
# Returns: system ramblock information # Returns: system ramblock information
@ -1600,6 +1616,7 @@
# Query RDMA state # Query RDMA state
# #
# Features: # Features:
#
# @unstable: This command is meant for debugging. # @unstable: This command is meant for debugging.
# #
# Returns: RDMA state # Returns: RDMA state
@ -1616,6 +1633,7 @@
# Query information on the registered ROMS # Query information on the registered ROMS
# #
# Features: # Features:
#
# @unstable: This command is meant for debugging. # @unstable: This command is meant for debugging.
# #
# Returns: registered ROMs # Returns: registered ROMs
@ -1632,6 +1650,7 @@
# Query information on the USB devices # Query information on the USB devices
# #
# Features: # Features:
#
# @unstable: This command is meant for debugging. # @unstable: This command is meant for debugging.
# #
# Returns: USB device information # Returns: USB device information
@ -1682,10 +1701,10 @@
# Since: 7.2 # Since: 7.2
# #
# Example: # Example:
#
# -> { "execute": "dumpdtb" } # -> { "execute": "dumpdtb" }
# "arguments": { "filename": "fdt.dtb" } } # "arguments": { "filename": "fdt.dtb" } }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'dumpdtb', { 'command': 'dumpdtb',
'data': { 'filename': 'str' }, '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: # @rtc-reset-reinjection:
# #
# This command will reset the RTC interrupt reinjection backlog. # This command will reset the RTC interrupt reinjection backlog. Can
# Can be used if another mechanism to synchronize guest time # be used if another mechanism to synchronize guest time is in effect,
# is in effect, for example QEMU guest agent's guest-set-time # for example QEMU guest agent's guest-set-time command.
# command.
# #
# Since: 2.1 # Since: 2.1
# #
@ -16,7 +15,6 @@
# #
# -> { "execute": "rtc-reset-reinjection" } # -> { "execute": "rtc-reset-reinjection" }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'rtc-reset-reinjection', { 'command': 'rtc-reset-reinjection',
'if': 'TARGET_I386' } 'if': 'TARGET_I386' }
@ -28,17 +26,19 @@
# #
# @uninit: The guest is uninitialized. # @uninit: The guest is uninitialized.
# #
# @launch-update: The guest is currently being launched; plaintext data and # @launch-update: The guest is currently being launched; plaintext
# register state is being imported. # data and register state is being imported.
# #
# @launch-secret: The guest is currently being launched; ciphertext data # @launch-secret: The guest is currently being launched; ciphertext
# is being imported. # data is being imported.
# #
# @running: The guest is fully launched or migrated in. # @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 # Since: 2.12
## ##
@ -95,7 +95,6 @@
# <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0, # <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
# "build-id" : 0, "policy" : 0, "state" : "running", # "build-id" : 0, "policy" : 0, "state" : "running",
# "handle" : 1 } } # "handle" : 1 } }
#
## ##
{ 'command': 'query-sev', 'returns': 'SevInfo', { 'command': 'query-sev', 'returns': 'SevInfo',
'if': 'TARGET_I386' } 'if': 'TARGET_I386' }
@ -125,7 +124,6 @@
# #
# -> { "execute": "query-sev-launch-measure" } # -> { "execute": "query-sev-launch-measure" }
# <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } } # <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
#
## ##
{ 'command': 'query-sev-launch-measure', 'returns': 'SevLaunchMeasureInfo', { 'command': 'query-sev-launch-measure', 'returns': 'SevLaunchMeasureInfo',
'if': 'TARGET_I386' } 'if': 'TARGET_I386' }
@ -133,8 +131,8 @@
## ##
# @SevCapability: # @SevCapability:
# #
# The struct describes capability for a Secure Encrypted Virtualization # The struct describes capability for a Secure Encrypted
# feature. # Virtualization feature.
# #
# @pdh: Platform Diffie-Hellman key (base64 encoded) # @pdh: Platform Diffie-Hellman key (base64 encoded)
# #
@ -144,8 +142,8 @@
# #
# @cbitpos: C-bit location in page table entry # @cbitpos: C-bit location in page table entry
# #
# @reduced-phys-bits: Number of physical Address bit reduction when SEV is # @reduced-phys-bits: Number of physical Address bit reduction when
# enabled # SEV is enabled
# #
# Since: 2.12 # Since: 2.12
## ##
@ -160,8 +158,8 @@
## ##
# @query-sev-capabilities: # @query-sev-capabilities:
# #
# This command is used to get the SEV capabilities, and is supported on AMD # This command is used to get the SEV capabilities, and is supported
# X86 platforms only. # on AMD X86 platforms only.
# #
# Returns: SevCapability objects. # Returns: SevCapability objects.
# #
@ -173,7 +171,6 @@
# <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE", # <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
# "cpu0-id": "2lvmGwo+...61iEinw==", # "cpu0-id": "2lvmGwo+...61iEinw==",
# "cbitpos": 47, "reduced-phys-bits": 1}} # "cbitpos": 47, "reduced-phys-bits": 1}}
#
## ##
{ 'command': 'query-sev-capabilities', 'returns': 'SevCapability', { 'command': 'query-sev-capabilities', 'returns': 'SevCapability',
'if': 'TARGET_I386' } 'if': 'TARGET_I386' }
@ -216,7 +213,7 @@
# supported on AMD X86 platforms only. # supported on AMD X86 platforms only.
# #
# @mnonce: a random 16 bytes value encoded in base64 (it will be # @mnonce: a random 16 bytes value encoded in base64 (it will be
# included in report) # included in report)
# #
# Returns: SevAttestationReport objects. # Returns: SevAttestationReport objects.
# #
@ -227,7 +224,6 @@
# -> { "execute" : "query-sev-attestation-report", # -> { "execute" : "query-sev-attestation-report",
# "arguments": { "mnonce": "aaaaaaa" } } # "arguments": { "mnonce": "aaaaaaa" } }
# <- { "return" : { "data": "aaaaaaaabbbddddd"} } # <- { "return" : { "data": "aaaaaaaabbbddddd"} }
#
## ##
{ 'command': 'query-sev-attestation-report', { 'command': 'query-sev-attestation-report',
'data': { 'mnonce': 'str' }, 'data': { 'mnonce': 'str' },
@ -250,7 +246,6 @@
# -> { "execute": "dump-skeys", # -> { "execute": "dump-skeys",
# "arguments": { "filename": "/tmp/skeys" } } # "arguments": { "filename": "/tmp/skeys" } }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'dump-skeys', { 'command': 'dump-skeys',
'data': { 'filename': 'str' }, 'data': { 'filename': 'str' },
@ -260,18 +255,18 @@
# @GICCapability: # @GICCapability:
# #
# The struct describes capability for a specific GIC (Generic # The struct describes capability for a specific GIC (Generic
# Interrupt Controller) version. These bits are not only decided by # Interrupt Controller) version. These bits are not only decided by
# QEMU/KVM software version, but also decided by the hardware that # QEMU/KVM software version, but also decided by the hardware that the
# the program is running upon. # program is running upon.
# #
# @version: version of GIC to be described. Currently, only 2 and 3 # @version: version of GIC to be described. Currently, only 2 and 3
# are supported. # are supported.
# #
# @emulated: whether current QEMU/hardware supports emulated GIC # @emulated: whether current QEMU/hardware supports emulated GIC
# device in user space. # device in user space.
# #
# @kernel: whether current QEMU/hardware supports hardware # @kernel: whether current QEMU/hardware supports hardware accelerated
# accelerated GIC device in kernel. # GIC device in kernel.
# #
# Since: 2.6 # Since: 2.6
## ##
@ -284,7 +279,7 @@
## ##
# @query-gic-capabilities: # @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. # objects that describe its capability bits.
# #
# Returns: a list of GICCapability objects. # Returns: a list of GICCapability objects.
@ -296,7 +291,6 @@
# -> { "execute": "query-gic-capabilities" } # -> { "execute": "query-gic-capabilities" }
# <- { "return": [{ "version": 2, "emulated": true, "kernel": false }, # <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
# { "version": 3, "emulated": false, "kernel": true } ] } # { "version": 3, "emulated": false, "kernel": true } ] }
#
## ##
{ 'command': 'query-gic-capabilities', 'returns': ['GICCapability'], { 'command': 'query-gic-capabilities', 'returns': ['GICCapability'],
'if': 'TARGET_ARM' } 'if': 'TARGET_ARM' }
@ -357,7 +351,6 @@
# "flc": true, # "flc": true,
# "sections": [{"node": 0, "size": 67108864}, # "sections": [{"node": 0, "size": 67108864},
# {"node": 1, "size": 29360128}]} } # {"node": 1, "size": 29360128}]} }
#
## ##
{ 'command': 'query-sgx', 'returns': 'SGXInfo', 'if': 'TARGET_I386' } { 'command': 'query-sgx', 'returns': 'SGXInfo', 'if': 'TARGET_I386' }
@ -377,7 +370,6 @@
# "flc": true, # "flc": true,
# "section" : [{"node": 0, "size": 67108864}, # "section" : [{"node": 0, "size": 67108864},
# {"node": 1, "size": 29360128}]} } # {"node": 1, "size": 29360128}]} }
#
## ##
{ 'command': 'query-sgx-capabilities', 'returns': 'SGXInfo', 'if': 'TARGET_I386' } { 'command': 'query-sgx-capabilities', 'returns': 'SGXInfo', 'if': 'TARGET_I386' }
@ -470,7 +462,6 @@
# } # }
# ] # ]
# } # }
#
## ##
{ 'command': 'xen-event-list', { 'command': 'xen-event-list',
'returns': ['EvtchnInfo'], 'returns': ['EvtchnInfo'],
@ -483,7 +474,8 @@
# #
# @port: The port number # @port: The port number
# #
# Returns: - Nothing on success. # Returns:
# - Nothing on success.
# #
# Since: 8.0 # Since: 8.0
# #
@ -491,7 +483,6 @@
# #
# -> { "execute": "xen-event-inject", "arguments": { "port": 1 } } # -> { "execute": "xen-event-inject", "arguments": { "port": 1 } }
# <- { "return": { } } # <- { "return": { } }
#
## ##
{ 'command': 'xen-event-inject', { 'command': 'xen-event-inject',
'data': { 'port': 'uint32' }, 'data': { 'port': 'uint32' },

180
qapi/misc.json
View File

@ -11,22 +11,22 @@
## ##
# @add_client: # @add_client:
# #
# Allow client connections for VNC, Spice and socket based # Allow client connections for VNC, Spice and socket based character
# character devices to be passed in to QEMU via SCM_RIGHTS. # 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 # If the FD associated with @fdname is not a socket, the command will
# the FD will be closed. # fail and the FD will be closed.
# #
# @protocol: protocol name. Valid names are "vnc", "spice", "@dbus-display" or # @protocol: protocol name. Valid names are "vnc", "spice",
# the name of a character device (eg. from -chardev id=XXXX) # "@dbus-display" or the name of a character device (eg. from
# -chardev id=XXXX)
# #
# @fdname: file descriptor name previously passed via 'getfd' command # @fdname: file descriptor name previously passed via 'getfd' command
# #
# @skipauth: whether to skip authentication. Only applies # @skipauth: whether to skip authentication. Only applies to "vnc"
# to "vnc" and "spice" protocols # and "spice" protocols
# #
# @tls: whether to perform TLS. Only applies to the "spice" # @tls: whether to perform TLS. Only applies to the "spice" protocol
# protocol
# #
# Returns: nothing on success. # Returns: nothing on success.
# #
@ -37,7 +37,6 @@
# -> { "execute": "add_client", "arguments": { "protocol": "vnc", # -> { "execute": "add_client", "arguments": { "protocol": "vnc",
# "fdname": "myclient" } } # "fdname": "myclient" } }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'add_client', { 'command': 'add_client',
'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool', 'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
@ -67,7 +66,6 @@
# #
# -> { "execute": "query-name" } # -> { "execute": "query-name" }
# <- { "return": { "name": "qemu-name" } } # <- { "return": { "name": "qemu-name" } }
#
## ##
{ 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true } { 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true }
@ -80,17 +78,17 @@
# #
# @thread-id: ID of the underlying host thread # @thread-id: ID of the underlying host thread
# #
# @poll-max-ns: maximum polling time in ns, 0 means polling is disabled # @poll-max-ns: maximum polling time in ns, 0 means polling is
# (since 2.9) # disabled (since 2.9)
# #
# @poll-grow: how many ns will be added to polling time, 0 means that it's not # @poll-grow: how many ns will be added to polling time, 0 means that
# configured (since 2.9) # it's not configured (since 2.9)
# #
# @poll-shrink: how many ns will be removed from polling time, 0 means that # @poll-shrink: how many ns will be removed from polling time, 0 means
# it's not configured (since 2.9) # that it's not configured (since 2.9)
# #
# @aio-max-batch: maximum number of requests in a batch for the AIO engine, # @aio-max-batch: maximum number of requests in a batch for the AIO
# 0 means that the engine will use its default (since 6.1) # engine, 0 means that the engine will use its default (since 6.1)
# #
# Since: 2.0 # Since: 2.0
## ##
@ -107,9 +105,9 @@
# #
# Returns a list of information about each iothread. # Returns a list of information about each iothread.
# #
# Note: this list excludes the QEMU main loop thread, which is not declared # Note: this list excludes the QEMU main loop thread, which is not
# using the -object iothread command-line option. It is always the main thread # declared using the -object iothread command-line option. It is
# of the process. # always the main thread of the process.
# #
# Returns: a list of @IOThreadInfo for each iothread # Returns: a list of @IOThreadInfo for each iothread
# #
@ -129,7 +127,6 @@
# } # }
# ] # ]
# } # }
#
## ##
{ 'command': 'query-iothreads', 'returns': ['IOThreadInfo'], { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'],
'allow-preconfig': true } 'allow-preconfig': true }
@ -141,16 +138,15 @@
# #
# Since: 0.14 # Since: 0.14
# #
# Notes: This function will succeed even if the guest is already in the stopped # Notes: This function will succeed even if the guest is already in
# state. In "inmigrate" state, it will ensure that the guest # the stopped state. In "inmigrate" state, it will ensure that
# remains paused once migration finishes, as if the -S option was # the guest remains paused once migration finishes, as if the -S
# passed on the command line. # option was passed on the command line.
# #
# Example: # Example:
# #
# -> { "execute": "stop" } # -> { "execute": "stop" }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'stop' } { 'command': 'stop' }
@ -163,17 +159,16 @@
# #
# Returns: If successful, nothing # Returns: If successful, nothing
# #
# Notes: This command will succeed if the guest is currently running. It # Notes: This command will succeed if the guest is currently running.
# will also succeed if the guest is in the "inmigrate" state; in # It will also succeed if the guest is in the "inmigrate" state;
# this case, the effect of the command is to make sure the guest # in this case, the effect of the command is to make sure the
# starts once migration finishes, removing the effect of the -S # guest starts once migration finishes, removing the effect of the
# command line option if it was passed. # -S command line option if it was passed.
# #
# Example: # Example:
# #
# -> { "execute": "cont" } # -> { "execute": "cont" }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'cont' } { 'command': 'cont' }
@ -182,13 +177,14 @@
# #
# Exit from "preconfig" state # Exit from "preconfig" state
# #
# This command makes QEMU exit the preconfig state and proceed with # This command makes QEMU exit the preconfig state and proceed with VM
# VM initialization using configuration data provided on the command line # initialization using configuration data provided on the command line
# and via the QMP monitor during the preconfig state. The command is only # and via the QMP monitor during the preconfig state. The command is
# available during the preconfig state (i.e. when the --preconfig command # only available during the preconfig state (i.e. when the --preconfig
# line option was in use). # command line option was in use).
# #
# Features: # Features:
#
# @unstable: This command is experimental. # @unstable: This command is experimental.
# #
# Since: 3.0 # Since: 3.0
@ -199,7 +195,6 @@
# #
# -> { "execute": "x-exit-preconfig" } # -> { "execute": "x-exit-preconfig" }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'x-exit-preconfig', 'allow-preconfig': true, { 'command': 'x-exit-preconfig', 'allow-preconfig': true,
'features': [ 'unstable' ] } 'features': [ 'unstable' ] }
@ -214,35 +209,33 @@
# @cpu-index: The CPU to use for commands that require an implicit CPU # @cpu-index: The CPU to use for commands that require an implicit CPU
# #
# Features: # Features:
#
# @savevm-monitor-nodes: If present, HMP command savevm only snapshots # @savevm-monitor-nodes: If present, HMP command savevm only snapshots
# monitor-owned nodes if they have no parents. # monitor-owned nodes if they have no parents. This allows the
# This allows the use of 'savevm' with # use of 'savevm' with -blockdev. (since 4.2)
# -blockdev. (since 4.2)
# #
# Returns: the output of the command as a string # Returns: the output of the command as a string
# #
# Since: 0.14 # Since: 0.14
# #
# Notes: This command only exists as a stop-gap. Its use is highly # Notes: This command only exists as a stop-gap. Its use is highly
# discouraged. The semantics of this command are not # discouraged. The semantics of this command are not guaranteed:
# guaranteed: this means that command names, arguments and # this means that command names, arguments and responses can
# responses can change or be removed at ANY time. Applications # change or be removed at ANY time. Applications that rely on
# that rely on long term stability guarantees should NOT # long term stability guarantees should NOT use this command.
# use this command.
# #
# Known limitations: # Known limitations:
# #
# * This command is stateless, this means that commands that depend # * This command is stateless, this means that commands that
# on state information (such as getfd) might not work # 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: # Example:
# #
# -> { "execute": "human-monitor-command", # -> { "execute": "human-monitor-command",
# "arguments": { "command-line": "info kvm" } } # "arguments": { "command-line": "info kvm" } }
# <- { "return": "kvm support: enabled\r\n" } # <- { "return": "kvm support: enabled\r\n" }
#
## ##
{ 'command': 'human-monitor-command', { 'command': 'human-monitor-command',
'data': {'command-line': 'str', '*cpu-index': 'int'}, 'data': {'command-line': 'str', '*cpu-index': 'int'},
@ -260,18 +253,16 @@
# #
# Since: 0.14 # Since: 0.14
# #
# Notes: If @fdname already exists, the file descriptor assigned to # Notes: If @fdname already exists, the file descriptor assigned to it
# it will be closed and replaced by the received file # will be closed and replaced by the received file descriptor.
# descriptor.
# #
# The 'closefd' command can be used to explicitly close the # The 'closefd' command can be used to explicitly close the file
# file descriptor when it is no longer needed. # descriptor when it is no longer needed.
# #
# Example: # Example:
# #
# -> { "execute": "getfd", "arguments": { "fdname": "fd1" } } # -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'getfd', 'data': {'fdname': 'str'}, 'if': 'CONFIG_POSIX' } { 'command': 'getfd', 'data': {'fdname': 'str'}, 'if': 'CONFIG_POSIX' }
@ -291,18 +282,16 @@
# #
# Since: 8.0 # Since: 8.0
# #
# Notes: If @fdname already exists, the file descriptor assigned to # Notes: If @fdname already exists, the file descriptor assigned to it
# it will be closed and replaced by the received file # will be closed and replaced by the received file descriptor.
# descriptor.
# #
# The 'closefd' command can be used to explicitly close the # The 'closefd' command can be used to explicitly close the file
# file descriptor when it is no longer needed. # descriptor when it is no longer needed.
# #
# Example: # Example:
# #
# -> { "execute": "get-win32-socket", "arguments": { "info": "abcd123..", fdname": "skclient" } } # -> { "execute": "get-win32-socket", "arguments": { "info": "abcd123..", fdname": "skclient" } }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'get-win32-socket', 'data': {'info': 'str', 'fdname': 'str'}, 'if': 'CONFIG_WIN32' } { 'command': 'get-win32-socket', 'data': {'info': 'str', 'fdname': 'str'}, 'if': 'CONFIG_WIN32' }
@ -321,7 +310,6 @@
# #
# -> { "execute": "closefd", "arguments": { "fdname": "fd1" } } # -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'closefd', 'data': {'fdname': 'str'} } { 'command': 'closefd', 'data': {'fdname': 'str'} }
@ -332,8 +320,8 @@
# #
# @fdset-id: The ID of the fd set that @fd was added to. # @fdset-id: The ID of the fd set that @fd was added to.
# #
# @fd: The file descriptor that was received via SCM rights and # @fd: The file descriptor that was received via SCM rights and added
# added to the fd set. # to the fd set.
# #
# Since: 1.2 # Since: 1.2
## ##
@ -348,13 +336,14 @@
# #
# @opaque: A free-form string that can be used to describe the fd. # @opaque: A free-form string that can be used to describe the fd.
# #
# Returns: - @AddfdInfo on success # Returns:
# - If file descriptor was not received, GenericError # - @AddfdInfo on success
# - If @fdset-id is a negative value, GenericError # - 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. # 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 # Since: 1.2
# #
@ -362,7 +351,6 @@
# #
# -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } } # -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
# <- { "return": { "fdset-id": 1, "fd": 3 } } # <- { "return": { "fdset-id": 1, "fd": 3 } }
#
## ##
{ 'command': 'add-fd', { 'command': 'add-fd',
'data': { '*fdset-id': 'int', 'data': { '*fdset-id': 'int',
@ -378,21 +366,21 @@
# #
# @fd: The file descriptor that is to be removed. # @fd: The file descriptor that is to be removed.
# #
# Returns: - Nothing on success # Returns:
# - If @fdset-id or @fd is not found, GenericError # - Nothing on success
# - If @fdset-id or @fd is not found, GenericError
# #
# Since: 1.2 # Since: 1.2
# #
# Notes: The list of fd sets is shared by all monitor connections. # Notes: The list of fd sets is shared by all monitor connections.
# #
# If @fd is not specified, all file descriptors in @fdset-id # If @fd is not specified, all file descriptors in @fdset-id will be
# will be removed. # removed.
# #
# Example: # Example:
# #
# -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } } # -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} } { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
@ -465,7 +453,6 @@
# } # }
# ] # ]
# } # }
#
## ##
{ 'command': 'query-fdsets', 'returns': ['FdsetInfo'] } { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
@ -481,7 +468,7 @@
# @number: accepts a number # @number: accepts a number
# #
# @size: accepts a number followed by an optional suffix (K)ilo, # @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 # Since: 1.5
## ##
@ -512,7 +499,8 @@
## ##
# @CommandLineOptionInfo: # @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 # @option: option name
# #
@ -530,8 +518,9 @@
# #
# @option: option name # @option: option name
# #
# Returns: list of @CommandLineOptionInfo for all options (or for the given # Returns: list of @CommandLineOptionInfo for all options (or for the
# @option). Returns an error if the given @option doesn't exist. # given @option). Returns an error if the given @option doesn't
# exist.
# #
# Since: 1.5 # Since: 1.5
# #
@ -555,26 +544,25 @@
# } # }
# ] # ]
# } # }
#
## ##
{'command': 'query-command-line-options', {'command': 'query-command-line-options',
'data': { '*option': 'str' }, 'data': {'*option': 'str'},
'returns': ['CommandLineOptionInfo'], 'returns': ['CommandLineOptionInfo'],
'allow-preconfig': true } 'allow-preconfig': true}
## ##
# @RTC_CHANGE: # @RTC_CHANGE:
# #
# Emitted when the guest changes the RTC time. # Emitted when the guest changes the RTC time.
# #
# @offset: offset in seconds between base RTC clock (as specified # @offset: offset in seconds between base RTC clock (as specified by
# by -rtc base), and new RTC clock value # -rtc base), and new RTC clock value
# #
# @qom-path: path to the RTC object in the QOM tree # @qom-path: path to the RTC object in the QOM tree
# #
# Note: This event is rate-limited. # Note: This event is rate-limited. It is not guaranteed that the RTC
# It is not guaranteed that the RTC in the system implements # in the system implements this event, or even that the system has
# this event, or even that the system has an RTC at all. # an RTC at all.
# #
# Since: 0.13 # Since: 0.13
# #
@ -593,10 +581,11 @@
# Emitted when the client of a TYPE_VFIO_USER_SERVER closes the # Emitted when the client of a TYPE_VFIO_USER_SERVER closes the
# communication channel # communication channel
# #
# @vfu-id: ID of the TYPE_VFIO_USER_SERVER object. It is the last component # @vfu-id: ID of the TYPE_VFIO_USER_SERVER object. It is the last
# of @vfu-qom-path referenced below # 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 # @dev-id: ID of attached PCI device
# #
@ -612,7 +601,6 @@
# "dev-id": "sas1", # "dev-id": "sas1",
# "dev-qom-path": "/machine/peripheral/sas1" }, # "dev-qom-path": "/machine/peripheral/sas1" },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
#
## ##
{ 'event': 'VFU_CLIENT_HANGUP', { 'event': 'VFU_CLIENT_HANGUP',
'data': { 'vfu-id': 'str', 'vfu-qom-path': 'str', '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 # @up: true to set the link status to be up
# #
# Returns: Nothing on success # Returns: Nothing on success If @name is not a valid network device,
# If @name is not a valid network device, DeviceNotFound # DeviceNotFound
# #
# Since: 0.14 # Since: 0.14
# #
# Notes: Not all network adapters support setting link status. This command # Notes: Not all network adapters support setting link status. This
# will succeed even if the network adapter does not support link status # command will succeed even if the network adapter does not
# notification. # support link status notification.
# #
# Example: # Example:
# #
# -> { "execute": "set_link", # -> { "execute": "set_link",
# "arguments": { "name": "e1000.0", "up": false } } # "arguments": { "name": "e1000.0", "up": false } }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'set_link', 'data': {'name': 'str', 'up': 'bool'} } { 'command': 'set_link', 'data': {'name': 'str', 'up': 'bool'} }
@ -45,8 +44,8 @@
# #
# Since: 0.14 # Since: 0.14
# #
# Returns: Nothing on success # Returns: Nothing on success If @type is not a valid network backend,
# If @type is not a valid network backend, DeviceNotFound # DeviceNotFound
# #
# Example: # Example:
# #
@ -54,7 +53,6 @@
# "arguments": { "type": "user", "id": "netdev1", # "arguments": { "type": "user", "id": "netdev1",
# "dnssearch": [ { "str": "example.org" } ] } } # "dnssearch": [ { "str": "example.org" } ] } }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'netdev_add', 'data': 'Netdev', 'boxed': true, { 'command': 'netdev_add', 'data': 'Netdev', 'boxed': true,
'allow-preconfig': true } 'allow-preconfig': true }
@ -66,8 +64,8 @@
# #
# @id: the name of the network backend to remove # @id: the name of the network backend to remove
# #
# Returns: Nothing on success # Returns: Nothing on success If @id is not a valid network backend,
# If @id is not a valid network backend, DeviceNotFound # DeviceNotFound
# #
# Since: 0.14 # Since: 0.14
# #
@ -75,7 +73,6 @@
# #
# -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } } # -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
# <- { "return": {} } # <- { "return": {} }
#
## ##
{ 'command': 'netdev_del', 'data': {'id': 'str'}, { 'command': 'netdev_del', 'data': {'id': 'str'},
'allow-preconfig': true } 'allow-preconfig': true }
@ -108,25 +105,23 @@
## ##
# @NetdevUserOptions: # @NetdevUserOptions:
# #
# Use the user mode network stack which requires no administrator privilege to # Use the user mode network stack which requires no administrator
# run. # privilege to run.
# #
# @hostname: client hostname reported by the builtin DHCP server # @hostname: client hostname reported by the builtin DHCP server
# #
# @restrict: isolate the guest from the host # @restrict: isolate the guest from the host
# #
# @ipv4: whether to support IPv4, default true for enabled # @ipv4: whether to support IPv4, default true for enabled (since 2.6)
# (since 2.6)
# #
# @ipv6: whether to support IPv6, default true for enabled # @ipv6: whether to support IPv6, default true for enabled (since 2.6)
# (since 2.6)
# #
# @ip: legacy parameter, use net= instead # @ip: legacy parameter, use net= instead
# #
# @net: IP network address that the guest will see, in the # @net: IP network address that the guest will see, in the form
# form addr[/netmask] The netmask is optional, and can be # addr[/netmask] The netmask is optional, and can be either in the
# either in the form a.b.c.d or as a number of valid top-most # form a.b.c.d or as a number of valid top-most bits. Default is
# bits. Default is 10.0.2.0/24. # 10.0.2.0/24.
# #
# @host: guest-visible address of the host # @host: guest-visible address of the host
# #
@ -135,34 +130,34 @@
# @bootfile: BOOTP filename, for use with tftp= # @bootfile: BOOTP filename, for use with tftp=
# #
# @dhcpstart: the first of the 16 IPs the built-in DHCP server can # @dhcpstart: the first of the 16 IPs the built-in DHCP server can
# assign # assign
# #
# @dns: guest-visible address of the virtual nameserver # @dns: guest-visible address of the virtual nameserver
# #
# @dnssearch: list of DNS suffixes to search, passed as DHCP option # @dnssearch: list of DNS suffixes to search, passed as DHCP option to
# to the guest # the guest
# #
# @domainname: guest-visible domain name of the virtual nameserver # @domainname: guest-visible domain name of the virtual nameserver
# (since 3.0) # (since 3.0)
# #
# @ipv6-prefix: IPv6 network prefix (default is fec0::) (since # @ipv6-prefix: IPv6 network prefix (default is fec0::) (since 2.6).
# 2.6). The network prefix is given in the usual # The network prefix is given in the usual hexadecimal IPv6
# hexadecimal IPv6 address notation. # address notation.
# #
# @ipv6-prefixlen: IPv6 network prefix length (default is 64) # @ipv6-prefixlen: IPv6 network prefix length (default is 64) (since
# (since 2.6) # 2.6)
# #
# @ipv6-host: guest-visible IPv6 address of the host (since 2.6) # @ipv6-host: guest-visible IPv6 address of the host (since 2.6)
# #
# @ipv6-dns: guest-visible IPv6 address of the virtual # @ipv6-dns: guest-visible IPv6 address of the virtual nameserver
# nameserver (since 2.6) # (since 2.6)
# #
# @smb: root directory of the built-in SMB server # @smb: root directory of the built-in SMB server
# #
# @smbserver: IP address 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 # @hostfwd: redirect incoming TCP or UDP host connections to guest
# endpoints # endpoints
# #
# @guestfwd: forward guest TCP connections # @guestfwd: forward guest TCP connections
# #
@ -205,7 +200,7 @@
# @fd: file descriptor of an already opened tap # @fd: file descriptor of an already opened tap
# #
# @fds: multiple file descriptors of already opened multiqueue capable # @fds: multiple file descriptors of already opened multiqueue capable
# tap # tap
# #
# @script: script to initialize the interface # @script: script to initialize the interface
# #
@ -215,7 +210,7 @@
# #
# @helper: command to execute to configure bridge # @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 # @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 # @vhostfd: file descriptor of an already opened vhost net device
# #
# @vhostfds: file descriptors of multiple already opened vhost net # @vhostfds: file descriptors of multiple already opened vhost net
# devices # devices
# #
# @vhostforce: vhost on for non-MSIX virtio guests # @vhostforce: vhost on for non-MSIX virtio guests
# #
# @queues: number of queues to be created for multiqueue capable tap # @queues: number of queues to be created for multiqueue capable tap
# #
# @poll-us: maximum number of microseconds that could # @poll-us: maximum number of microseconds that could be spent on busy
# be spent on busy polling for tap (since 2.7) # polling for tap (since 2.7)
# #
# Since: 1.2 # Since: 1.2
## ##
@ -303,9 +298,8 @@
# #
# @counter: have sequence counter # @counter: have sequence counter
# #
# @pincounter: pin sequence counter to zero - # @pincounter: pin sequence counter to zero - workaround for buggy
# workaround for buggy implementations or # implementations or networks with packet reorder
# networks with packet reorder
# #
# @txcookie: 32 or 64 bit transmit cookie # @txcookie: 32 or 64 bit transmit cookie
# #
@ -313,11 +307,11 @@
# #
# @txsession: 32 bit transmit session # @txsession: 32 bit transmit session
# #
# @rxsession: 32 bit receive session - if not specified # @rxsession: 32 bit receive session - if not specified set to the
# set to the same value as transmit # same value as transmit
# #
# @offset: additional offset - allows the insertion of # @offset: additional offset - allows the insertion of additional
# additional application-specific data before the packet payload # application-specific data before the packet payload
# #
# Since: 2.1 # Since: 2.1
## ##
@ -382,7 +376,9 @@
# Connect two or more net clients through a software hub. # Connect two or more net clients through a software hub.
# #
# @hubid: hub identifier number # @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 # Since: 1.2
## ##
@ -396,12 +392,12 @@
# #
# Connect a client to a netmap-enabled NIC or to a VALE switch port # 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 # @ifname: Either the name of an existing network interface supported
# netmap, or the name of a VALE port (created on the fly). # by netmap, or the name of a VALE port (created on the fly). A
# A VALE port name is in the form 'valeXXX:YYY', where XXX and # VALE port name is in the form 'valeXXX:YYY', where XXX and YYY
# YYY are non-negative integers. XXX identifies a switch and # are non-negative integers. XXX identifies a switch and YYY
# YYY identifies a port of the switch. VALE ports having the # identifies a port of the switch. VALE ports having the same XXX
# same XXX are therefore connected to the same switch. # are therefore connected to the same switch.
# #
# @devname: path of the netmap device (default: '/dev/netmap'). # @devname: path of the netmap device (default: '/dev/netmap').
# #
@ -422,7 +418,7 @@
# @vhostforce: vhost on for non-MSIX virtio guests (default: false). # @vhostforce: vhost on for non-MSIX virtio guests (default: false).
# #
# @queues: number of queues to be created for multiqueue vhost-user # @queues: number of queues to be created for multiqueue vhost-user
# (default: 1) (Since 2.5) # (default: 1) (Since 2.5)
# #
# Since: 2.1 # Since: 2.1
## ##
@ -437,21 +433,21 @@
# #
# Vhost-vdpa network backend # Vhost-vdpa network backend
# #
# vDPA device is a device that uses a datapath which complies with the virtio # vDPA device is a device that uses a datapath which complies with the
# specifications with a vendor specific control path. # virtio specifications with a vendor specific control path.
# #
# @vhostdev: path of vhost-vdpa device # @vhostdev: path of vhost-vdpa device (default:'/dev/vhost-vdpa-0')
# (default:'/dev/vhost-vdpa-0')
# #
# @vhostfd: file descriptor of an already opened vhost vdpa device # @vhostfd: file descriptor of an already opened vhost vdpa device
# #
# @queues: number of queues to be created for multiqueue vhost-vdpa # @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) # @x-svq: Start device with (experimental) shadow virtqueue. (Since
# (default: false) # 7.1) (default: false)
# #
# Features: # Features:
#
# @unstable: Member @x-svq is experimental. # @unstable: Member @x-svq is experimental.
# #
# Since: 5.1 # Since: 5.1
@ -472,31 +468,28 @@
# interfaces that are in host mode and also with the host. # interfaces that are in host mode and also with the host.
# #
# @start-address: The starting IPv4 address to use for the interface. # @start-address: The starting IPv4 address to use for the interface.
# Must be in the private IP range (RFC 1918). Must be # Must be in the private IP range (RFC 1918). Must be specified
# specified along with @end-address and @subnet-mask. # along with @end-address and @subnet-mask. This address is used
# This address is used as the gateway address. The # as the gateway address. The subsequent address up to and
# subsequent address up to and including end-address are # including end-address are placed in the DHCP pool.
# placed in the DHCP pool.
# #
# @end-address: The DHCP IPv4 range end address to use for the # @end-address: The DHCP IPv4 range end address to use for the
# interface. Must be in the private IP range (RFC 1918). # interface. Must be in the private IP range (RFC 1918). Must be
# Must be specified along with @start-address and # specified along with @start-address and @subnet-mask.
# @subnet-mask.
# #
# @subnet-mask: The IPv4 subnet mask to use on the interface. Must # @subnet-mask: The IPv4 subnet mask to use on the interface. Must be
# be specified along with @start-address and @subnet-mask. # specified along with @start-address and @subnet-mask.
# #
# @isolated: Enable isolation for this interface. Interface isolation # @isolated: Enable isolation for this interface. Interface isolation
# ensures that vmnet interface is not able to communicate # ensures that vmnet interface is not able to communicate with any
# with any other vmnet interfaces. Only communication with # other vmnet interfaces. Only communication with host is
# host is allowed. Requires at least macOS Big Sur 11.0. # allowed. Requires at least macOS Big Sur 11.0.
# #
# @net-uuid: The identifier (UUID) to uniquely identify the isolated # @net-uuid: The identifier (UUID) to uniquely identify the isolated
# network vmnet interface should be added to. If # network vmnet interface should be added to. If set, no DHCP
# set, no DHCP service is provided for this interface and # service is provided for this interface and network communication
# network communication is allowed only with other interfaces # is allowed only with other interfaces added to this network
# added to this network identified by the UUID. Requires # identified by the UUID. Requires at least macOS Big Sur 11.0.
# at least macOS Big Sur 11.0.
# #
# Since: 7.1 # Since: 7.1
## ##
@ -515,34 +508,33 @@
# vmnet (shared mode) network backend. # vmnet (shared mode) network backend.
# #
# Allows traffic originating from the vmnet interface to reach the # Allows traffic originating from the vmnet interface to reach the
# Internet through a network address translator (NAT). # Internet through a network address translator (NAT). The vmnet
# The vmnet interface can communicate with the host and with # interface can communicate with the host and with other shared mode
# other shared mode interfaces on the same subnet. If no DHCP # interfaces on the same subnet. If no DHCP settings, subnet mask and
# settings, subnet mask and IPv6 prefix specified, the interface can # IPv6 prefix specified, the interface can communicate with any of
# communicate with any of other interfaces in shared mode. # other interfaces in shared mode.
# #
# @start-address: The starting IPv4 address to use for the interface. # @start-address: The starting IPv4 address to use for the interface.
# Must be in the private IP range (RFC 1918). Must be # Must be in the private IP range (RFC 1918). Must be specified
# specified along with @end-address and @subnet-mask. # along with @end-address and @subnet-mask. This address is used
# This address is used as the gateway address. The # as the gateway address. The subsequent address up to and
# subsequent address up to and including end-address are # including end-address are placed in the DHCP pool.
# placed in the DHCP pool.
# #
# @end-address: The DHCP IPv4 range end address to use for the # @end-address: The DHCP IPv4 range end address to use for the
# interface. Must be in the private IP range (RFC 1918). # interface. Must be in the private IP range (RFC 1918). Must be
# Must be specified along with @start-address and @subnet-mask. # specified along with @start-address and @subnet-mask.
# #
# @subnet-mask: The IPv4 subnet mask to use on the interface. Must # @subnet-mask: The IPv4 subnet mask to use on the interface. Must be
# be specified along with @start-address and @subnet-mask. # specified along with @start-address and @subnet-mask.
# #
# @isolated: Enable isolation for this interface. Interface isolation # @isolated: Enable isolation for this interface. Interface isolation
# ensures that vmnet interface is not able to communicate # ensures that vmnet interface is not able to communicate with any
# with any other vmnet interfaces. Only communication with # other vmnet interfaces. Only communication with host is
# host is allowed. Requires at least macOS Big Sur 11.0. # allowed. Requires at least macOS Big Sur 11.0.
# #
# @nat66-prefix: The IPv6 prefix to use into guest network. Must be a # @nat66-prefix: The IPv6 prefix to use into guest network. Must be a
# unique local address i.e. start with fd00::/8 and have # unique local address i.e. start with fd00::/8 and have length of
# length of 64. # 64.
# #
# Since: 7.1 # Since: 7.1
## ##
@ -564,10 +556,10 @@
# #
# @ifname: The name of the physical interface to be bridged. # @ifname: The name of the physical interface to be bridged.
# #
# @isolated: Enable isolation for this interface. Interface isolation # @isolated: Enable isolation for this interface. Interface isolation
# ensures that vmnet interface is not able to communicate # ensures that vmnet interface is not able to communicate with any
# with any other vmnet interfaces. Only communication with # other vmnet interfaces. Only communication with host is
# host is allowed. Requires at least macOS Big Sur 11.0. # allowed. Requires at least macOS Big Sur 11.0.
# #
# Since: 7.1 # Since: 7.1
## ##
@ -582,13 +574,14 @@
# #
# Configuration info for stream socket netdev # Configuration info for stream socket netdev
# #
# @addr: socket address to listen on (server=true) # @addr: socket address to listen on (server=true) or connect to
# or connect to (server=false) # (server=false)
#
# @server: create server socket (default: 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. # @reconnect: For a client socket, if a socket is disconnected, then
# Setting this to zero disables this function. (default: 0) # attempt a reconnect after the given number of seconds. Setting
# (since 8.0) # this to zero disables this function. (default: 0) (since 8.0)
# #
# Only SocketAddress types 'unix', 'inet' and 'fd' are supported. # Only SocketAddress types 'unix', 'inet' and 'fd' are supported.
# #
@ -606,13 +599,14 @@
# Configuration info for datagram socket netdev. # Configuration info for datagram socket netdev.
# #
# @remote: remote address # @remote: remote address
#
# @local: local address # @local: local address
# #
# Only SocketAddress types 'unix', 'inet' and 'fd' are supported. # Only SocketAddress types 'unix', 'inet' and 'fd' are supported.
# #
# If remote address is present and it's a multicast address, local address # If remote address is present and it's a multicast address, local
# is optional. Otherwise local address is required and remote address is # address is optional. Otherwise local address is required and remote
# optional. # address is optional.
# #
# .. table:: Valid parameters combination table # .. table:: Valid parameters combination table
# :widths: auto # :widths: auto
@ -764,9 +758,9 @@
# @name: net client name # @name: net client name
# #
# Returns: list of @RxFilterInfo for all NICs (or for the given NIC). # Returns: list of @RxFilterInfo for all NICs (or for the given NIC).
# Returns an error if the given @name doesn't exist, or given # Returns an error if the given @name doesn't exist, or given NIC
# NIC doesn't support rx-filter querying, or given net client # doesn't support rx-filter querying, or given net client isn't a
# isn't a NIC. # NIC.
# #
# Since: 1.6 # Since: 1.6
# #
@ -798,7 +792,6 @@
# } # }
# ] # ]
# } # }
#
## ##
{ 'command': 'query-rx-filter', { 'command': 'query-rx-filter',
'data': { '*name': 'str' }, 'data': { '*name': 'str' },
@ -807,8 +800,8 @@
## ##
# @NIC_RX_FILTER_CHANGED: # @NIC_RX_FILTER_CHANGED:
# #
# Emitted once until the 'query-rx-filter' command is executed, the first event # Emitted once until the 'query-rx-filter' command is executed, the
# will always be emitted # first event will always be emitted
# #
# @name: net client name # @name: net client name
# #
@ -822,7 +815,6 @@
# "data": { "name": "vnet0", # "data": { "name": "vnet0",
# "path": "/machine/peripheral/vnet0/virtio-backend" }, # "path": "/machine/peripheral/vnet0/virtio-backend" },
# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } } # "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
#
## ##
{ 'event': 'NIC_RX_FILTER_CHANGED', { 'event': 'NIC_RX_FILTER_CHANGED',
'data': { '*name': 'str', 'path': 'str' } } 'data': { '*name': 'str', 'path': 'str' } }
@ -833,7 +825,7 @@
# Parameters for self-announce timers # Parameters for self-announce timers
# #
# @initial: Initial delay (in ms) before sending the first GARP/RARP # @initial: Initial delay (in ms) before sending the first GARP/RARP
# announcement # announcement
# #
# @max: Maximum delay (in ms) between GARP/RARP announcement packets # @max: Maximum delay (in ms) between GARP/RARP announcement packets
# #
@ -841,12 +833,12 @@
# #
# @step: Delay increase (in ms) after each self-announcement attempt # @step: Delay increase (in ms) after each self-announcement attempt
# #
# @interfaces: An optional list of interface names, which restricts the # @interfaces: An optional list of interface names, which restricts
# announcement to the listed interfaces. (Since 4.1) # the announcement to the listed interfaces. (Since 4.1)
# #
# @id: A name to be used to identify an instance of announce-timers # @id: A name to be used to identify an instance of announce-timers
# and to allow it to modified later. Not for use as # and to allow it to modified later. Not for use as part of the
# part of the migration parameters. (Since 4.1) # migration parameters. (Since 4.1)
# #
# Since: 4.0 # Since: 4.0
## ##
@ -862,8 +854,9 @@
## ##
# @announce-self: # @announce-self:
# #
# Trigger generation of broadcast RARP frames to update network switches. # Trigger generation of broadcast RARP frames to update network
# This can be useful when network bonds fail-over the active slave. # switches. This can be useful when network bonds fail-over the
# active slave.
# #
# Example: # Example:
# #
@ -881,9 +874,10 @@
## ##
# @FAILOVER_NEGOTIATED: # @FAILOVER_NEGOTIATED:
# #
# Emitted when VIRTIO_NET_F_STANDBY was enabled during feature negotiation. # Emitted when VIRTIO_NET_F_STANDBY was enabled during feature
# Failover primary devices which were hidden (not hotplugged when requested) # negotiation. Failover primary devices which were hidden (not
# before will now be hotplugged by the virtio-net standby device. # hotplugged when requested) before will now be hotplugged by the
# virtio-net standby device.
# #
# @device-id: QEMU device id of the unplugged device # @device-id: QEMU device id of the unplugged device
# #
@ -894,7 +888,6 @@
# <- { "event": "FAILOVER_NEGOTIATED", # <- { "event": "FAILOVER_NEGOTIATED",
# "data": { "device-id": "net1" }, # "data": { "device-id": "net1" },
# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } } # "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
#
## ##
{ 'event': 'FAILOVER_NEGOTIATED', { 'event': 'FAILOVER_NEGOTIATED',
'data': {'device-id': 'str'} } 'data': {'device-id': 'str'} }
@ -905,6 +898,7 @@
# Emitted when the netdev stream backend is connected # Emitted when the netdev stream backend is connected
# #
# @netdev-id: QEMU netdev id that is connected # @netdev-id: QEMU netdev id that is connected
#
# @addr: The destination address # @addr: The destination address
# #
# Since: 7.2 # Since: 7.2
@ -921,7 +915,6 @@
# "data": { "netdev-id": "netdev0", # "data": { "netdev-id": "netdev0",
# "addr": { "path": "/tmp/qemu0", "type": "unix" } }, # "addr": { "path": "/tmp/qemu0", "type": "unix" } },
# "timestamp": { "seconds": 1666269706, "microseconds": 413651 } } # "timestamp": { "seconds": 1666269706, "microseconds": 413651 } }
#
## ##
{ 'event': 'NETDEV_STREAM_CONNECTED', { 'event': 'NETDEV_STREAM_CONNECTED',
'data': { 'netdev-id': 'str', 'data': { 'netdev-id': 'str',
@ -941,7 +934,6 @@
# <- { 'event': 'NETDEV_STREAM_DISCONNECTED', # <- { 'event': 'NETDEV_STREAM_DISCONNECTED',
# 'data': {'netdev-id': 'netdev0'}, # 'data': {'netdev-id': 'netdev0'},
# 'timestamp': {'seconds': 1663330937, 'microseconds': 526695} } # 'timestamp': {'seconds': 1663330937, 'microseconds': 526695} }
#
## ##
{ 'event': 'NETDEV_STREAM_DISCONNECTED', { 'event': 'NETDEV_STREAM_DISCONNECTED',
'data': { 'netdev-id': 'str' } } '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 # @bar: the index of the Base Address Register for this region
# #
# @type: - 'io' if the region is a PIO region # @type:
# - 'memory' if the region is a MMIO region # - 'io' if the region is a PIO region
# - 'memory' if the region is a MMIO region
# #
# @size: memory size # @size: memory size
# #
@ -49,21 +50,21 @@
# #
# Information about a bus of a PCI Bridge device # Information about a bus of a PCI Bridge device
# #
# @number: primary bus interface number. This should be the number of the # @number: primary bus interface number. This should be the number of
# bus the device resides on. # the bus the device resides on.
# #
# @secondary: secondary bus interface number. This is the number of the # @secondary: secondary bus interface number. This is the number of
# main bus for the bridge # the main bus for the bridge
# #
# @subordinate: This is the highest number bus that resides below the # @subordinate: This is the highest number bus that resides below the
# bridge. # bridge.
# #
# @io_range: The PIO range for all devices on this bridge # @io_range: The PIO range for all devices on this bridge
# #
# @memory_range: The MMIO 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 # @prefetchable_range: The range of prefetchable MMIO for all devices
# this bridge # on this bridge
# #
# Since: 2.4 # Since: 2.4
## ##
@ -145,8 +146,8 @@
# #
# @regions: a list of the PCI I/O regions associated with the device # @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 # Notes: the contents of @class_info.desc are not stable and should
# treated as informational. # only be treated as informational.
# #
# Since: 0.14 # Since: 0.14
## ##
@ -174,10 +175,10 @@
# #
# Return information about the PCI bus topology of the guest. # Return information about the PCI bus topology of the guest.
# #
# Returns: a list of @PciInfo for each PCI bus. Each bus is # 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 # represented by a json-object, which has a key with a json-array
# all PCI devices attached to it. Each device is represented by a # of all PCI devices attached to it. Each device is represented
# json-object. # by a json-object.
# #
# Since: 0.14 # 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'] } { '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. # 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 # Most of the time their usage is exactly the same as in the user
# means that any other document which also describe commands (the manpage, # Monitor, this means that any other document which also describe
# QEMU's manual, etc) can and should be consulted. # commands (the manpage, QEMU's manual, etc) can and should be
# consulted.
# #
# QMP has two types of commands: regular and query commands. Regular commands # QMP has two types of commands: regular and query commands. Regular
# usually change the Virtual Machine's state someway, while query commands just # commands usually change the Virtual Machine's state someway, while
# return information. The sections below are divided accordingly. # query commands just return information. The sections below are
# divided accordingly.
# #
# It's important to observe that all communication examples are formatted in # It's important to observe that all communication examples are
# a reader-friendly way, so that they're easier to understand. However, in real # formatted in a reader-friendly way, so that they're easier to
# protocol usage, they're emitted as a single line. # understand. However, in real protocol usage, they're emitted as a
# single line.
# #
# Also, the following notation is used to denote data flow: # Also, the following notation is used to denote data flow:
# #
@ -26,8 +29,8 @@
# -> data issued by the Client # -> data issued by the Client
# <- Server data response # <- Server data response
# #
# Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for # Please, refer to the QMP specification (docs/interop/qmp-spec.txt)
# detailed information on the Server command and response formats. # for detailed information on the Server command and response formats.
## ##
{ 'include': 'pragma.json' } { 'include': 'pragma.json' }

63
qapi/qdev.json
View File

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

404
qapi/qom.json
View File

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

1
qapi/rdma.json
View File

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

48
qapi/replay.json
View File

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

20
qapi/rocker.json
View File

@ -34,7 +34,6 @@
# #
# -> { "execute": "query-rocker", "arguments": { "name": "sw1" } } # -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
# <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}} # <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
#
## ##
{ 'command': 'query-rocker', { 'command': 'query-rocker',
'data': { 'name': 'str' }, 'data': { 'name': 'str' },
@ -107,7 +106,6 @@
# {"duplex": "full", "enabled": true, "name": "sw1.2", # {"duplex": "full", "enabled": true, "name": "sw1.2",
# "autoneg": "off", "link-up": true, "speed": 10000} # "autoneg": "off", "link-up": true, "speed": 10000}
# ]} # ]}
#
## ##
{ 'command': 'query-rocker-ports', { 'command': 'query-rocker-ports',
'data': { 'name': 'str' }, 'data': { 'name': 'str' },
@ -141,7 +139,7 @@
# @ip-dst: IP header destination address # @ip-dst: IP header destination address
# #
# Note: optional members may or may not appear in the flow key # 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 # Since: 2.4
## ##
@ -171,7 +169,7 @@
# @ip-tos: IP header TOS field # @ip-tos: IP header TOS field
# #
# Note: optional members may or may not appear in the flow mask # 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 # Since: 2.4
## ##
@ -198,7 +196,7 @@
# @out-pport: physical output port # @out-pport: physical output port
# #
# Note: optional members may or may not appear in the flow action # 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 # Since: 2.4
## ##
@ -235,8 +233,8 @@
# #
# @name: switch name # @name: switch name
# #
# @tbl-id: flow table ID. If tbl-id is not specified, returns # @tbl-id: flow table ID. If tbl-id is not specified, returns flow
# flow information for all tables. # information for all tables.
# #
# Returns: rocker OF-DPA flow information # Returns: rocker OF-DPA flow information
# #
@ -254,7 +252,6 @@
# }, # },
# {...more...}, # {...more...},
# ]} # ]}
#
## ##
{ 'command': 'query-rocker-of-dpa-flows', { 'command': 'query-rocker-of-dpa-flows',
'data': { 'name': 'str', '*tbl-id': 'uint32' }, 'data': { 'name': 'str', '*tbl-id': 'uint32' },
@ -292,7 +289,7 @@
# @ttl-check: perform TTL check # @ttl-check: perform TTL check
# #
# Note: optional members may or may not appear in the group depending # 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 # Since: 2.4
## ##
@ -311,8 +308,8 @@
# #
# @name: switch name # @name: switch name
# #
# @type: group type. If type is not specified, returns # @type: group type. If type is not specified, returns group
# group information for all group types. # information for all group types.
# #
# Returns: rocker OF-DPA group information # Returns: rocker OF-DPA group information
# #
@ -335,7 +332,6 @@
# "pport": 0, "vlan-id": 3840, # "pport": 0, "vlan-id": 3840,
# "pop-vlan": 1, "id": 251658240} # "pop-vlan": 1, "id": 251658240}
# ]} # ]}
#
## ##
{ 'command': 'query-rocker-of-dpa-groups', { 'command': 'query-rocker-of-dpa-groups',
'data': { 'name': 'str', '*type': 'uint8' }, '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 # @finish-migrate: guest is paused to finish the migration process
# #
# @inmigrate: guest is paused waiting for an incoming migration. Note # @inmigrate: guest is paused waiting for an incoming migration. Note
# that this state does not tell whether the machine will start at the # that this state does not tell whether the machine will start at
# end of the migration. This depends on the command-line -S option and # the end of the migration. This depends on the command-line -S
# any invocation of 'stop' or 'cont' that has happened since QEMU was # option and any invocation of 'stop' or 'cont' that has happened
# started. # since QEMU was started.
# #
# @internal-error: An internal error that prevents further guest execution # @internal-error: An internal error that prevents further guest
# has occurred # execution has occurred
# #
# @io-error: the last IOP has failed and the device is configured to pause # @io-error: the last IOP has failed and the device is configured to
# on I/O errors # pause on I/O errors
# #
# @paused: guest has been paused via the 'stop' command # @paused: guest has been paused via the 'stop' command
# #
@ -43,13 +43,15 @@
# #
# @suspended: guest is suspended (ACPI S3) # @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, # @colo: guest is paused to save/restore VM state under colo
# VM can not get into this state unless colo capability is enabled # checkpoint, VM can not get into this state unless colo
# for migration. (since 2.8) # capability is enabled for migration. (since 2.8)
## ##
{ 'enum': 'RunState', { 'enum': 'RunState',
'data': [ 'debug', 'inmigrate', 'internal-error', 'io-error', 'paused', 'data': [ 'debug', 'inmigrate', 'internal-error', 'io-error', 'paused',
@ -75,21 +77,21 @@
# @host-ui: Reaction to a UI event, like window close # @host-ui: Reaction to a UI event, like window close
# #
# @guest-shutdown: Guest shutdown/suspend request, via ACPI or other # @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 # @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 # @subsystem-reset: Partial guest reset that does not trigger QMP
# ignores --no-reboot. This is useful for sanitizing # events and ignores --no-reboot. This is useful for sanitizing
# hypercalls on s390 that are used during kexec/kdump/boot # hypercalls on s390 that are used during kexec/kdump/boot
# #
# @snapshot-load: A snapshot is being loaded by the record & replay # @snapshot-load: A snapshot is being loaded by the record & replay
# subsystem. This value is used only within QEMU. It # subsystem. This value is used only within QEMU. It doesn't
# doesn't occur in QMP. (since 7.2) # occur in QMP. (since 7.2)
#
## ##
{ 'enum': 'ShutdownCause', { 'enum': 'ShutdownCause',
# Beware, shutdown_caused_by_guest() depends on enumeration order # Beware, shutdown_caused_by_guest() depends on enumeration order
@ -104,19 +106,21 @@
# #
# @running: true if all VCPUs are runnable, false if not runnable # @running: true if all VCPUs are runnable, false if not runnable
# #
# @singlestep: true if using TCG with one guest instruction # @singlestep: true if using TCG with one guest instruction per
# per translation block # translation block
# #
# @status: the virtual machine @RunState # @status: the virtual machine @RunState
# #
# Features: # Features:
# @deprecated: Member 'singlestep' is deprecated (with no replacement). #
# @deprecated: Member 'singlestep' is deprecated (with no
# replacement).
# #
# Since: 0.14 # Since: 0.14
# #
# Notes: @singlestep is enabled on the command line with # Notes: @singlestep is enabled on the command line with '-accel
# '-accel tcg,one-insn-per-tb=on', or with the HMP # tcg,one-insn-per-tb=on', or with the HMP 'one-insn-per-tb'
# 'one-insn-per-tb' command. # command.
## ##
{ 'struct': 'StatusInfo', { 'struct': 'StatusInfo',
'data': {'running': 'bool', 'data': {'running': 'bool',
@ -138,7 +142,6 @@
# <- { "return": { "running": true, # <- { "return": { "running": true,
# "singlestep": false, # "singlestep": false,
# "status": "running" } } # "status": "running" } }
#
## ##
{ 'command': 'query-status', 'returns': 'StatusInfo', { 'command': 'query-status', 'returns': 'StatusInfo',
'allow-preconfig': true } 'allow-preconfig': true }
@ -146,17 +149,20 @@
## ##
# @SHUTDOWN: # @SHUTDOWN:
# #
# Emitted when the virtual machine has shut down, indicating that qemu is # Emitted when the virtual machine has shut down, indicating that qemu
# about to exit. # is about to exit.
# #
# @guest: If true, the shutdown was triggered by a guest request (such as # @guest: If true, the shutdown was triggered by a guest request (such
# a guest-initiated ACPI shutdown request or other hardware-specific action) # as a guest-initiated ACPI shutdown request or other
# rather than a host request (such as sending qemu a SIGINT). (since 2.10) # 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 # Note: If the command-line option "-no-shutdown" has been specified,
# not exit, and a STOP event will eventually follow the SHUTDOWN event # qemu will not exit, and a STOP event will eventually follow the
# SHUTDOWN event
# #
# Since: 0.12 # Since: 0.12
# #
@ -165,15 +171,14 @@
# <- { "event": "SHUTDOWN", # <- { "event": "SHUTDOWN",
# "data": { "guest": true, "reason": "guest-shutdown" }, # "data": { "guest": true, "reason": "guest-shutdown" },
# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } # "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
#
## ##
{ 'event': 'SHUTDOWN', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } } { 'event': 'SHUTDOWN', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } }
## ##
# @POWERDOWN: # @POWERDOWN:
# #
# Emitted when the virtual machine is powered down through the power control # Emitted when the virtual machine is powered down through the power
# system, such as via ACPI. # control system, such as via ACPI.
# #
# Since: 0.12 # Since: 0.12
# #
@ -181,7 +186,6 @@
# #
# <- { "event": "POWERDOWN", # <- { "event": "POWERDOWN",
# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } # "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
#
## ##
{ 'event': 'POWERDOWN' } { 'event': 'POWERDOWN' }
@ -191,9 +195,9 @@
# Emitted when the virtual machine is reset # Emitted when the virtual machine is reset
# #
# @guest: If true, the reset was triggered by a guest request (such as # @guest: If true, the reset was triggered by a guest request (such as
# a guest-initiated ACPI reboot request or other hardware-specific action) # a guest-initiated ACPI reboot request or other hardware-specific
# rather than a host request (such as the QMP command system_reset). # action) rather than a host request (such as the QMP command
# (since 2.10) # system_reset). (since 2.10)
# #
# @reason: The @ShutdownCause of the RESET. (since 4.0) # @reason: The @ShutdownCause of the RESET. (since 4.0)
# #
@ -204,7 +208,6 @@
# <- { "event": "RESET", # <- { "event": "RESET",
# "data": { "guest": false, "reason": "guest-reset" }, # "data": { "guest": false, "reason": "guest-reset" },
# "timestamp": { "seconds": 1267041653, "microseconds": 9518 } } # "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
#
## ##
{ 'event': 'RESET', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } } { 'event': 'RESET', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } }
@ -219,7 +222,6 @@
# #
# <- { "event": "STOP", # <- { "event": "STOP",
# "timestamp": { "seconds": 1267041730, "microseconds": 281295 } } # "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
#
## ##
{ 'event': 'STOP' } { 'event': 'STOP' }
@ -234,15 +236,14 @@
# #
# <- { "event": "RESUME", # <- { "event": "RESUME",
# "timestamp": { "seconds": 1271770767, "microseconds": 582542 } } # "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
#
## ##
{ 'event': 'RESUME' } { 'event': 'RESUME' }
## ##
# @SUSPEND: # @SUSPEND:
# #
# Emitted when guest enters a hardware suspension state, for example, S3 state, # Emitted when guest enters a hardware suspension state, for example,
# which is sometimes called standby state # S3 state, which is sometimes called standby state
# #
# Since: 1.1 # Since: 1.1
# #
@ -250,17 +251,18 @@
# #
# <- { "event": "SUSPEND", # <- { "event": "SUSPEND",
# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } # "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
#
## ##
{ 'event': 'SUSPEND' } { 'event': 'SUSPEND' }
## ##
# @SUSPEND_DISK: # @SUSPEND_DISK:
# #
# Emitted when guest enters a hardware suspension state with data saved on # Emitted when guest enters a hardware suspension state with data
# disk, for example, S4 state, which is sometimes called hibernate state # 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 # Since: 1.2
# #
@ -274,7 +276,8 @@
## ##
# @WAKEUP: # @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 # Since: 1.1
# #
@ -282,7 +285,6 @@
# #
# <- { "event": "WAKEUP", # <- { "event": "WAKEUP",
# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } # "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
#
## ##
{ 'event': 'WAKEUP' } { 'event': 'WAKEUP' }
@ -293,8 +295,9 @@
# #
# @action: action that has been taken # @action: action that has been taken
# #
# Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is # Note: If action is "reset", "shutdown", or "pause" the WATCHDOG
# followed respectively by the RESET, SHUTDOWN, or STOP events # event is followed respectively by the RESET, SHUTDOWN, or STOP
# events
# #
# Note: This event is rate-limited. # Note: This event is rate-limited.
# #
@ -305,7 +308,6 @@
# <- { "event": "WATCHDOG", # <- { "event": "WATCHDOG",
# "data": { "action": "reset" }, # "data": { "action": "reset" },
# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } # "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
#
## ##
{ 'event': 'WATCHDOG', { 'event': 'WATCHDOG',
'data': { 'action': 'WatchdogAction' } } 'data': { 'action': 'WatchdogAction' } }
@ -313,13 +315,13 @@
## ##
# @WatchdogAction: # @WatchdogAction:
# #
# An enumeration of the actions taken when the watchdog device's timer is # An enumeration of the actions taken when the watchdog device's timer
# expired # is expired
# #
# @reset: system resets # @reset: system resets
# #
# @shutdown: system shutdown, note that it is similar to @powerdown, which # @shutdown: system shutdown, note that it is similar to @powerdown,
# tries to set to system status and notify guest # which tries to set to system status and notify guest
# #
# @poweroff: system poweroff, the emulator program exits # @poweroff: system poweroff, the emulator program exits
# #
@ -329,8 +331,8 @@
# #
# @none: nothing is done # @none: nothing is done
# #
# @inject-nmi: a non-maskable interrupt is injected into the first VCPU (all # @inject-nmi: a non-maskable interrupt is injected into the first
# VCPUS on x86) (since 2.4) # VCPU (all VCPUS on x86) (since 2.4)
# #
# Since: 2.1 # Since: 2.1
## ##
@ -345,7 +347,8 @@
# #
# @reset: Reset the VM # @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 # Since: 6.0
## ##
@ -373,10 +376,11 @@
# #
# @pause: Pause the VM # @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 # @exit-failure: Shutdown the VM and exit with nonzero status (since
# (since 7.1) # 7.1)
# #
# Since: 6.0 # Since: 6.0
## ##
@ -395,8 +399,8 @@
## ##
# @set-action: # @set-action:
# #
# Set the actions that will be taken by the emulator in response to guest # Set the actions that will be taken by the emulator in response to
# events. # guest events.
# #
# @reboot: @RebootAction action taken on guest reboot. # @reboot: @RebootAction action taken on guest reboot.
# #
@ -404,7 +408,8 @@
# #
# @panic: @PanicAction action taken on guest panic. # @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. # Returns: Nothing on success.
# #
@ -442,7 +447,6 @@
# <- { "event": "GUEST_PANICKED", # <- { "event": "GUEST_PANICKED",
# "data": { "action": "pause" }, # "data": { "action": "pause" },
# "timestamp": { "seconds": 1648245231, "microseconds": 900001 } } # "timestamp": { "seconds": 1648245231, "microseconds": 900001 } }
#
## ##
{ 'event': 'GUEST_PANICKED', { 'event': 'GUEST_PANICKED',
'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } } 'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }
@ -463,7 +467,6 @@
# <- { "event": "GUEST_CRASHLOADED", # <- { "event": "GUEST_CRASHLOADED",
# "data": { "action": "run" }, # "data": { "action": "run" },
# "timestamp": { "seconds": 1648245259, "microseconds": 893771 } } # "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }
#
## ##
{ 'event': 'GUEST_CRASHLOADED', { 'event': 'GUEST_CRASHLOADED',
'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } } 'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }
@ -510,8 +513,8 @@
{'union': 'GuestPanicInformation', {'union': 'GuestPanicInformation',
'base': {'type': 'GuestPanicInformationType'}, 'base': {'type': 'GuestPanicInformationType'},
'discriminator': 'type', 'discriminator': 'type',
'data': { 'hyper-v': 'GuestPanicInformationHyperV', 'data': {'hyper-v': 'GuestPanicInformationHyperV',
's390': 'GuestPanicInformationS390' } } 's390': 'GuestPanicInformationS390'}}
## ##
# @GuestPanicInformationHyperV: # @GuestPanicInformationHyperV:
@ -521,11 +524,11 @@
# Since: 2.9 # Since: 2.9
## ##
{'struct': 'GuestPanicInformationHyperV', {'struct': 'GuestPanicInformationHyperV',
'data': { 'arg1': 'uint64', 'data': {'arg1': 'uint64',
'arg2': 'uint64', 'arg2': 'uint64',
'arg3': 'uint64', 'arg3': 'uint64',
'arg4': 'uint64', 'arg4': 'uint64',
'arg5': 'uint64' } } 'arg5': 'uint64'}}
## ##
# @S390CrashReason: # @S390CrashReason:
@ -536,13 +539,13 @@
# #
# @disabled-wait: the CPU has entered a disabled wait state # @disabled-wait: the CPU has entered a disabled wait state
# #
# @extint-loop: clock comparator or cpu timer interrupt with new PSW enabled # @extint-loop: clock comparator or cpu timer interrupt with new PSW
# for external interrupts # enabled for external interrupts
# #
# @pgmint-loop: program interrupt with BAD new PSW # @pgmint-loop: program interrupt with BAD new PSW
# #
# @opint-loop: operation exception interrupt with invalid code at the program # @opint-loop: operation exception interrupt with invalid code at the
# interrupt new PSW # program interrupt new PSW
# #
# Since: 2.12 # Since: 2.12
## ##
@ -559,17 +562,20 @@
# S390 specific guest panic information (PSW) # S390 specific guest panic information (PSW)
# #
# @core: core id of the CPU that crashed # @core: core id of the CPU that crashed
#
# @psw-mask: control fields of guest PSW # @psw-mask: control fields of guest PSW
#
# @psw-addr: guest instruction address # @psw-addr: guest instruction address
#
# @reason: guest crash reason # @reason: guest crash reason
# #
# Since: 2.12 # Since: 2.12
## ##
{'struct': 'GuestPanicInformationS390', {'struct': 'GuestPanicInformationS390',
'data': { 'core': 'uint32', 'data': {'core': 'uint32',
'psw-mask': 'uint64', 'psw-mask': 'uint64',
'psw-addr': 'uint64', 'psw-addr': 'uint64',
'reason': 'S390CrashReason' } } 'reason': 'S390CrashReason'}}
## ##
# @MEMORY_FAILURE: # @MEMORY_FAILURE:
@ -578,9 +584,11 @@
# #
# @recipient: recipient is defined as @MemoryFailureRecipient. # @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 # Since: 5.2
# #
@ -592,7 +600,6 @@
# "flags": { "action-required": false, # "flags": { "action-required": false,
# "recursive": false } }, # "recursive": false } },
# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } # "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
#
## ##
{ 'event': 'MEMORY_FAILURE', { 'event': 'MEMORY_FAILURE',
'data': { 'recipient': 'MemoryFailureRecipient', 'data': { 'recipient': 'MemoryFailureRecipient',
@ -604,8 +611,8 @@
# #
# Hardware memory failure occurs, handled by recipient. # Hardware memory failure occurs, handled by recipient.
# #
# @hypervisor: memory failure at QEMU process address space. # @hypervisor: memory failure at QEMU process address space. (none
# (none guest memory, but used by QEMU itself). # guest memory, but used by QEMU itself).
# #
# @guest: memory failure at guest memory, # @guest: memory failure at guest memory,
# #
@ -620,19 +627,20 @@
# #
# Actions taken by QEMU in response to a hardware memory failure. # Actions taken by QEMU in response to a hardware memory failure.
# #
# @ignore: the memory failure could be ignored. This will only be the case # @ignore: the memory failure could be ignored. This will only be the
# for action-optional failures. # case for action-optional failures.
# #
# @inject: memory failure occurred in guest memory, the guest enabled MCE # @inject: memory failure occurred in guest memory, the guest enabled
# handling mechanism, and QEMU could inject the MCE into the guest # MCE handling mechanism, and QEMU could inject the MCE into the
# successfully. # guest successfully.
# #
# @fatal: the failure is unrecoverable. This occurs for action-required # @fatal: the failure is unrecoverable. This occurs for
# failures if the recipient is the hypervisor; QEMU will exit. # action-required failures if the recipient is the hypervisor;
# QEMU will exit.
# #
# @reset: the failure is unrecoverable but confined to the guest. This # @reset: the failure is unrecoverable but confined to the guest.
# occurs if the recipient is a guest guest which is not ready # This occurs if the recipient is a guest guest which is not ready
# to handle memory failures. # to handle memory failures.
# #
# Since: 5.2 # Since: 5.2
## ##
@ -648,10 +656,10 @@
# Additional information on memory failures. # Additional information on memory failures.
# #
# @action-required: whether a memory failure event is action-required # @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 # @recursive: whether the failure occurred while the previous failure
# failure was still in progress. # was still in progress.
# #
# Since: 5.2 # Since: 5.2
## ##
@ -664,10 +672,11 @@
# #
# An enumeration of the options specified when enabling notify VM exit # 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 # @internal-error: enable the feature, raise a internal error if the
# VM exit happens. # notify VM exit happens.
# #
# @disable: disable the feature. # @disable: disable the feature.
# #

50
qapi/sockets.json
View File

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

83
qapi/stats.json
View File

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

20
qapi/tpm.json
View File

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

34
qapi/trace.json
View File

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

87
qapi/transaction.json
View File

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

435
qapi/ui.json
View File

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

84
qapi/virtio.json
View File

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

42
qapi/yank.json
View File

@ -9,7 +9,7 @@
## ##
# @YankInstanceType: # @YankInstanceType:
# #
# An enumeration of yank instance types. See @YankInstance for more # An enumeration of yank instance types. See @YankInstance for more
# information. # information.
# #
# Since: 6.0 # Since: 6.0
@ -20,8 +20,8 @@
## ##
# @YankInstanceBlockNode: # @YankInstanceBlockNode:
# #
# Specifies which block graph node to yank. See @YankInstance for more # Specifies which block graph node to yank. See @YankInstance for
# information. # more information.
# #
# @node-name: the name of the block graph node # @node-name: the name of the block graph node
# #
@ -33,8 +33,8 @@
## ##
# @YankInstanceChardev: # @YankInstanceChardev:
# #
# Specifies which character device to yank. See @YankInstance for more # Specifies which character device to yank. See @YankInstance for
# information. # more information.
# #
# @id: the chardev's ID # @id: the chardev's ID
# #
@ -46,21 +46,18 @@
## ##
# @YankInstance: # @YankInstance:
# #
# A yank instance can be yanked with the @yank qmp command to recover from a # A yank instance can be yanked with the @yank qmp command to recover
# hanging QEMU. # from a hanging QEMU.
# #
# Currently implemented yank instances: # Currently implemented yank instances:
# #
# - nbd block device: # - nbd block device: Yanking it will shut down the connection to the
# Yanking it will shut down the connection to the nbd server without # nbd server without attempting to reconnect.
# attempting to reconnect. # - socket chardev: Yanking it will shut down the connected socket.
# - socket chardev: # - migration: Yanking it will shut down all migration connections.
# Yanking it will shut down the connected socket. # Unlike @migrate_cancel, it will not notify the migration process,
# - migration: # so migration will go into @failed state, instead of @cancelled
# Yanking it will shut down all migration connections. Unlike # state. @yank should be used to recover from hangs.
# @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 # Since: 6.0
## ##
@ -74,13 +71,14 @@
## ##
# @yank: # @yank:
# #
# Try to recover from hanging QEMU by yanking the specified instances. See # Try to recover from hanging QEMU by yanking the specified instances.
# @YankInstance for more information. # See @YankInstance for more information.
# #
# Takes a list of @YankInstance as argument. # Takes a list of @YankInstance as argument.
# #
# Returns: - Nothing on success # Returns:
# - @DeviceNotFound error, if any of the YankInstances doesn't exist # - Nothing on success
# - @DeviceNotFound error, if any of the YankInstances doesn't exist
# #
# Example: # Example:
# #
@ -101,7 +99,7 @@
## ##
# @query-yank: # @query-yank:
# #
# Query yank instances. See @YankInstance for more information. # Query yank instances. See @YankInstance for more information.
# #
# Returns: list of @YankInstance # 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(): elif not self.tok.isspace():
# Show up to next structural, whitespace or quote # Show up to next structural, whitespace or quote
# character # character
match = must_match('[^[\\]{}:,\\s\'"]+', match = must_match('[^[\\]{}:,\\s\']+',
self.src[self.cursor-1:]) self.src[self.cursor-1:])
raise QAPIParseError(self, "stray '%s'" % match.group(0)) raise QAPIParseError(self, "stray '%s'" % match.group(0))
@ -468,34 +468,39 @@ class QAPIDoc:
class Section: class Section:
# pylint: disable=too-few-public-methods # pylint: disable=too-few-public-methods
def __init__(self, parser: QAPISchemaParser, def __init__(self, parser: QAPISchemaParser,
name: Optional[str] = None, indent: int = 0): name: Optional[str] = None):
# parser, for error messages about indentation # parser, for error messages about indentation
self._parser = parser self._parser = parser
# optional section name (argument/member or section name) # optional section name (argument/member or section name)
self.name = name self.name = name
# section text without section name
self.text = '' self.text = ''
# the expected indent level of the text of this section # indentation to strip (None means indeterminate)
self._indent = indent self._indent = None if self.name else 0
def append(self, line: str) -> None: def append(self, line: str) -> None:
# Strip leading spaces corresponding to the expected indent level line = line.rstrip()
# Blank lines are always OK.
if line: if line:
indent = must_match(r'\s*', line).end() 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( raise QAPIParseError(
self._parser, self._parser,
"unexpected de-indent (expected at least %d spaces)" % "unexpected de-indent (expected at least %d spaces)" %
self._indent) self._indent)
line = line[self._indent:] line = line[self._indent:]
self.text += line.rstrip() + '\n' self.text += line + '\n'
class ArgSection(Section): class ArgSection(Section):
def __init__(self, parser: QAPISchemaParser, def __init__(self, parser: QAPISchemaParser,
name: str, indent: int = 0): name: str):
super().__init__(parser, name, indent) super().__init__(parser, name)
self.member: Optional['QAPISchemaMember'] = None self.member: Optional['QAPISchemaMember'] = None
def connect(self, member: 'QAPISchemaMember') -> None: def connect(self, member: 'QAPISchemaMember') -> None:
@ -558,12 +563,12 @@ class QAPIDoc:
self._switch_section(QAPIDoc.NullSection(self._parser)) self._switch_section(QAPIDoc.NullSection(self._parser))
@staticmethod @staticmethod
def _is_section_tag(name: str) -> bool: def _match_at_name_colon(string: str) -> re.Match:
return name in ('Returns:', 'Since:', return re.match(r'@([^:]*): *', string)
# those are often singular or plural
'Note:', 'Notes:', @staticmethod
'Example:', 'Examples:', def _match_section_tag(string: str) -> re.Match:
'TODO:') return re.match(r'(Returns|Since|Notes?|Examples?|TODO): *', string)
def _append_body_line(self, line: str) -> None: def _append_body_line(self, line: str) -> None:
""" """
@ -579,7 +584,6 @@ class QAPIDoc:
Else, append the line to the current section. Else, append the line to the current section.
""" """
name = line.split(' ', 1)[0]
# FIXME not nice: things like '# @foo:' and '# @foo: ' aren't # FIXME not nice: things like '# @foo:' and '# @foo: ' aren't
# recognized, and get silently treated as ordinary text # recognized, and get silently treated as ordinary text
if not self.symbol and not self.body.text and line.startswith('@'): if not self.symbol and not self.body.text and line.startswith('@'):
@ -593,12 +597,12 @@ class QAPIDoc:
self._parser, "name required after '@'") self._parser, "name required after '@'")
elif self.symbol: elif self.symbol:
# This is a definition documentation block # 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_line = self._append_args_line
self._append_args_line(line) self._append_args_line(line)
elif line == 'Features:': elif line == 'Features:':
self._append_line = self._append_features_line 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_line = self._append_various_line
self._append_various_line(line) self._append_various_line(line)
else: else:
@ -619,25 +623,11 @@ class QAPIDoc:
Else, append the line to the current section. Else, append the line to the current section.
""" """
name = line.split(' ', 1)[0] match = self._match_at_name_colon(line)
if match:
if name.startswith('@') and name.endswith(':'): line = line[match.end():]
# If line is "@arg: first line of description", find self._start_args_section(match.group(1))
# the index of 'f', which is the indent we expect for any elif self._match_section_tag(line):
# 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):
self._append_line = self._append_various_line self._append_line = self._append_various_line
self._append_various_line(line) self._append_various_line(line)
return return
@ -654,25 +644,11 @@ class QAPIDoc:
self._append_freeform(line) self._append_freeform(line)
def _append_features_line(self, line: str) -> None: def _append_features_line(self, line: str) -> None:
name = line.split(' ', 1)[0] match = self._match_at_name_colon(line)
if match:
if name.startswith('@') and name.endswith(':'): line = line[match.end():]
# If line is "@arg: first line of description", find self._start_features_section(match.group(1))
# the index of 'f', which is the indent we expect for any elif self._match_section_tag(line):
# 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):
self._append_line = self._append_various_line self._append_line = self._append_various_line
self._append_various_line(line) self._append_various_line(line)
return return
@ -696,36 +672,22 @@ class QAPIDoc:
Else, append the line to the current section. Else, append the line to the current section.
""" """
name = line.split(' ', 1)[0] match = self._match_at_name_colon(line)
if match:
if name.startswith('@') and name.endswith(':'):
raise QAPIParseError(self._parser, raise QAPIParseError(self._parser,
"'%s' can't follow '%s' section" "'@%s:' can't follow '%s' section"
% (name, self.sections[0].name)) % (match.group(1), self.sections[0].name))
if self._is_section_tag(name): match = self._match_section_tag(line)
# If line is "Section: first line of description", find if match:
# the index of 'f', which is the indent we expect for any line = line[match.end():]
# following lines. We then remove the leading "Section:" self._start_section(match.group(1))
# 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)
self._append_freeform(line) self._append_freeform(line)
def _start_symbol_section( def _start_symbol_section(
self, self,
symbols_dict: Dict[str, 'QAPIDoc.ArgSection'], symbols_dict: Dict[str, 'QAPIDoc.ArgSection'],
name: str, name: str) -> None:
indent: int) -> None:
# FIXME invalid names other than the empty string aren't flagged # FIXME invalid names other than the empty string aren't flagged
if not name: if not name:
raise QAPIParseError(self._parser, "invalid parameter name") raise QAPIParseError(self._parser, "invalid parameter name")
@ -733,27 +695,26 @@ class QAPIDoc:
raise QAPIParseError(self._parser, raise QAPIParseError(self._parser,
"'%s' parameter name duplicated" % name) "'%s' parameter name duplicated" % name)
assert not self.sections assert not self.sections
new_section = QAPIDoc.ArgSection(self._parser, name, indent) new_section = QAPIDoc.ArgSection(self._parser, name)
self._switch_section(new_section) self._switch_section(new_section)
symbols_dict[name] = new_section symbols_dict[name] = new_section
def _start_args_section(self, name: str, indent: int) -> None: def _start_args_section(self, name: str) -> None:
self._start_symbol_section(self.args, name, indent) self._start_symbol_section(self.args, name)
def _start_features_section(self, name: str, indent: int) -> None: def _start_features_section(self, name: str) -> None:
self._start_symbol_section(self.features, name, indent) self._start_symbol_section(self.features, name)
def _start_section(self, name: Optional[str] = None, def _start_section(self, name: Optional[str] = None) -> None:
indent: int = 0) -> None:
if name in ('Returns', 'Since') and self.has_section(name): if name in ('Returns', 'Since') and self.has_section(name):
raise QAPIParseError(self._parser, raise QAPIParseError(self._parser,
"duplicated '%s' section" % name) "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._switch_section(new_section)
self.sections.append(new_section) self.sections.append(new_section)
def _switch_section(self, new_section: 'QAPIDoc.Section') -> None: 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. # Only the 'body' section is allowed to have an empty body.
# All other sections, including anonymous ones, must have text. # 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: # @foo:
# @a: line one # @a: line one
# line two is wrongly indented # line two
# line three is wrongly indented
## ##
{ 'command': 'foo', 'data': { 'a': 'int' } } { 'command': 'foo', 'data': { 'a': 'int' } }

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

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

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

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