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

qapi: Reformat doc comments to conform to current conventions

Browse Source 
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]
This commit is contained in:
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

44
qapi/acpi.json
View File

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

83
qapi/audio.json
View File

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

25
qapi/authz.json
View File

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

2335
qapi/block-core.json
View File

File diff suppressed because it is too large Load Diff

218
qapi/block-export.json
View File

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

192
qapi/block.json
View File

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

124
qapi/char.json
View File

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

13
qapi/common.json
View File

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

9
qapi/compat.json
View File

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

57
qapi/control.json
View File

@ -14,10 +14,9 @@
# Arguments:
#
# @enable: An optional list of QMPCapability values to enable. The
# client must not enable any capability that is not
# mentioned in the QMP greeting message. If the field is not
# provided, it means no QMP capabilities will be enabled.
# (since 2.12)
# client must not enable any capability that is not mentioned in
# the QMP greeting message. If the field is not provided, it
# means no QMP capabilities will be enabled. (since 2.12)
#
# Example:
#
@ -25,12 +24,14 @@
# "arguments": { "enable": [ "oob" ] } }
# <- { "return": {} }
#
# Notes: This command is valid exactly when first connecting: it must be
# issued before any other command will be accepted, and will fail once the
# monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
# Notes: This command is valid exactly when first connecting: it must
# be issued before any other command will be accepted, and will
# fail once the monitor is accepting other commands. (see qemu
# docs/interop/qmp-spec.txt)
#
# The QMP client needs to explicitly enable QMP capabilities, otherwise
# all the QMP capabilities will be turned off by default.
# The QMP client needs to explicitly enable QMP capabilities,
# otherwise all the QMP capabilities will be turned off by
# default.
#
# Since: 0.13
##
@ -44,8 +45,8 @@
# Enumeration of capabilities to be advertised during initial client
# connection, used for agreeing on particular QMP extension behaviors.
#
# @oob: QMP ability to support out-of-band requests.
# (Please refer to qmp-spec.txt for more information on OOB)
# @oob: QMP ability to support out-of-band requests. (Please refer to
# qmp-spec.txt for more information on OOB)
#
# Since: 2.12
##
@ -73,16 +74,16 @@
#
# A description of QEMU's version.
#
# @qemu: The version of QEMU. By current convention, a micro
# version of 50 signifies a development branch. A micro version
# greater than or equal to 90 signifies a release candidate for
# the next minor version. A micro version of less than 50
# signifies a stable release.
# @qemu: The version of QEMU. By current convention, a micro version
# of 50 signifies a development branch. A micro version greater
# than or equal to 90 signifies a release candidate for the next
# minor version. A micro version of less than 50 signifies a
# stable release.
#
# @package: QEMU will always set this field to an empty string. Downstream
# versions of QEMU should set this to a non-empty string. The
# exact format depends on the downstream however it highly
# recommended that a unique name is used.
# @package: QEMU will always set this field to an empty string.
# Downstream versions of QEMU should set this to a non-empty
# string. The exact format depends on the downstream however it
# highly recommended that a unique name is used.
#
# Since: 0.14
##
@ -94,7 +95,8 @@
#
# Returns the current version of QEMU.
#
# Returns: A @VersionInfo object describing the current version of QEMU.
# Returns: A @VersionInfo object describing the current version of
# QEMU.
#
# Since: 0.14
#
@ -111,7 +113,6 @@
# "package":""
# }
# }
#
##
{ 'command': 'query-version', 'returns': 'VersionInfo',
'allow-preconfig': true }
@ -150,8 +151,8 @@
# ]
# }
#
# Note: This example has been shortened as the real response is too long.
#
# Note: This example has been shortened as the real response is too
# long.
##
{ 'command': 'query-commands', 'returns': ['CommandInfo'],
'allow-preconfig': true }
@ -159,10 +160,10 @@
##
# @quit:
#
# This command will cause the QEMU process to exit gracefully. While every
# attempt is made to send the QMP response before terminating, this is not
# guaranteed. When using this interface, a premature EOF would not be
# unexpected.
# This command will cause the QEMU process to exit gracefully. While
# every attempt is made to send the QMP response before terminating,
# this is not guaranteed. When using this interface, a premature EOF
# would not be unexpected.
#
# Since: 0.14
#

