izzy/xemu
0
0
Fork 0
mirror of https://github.com/izzy2lost/xemu.git synced 2026-03-26 18:22:55 -07:00
Code Issues Packages Projects Releases Wiki 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
Download Patch File Download Diff File Expand all files Collapse all files

50
qapi/acpi.json
View File

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

93
qapi/audio.json
View File

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

29
qapi/authz.json
View File

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

2801
qapi/block-core.json
View File

File diff suppressed because it is too large Load Diff

242
qapi/block-export.json
View File

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

214
qapi/block.json
View File

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

134
qapi/char.json
View File

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

19
qapi/common.json
View File

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

13
qapi/compat.json
View File

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

59
qapi/control.json
View File

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

261
qapi/crypto.json
View File

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

3
qapi/cryptodev.json
View File

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

74
qapi/cxl.json
View File

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

78
qapi/dump.json
View File

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

6
qapi/error.json
View File

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

89
qapi/introspect.json
View File

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

139
qapi/job.json
View File

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

303
qapi/machine-target.json
View File

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

389
qapi/machine.json
View File

File diff suppressed because it is too large Load Diff

1117
qapi/migration.json
View File

File diff suppressed because it is too large Load Diff

Some files were not shown because too many files have changed in this diff Show More