vitalif
/
mirror_qemu
mirror of https://github.com/proxmox/mirror_qemu
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

qapi: Reformat doc comments to conform to current conventions 

Change

    # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
    #        do eiusmod tempor incididunt ut labore et dolore magna aliqua.

to

    # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
    #     do eiusmod tempor incididunt ut labore et dolore magna aliqua.

See recent commit "qapi: Relax doc string @name: description
indentation rules" for rationale.

Reflow paragraphs to 70 columns width, and consistently use two spaces
to separate sentences.

To check the generated documentation does not change, I compared the
generated HTML before and after this commit with "wdiff -3".  Finds no
differences.  Comparing with diff is not useful, as the reflown
paragraphs are visible there.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-18-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
Acked-by: Lukas Straub <lukasstraub2@web.de>
[Straightforward conflicts in qapi/audio.json qapi/misc-target.json
qapi/run-state.json resolved]
master
Markus Armbruster 2023-04-28 12:54:29 +02:00
parent 059d341a67
commit a937b6aa73
39 changed files with 4333 additions and 3945 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

242
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.
# #
# 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' },

1117
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
# #