237
qapi/crypto.json
View File

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

3
qapi/cryptodev.json
View File

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

72
qapi/cxl.json
View File

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

56
qapi/dump.json
View File

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

4
qapi/error.json
View File

@ -10,8 +10,8 @@
#
# QEMU error classes
#
# @GenericError: this is used for errors that don't require a specific error
# class. This should be the default case for most errors
# @GenericError: this is used for errors that don't require a specific
# error class. This should be the default case for most errors
#
# @CommandNotFound: the requested command has not been found
#

71
qapi/introspect.json
View File

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

133
qapi/job.json
View File

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

291
qapi/machine-target.json
View File

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

339
qapi/machine.json
View File

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

997
qapi/migration.json
View File

File diff suppressed because it is too large Load Diff

55
qapi/misc-target.json
View File

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

162
qapi/misc.json
View File

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

234
qapi/net.json
View File

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

29
qapi/pci.json
View File

@ -29,7 +29,8 @@
#
# @bar: the index of the Base Address Register for this region
#
# @type: - 'io' if the region is a PIO region
# @type:
# - 'io' if the region is a PIO region
# - 'memory' if the region is a MMIO region
#
# @size: memory size
@ -49,11 +50,11 @@
#
# Information about a bus of a PCI Bridge device
#
# @number: primary bus interface number. This should be the number of the
# bus the device resides on.
# @number: primary bus interface number. This should be the number of
# the bus the device resides on.
#
# @secondary: secondary bus interface number. This is the number of the
# main bus for the bridge
# @secondary: secondary bus interface number. This is the number of
# the main bus for the bridge
#
# @subordinate: This is the highest number bus that resides below the
# bridge.
@ -62,8 +63,8 @@
#
# @memory_range: The MMIO range for all devices on this bridge
#
# @prefetchable_range: The range of prefetchable MMIO for all devices on
# this bridge
# @prefetchable_range: The range of prefetchable MMIO for all devices
# on this bridge
#
# Since: 2.4
##
@ -145,8 +146,8 @@
#
# @regions: a list of the PCI I/O regions associated with the device
#
# Notes: the contents of @class_info.desc are not stable and should only be
# treated as informational.
# Notes: the contents of @class_info.desc are not stable and should
# only be treated as informational.
#
# Since: 0.14
##
@ -175,9 +176,9 @@
# Return information about the PCI bus topology of the guest.
#
# Returns: a list of @PciInfo for each PCI bus. Each bus is
# represented by a json-object, which has a key with a json-array of
# all PCI devices attached to it. Each device is represented by a
# json-object.
# represented by a json-object, which has a key with a json-array
# of all PCI devices attached to it. Each device is represented
# by a json-object.
#
# Since: 0.14
#
@ -310,7 +311,7 @@
# ]
# }
#
# Note: This example has been shortened as the real response is too long.
#
# Note: This example has been shortened as the real response is too
# long.
##
{ 'command': 'query-pci', 'returns': ['PciInfo'] }

25
qapi/qapi-schema.json
View File

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

59
qapi/qdev.json
View File

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

370
qapi/qom.json
View File

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

1
qapi/rdma.json
View File

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

44
qapi/replay.json
View File

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

12
qapi/rocker.json
View File

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

195
qapi/run-state.json
View File

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

40
qapi/sockets.json
View File

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

77
qapi/stats.json
View File

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

20
qapi/tpm.json
View File

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

28
qapi/trace.json
View File

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

83
qapi/transaction.json
View File

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

365
qapi/ui.json
View File

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

68
qapi/virtio.json
View File

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

36
qapi/yank.json
View File

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