diff options
Diffstat (limited to 'qapi')
55 files changed, 13042 insertions, 6295 deletions
diff --git a/qapi/acpi.json b/qapi/acpi.json index 51f0d55db7..aa4dbe5794 100644 --- a/qapi/acpi.json +++ b/qapi/acpi.json @@ -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 # @@ -111,13 +113,12 @@ # # Example: # -# -> { "execute": "query-acpi-ospm-status" } -# <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0}, -# { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0}, -# { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0}, -# { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0} -# ]} -# +# -> { "execute": "query-acpi-ospm-status" } +# <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0}, +# { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0}, +# { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0}, +# { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0} +# ]} ## { 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] } @@ -132,10 +133,10 @@ # # Example: # -# <- { "event": "ACPI_DEVICE_OST", -# "data": { "device": "d1", "slot": "0", -# "slot-type": "DIMM", "source": 1, "status": 0 } } -# +# <- { "event": "ACPI_DEVICE_OST", +# "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' } } diff --git a/qapi/audio.json b/qapi/audio.json index 9cba0df8a4..519697c0cd 100644 --- a/qapi/audio.json +++ b/qapi/audio.json @@ -1,4 +1,5 @@ # -*- mode: python -*- +# vim: filetype=python # # Copyright (C) 2015-2019 Zoltán Kővágó <DirtY.iCE.hu@gmail.com> # @@ -15,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 # @@ -75,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 ## @@ -106,10 +107,32 @@ '*threshold': 'uint32' } } ## +# @AudiodevSndioOptions: +# +# Options of the sndio audio backend. +# +# @in: options of the capture stream +# +# @out: options of the playback stream +# +# @dev: the name of the sndio device to use (default 'default') +# +# @latency: play buffer size (in microseconds) +# +# Since: 7.2 +## +{ 'struct': 'AudiodevSndioOptions', + 'data': { + '*in': 'AudiodevPerDirectionOptions', + '*out': 'AudiodevPerDirectionOptions', + '*dev': 'str', + '*latency': 'uint32'} } + +## # @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 # @@ -145,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 ## @@ -162,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 ## @@ -216,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 ## @@ -237,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 ## @@ -260,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 ## @@ -302,6 +326,47 @@ '*server': 'str' } } ## +# @AudiodevPipewirePerDirectionOptions: +# +# Options of the PipeWire backend that are used for both playback and +# recording. +# +# @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) +# +# @latency: latency you want PipeWire to achieve in microseconds +# (default 46000) +# +# Since: 8.1 +## +{ 'struct': 'AudiodevPipewirePerDirectionOptions', + 'base': 'AudiodevPerDirectionOptions', + 'data': { + '*name': 'str', + '*stream-name': 'str', + '*latency': 'uint32' } } + +## +# @AudiodevPipewireOptions: +# +# Options of the PipeWire audio backend. +# +# @in: options of the capture stream +# +# @out: options of the playback stream +# +# Since: 8.1 +## +{ 'struct': 'AudiodevPipewireOptions', + 'data': { + '*in': 'AudiodevPipewirePerDirectionOptions', + '*out': 'AudiodevPipewirePerDirectionOptions' } } + +## # @AudiodevSdlPerDirectionOptions: # # Options of the SDL audio backend that are used for both playback and @@ -351,7 +416,6 @@ '*out': 'AudiodevPerDirectionOptions', '*path': 'str' } } - ## # @AudioFormat: # @@ -386,8 +450,19 @@ # Since: 4.0 ## { 'enum': 'AudiodevDriver', - 'data': [ 'none', 'alsa', 'coreaudio', 'dsound', 'jack', 'oss', 'pa', - 'sdl', 'spice', 'wav' ] } + 'data': [ 'none', + { 'name': 'alsa', 'if': 'CONFIG_AUDIO_ALSA' }, + { 'name': 'coreaudio', 'if': 'CONFIG_AUDIO_COREAUDIO' }, + { 'name': 'dbus', 'if': 'CONFIG_DBUS_DISPLAY' }, + { 'name': 'dsound', 'if': 'CONFIG_AUDIO_DSOUND' }, + { 'name': 'jack', 'if': 'CONFIG_AUDIO_JACK' }, + { 'name': 'oss', 'if': 'CONFIG_AUDIO_OSS' }, + { 'name': 'pa', 'if': 'CONFIG_AUDIO_PA' }, + { 'name': 'pipewire', 'if': 'CONFIG_AUDIO_PIPEWIRE' }, + { 'name': 'sdl', 'if': 'CONFIG_AUDIO_SDL' }, + { 'name': 'sndio', 'if': 'CONFIG_AUDIO_SNDIO' }, + { 'name': 'spice', 'if': 'CONFIG_SPICE' }, + 'wav' ] } ## # @Audiodev: @@ -398,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 ## @@ -410,12 +486,38 @@ 'discriminator': 'driver', 'data': { 'none': 'AudiodevGenericOptions', - 'alsa': 'AudiodevAlsaOptions', - 'coreaudio': 'AudiodevCoreaudioOptions', - 'dsound': 'AudiodevDsoundOptions', - 'jack': 'AudiodevJackOptions', - 'oss': 'AudiodevOssOptions', - 'pa': 'AudiodevPaOptions', - 'sdl': 'AudiodevSdlOptions', - 'spice': 'AudiodevGenericOptions', + 'alsa': { 'type': 'AudiodevAlsaOptions', + 'if': 'CONFIG_AUDIO_ALSA' }, + 'coreaudio': { 'type': 'AudiodevCoreaudioOptions', + 'if': 'CONFIG_AUDIO_COREAUDIO' }, + 'dbus': { 'type': 'AudiodevGenericOptions', + 'if': 'CONFIG_DBUS_DISPLAY' }, + 'dsound': { 'type': 'AudiodevDsoundOptions', + 'if': 'CONFIG_AUDIO_DSOUND' }, + 'jack': { 'type': 'AudiodevJackOptions', + 'if': 'CONFIG_AUDIO_JACK' }, + 'oss': { 'type': 'AudiodevOssOptions', + 'if': 'CONFIG_AUDIO_OSS' }, + 'pa': { 'type': 'AudiodevPaOptions', + 'if': 'CONFIG_AUDIO_PA' }, + 'pipewire': { 'type': 'AudiodevPipewireOptions', + 'if': 'CONFIG_AUDIO_PIPEWIRE' }, + 'sdl': { 'type': 'AudiodevSdlOptions', + 'if': 'CONFIG_AUDIO_SDL' }, + 'sndio': { 'type': 'AudiodevSndioOptions', + 'if': 'CONFIG_AUDIO_SNDIO' }, + 'spice': { 'type': 'AudiodevGenericOptions', + 'if': 'CONFIG_SPICE' }, 'wav': 'AudiodevWavOptions' } } + +## +# @query-audiodevs: +# +# Returns information about audiodev configuration +# +# Returns: array of @Audiodev +# +# Since: 8.0 +## +{ 'command': 'query-audiodevs', + 'returns': ['Audiodev'] } diff --git a/qapi/authz.json b/qapi/authz.json index 51845e37cc..7fc6e3032e 100644 --- a/qapi/authz.json +++ b/qapi/authz.json @@ -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 ## diff --git a/qapi/block-core.json b/qapi/block-core.json index 6d227924d0..746d1694c2 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -25,15 +25,16 @@ # # @vm-clock-sec: VM clock relative to boot in seconds # -# @vm-clock-nsec: fractional part in nano seconds to be used with vm-clock-sec +# @vm-clock-nsec: fractional part in nano seconds to be used with +# vm-clock-sec # -# @icount: Current instruction count. Appears when execution record/replay -# is enabled. Used for "time-traveling" to match the moment -# in the recorded execution with the snapshots. This counter may -# be obtained through @query-replay command (since 5.2) +# @icount: Current instruction count. Appears when execution +# record/replay is enabled. Used for "time-traveling" to match +# the moment in the recorded execution with the snapshots. This +# counter may be obtained through @query-replay command (since +# 5.2) # # Since: 1.3 -# ## { 'struct': 'SnapshotInfo', 'data': { 'id': 'str', 'name': 'str', 'vm-state-size': 'int', @@ -66,25 +67,26 @@ # # @compat: compatibility level # -# @data-file: the filename of the external data file that is stored in the -# image and used as a default for opening the image (since: 4.0) +# @data-file: the filename of the external data file that is stored in +# the image and used as a default for opening the image +# (since: 4.0) # # @data-file-raw: True if the external data file must stay valid as a -# standalone (read-only) raw image without looking at qcow2 -# metadata (since: 4.0) +# standalone (read-only) raw image without looking at qcow2 +# metadata (since: 4.0) # -# @extended-l2: true if the image has extended L2 entries; only valid for -# compat >= 1.1 (since 5.2) +# @extended-l2: true if the image has extended L2 entries; only valid +# for compat >= 1.1 (since 5.2) # # @lazy-refcounts: on or off; only valid for compat >= 1.1 # # @corrupt: true if the image has been marked corrupt; only valid for -# compat >= 1.1 (since 2.2) +# compat >= 1.1 (since 2.2) # # @refcount-bits: width of a refcount entry in bits (since 2.3) # -# @encrypt: details about encryption parameters; only set if image -# is encrypted (since 2.10) +# @encrypt: details about encryption parameters; only set if image is +# encrypted (since 2.10) # # @bitmaps: A list of qcow2 bitmap details (since 4.0) # @@ -124,28 +126,149 @@ 'create-type': 'str', 'cid': 'int', 'parent-cid': 'int', - 'extents': ['ImageInfo'] + 'extents': ['VmdkExtentInfo'] + } } + +## +# @VmdkExtentInfo: +# +# Information about a VMDK extent file +# +# @filename: Name of the extent file +# +# @format: Extent type (e.g. FLAT or SPARSE) +# +# @virtual-size: Number of bytes covered by this extent +# +# @cluster-size: Cluster size in bytes (for non-flat extents) +# +# @compressed: Whether this extent contains compressed data +# +# Since: 8.0 +## +{ 'struct': 'VmdkExtentInfo', + 'data': { + 'filename': 'str', + 'format': 'str', + 'virtual-size': 'int', + '*cluster-size': 'int', + '*compressed': 'bool' + } } + +## +# @ImageInfoSpecificRbd: +# +# @encryption-format: Image encryption format +# +# Since: 6.1 +## +{ 'struct': 'ImageInfoSpecificRbd', + 'data': { + '*encryption-format': 'RbdImageEncryptionFormat' + } } + +## +# @ImageInfoSpecificFile: +# +# @extent-size-hint: Extent size hint (if available) +# +# Since: 8.0 +## +{ 'struct': 'ImageInfoSpecificFile', + 'data': { + '*extent-size-hint': 'size' } } ## +# @ImageInfoSpecificKind: +# +# @luks: Since 2.7 +# +# @rbd: Since 6.1 +# +# @file: Since 8.0 +# +# Since: 1.7 +## +{ 'enum': 'ImageInfoSpecificKind', + 'data': [ 'qcow2', 'vmdk', 'luks', 'rbd', 'file' ] } + +## +# @ImageInfoSpecificQCow2Wrapper: +# +# @data: image information specific to QCOW2 +# +# Since: 1.7 +## +{ 'struct': 'ImageInfoSpecificQCow2Wrapper', + 'data': { 'data': 'ImageInfoSpecificQCow2' } } + +## +# @ImageInfoSpecificVmdkWrapper: +# +# @data: image information specific to VMDK +# +# Since: 6.1 +## +{ 'struct': 'ImageInfoSpecificVmdkWrapper', + 'data': { 'data': 'ImageInfoSpecificVmdk' } } + +## +# @ImageInfoSpecificLUKSWrapper: +# +# @data: image information specific to LUKS +# +# Since: 2.7 +## +{ 'struct': 'ImageInfoSpecificLUKSWrapper', + 'data': { 'data': 'QCryptoBlockInfoLUKS' } } +# If we need to add block driver specific parameters for +# LUKS in future, then we'll subclass QCryptoBlockInfoLUKS +# to define a ImageInfoSpecificLUKS + +## +# @ImageInfoSpecificRbdWrapper: +# +# @data: image information specific to RBD +# +# Since: 6.1 +## +{ 'struct': 'ImageInfoSpecificRbdWrapper', + 'data': { 'data': 'ImageInfoSpecificRbd' } } + +## +# @ImageInfoSpecificFileWrapper: +# +# @data: image information specific to files +# +# Since: 8.0 +## +{ 'struct': 'ImageInfoSpecificFileWrapper', + 'data': { 'data': 'ImageInfoSpecificFile' } } + +## # @ImageInfoSpecific: # -# A discriminated record of image format specific information structures. +# A discriminated record of image format specific information +# structures. +# +# @type: block driver name # # Since: 1.7 ## { 'union': 'ImageInfoSpecific', + 'base': { 'type': 'ImageInfoSpecificKind' }, + 'discriminator': 'type', 'data': { - 'qcow2': 'ImageInfoSpecificQCow2', - 'vmdk': 'ImageInfoSpecificVmdk', - # If we need to add block driver specific parameters for - # LUKS in future, then we'll subclass QCryptoBlockInfoLUKS - # to define a ImageInfoSpecificLUKS - 'luks': 'QCryptoBlockInfoLUKS' + 'qcow2': 'ImageInfoSpecificQCow2Wrapper', + 'vmdk': 'ImageInfoSpecificVmdkWrapper', + 'luks': 'ImageInfoSpecificLUKSWrapper', + 'rbd': 'ImageInfoSpecificRbdWrapper', + 'file': 'ImageInfoSpecificFileWrapper' } } ## -# @ImageInfo: +# @BlockNodeInfo: # # Information about a QEMU image file # @@ -173,24 +296,71 @@ # # @snapshots: list of VM snapshots # -# @backing-image: info of the backing image (since 1.6) -# # @format-specific: structure supplying additional format-specific -# information (since 1.7) -# -# Since: 1.3 +# information (since 1.7) # +# Since: 8.0 ## -{ 'struct': 'ImageInfo', +{ 'struct': 'BlockNodeInfo', 'data': {'filename': 'str', 'format': 'str', '*dirty-flag': 'bool', '*actual-size': 'int', 'virtual-size': 'int', '*cluster-size': 'int', '*encrypted': 'bool', '*compressed': 'bool', '*backing-filename': 'str', '*full-backing-filename': 'str', '*backing-filename-format': 'str', '*snapshots': ['SnapshotInfo'], - '*backing-image': 'ImageInfo', '*format-specific': 'ImageInfoSpecific' } } ## +# @ImageInfo: +# +# Information about a QEMU image file, and potentially its backing +# image +# +# @backing-image: info of the backing image +# +# Since: 1.3 +## +{ 'struct': 'ImageInfo', + 'base': 'BlockNodeInfo', + 'data': { + '*backing-image': 'ImageInfo' + } } + +## +# @BlockChildInfo: +# +# Information about all nodes in the block graph starting at some +# node, annotated with information about that node in relation to its +# parent. +# +# @name: Child name of the root node in the BlockGraphInfo struct, in +# its role as the child of some undescribed parent node +# +# @info: Block graph information starting at this node +# +# Since: 8.0 +## +{ 'struct': 'BlockChildInfo', + 'data': { + 'name': 'str', + 'info': 'BlockGraphInfo' + } } + +## +# @BlockGraphInfo: +# +# Information about all nodes in a block (sub)graph in the form of +# BlockNodeInfo data. The base BlockNodeInfo struct contains the +# information for the (sub)graph's root node. +# +# @children: Array of links to this node's child nodes' information +# +# Since: 8.0 +## +{ 'struct': 'BlockGraphInfo', + 'base': 'BlockNodeInfo', + 'data': { 'children': ['BlockChildInfo'] } } + +## # @ImageCheck: # # Information about a QEMU image file check @@ -202,35 +372,30 @@ # @check-errors: number of unexpected errors occurred during check # # @image-end-offset: offset (in bytes) where the image ends, this -# field is present if the driver for the image format -# supports it +# field is present if the driver for the image format supports it # # @corruptions: number of corruptions found during the check if any # # @leaks: number of leaks found during the check if any # -# @corruptions-fixed: number of corruptions fixed during the check -# if any +# @corruptions-fixed: number of corruptions fixed during the check if +# any # # @leaks-fixed: number of leaks fixed during the check if any # -# @total-clusters: total number of clusters, this field is present -# if the driver for the image format supports it +# @total-clusters: total number of clusters, this field is present if +# the driver for the image format supports it # -# @allocated-clusters: total number of allocated clusters, this -# field is present if the driver for the image format -# supports it +# @allocated-clusters: total number of allocated clusters, this field +# is present if the driver for the image format supports it # # @fragmented-clusters: total number of fragmented clusters, this -# field is present if the driver for the image format -# supports it +# field is present if the driver for the image format supports it # # @compressed-clusters: total number of compressed clusters, this -# field is present if the driver for the image format -# supports it +# field is present if the driver for the image format supports it # # Since: 1.4 -# ## { 'struct': 'ImageCheck', 'data': {'filename': 'str', 'format': 'str', 'check-errors': 'int', @@ -245,43 +410,49 @@ # Mapping information from a virtual block range to a host file range # # @start: virtual (guest) offset of the first byte described by this -# entry +# entry # # @length: the number of bytes of the mapped virtual range # # @data: reading the image will actually read data from a file (in -# particular, if @offset is present this means that the sectors -# are not simply preallocated, but contain actual data in raw -# format) +# particular, if @offset is present this means that the sectors +# are not simply preallocated, but contain actual data in raw +# format) # # @zero: whether the virtual blocks read as zeroes # +# @compressed: true if the data is stored compressed (since 8.2) +# # @depth: number of layers (0 = top image, 1 = top image's backing -# file, ..., n - 1 = bottom image (where n is the number of -# images in the chain)) before reaching one for which the -# range is allocated +# file, ..., n - 1 = bottom image (where n is the number of images +# in the chain)) before reaching one for which the range is +# allocated +# +# @present: true if this layer provides the data, false if adding a +# backing layer could impact this region (since 6.1) # # @offset: if present, the image file stores the data for this range -# in raw format at the given (host) offset +# in raw format at the given (host) offset # # @filename: filename that is referred to by @offset # # Since: 2.6 -# ## { 'struct': 'MapEntry', 'data': {'start': 'int', 'length': 'int', 'data': 'bool', - 'zero': 'bool', 'depth': 'int', '*offset': 'int', - '*filename': 'str' } } + 'zero': 'bool', 'compressed': 'bool', 'depth': 'int', + 'present': 'bool', '*offset': 'int', '*filename': 'str' } } ## # @BlockdevCacheInfo: # # Cache mode information for a block device # -# @writeback: true if writeback mode is enabled -# @direct: true if the host page cache is bypassed (O_DIRECT) -# @no-flush: true if flush requests are ignored for the device +# @writeback: true if writeback mode is enabled +# +# @direct: true if the host page cache is bypassed (O_DIRECT) +# +# @no-flush: true if flush requests are ignored for the device # # Since: 2.3 ## @@ -301,21 +472,19 @@ # # @ro: true if the backing device was open read-only # -# @drv: the name of the block format used to open the backing device. As of -# 0.14 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg', -# 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device', -# 'http', 'https', 'luks', 'nbd', 'parallels', 'qcow', -# 'qcow2', 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' -# 2.2: 'archipelago' added, 'cow' dropped -# 2.3: 'host_floppy' deprecated -# 2.5: 'host_floppy' dropped -# 2.6: 'luks' added -# 2.8: 'replication' added, 'tftp' dropped -# 2.9: 'archipelago' dropped +# @drv: the name of the block format used to open the backing device. +# As of 0.14 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', +# 'dmg', 'file', 'file', 'ftp', 'ftps', 'host_cdrom', +# 'host_device', 'http', 'https', 'luks', 'nbd', 'parallels', +# 'qcow', 'qcow2', 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' 2.2: +# 'archipelago' added, 'cow' dropped 2.3: 'host_floppy' deprecated +# 2.5: 'host_floppy' dropped 2.6: 'luks' added 2.8: 'replication' +# added, 'tftp' dropped 2.9: 'archipelago' dropped # # @backing_file: the name of the backing file (for copy-on-write) # -# @backing_file_depth: number of files in the backing file chain (since: 1.2) +# @backing_file_depth: number of files in the backing file chain +# (since: 1.2) # # @encrypted: true if the backing device is encrypted # @@ -335,41 +504,40 @@ # # @image: the info of image used (since: 1.6) # -# @bps_max: total throughput limit during bursts, -# in bytes (Since 1.7) +# @bps_max: total throughput limit during bursts, in bytes (Since 1.7) # -# @bps_rd_max: read throughput limit during bursts, -# in bytes (Since 1.7) +# @bps_rd_max: read throughput limit during bursts, in bytes (Since +# 1.7) # -# @bps_wr_max: write throughput limit during bursts, -# in bytes (Since 1.7) +# @bps_wr_max: write throughput limit during bursts, in bytes (Since +# 1.7) # -# @iops_max: total I/O operations per second during bursts, -# in bytes (Since 1.7) +# @iops_max: total I/O operations per second during bursts, in bytes +# (Since 1.7) # -# @iops_rd_max: read I/O operations per second during bursts, -# in bytes (Since 1.7) +# @iops_rd_max: read I/O operations per second during bursts, in bytes +# (Since 1.7) # -# @iops_wr_max: write I/O operations per second during bursts, -# in bytes (Since 1.7) +# @iops_wr_max: write I/O operations per second during bursts, in +# bytes (Since 1.7) # -# @bps_max_length: maximum length of the @bps_max burst -# period, in seconds. (Since 2.6) +# @bps_max_length: maximum length of the @bps_max burst period, in +# seconds. (Since 2.6) # -# @bps_rd_max_length: maximum length of the @bps_rd_max -# burst period, in seconds. (Since 2.6) +# @bps_rd_max_length: maximum length of the @bps_rd_max burst period, +# in seconds. (Since 2.6) # -# @bps_wr_max_length: maximum length of the @bps_wr_max -# burst period, in seconds. (Since 2.6) +# @bps_wr_max_length: maximum length of the @bps_wr_max burst period, +# in seconds. (Since 2.6) # -# @iops_max_length: maximum length of the @iops burst -# period, in seconds. (Since 2.6) +# @iops_max_length: maximum length of the @iops burst period, in +# seconds. (Since 2.6) # -# @iops_rd_max_length: maximum length of the @iops_rd_max -# burst period, in seconds. (Since 2.6) +# @iops_rd_max_length: maximum length of the @iops_rd_max burst +# period, in seconds. (Since 2.6) # -# @iops_wr_max_length: maximum length of the @iops_wr_max -# burst period, in seconds. (Since 2.6) +# @iops_wr_max_length: maximum length of the @iops_wr_max burst +# period, in seconds. (Since 2.6) # # @iops_size: an I/O size in bytes (Since 1.7) # @@ -377,14 +545,13 @@ # # @cache: the cache mode used for the block device (since: 2.3) # -# @write_threshold: configured write threshold for the device. -# 0 if disabled. (Since 2.3) +# @write_threshold: configured write threshold for the device. 0 if +# disabled. (Since 2.3) # -# @dirty-bitmaps: dirty bitmaps information (only present if node -# has one or more dirty bitmaps) (Since 4.2) +# @dirty-bitmaps: dirty bitmaps information (only present if node has +# one or more dirty bitmaps) (Since 4.2) # # Since: 0.14 -# ## { 'struct': 'BlockDeviceInfo', 'data': { 'file': 'str', '*node-name': 'str', 'ro': 'bool', 'drv': 'str', @@ -412,7 +579,8 @@ # # @failed: The last I/O operation has failed # -# @nospace: The last I/O operation has failed due to a no-space condition +# @nospace: The last I/O operation has failed due to a no-space +# condition # # Since: 1.0 ## @@ -429,20 +597,20 @@ # # @granularity: granularity of the dirty bitmap in bytes (since 1.4) # -# @recording: true if the bitmap is recording new writes from the guest. -# Replaces `active` and `disabled` statuses. (since 4.0) +# @recording: true if the bitmap is recording new writes from the +# guest. (since 4.0) # # @busy: true if the bitmap is in-use by some operation (NBD or jobs) -# and cannot be modified via QMP or used by another operation. -# Replaces `locked` and `frozen` statuses. (since 4.0) +# and cannot be modified via QMP or used by another operation. +# (since 4.0) # -# @persistent: true if the bitmap was stored on disk, is scheduled to be stored -# on disk, or both. (since 4.0) +# @persistent: true if the bitmap was stored on disk, is scheduled to +# be stored on disk, or both. (since 4.0) # -# @inconsistent: true if this is a persistent bitmap that was improperly -# stored. Implies @persistent to be true; @recording and -# @busy to be false. This bitmap cannot be used. To remove -# it, use @block-dirty-bitmap-remove. (Since 4.0) +# @inconsistent: true if this is a persistent bitmap that was +# improperly stored. Implies @persistent to be true; @recording +# and @busy to be false. This bitmap cannot be used. To remove +# it, use @block-dirty-bitmap-remove. (Since 4.0) # # Since: 1.3 ## @@ -456,14 +624,14 @@ # # An enumeration of flags that a bitmap can report to the user. # -# @in-use: This flag is set by any process actively modifying the qcow2 file, -# and cleared when the updated bitmap is flushed to the qcow2 image. -# The presence of this flag in an offline image means that the bitmap -# was not saved correctly after its last usage, and may contain -# inconsistent data. +# @in-use: This flag is set by any process actively modifying the +# qcow2 file, and cleared when the updated bitmap is flushed to +# the qcow2 image. The presence of this flag in an offline image +# means that the bitmap was not saved correctly after its last +# usage, and may contain inconsistent data. # -# @auto: The bitmap must reflect all changes of the virtual disk by any -# application that would write to this qcow2 file. +# @auto: The bitmap must reflect all changes of the virtual disk by +# any application that would write to this qcow2 file. # # Since: 4.0 ## @@ -492,17 +660,15 @@ # # Block latency histogram. # -# @boundaries: list of interval boundary values in nanoseconds, all greater -# than zero and in ascending order. -# For example, the list [10, 50, 100] produces the following -# histogram intervals: [0, 10), [10, 50), [50, 100), [100, +inf). +# @boundaries: list of interval boundary values in nanoseconds, all +# greater than zero and in ascending order. For example, the list +# [10, 50, 100] produces the following histogram intervals: [0, +# 10), [10, 50), [50, 100), [100, +inf). # -# @bins: list of io request counts corresponding to histogram intervals. -# len(@bins) = len(@boundaries) + 1 -# For the example above, @bins may be something like [3, 1, 5, 2], -# and corresponding histogram looks like: -# -# :: +# @bins: list of io request counts corresponding to histogram +# intervals, one more element than @boundaries has. For the +# example above, @bins may be something like [3, 1, 5, 2], and +# corresponding histogram looks like:: # # 5| * # 4| * @@ -520,34 +686,34 @@ ## # @BlockInfo: # -# Block device information. This structure describes a virtual device and -# the backing device associated with it. +# Block device information. This structure describes a virtual device +# and the backing device associated with it. # # @device: The device name associated with the virtual device. # -# @qdev: The qdev ID, or if no ID is assigned, the QOM path of the block -# device. (since 2.10) +# @qdev: The qdev ID, or if no ID is assigned, the QOM path of the +# block device. (since 2.10) # -# @type: This field is returned only for compatibility reasons, it should -# not be used (always returns 'unknown') +# @type: This field is returned only for compatibility reasons, it +# should not be used (always returns 'unknown') # # @removable: True if the device supports removable media. # -# @locked: True if the guest has locked this device from having its media -# removed +# @locked: True if the guest has locked this device from having its +# media removed # -# @tray_open: True if the device's tray is open -# (only present if it has a tray) +# @tray_open: True if the device's tray is open (only present if it +# has a tray) # -# @io-status: @BlockDeviceIoStatus. Only present if the device -# supports it and the VM is configured to stop on errors -# (supported device models: virtio-blk, IDE, SCSI except -# scsi-generic) +# @io-status: @BlockDeviceIoStatus. Only present if the device +# supports it and the VM is configured to stop on errors +# (supported device models: virtio-blk, IDE, SCSI except +# scsi-generic) # # @inserted: @BlockDeviceInfo describing the device if media is -# present +# present # -# Since: 0.14 +# Since: 0.14 ## { 'struct': 'BlockInfo', 'data': {'device': 'str', '*qdev': 'str', 'type': 'str', 'removable': 'bool', @@ -557,28 +723,31 @@ ## # @BlockMeasureInfo: # -# Image file size calculation information. This structure describes the size -# requirements for creating a new image file. +# Image file size calculation information. This structure describes +# the size requirements for creating a new image file. # -# The size requirements depend on the new image file format. File size always -# equals virtual disk size for the 'raw' format, even for sparse POSIX files. -# Compact formats such as 'qcow2' represent unallocated and zero regions -# efficiently so file size may be smaller than virtual disk size. +# The size requirements depend on the new image file format. File +# size always equals virtual disk size for the 'raw' format, even for +# sparse POSIX files. Compact formats such as 'qcow2' represent +# unallocated and zero regions efficiently so file size may be smaller +# than virtual disk size. # -# The values are upper bounds that are guaranteed to fit the new image file. -# Subsequent modification, such as internal snapshot or further bitmap -# creation, may require additional space and is not covered here. +# The values are upper bounds that are guaranteed to fit the new image +# file. Subsequent modification, such as internal snapshot or further +# bitmap creation, may require additional space and is not covered +# here. # -# @required: Size required for a new image file, in bytes, when copying just -# allocated guest-visible contents. +# @required: Size required for a new image file, in bytes, when +# copying just allocated guest-visible contents. # -# @fully-allocated: Image file size, in bytes, once data has been written -# to all sectors, when copying just guest-visible contents. +# @fully-allocated: Image file size, in bytes, once data has been +# written to all sectors, when copying just guest-visible +# contents. # -# @bitmaps: Additional size required if all the top-level bitmap metadata -# in the source image were to be copied to the destination, -# present only when source and destination both support -# persistent bitmaps. (since 5.1) +# @bitmaps: Additional size required if all the top-level bitmap +# metadata in the source image were to be copied to the +# destination, present only when source and destination both +# support persistent bitmaps. (since 5.1) # # Since: 2.10 ## @@ -590,139 +759,150 @@ # # Get a list of BlockInfo for all virtual block devices. # -# Returns: a list of @BlockInfo describing each virtual block device. Filter -# nodes that were created implicitly are skipped over. +# Returns: a list of @BlockInfo describing each virtual block device. +# Filter nodes that were created implicitly are skipped over. # # Since: 0.14 # # Example: # -# -> { "execute": "query-block" } -# <- { -# "return":[ -# { -# "io-status": "ok", -# "device":"ide0-hd0", -# "locked":false, -# "removable":false, -# "inserted":{ -# "ro":false, -# "drv":"qcow2", -# "encrypted":false, -# "file":"disks/test.qcow2", -# "backing_file_depth":1, -# "bps":1000000, -# "bps_rd":0, -# "bps_wr":0, -# "iops":1000000, -# "iops_rd":0, -# "iops_wr":0, -# "bps_max": 8000000, -# "bps_rd_max": 0, -# "bps_wr_max": 0, -# "iops_max": 0, -# "iops_rd_max": 0, -# "iops_wr_max": 0, -# "iops_size": 0, -# "detect_zeroes": "on", -# "write_threshold": 0, -# "image":{ -# "filename":"disks/test.qcow2", -# "format":"qcow2", -# "virtual-size":2048000, -# "backing_file":"base.qcow2", -# "full-backing-filename":"disks/base.qcow2", -# "backing-filename-format":"qcow2", -# "snapshots":[ -# { -# "id": "1", -# "name": "snapshot1", -# "vm-state-size": 0, -# "date-sec": 10000200, -# "date-nsec": 12, -# "vm-clock-sec": 206, -# "vm-clock-nsec": 30 -# } -# ], -# "backing-image":{ -# "filename":"disks/base.qcow2", +# -> { "execute": "query-block" } +# <- { +# "return":[ +# { +# "io-status": "ok", +# "device":"ide0-hd0", +# "locked":false, +# "removable":false, +# "inserted":{ +# "ro":false, +# "drv":"qcow2", +# "encrypted":false, +# "file":"disks/test.qcow2", +# "backing_file_depth":1, +# "bps":1000000, +# "bps_rd":0, +# "bps_wr":0, +# "iops":1000000, +# "iops_rd":0, +# "iops_wr":0, +# "bps_max": 8000000, +# "bps_rd_max": 0, +# "bps_wr_max": 0, +# "iops_max": 0, +# "iops_rd_max": 0, +# "iops_wr_max": 0, +# "iops_size": 0, +# "detect_zeroes": "on", +# "write_threshold": 0, +# "image":{ +# "filename":"disks/test.qcow2", # "format":"qcow2", -# "virtual-size":2048000 -# } -# } -# }, -# "qdev": "ide_disk", -# "type":"unknown" -# }, -# { -# "io-status": "ok", -# "device":"ide1-cd0", -# "locked":false, -# "removable":true, -# "qdev": "/machine/unattached/device[23]", -# "tray_open": false, -# "type":"unknown" -# }, -# { -# "device":"floppy0", -# "locked":false, -# "removable":true, -# "qdev": "/machine/unattached/device[20]", -# "type":"unknown" -# }, -# { -# "device":"sd0", -# "locked":false, -# "removable":true, -# "type":"unknown" -# } -# ] -# } -# +# "virtual-size":2048000, +# "backing_file":"base.qcow2", +# "full-backing-filename":"disks/base.qcow2", +# "backing-filename-format":"qcow2", +# "snapshots":[ +# { +# "id": "1", +# "name": "snapshot1", +# "vm-state-size": 0, +# "date-sec": 10000200, +# "date-nsec": 12, +# "vm-clock-sec": 206, +# "vm-clock-nsec": 30 +# } +# ], +# "backing-image":{ +# "filename":"disks/base.qcow2", +# "format":"qcow2", +# "virtual-size":2048000 +# } +# } +# }, +# "qdev": "ide_disk", +# "type":"unknown" +# }, +# { +# "io-status": "ok", +# "device":"ide1-cd0", +# "locked":false, +# "removable":true, +# "qdev": "/machine/unattached/device[23]", +# "tray_open": false, +# "type":"unknown" +# }, +# { +# "device":"floppy0", +# "locked":false, +# "removable":true, +# "qdev": "/machine/unattached/device[20]", +# "type":"unknown" +# }, +# { +# "device":"sd0", +# "locked":false, +# "removable":true, +# "type":"unknown" +# } +# ] +# } ## -{ 'command': 'query-block', 'returns': ['BlockInfo'] } - +{ 'command': 'query-block', 'returns': ['BlockInfo'], + 'allow-preconfig': true } ## # @BlockDeviceTimedStats: # # Statistics of a block device during a given interval of time. # -# @interval_length: Interval used for calculating the statistics, -# in seconds. +# @interval_length: Interval used for calculating the statistics, in +# seconds. # # @min_rd_latency_ns: Minimum latency of read operations in the -# defined interval, in nanoseconds. +# defined interval, in nanoseconds. # # @min_wr_latency_ns: Minimum latency of write operations in the -# defined interval, in nanoseconds. +# defined interval, in nanoseconds. +# +# @min_zone_append_latency_ns: Minimum latency of zone append +# operations in the defined interval, in nanoseconds (since 8.1) # # @min_flush_latency_ns: Minimum latency of flush operations in the -# defined interval, in nanoseconds. +# defined interval, in nanoseconds. # # @max_rd_latency_ns: Maximum latency of read operations in the -# defined interval, in nanoseconds. +# defined interval, in nanoseconds. # # @max_wr_latency_ns: Maximum latency of write operations in the -# defined interval, in nanoseconds. +# defined interval, in nanoseconds. +# +# @max_zone_append_latency_ns: Maximum latency of zone append +# operations in the defined interval, in nanoseconds (since 8.1) # # @max_flush_latency_ns: Maximum latency of flush operations in the -# defined interval, in nanoseconds. +# defined interval, in nanoseconds. # # @avg_rd_latency_ns: Average latency of read operations in the -# defined interval, in nanoseconds. +# defined interval, in nanoseconds. # # @avg_wr_latency_ns: Average latency of write operations in the -# defined interval, in nanoseconds. +# defined interval, in nanoseconds. +# +# @avg_zone_append_latency_ns: Average latency of zone append +# operations in the defined interval, in nanoseconds (since 8.1) # # @avg_flush_latency_ns: Average latency of flush operations in the -# defined interval, in nanoseconds. +# defined interval, in nanoseconds. +# +# @avg_rd_queue_depth: Average number of pending read operations in +# the defined interval. # -# @avg_rd_queue_depth: Average number of pending read operations -# in the defined interval. +# @avg_wr_queue_depth: Average number of pending write operations in +# the defined interval. # -# @avg_wr_queue_depth: Average number of pending write operations -# in the defined interval. +# @avg_zone_append_queue_depth: Average number of pending zone append +# operations in the defined interval (since 8.1). # # Since: 2.5 ## @@ -730,117 +910,151 @@ 'data': { 'interval_length': 'int', 'min_rd_latency_ns': 'int', 'max_rd_latency_ns': 'int', 'avg_rd_latency_ns': 'int', 'min_wr_latency_ns': 'int', 'max_wr_latency_ns': 'int', - 'avg_wr_latency_ns': 'int', 'min_flush_latency_ns': 'int', - 'max_flush_latency_ns': 'int', 'avg_flush_latency_ns': 'int', - 'avg_rd_queue_depth': 'number', 'avg_wr_queue_depth': 'number' } } + 'avg_wr_latency_ns': 'int', 'min_zone_append_latency_ns': 'int', + 'max_zone_append_latency_ns': 'int', + 'avg_zone_append_latency_ns': 'int', + 'min_flush_latency_ns': 'int', 'max_flush_latency_ns': 'int', + 'avg_flush_latency_ns': 'int', 'avg_rd_queue_depth': 'number', + 'avg_wr_queue_depth': 'number', + 'avg_zone_append_queue_depth': 'number' } } ## # @BlockDeviceStats: # # Statistics of a virtual block device or a block backing device. # -# @rd_bytes: The number of bytes read by the device. +# @rd_bytes: The number of bytes read by the device. +# +# @wr_bytes: The number of bytes written by the device. # -# @wr_bytes: The number of bytes written by the device. +# @zone_append_bytes: The number of bytes appended by the zoned +# devices (since 8.1) # # @unmap_bytes: The number of bytes unmapped by the device (Since 4.2) # -# @rd_operations: The number of read operations performed by the device. +# @rd_operations: The number of read operations performed by the +# device. +# +# @wr_operations: The number of write operations performed by the +# device. +# +# @zone_append_operations: The number of zone append operations +# performed by the zoned devices (since 8.1) # -# @wr_operations: The number of write operations performed by the device. +# @flush_operations: The number of cache flush operations performed by +# the device (since 0.15) # -# @flush_operations: The number of cache flush operations performed by the -# device (since 0.15) +# @unmap_operations: The number of unmap operations performed by the +# device (Since 4.2) # -# @unmap_operations: The number of unmap operations performed by the device -# (Since 4.2) +# @rd_total_time_ns: Total time spent on reads in nanoseconds (since +# 0.15). # -# @rd_total_time_ns: Total time spent on reads in nanoseconds (since 0.15). +# @wr_total_time_ns: Total time spent on writes in nanoseconds (since +# 0.15). # -# @wr_total_time_ns: Total time spent on writes in nanoseconds (since 0.15). +# @zone_append_total_time_ns: Total time spent on zone append writes +# in nanoseconds (since 8.1) # -# @flush_total_time_ns: Total time spent on cache flushes in nanoseconds -# (since 0.15). +# @flush_total_time_ns: Total time spent on cache flushes in +# nanoseconds (since 0.15). # -# @unmap_total_time_ns: Total time spent on unmap operations in nanoseconds -# (Since 4.2) +# @unmap_total_time_ns: Total time spent on unmap operations in +# nanoseconds (Since 4.2) # -# @wr_highest_offset: The offset after the greatest byte written to the -# device. The intended use of this information is for -# growable sparse files (like qcow2) that are used on top -# of a physical device. +# @wr_highest_offset: The offset after the greatest byte written to +# the device. The intended use of this information is for +# growable sparse files (like qcow2) that are used on top of a +# physical device. # -# @rd_merged: Number of read requests that have been merged into another -# request (Since 2.3). +# @rd_merged: Number of read requests that have been merged into +# another request (Since 2.3). # -# @wr_merged: Number of write requests that have been merged into another -# request (Since 2.3). +# @wr_merged: Number of write requests that have been merged into +# another request (Since 2.3). # -# @unmap_merged: Number of unmap requests that have been merged into another -# request (Since 4.2) +# @zone_append_merged: Number of zone append requests that have been +# merged into another request (since 8.1) # -# @idle_time_ns: Time since the last I/O operation, in -# nanoseconds. If the field is absent it means that -# there haven't been any operations yet (Since 2.5). +# @unmap_merged: Number of unmap requests that have been merged into +# another request (Since 4.2) +# +# @idle_time_ns: Time since the last I/O operation, in nanoseconds. +# If the field is absent it means that there haven't been any +# operations yet (Since 2.5). # # @failed_rd_operations: The number of failed read operations -# performed by the device (Since 2.5) +# performed by the device (Since 2.5) # # @failed_wr_operations: The number of failed write operations -# performed by the device (Since 2.5) +# performed by the device (Since 2.5) +# +# @failed_zone_append_operations: The number of failed zone append +# write operations performed by the zoned devices (since 8.1) # # @failed_flush_operations: The number of failed flush operations -# performed by the device (Since 2.5) +# performed by the device (Since 2.5) # -# @failed_unmap_operations: The number of failed unmap operations performed -# by the device (Since 4.2) +# @failed_unmap_operations: The number of failed unmap operations +# performed by the device (Since 4.2) # # @invalid_rd_operations: The number of invalid read operations -# performed by the device (Since 2.5) +# performed by the device (Since 2.5) # # @invalid_wr_operations: The number of invalid write operations -# performed by the device (Since 2.5) +# performed by the device (Since 2.5) +# +# @invalid_zone_append_operations: The number of invalid zone append +# operations performed by the zoned device (since 8.1) # # @invalid_flush_operations: The number of invalid flush operations -# performed by the device (Since 2.5) +# performed by the device (Since 2.5) # -# @invalid_unmap_operations: The number of invalid unmap operations performed -# by the device (Since 4.2) +# @invalid_unmap_operations: The number of invalid unmap operations +# performed by the device (Since 4.2) # # @account_invalid: Whether invalid operations are included in the -# last access statistics (Since 2.5) +# last access statistics (Since 2.5) # # @account_failed: Whether failed operations are included in the -# latency and last access statistics (Since 2.5) +# latency and last access statistics (Since 2.5) # # @timed_stats: Statistics specific to the set of previously defined -# intervals of time (Since 2.5) +# intervals of time (Since 2.5) # -# @rd_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0) +# @rd_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0) # -# @wr_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0) +# @wr_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0) # -# @flush_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0) +# @zone_append_latency_histogram: @BlockLatencyHistogramInfo. +# (since 8.1) +# +# @flush_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0) # # Since: 0.14 ## { 'struct': 'BlockDeviceStats', - 'data': {'rd_bytes': 'int', 'wr_bytes': 'int', 'unmap_bytes' : 'int', - 'rd_operations': 'int', 'wr_operations': 'int', + 'data': {'rd_bytes': 'int', 'wr_bytes': 'int', 'zone_append_bytes': 'int', + 'unmap_bytes' : 'int', 'rd_operations': 'int', + 'wr_operations': 'int', 'zone_append_operations': 'int', 'flush_operations': 'int', 'unmap_operations': 'int', 'rd_total_time_ns': 'int', 'wr_total_time_ns': 'int', - 'flush_total_time_ns': 'int', 'unmap_total_time_ns': 'int', - 'wr_highest_offset': 'int', - 'rd_merged': 'int', 'wr_merged': 'int', 'unmap_merged': 'int', - '*idle_time_ns': 'int', + 'zone_append_total_time_ns': 'int', 'flush_total_time_ns': 'int', + 'unmap_total_time_ns': 'int', 'wr_highest_offset': 'int', + 'rd_merged': 'int', 'wr_merged': 'int', 'zone_append_merged': 'int', + 'unmap_merged': 'int', '*idle_time_ns': 'int', 'failed_rd_operations': 'int', 'failed_wr_operations': 'int', - 'failed_flush_operations': 'int', 'failed_unmap_operations': 'int', - 'invalid_rd_operations': 'int', 'invalid_wr_operations': 'int', + 'failed_zone_append_operations': 'int', + 'failed_flush_operations': 'int', + 'failed_unmap_operations': 'int', 'invalid_rd_operations': 'int', + 'invalid_wr_operations': 'int', + 'invalid_zone_append_operations': 'int', 'invalid_flush_operations': 'int', 'invalid_unmap_operations': 'int', 'account_invalid': 'bool', 'account_failed': 'bool', 'timed_stats': ['BlockDeviceTimedStats'], '*rd_latency_histogram': 'BlockLatencyHistogramInfo', '*wr_latency_histogram': 'BlockLatencyHistogramInfo', + '*zone_append_latency_histogram': 'BlockLatencyHistogramInfo', '*flush_latency_histogram': 'BlockLatencyHistogramInfo' } } ## @@ -848,11 +1062,11 @@ # # File driver statistics # -# @discard-nb-ok: The number of successful discard operations performed by -# the driver. +# @discard-nb-ok: The number of successful discard operations +# performed by the driver. # -# @discard-nb-failed: The number of failed discard operations performed by -# the driver. +# @discard-nb-failed: The number of failed discard operations +# performed by the driver. # # @discard-bytes-ok: The number of bytes discarded by the driver. # @@ -871,11 +1085,11 @@ # # @completion-errors: The number of completion errors. # -# @aligned-accesses: The number of aligned accesses performed by -# the driver. +# @aligned-accesses: The number of aligned accesses performed by the +# driver. # # @unaligned-accesses: The number of unaligned accesses performed by -# the driver. +# the driver. # # Since: 5.2 ## @@ -890,6 +1104,8 @@ # # Block driver specific statistics # +# @driver: block driver name +# # Since: 4.2 ## { 'union': 'BlockStatsSpecific', @@ -897,7 +1113,8 @@ 'discriminator': 'driver', 'data': { 'file': 'BlockStatsSpecificFile', - 'host_device': 'BlockStatsSpecificFile', + 'host_device': { 'type': 'BlockStatsSpecificFile', + 'if': 'HAVE_HOST_BLOCK_DEVICE' }, 'nvme': 'BlockStatsSpecificNvme' } } ## @@ -906,24 +1123,24 @@ # Statistics of a virtual block device or a block backing device. # # @device: If the stats are for a virtual block device, the name -# corresponding to the virtual block device. +# corresponding to the virtual block device. # -# @node-name: The node name of the device. (Since 2.3) +# @node-name: The node name of the device. (Since 2.3) # -# @qdev: The qdev ID, or if no ID is assigned, the QOM path of the block -# device. (since 3.0) +# @qdev: The qdev ID, or if no ID is assigned, the QOM path of the +# block device. (since 3.0) # -# @stats: A @BlockDeviceStats for the device. +# @stats: A @BlockDeviceStats for the device. # -# @driver-specific: Optional driver-specific stats. (Since 4.2) +# @driver-specific: Optional driver-specific stats. (Since 4.2) # # @parent: This describes the file block device if it has one. -# Contains recursively the statistics of the underlying -# protocol (e.g. the host file for a qcow2 image). If there is -# no underlying protocol, this field is omitted +# Contains recursively the statistics of the underlying protocol +# (e.g. the host file for a qcow2 image). If there is no +# underlying protocol, this field is omitted # # @backing: This describes the backing block device if it has one. -# (Since 2.0) +# (Since 2.0) # # Since: 0.14 ## @@ -940,12 +1157,12 @@ # Query the @BlockStats for all virtual block devices. # # @query-nodes: If true, the command will query all the block nodes -# that have a node name, in a list which will include "parent" -# information, but not "backing". -# If false or omitted, the behavior is as before - query all the -# device backends, recursively including their "parent" and -# "backing". Filter nodes that were created implicitly are -# skipped over in this mode. (Since 2.3) +# that have a node name, in a list which will include "parent" +# information, but not "backing". If false or omitted, the +# behavior is as before - query all the device backends, +# recursively including their "parent" and "backing". Filter nodes +# that were created implicitly are skipped over in this mode. +# (Since 2.3) # # Returns: A list of @BlockStats for each virtual block devices. # @@ -953,131 +1170,131 @@ # # Example: # -# -> { "execute": "query-blockstats" } -# <- { -# "return":[ -# { -# "device":"ide0-hd0", -# "parent":{ -# "stats":{ -# "wr_highest_offset":3686448128, -# "wr_bytes":9786368, -# "wr_operations":751, -# "rd_bytes":122567168, -# "rd_operations":36772 -# "wr_total_times_ns":313253456 -# "rd_total_times_ns":3465673657 -# "flush_total_times_ns":49653 -# "flush_operations":61, -# "rd_merged":0, -# "wr_merged":0, -# "idle_time_ns":2953431879, -# "account_invalid":true, -# "account_failed":false -# } -# }, -# "stats":{ -# "wr_highest_offset":2821110784, -# "wr_bytes":9786368, -# "wr_operations":692, -# "rd_bytes":122739200, -# "rd_operations":36604 -# "flush_operations":51, -# "wr_total_times_ns":313253456 -# "rd_total_times_ns":3465673657 -# "flush_total_times_ns":49653, -# "rd_merged":0, -# "wr_merged":0, -# "idle_time_ns":2953431879, -# "account_invalid":true, -# "account_failed":false -# }, -# "qdev": "/machine/unattached/device[23]" -# }, -# { -# "device":"ide1-cd0", -# "stats":{ -# "wr_highest_offset":0, -# "wr_bytes":0, -# "wr_operations":0, -# "rd_bytes":0, -# "rd_operations":0 -# "flush_operations":0, -# "wr_total_times_ns":0 -# "rd_total_times_ns":0 -# "flush_total_times_ns":0, -# "rd_merged":0, -# "wr_merged":0, -# "account_invalid":false, -# "account_failed":false -# }, -# "qdev": "/machine/unattached/device[24]" -# }, -# { -# "device":"floppy0", -# "stats":{ -# "wr_highest_offset":0, -# "wr_bytes":0, -# "wr_operations":0, -# "rd_bytes":0, -# "rd_operations":0 -# "flush_operations":0, -# "wr_total_times_ns":0 -# "rd_total_times_ns":0 -# "flush_total_times_ns":0, -# "rd_merged":0, -# "wr_merged":0, -# "account_invalid":false, -# "account_failed":false -# }, -# "qdev": "/machine/unattached/device[16]" -# }, -# { -# "device":"sd0", -# "stats":{ -# "wr_highest_offset":0, -# "wr_bytes":0, -# "wr_operations":0, -# "rd_bytes":0, -# "rd_operations":0 -# "flush_operations":0, -# "wr_total_times_ns":0 -# "rd_total_times_ns":0 -# "flush_total_times_ns":0, -# "rd_merged":0, -# "wr_merged":0, -# "account_invalid":false, -# "account_failed":false -# } -# } -# ] -# } -# +# -> { "execute": "query-blockstats" } +# <- { +# "return":[ +# { +# "device":"ide0-hd0", +# "parent":{ +# "stats":{ +# "wr_highest_offset":3686448128, +# "wr_bytes":9786368, +# "wr_operations":751, +# "rd_bytes":122567168, +# "rd_operations":36772 +# "wr_total_times_ns":313253456 +# "rd_total_times_ns":3465673657 +# "flush_total_times_ns":49653 +# "flush_operations":61, +# "rd_merged":0, +# "wr_merged":0, +# "idle_time_ns":2953431879, +# "account_invalid":true, +# "account_failed":false +# } +# }, +# "stats":{ +# "wr_highest_offset":2821110784, +# "wr_bytes":9786368, +# "wr_operations":692, +# "rd_bytes":122739200, +# "rd_operations":36604 +# "flush_operations":51, +# "wr_total_times_ns":313253456 +# "rd_total_times_ns":3465673657 +# "flush_total_times_ns":49653, +# "rd_merged":0, +# "wr_merged":0, +# "idle_time_ns":2953431879, +# "account_invalid":true, +# "account_failed":false +# }, +# "qdev": "/machine/unattached/device[23]" +# }, +# { +# "device":"ide1-cd0", +# "stats":{ +# "wr_highest_offset":0, +# "wr_bytes":0, +# "wr_operations":0, +# "rd_bytes":0, +# "rd_operations":0 +# "flush_operations":0, +# "wr_total_times_ns":0 +# "rd_total_times_ns":0 +# "flush_total_times_ns":0, +# "rd_merged":0, +# "wr_merged":0, +# "account_invalid":false, +# "account_failed":false +# }, +# "qdev": "/machine/unattached/device[24]" +# }, +# { +# "device":"floppy0", +# "stats":{ +# "wr_highest_offset":0, +# "wr_bytes":0, +# "wr_operations":0, +# "rd_bytes":0, +# "rd_operations":0 +# "flush_operations":0, +# "wr_total_times_ns":0 +# "rd_total_times_ns":0 +# "flush_total_times_ns":0, +# "rd_merged":0, +# "wr_merged":0, +# "account_invalid":false, +# "account_failed":false +# }, +# "qdev": "/machine/unattached/device[16]" +# }, +# { +# "device":"sd0", +# "stats":{ +# "wr_highest_offset":0, +# "wr_bytes":0, +# "wr_operations":0, +# "rd_bytes":0, +# "rd_operations":0 +# "flush_operations":0, +# "wr_total_times_ns":0 +# "rd_total_times_ns":0 +# "flush_total_times_ns":0, +# "rd_merged":0, +# "wr_merged":0, +# "account_invalid":false, +# "account_failed":false +# } +# } +# ] +# } ## { 'command': 'query-blockstats', 'data': { '*query-nodes': 'bool' }, - 'returns': ['BlockStats'] } + 'returns': ['BlockStats'], + 'allow-preconfig': true } ## # @BlockdevOnError: # # An enumeration of possible behaviors for errors on I/O operations. -# The exact meaning depends on whether the I/O was initiated by a guest -# or by a block job +# The exact meaning depends on whether the I/O was initiated by a +# guest or by a block job # -# @report: for guest operations, report the error to the guest; -# for jobs, cancel the job +# @report: for guest operations, report the error to the guest; for +# jobs, cancel the job # # @ignore: ignore the error, only report a QMP event (BLOCK_IO_ERROR -# or BLOCK_JOB_ERROR). The backup, mirror and commit block jobs retry -# the failing request later and may still complete successfully. The -# stream block job continues to stream and will complete with an -# error. +# or BLOCK_JOB_ERROR). The backup, mirror and commit block jobs +# retry the failing request later and may still complete +# successfully. The stream block job continues to stream and will +# complete with an error. # # @enospc: same as @stop on ENOSPC, same as @report otherwise. # -# @stop: for guest operations, stop the virtual machine; -# for jobs, pause the job +# @stop: for guest operations, stop the virtual machine; for jobs, +# pause the job # # @auto: inherit the error handling policy of the backend (since: 2.7) # @@ -1098,10 +1315,11 @@ # # @none: only copy data written from now on # -# @incremental: only copy data described by the dirty bitmap. (since: 2.4) +# @incremental: only copy data described by the dirty bitmap. +# (since: 2.4) # -# @bitmap: only copy data described by the dirty bitmap. (since: 4.2) -# Behavior on completion is determined by the BitmapSyncMode. +# @bitmap: only copy data described by the dirty bitmap. (since: 4.2) +# Behavior on completion is determined by the BitmapSyncMode. # # Since: 1.3 ## @@ -1111,17 +1329,18 @@ ## # @BitmapSyncMode: # -# An enumeration of possible behaviors for the synchronization of a bitmap -# when used for data copy operations. +# An enumeration of possible behaviors for the synchronization of a +# bitmap when used for data copy operations. # -# @on-success: The bitmap is only synced when the operation is successful. -# This is the behavior always used for 'INCREMENTAL' backups. +# @on-success: The bitmap is only synced when the operation is +# successful. This is the behavior always used for 'INCREMENTAL' +# backups. # # @never: The bitmap is never synchronized with the operation, and is -# treated solely as a read-only manifest of blocks to copy. +# treated solely as a read-only manifest of blocks to copy. # # @always: The bitmap is always synchronized with the operation, -# regardless of whether or not the operation was successful. +# regardless of whether or not the operation was successful. # # Since: 4.2 ## @@ -1137,9 +1356,8 @@ # @background: copy data in background only. # # @write-blocking: when data is written to the source, write it -# (synchronously) to the target as well. In -# addition, data is copied in background just like in -# @background mode. +# (synchronously) to the target as well. In addition, data is +# copied in background just like in @background mode. # # Since: 3.0 ## @@ -1147,27 +1365,42 @@ 'data': ['background', 'write-blocking'] } ## +# @BlockJobInfoMirror: +# +# Information specific to mirror block jobs. +# +# @actively-synced: Whether the source is actively synced to the +# target, i.e. same data and new writes are done synchronously to +# both. +# +# Since: 8.2 +## +{ 'struct': 'BlockJobInfoMirror', + 'data': { 'actively-synced': 'bool' } } + +## # @BlockJobInfo: # # Information about a long-running block device operation. # # @type: the job type ('stream' for image streaming) # -# @device: The job identifier. Originally the device name but other -# values are allowed since QEMU 2.7 +# @device: The job identifier. Originally the device name but other +# values are allowed since QEMU 2.7 # -# @len: Estimated @offset value at the completion of the job. This value can -# arbitrarily change while the job is running, in both directions. +# @len: Estimated @offset value at the completion of the job. This +# value can arbitrarily change while the job is running, in both +# directions. # -# @offset: Progress made until now. The unit is arbitrary and the value can -# only meaningfully be used for the ratio of @offset to @len. The -# value is monotonically increasing. +# @offset: Progress made until now. The unit is arbitrary and the +# value can only meaningfully be used for the ratio of @offset to +# @len. The value is monotonically increasing. # -# @busy: false if the job is known to be in a quiescent state, with -# no pending I/O. Since 1.3. +# @busy: false if the job is known to be in a quiescent state, with no +# pending I/O. (Since 1.3) # -# @paused: whether the job is paused or, if @busy is true, will -# pause itself as soon as possible. Since 1.3. +# @paused: whether the job is paused or, if @busy is true, will pause +# itself as soon as possible. (Since 1.3) # # @speed: the rate limit, bytes per second # @@ -1177,24 +1410,26 @@ # # @status: Current job state/status (since 2.12) # -# @auto-finalize: Job will finalize itself when PENDING, moving to -# the CONCLUDED state. (since 2.12) +# @auto-finalize: Job will finalize itself when PENDING, moving to the +# CONCLUDED state. (since 2.12) # -# @auto-dismiss: Job will dismiss itself when CONCLUDED, moving to the NULL -# state and disappearing from the query list. (since 2.12) +# @auto-dismiss: Job will dismiss itself when CONCLUDED, moving to the +# NULL state and disappearing from the query list. (since 2.12) # # @error: Error information if the job did not complete successfully. -# Not set if the job completed successfully. (since 2.12.1) +# Not set if the job completed successfully. (since 2.12.1) # # Since: 1.1 ## -{ 'struct': 'BlockJobInfo', - 'data': {'type': 'str', 'device': 'str', 'len': 'int', +{ 'union': 'BlockJobInfo', + 'base': {'type': 'JobType', 'device': 'str', 'len': 'int', 'offset': 'int', 'busy': 'bool', 'paused': 'bool', 'speed': 'int', 'io-status': 'BlockDeviceIoStatus', 'ready': 'bool', 'status': 'JobStatus', 'auto-finalize': 'bool', 'auto-dismiss': 'bool', - '*error': 'str' } } + '*error': 'str' }, + 'discriminator': 'type', + 'data': { 'mirror': 'BlockJobInfoMirror' } } ## # @query-block-jobs: @@ -1205,7 +1440,8 @@ # # Since: 1.1 ## -{ 'command': 'query-block-jobs', 'returns': ['BlockJobInfo'] } +{ 'command': 'query-block-jobs', 'returns': ['BlockJobInfo'], + 'allow-preconfig': true } ## # @block_resize: @@ -1218,37 +1454,37 @@ # # @node-name: graph node name to get the image resized (Since 2.0) # -# @size: new image size in bytes +# @size: new image size in bytes # -# Returns: - nothing on success -# - If @device is not a valid block device, DeviceNotFound +# Errors: +# - If @device is not a valid block device, DeviceNotFound # # Since: 0.14 # # Example: # -# -> { "execute": "block_resize", -# "arguments": { "device": "scratch", "size": 1073741824 } } -# <- { "return": {} } -# +# -> { "execute": "block_resize", +# "arguments": { "device": "scratch", "size": 1073741824 } } +# <- { "return": {} } ## { 'command': 'block_resize', 'data': { '*device': 'str', '*node-name': 'str', 'size': 'int' }, - 'coroutine': true } + 'coroutine': true, + 'allow-preconfig': true } ## # @NewImageMode: # -# An enumeration that tells QEMU how to set the backing file path in -# a new image file. +# An enumeration that tells QEMU how to set the backing file path in a +# new image file. # # @existing: QEMU should look for an existing image file. # # @absolute-paths: QEMU should create a new image with absolute paths -# for the backing file. If there is no backing file available, the new -# image will not be backed either. +# for the backing file. If there is no backing file available, +# the new image will not be backed either. # # Since: 1.1 ## @@ -1262,18 +1498,20 @@ # # @device: the name of the device to take a snapshot of. # -# @node-name: graph node name to generate the snapshot from (Since 2.0) +# @node-name: graph node name to generate the snapshot from (Since +# 2.0) # -# @snapshot-file: the target of the new overlay image. If the file -# exists, or if it is a device, the overlay will be created in the -# existing file/device. Otherwise, a new file will be created. +# @snapshot-file: the target of the new overlay image. If the file +# exists, or if it is a device, the overlay will be created in the +# existing file/device. Otherwise, a new file will be created. # -# @snapshot-node-name: the graph node name of the new image (Since 2.0) +# @snapshot-node-name: the graph node name of the new image (Since +# 2.0) # # @format: the format of the overlay image, default is 'qcow2'. # # @mode: whether and how QEMU should create a new image, default is -# 'absolute-paths'. +# 'absolute-paths'. ## { 'struct': 'BlockdevSnapshotSync', 'data': { '*device': 'str', '*node-name': 'str', @@ -1286,9 +1524,9 @@ # @node: device or node name that will have a snapshot taken. # # @overlay: reference to the existing block device that will become -# the overlay of @node, as part of taking the snapshot. -# It must not have a current backing file (this can be -# achieved by passing "backing": null to blockdev-add). +# the overlay of @node, as part of taking the snapshot. It must +# not have a current backing file (this can be achieved by passing +# "backing": null to blockdev-add). # # Since: 2.5 ## @@ -1298,20 +1536,20 @@ ## # @BackupPerf: # -# Optional parameters for backup. These parameters don't affect +# Optional parameters for backup. These parameters don't affect # functionality, but may significantly affect performance. # -# @use-copy-range: Use copy offloading. Default false. +# @use-copy-range: Use copy offloading. Default false. # -# @max-workers: Maximum number of parallel requests for the sustained background -# copying process. Doesn't influence copy-before-write operations. -# Default 64. +# @max-workers: Maximum number of parallel requests for the sustained +# background copying process. Doesn't influence copy-before-write +# operations. Default 64. # -# @max-chunk: Maximum request length for the sustained background copying -# process. Doesn't influence copy-before-write operations. -# 0 means unlimited. If max-chunk is non-zero then it should not be -# less than job cluster size which is calculated as maximum of -# target image cluster size and 64k. Default 0. +# @max-chunk: Maximum request length for the sustained background +# copying process. Doesn't influence copy-before-write +# operations. 0 means unlimited. If max-chunk is non-zero then +# it should not be less than job cluster size which is calculated +# as maximum of target image cluster size and 64k. Default 0. # # Since: 6.0 ## @@ -1322,63 +1560,65 @@ ## # @BackupCommon: # -# @job-id: identifier for the newly-created block job. If -# omitted, the device name will be used. (Since 2.7) +# @job-id: identifier for the newly-created block job. If omitted, +# the device name will be used. (Since 2.7) # -# @device: the device name or node-name of a root node which should be copied. +# @device: the device name or node-name of a root node which should be +# copied. # -# @sync: what parts of the disk image should be copied to the destination -# (all the disk, only the sectors allocated in the topmost image, from a -# dirty bitmap, or only new I/O). +# @sync: what parts of the disk image should be copied to the +# destination (all the disk, only the sectors allocated in the +# topmost image, from a dirty bitmap, or only new I/O). # -# @speed: the maximum speed, in bytes per second. The default is 0, -# for unlimited. +# @speed: the maximum speed, in bytes per second. The default is 0, +# for unlimited. # -# @bitmap: The name of a dirty bitmap to use. -# Must be present if sync is "bitmap" or "incremental". -# Can be present if sync is "full" or "top". -# Must not be present otherwise. -# (Since 2.4 (drive-backup), 3.1 (blockdev-backup)) +# @bitmap: The name of a dirty bitmap to use. Must be present if sync +# is "bitmap" or "incremental". Can be present if sync is "full" +# or "top". Must not be present otherwise. +# (Since 2.4 (drive-backup), 3.1 (blockdev-backup)) # -# @bitmap-mode: Specifies the type of data the bitmap should contain after -# the operation concludes. -# Must be present if a bitmap was provided, -# Must NOT be present otherwise. (Since 4.2) +# @bitmap-mode: Specifies the type of data the bitmap should contain +# after the operation concludes. Must be present if a bitmap was +# provided, Must NOT be present otherwise. (Since 4.2) # # @compress: true to compress data, if the target format supports it. -# (default: false) (since 2.8) +# (default: false) (since 2.8) # # @on-source-error: the action to take on an error on the source, -# default 'report'. 'stop' and 'enospc' can only be used -# if the block device supports io-status (see BlockInfo). +# default 'report'. 'stop' and 'enospc' can only be used if the +# block device supports io-status (see BlockInfo). # # @on-target-error: the action to take on an error on the target, -# default 'report' (no limitations, since this applies to -# a different block device than @device). -# -# @auto-finalize: When false, this job will wait in a PENDING state after it has -# finished its work, waiting for @block-job-finalize before -# making any block graph changes. -# When true, this job will automatically -# perform its abort or commit actions. -# Defaults to true. (Since 2.12) -# -# @auto-dismiss: When false, this job will wait in a CONCLUDED state after it -# has completely ceased all work, and awaits @block-job-dismiss. -# When true, this job will automatically disappear from the query -# list without user intervention. -# Defaults to true. (Since 2.12) +# default 'report' (no limitations, since this applies to a +# different block device than @device). +# +# @auto-finalize: When false, this job will wait in a PENDING state +# after it has finished its work, waiting for @block-job-finalize +# before making any block graph changes. When true, this job will +# automatically perform its abort or commit actions. Defaults to +# true. (Since 2.12) +# +# @auto-dismiss: When false, this job will wait in a CONCLUDED state +# after it has completely ceased all work, and awaits +# @block-job-dismiss. When true, this job will automatically +# disappear from the query list without user intervention. +# Defaults to true. (Since 2.12) # # @filter-node-name: the node name that should be assigned to the -# filter driver that the backup job inserts into the graph -# above node specified by @drive. If this option is not given, -# a node name is autogenerated. (Since: 4.2) +# filter driver that the backup job inserts into the graph above +# node specified by @drive. If this option is not given, a node +# name is autogenerated. (Since: 4.2) # -# @x-perf: Performance options. (Since 6.0) +# @x-perf: Performance options. (Since 6.0) +# +# Features: +# +# @unstable: Member @x-perf is experimental. # # Note: @on-source-error and @on-target-error only affect background -# I/O. If an error occurs during a guest write request, the device's -# rerror/werror actions will be used. +# I/O. If an error occurs during a guest write request, the +# device's rerror/werror actions will be used. # # Since: 4.2 ## @@ -1390,20 +1630,22 @@ '*on-source-error': 'BlockdevOnError', '*on-target-error': 'BlockdevOnError', '*auto-finalize': 'bool', '*auto-dismiss': 'bool', - '*filter-node-name': 'str', '*x-perf': 'BackupPerf' } } + '*filter-node-name': 'str', + '*x-perf': { 'type': 'BackupPerf', + 'features': [ 'unstable' ] } } } ## # @DriveBackup: # -# @target: the target of the new image. If the file exists, or if it -# is a device, the existing file/device will be used as the new -# destination. If it does not exist, a new file will be created. +# @target: the target of the new image. If the file exists, or if it +# is a device, the existing file/device will be used as the new +# destination. If it does not exist, a new file will be created. # -# @format: the format of the new destination, default is to -# probe if @mode is 'existing', else the format of the source +# @format: the format of the new destination, default is to probe if +# @mode is 'existing', else the format of the source # # @mode: whether and how QEMU should create a new image, default is -# 'absolute-paths'. +# 'absolute-paths'. # # Since: 1.6 ## @@ -1431,24 +1673,23 @@ # # For the arguments, see the documentation of BlockdevSnapshotSync. # -# Returns: - nothing on success -# - If @device is not a valid block device, DeviceNotFound +# Errors: +# - If @device is not a valid block device, DeviceNotFound # # Since: 0.14 # # Example: # -# -> { "execute": "blockdev-snapshot-sync", -# "arguments": { "device": "ide-hd0", -# "snapshot-file": -# "/some/place/my-image", -# "format": "qcow2" } } -# <- { "return": {} } -# +# -> { "execute": "blockdev-snapshot-sync", +# "arguments": { "device": "ide-hd0", +# "snapshot-file": +# "/some/place/my-image", +# "format": "qcow2" } } +# <- { "return": {} } ## { 'command': 'blockdev-snapshot-sync', - 'data': 'BlockdevSnapshotSync' } - + 'data': 'BlockdevSnapshotSync', + 'allow-preconfig': true } ## # @blockdev-snapshot: @@ -1457,83 +1698,82 @@ # # Take a snapshot, by installing 'node' as the backing image of # 'overlay'. Additionally, if 'node' is associated with a block -# device, the block device changes to using 'overlay' as its new active -# image. +# device, the block device changes to using 'overlay' as its new +# active image. # # For the arguments, see the documentation of BlockdevSnapshot. # # Features: -# @allow-write-only-overlay: If present, the check whether this operation is safe -# was relaxed so that it can be used to change -# backing file of a destination of a blockdev-mirror. -# (since 5.0) +# +# @allow-write-only-overlay: If present, the check whether this +# operation is safe was relaxed so that it can be used to change +# backing file of a destination of a blockdev-mirror. (since 5.0) # # Since: 2.5 # # Example: # -# -> { "execute": "blockdev-add", -# "arguments": { "driver": "qcow2", -# "node-name": "node1534", -# "file": { "driver": "file", -# "filename": "hd1.qcow2" }, -# "backing": null } } -# -# <- { "return": {} } +# -> { "execute": "blockdev-add", +# "arguments": { "driver": "qcow2", +# "node-name": "node1534", +# "file": { "driver": "file", +# "filename": "hd1.qcow2" }, +# "backing": null } } # -# -> { "execute": "blockdev-snapshot", -# "arguments": { "node": "ide-hd0", -# "overlay": "node1534" } } -# <- { "return": {} } +# <- { "return": {} } # +# -> { "execute": "blockdev-snapshot", +# "arguments": { "node": "ide-hd0", +# "overlay": "node1534" } } +# <- { "return": {} } ## { 'command': 'blockdev-snapshot', 'data': 'BlockdevSnapshot', - 'features': [ 'allow-write-only-overlay' ] } + 'features': [ 'allow-write-only-overlay' ], + 'allow-preconfig': true } ## # @change-backing-file: # # Change the backing file in the image file metadata. This does not # cause QEMU to reopen the image file to reparse the backing filename -# (it may, however, perform a reopen to change permissions from -# r/o -> r/w -> r/o, if needed). The new backing file string is written -# into the image file metadata, and the QEMU internal strings are -# updated. +# (it may, however, perform a reopen to change permissions from r/o -> +# r/w -> r/o, if needed). The new backing file string is written into +# the image file metadata, and the QEMU internal strings are updated. # # @image-node-name: The name of the block driver state node of the -# image to modify. The "device" argument is used -# to verify "image-node-name" is in the chain -# described by "device". +# image to modify. The "device" argument is used to verify +# "image-node-name" is in the chain described by "device". # # @device: The device name or node-name of the root node that owns -# image-node-name. +# image-node-name. # -# @backing-file: The string to write as the backing file. This -# string is not validated, so care should be taken -# when specifying the string or the image chain may -# not be able to be reopened again. +# @backing-file: The string to write as the backing file. This string +# is not validated, so care should be taken when specifying the +# string or the image chain may not be able to be reopened again. # -# Returns: - Nothing on success -# - If "device" does not exist or cannot be determined, DeviceNotFound +# Errors: +# - If "device" does not exist or cannot be determined, +# DeviceNotFound # # Since: 2.1 ## { 'command': 'change-backing-file', 'data': { 'device': 'str', 'image-node-name': 'str', - 'backing-file': 'str' } } + 'backing-file': 'str' }, + 'allow-preconfig': true } ## # @block-commit: # -# Live commit of data from overlay image nodes into backing nodes - i.e., -# writes data between 'top' and 'base' into 'base'. +# Live commit of data from overlay image nodes into backing nodes - +# i.e., writes data between 'top' and 'base' into 'base'. # -# If top == base, that is an error. -# If top has no overlays on top of it, or if it is in use by a writer, -# the job will not be completed by itself. The user needs to complete -# the job with the block-job-complete command after getting the ready -# event. (Since 2.0) +# If top == base, that is an error. If top has no overlays on top of +# it, or if it is in use by a writer, the job will not be completed by +# itself. The user needs to complete the job with the +# block-job-complete command after getting the ready event. (Since +# 2.0) # # If the base image is smaller than top, then the base image will be # resized to be the same size as top. If top is smaller than the base @@ -1541,157 +1781,165 @@ # size to match the size of the smaller top, you can safely truncate # it yourself once the commit operation successfully completes. # -# @job-id: identifier for the newly-created block job. If -# omitted, the device name will be used. (Since 2.7) +# @job-id: identifier for the newly-created block job. If omitted, +# the device name will be used. (Since 2.7) # # @device: the device name or node-name of a root node # # @base-node: The node name of the backing image to write data into. -# If not specified, this is the deepest backing image. -# (since: 3.1) +# If not specified, this is the deepest backing image. +# (since: 3.1) # -# @base: Same as @base-node, except that it is a file name rather than a node -# name. This must be the exact filename string that was used to open the -# node; other strings, even if addressing the same file, are not -# accepted +# @base: Same as @base-node, except that it is a file name rather than +# a node name. This must be the exact filename string that was +# used to open the node; other strings, even if addressing the +# same file, are not accepted # # @top-node: The node name of the backing image within the image chain -# which contains the topmost data to be committed down. If -# not specified, this is the active layer. (since: 3.1) +# which contains the topmost data to be committed down. If not +# specified, this is the active layer. (since: 3.1) # -# @top: Same as @top-node, except that it is a file name rather than a node -# name. This must be the exact filename string that was used to open the -# node; other strings, even if addressing the same file, are not -# accepted +# @top: Same as @top-node, except that it is a file name rather than a +# node name. This must be the exact filename string that was used +# to open the node; other strings, even if addressing the same +# file, are not accepted # # @backing-file: The backing file string to write into the overlay -# image of 'top'. If 'top' does not have an overlay -# image, or if 'top' is in use by a writer, specifying -# a backing file string is an error. -# -# This filename is not validated. If a pathname string -# is such that it cannot be resolved by QEMU, that -# means that subsequent QMP or HMP commands must use -# node-names for the image in question, as filename -# lookup methods will fail. -# -# If not specified, QEMU will automatically determine -# the backing file string to use, or error out if -# there is no obvious choice. Care should be taken -# when specifying the string, to specify a valid -# filename or protocol. -# (Since 2.1) +# image of 'top'. If 'top' does not have an overlay image, or if +# 'top' is in use by a writer, specifying a backing file string is +# an error. +# +# This filename is not validated. If a pathname string is such +# that it cannot be resolved by QEMU, that means that subsequent +# QMP or HMP commands must use node-names for the image in +# question, as filename lookup methods will fail. +# +# If not specified, QEMU will automatically determine the backing +# file string to use, or error out if there is no obvious choice. +# Care should be taken when specifying the string, to specify a +# valid filename or protocol. (Since 2.1) +# +# @backing-mask-protocol: If true, replace any protocol mentioned in +# the 'backing file format' with 'raw', rather than storing the +# protocol name as the backing format. Can be used even when no +# image header will be updated (default false; since 9.0). # # @speed: the maximum speed, in bytes per second # -# @on-error: the action to take on an error. 'ignore' means that the request -# should be retried. (default: report; Since: 5.0) +# @on-error: the action to take on an error. 'ignore' means that the +# request should be retried. (default: report; Since: 5.0) # # @filter-node-name: the node name that should be assigned to the -# filter driver that the commit job inserts into the graph -# above @top. If this option is not given, a node name is -# autogenerated. (Since: 2.9) -# -# @auto-finalize: When false, this job will wait in a PENDING state after it has -# finished its work, waiting for @block-job-finalize before -# making any block graph changes. -# When true, this job will automatically -# perform its abort or commit actions. -# Defaults to true. (Since 3.1) -# -# @auto-dismiss: When false, this job will wait in a CONCLUDED state after it -# has completely ceased all work, and awaits @block-job-dismiss. -# When true, this job will automatically disappear from the query -# list without user intervention. -# Defaults to true. (Since 3.1) +# filter driver that the commit job inserts into the graph above +# @top. If this option is not given, a node name is +# autogenerated. (Since: 2.9) +# +# @auto-finalize: When false, this job will wait in a PENDING state +# after it has finished its work, waiting for @block-job-finalize +# before making any block graph changes. When true, this job will +# automatically perform its abort or commit actions. Defaults to +# true. (Since 3.1) +# +# @auto-dismiss: When false, this job will wait in a CONCLUDED state +# after it has completely ceased all work, and awaits +# @block-job-dismiss. When true, this job will automatically +# disappear from the query list without user intervention. +# Defaults to true. (Since 3.1) # # Features: +# # @deprecated: Members @base and @top are deprecated. Use @base-node -# and @top-node instead. +# and @top-node instead. # -# Returns: - Nothing on success -# - If @device does not exist, DeviceNotFound -# - Any other error returns a GenericError. +# Errors: +# - If @device does not exist, DeviceNotFound +# - Any other error returns a GenericError. # # Since: 1.3 # # Example: # -# -> { "execute": "block-commit", -# "arguments": { "device": "virtio0", -# "top": "/tmp/snap1.qcow2" } } -# <- { "return": {} } -# +# -> { "execute": "block-commit", +# "arguments": { "device": "virtio0", +# "top": "/tmp/snap1.qcow2" } } +# <- { "return": {} } ## { 'command': 'block-commit', 'data': { '*job-id': 'str', 'device': 'str', '*base-node': 'str', '*base': { 'type': 'str', 'features': [ 'deprecated' ] }, '*top-node': 'str', '*top': { 'type': 'str', 'features': [ 'deprecated' ] }, - '*backing-file': 'str', '*speed': 'int', + '*backing-file': 'str', '*backing-mask-protocol': 'bool', + '*speed': 'int', '*on-error': 'BlockdevOnError', '*filter-node-name': 'str', - '*auto-finalize': 'bool', '*auto-dismiss': 'bool' } } + '*auto-finalize': 'bool', '*auto-dismiss': 'bool' }, + 'allow-preconfig': true } ## # @drive-backup: # -# Start a point-in-time copy of a block device to a new destination. The -# status of ongoing drive-backup operations can be checked with -# query-block-jobs where the BlockJobInfo.type field has the value 'backup'. -# The operation can be stopped before it has completed using the -# block-job-cancel command. +# Start a point-in-time copy of a block device to a new destination. +# The status of ongoing drive-backup operations can be checked with +# query-block-jobs where the BlockJobInfo.type field has the value +# 'backup'. The operation can be stopped before it has completed using +# the block-job-cancel command. +# +# Features: # -# Returns: - nothing on success -# - If @device is not a valid block device, GenericError +# @deprecated: This command is deprecated. Use @blockdev-backup +# instead. +# +# Errors: +# - If @device is not a valid block device, GenericError # # Since: 1.6 # # Example: # -# -> { "execute": "drive-backup", -# "arguments": { "device": "drive0", -# "sync": "full", -# "target": "backup.img" } } -# <- { "return": {} } -# +# -> { "execute": "drive-backup", +# "arguments": { "device": "drive0", +# "sync": "full", +# "target": "backup.img" } } +# <- { "return": {} } ## { 'command': 'drive-backup', 'boxed': true, - 'data': 'DriveBackup' } + 'data': 'DriveBackup', 'features': ['deprecated'], + 'allow-preconfig': true } ## # @blockdev-backup: # -# Start a point-in-time copy of a block device to a new destination. The -# status of ongoing blockdev-backup operations can be checked with -# query-block-jobs where the BlockJobInfo.type field has the value 'backup'. -# The operation can be stopped before it has completed using the -# block-job-cancel command. +# Start a point-in-time copy of a block device to a new destination. +# The status of ongoing blockdev-backup operations can be checked with +# query-block-jobs where the BlockJobInfo.type field has the value +# 'backup'. The operation can be stopped before it has completed using +# the block-job-cancel command. # -# Returns: - nothing on success -# - If @device is not a valid block device, DeviceNotFound +# Errors: +# - If @device is not a valid block device, DeviceNotFound # # Since: 2.3 # # Example: -# -> { "execute": "blockdev-backup", -# "arguments": { "device": "src-id", -# "sync": "full", -# "target": "tgt-id" } } -# <- { "return": {} } # +# -> { "execute": "blockdev-backup", +# "arguments": { "device": "src-id", +# "sync": "full", +# "target": "tgt-id" } } +# <- { "return": {} } ## { 'command': 'blockdev-backup', 'boxed': true, - 'data': 'BlockdevBackup' } - + 'data': 'BlockdevBackup', + 'allow-preconfig': true } ## # @query-named-block-nodes: # # Get the named block driver list # -# @flat: Omit the nested data about backing image ("backing-image" key) if true. -# Default is false (Since 5.0) +# @flat: Omit the nested data about backing image ("backing-image" +# key) if true. Default is false (Since 5.0) # # Returns: the list of BlockDeviceInfo # @@ -1699,56 +1947,57 @@ # # Example: # -# -> { "execute": "query-named-block-nodes" } -# <- { "return": [ { "ro":false, -# "drv":"qcow2", -# "encrypted":false, -# "file":"disks/test.qcow2", -# "node-name": "my-node", -# "backing_file_depth":1, -# "bps":1000000, -# "bps_rd":0, -# "bps_wr":0, -# "iops":1000000, -# "iops_rd":0, -# "iops_wr":0, -# "bps_max": 8000000, -# "bps_rd_max": 0, -# "bps_wr_max": 0, -# "iops_max": 0, -# "iops_rd_max": 0, -# "iops_wr_max": 0, -# "iops_size": 0, -# "write_threshold": 0, -# "image":{ -# "filename":"disks/test.qcow2", -# "format":"qcow2", -# "virtual-size":2048000, -# "backing_file":"base.qcow2", -# "full-backing-filename":"disks/base.qcow2", -# "backing-filename-format":"qcow2", -# "snapshots":[ -# { -# "id": "1", -# "name": "snapshot1", -# "vm-state-size": 0, -# "date-sec": 10000200, -# "date-nsec": 12, -# "vm-clock-sec": 206, -# "vm-clock-nsec": 30 -# } -# ], -# "backing-image":{ -# "filename":"disks/base.qcow2", +# -> { "execute": "query-named-block-nodes" } +# <- { "return": [ { "ro":false, +# "drv":"qcow2", +# "encrypted":false, +# "file":"disks/test.qcow2", +# "node-name": "my-node", +# "backing_file_depth":1, +# "detect_zeroes":"off", +# "bps":1000000, +# "bps_rd":0, +# "bps_wr":0, +# "iops":1000000, +# "iops_rd":0, +# "iops_wr":0, +# "bps_max": 8000000, +# "bps_rd_max": 0, +# "bps_wr_max": 0, +# "iops_max": 0, +# "iops_rd_max": 0, +# "iops_wr_max": 0, +# "iops_size": 0, +# "write_threshold": 0, +# "image":{ +# "filename":"disks/test.qcow2", # "format":"qcow2", -# "virtual-size":2048000 -# } -# } } ] } -# +# "virtual-size":2048000, +# "backing_file":"base.qcow2", +# "full-backing-filename":"disks/base.qcow2", +# "backing-filename-format":"qcow2", +# "snapshots":[ +# { +# "id": "1", +# "name": "snapshot1", +# "vm-state-size": 0, +# "date-sec": 10000200, +# "date-nsec": 12, +# "vm-clock-sec": 206, +# "vm-clock-nsec": 30 +# } +# ], +# "backing-image":{ +# "filename":"disks/base.qcow2", +# "format":"qcow2", +# "virtual-size":2048000 +# } +# } } ] } ## { 'command': 'query-named-block-nodes', 'returns': [ 'BlockDeviceInfo' ], - 'data': { '*flat': 'bool' } } + 'data': { '*flat': 'bool' }, + 'allow-preconfig': true } ## # @XDbgBlockGraphNodeType: @@ -1767,16 +2016,16 @@ ## # @XDbgBlockGraphNode: # -# @id: Block graph node identifier. This @id is generated only for -# x-debug-query-block-graph and does not relate to any other identifiers in -# Qemu. +# @id: Block graph node identifier. This @id is generated only for +# x-debug-query-block-graph and does not relate to any other +# identifiers in Qemu. # -# @type: Type of graph node. Can be one of block-backend, block-job or -# block-driver-state. +# @type: Type of graph node. Can be one of block-backend, block-job +# or block-driver-state. # -# @name: Human readable name of the node. Corresponds to node-name for -# block-driver-state nodes; is not guaranteed to be unique in the whole -# graph (with block-jobs and block-backends). +# @name: Human readable name of the node. Corresponds to node-name +# for block-driver-state nodes; is not guaranteed to be unique in +# the whole graph (with block-jobs and block-backends). # # Since: 4.0 ## @@ -1788,34 +2037,32 @@ # # Enum of base block permissions. # -# @consistent-read: A user that has the "permission" of consistent reads is -# guaranteed that their view of the contents of the block -# device is complete and self-consistent, representing the -# contents of a disk at a specific point. -# For most block devices (including their backing files) this -# is true, but the property cannot be maintained in a few -# situations like for intermediate nodes of a commit block -# job. -# -# @write: This permission is required to change the visible disk contents. +# @consistent-read: A user that has the "permission" of consistent +# reads is guaranteed that their view of the contents of the block +# device is complete and self-consistent, representing the +# contents of a disk at a specific point. For most block devices +# (including their backing files) this is true, but the property +# cannot be maintained in a few situations like for intermediate +# nodes of a commit block job. # -# @write-unchanged: This permission (which is weaker than BLK_PERM_WRITE) is -# both enough and required for writes to the block node when -# the caller promises that the visible disk content doesn't -# change. -# As the BLK_PERM_WRITE permission is strictly stronger, -# either is sufficient to perform an unchanging write. +# @write: This permission is required to change the visible disk +# contents. # -# @resize: This permission is required to change the size of a block node. +# @write-unchanged: This permission (which is weaker than +# BLK_PERM_WRITE) is both enough and required for writes to the +# block node when the caller promises that the visible disk +# content doesn't change. As the BLK_PERM_WRITE permission is +# strictly stronger, either is sufficient to perform an unchanging +# write. # -# @graph-mod: This permission is required to change the node that this -# BdrvChild points to. +# @resize: This permission is required to change the size of a block +# node. # # Since: 4.0 ## { 'enum': 'BlockPermission', - 'data': [ 'consistent-read', 'write', 'write-unchanged', 'resize', - 'graph-mod' ] } + 'data': [ 'consistent-read', 'write', 'write-unchanged', 'resize' ] } + ## # @XDbgBlockGraphEdge: # @@ -1829,8 +2076,8 @@ # # @perm: granted permissions for the parent operating on the child # -# @shared-perm: permissions that can still be granted to other users of the -# child while it is still attached to this parent +# @shared-perm: permissions that can still be granted to other users +# of the child while it is still attached to this parent # # Since: 4.0 ## @@ -1854,109 +2101,116 @@ # # Get the block graph. # +# Features: +# +# @unstable: This command is meant for debugging. +# # Since: 4.0 ## -{ 'command': 'x-debug-query-block-graph', 'returns': 'XDbgBlockGraph' } +{ 'command': 'x-debug-query-block-graph', 'returns': 'XDbgBlockGraph', + 'features': [ 'unstable' ], + 'allow-preconfig': true } ## # @drive-mirror: # -# Start mirroring a block device's writes to a new destination. target -# specifies the target of the new image. If the file exists, or if it -# is a device, it will be used as the new destination for writes. If -# it does not exist, a new file will be created. format specifies the -# format of the mirror image, default is to probe if mode='existing', -# else the format of the source. +# Start mirroring a block device's writes to a new destination. +# target specifies the target of the new image. If the file exists, +# or if it is a device, it will be used as the new destination for +# writes. If it does not exist, a new file will be created. @format +# specifies the format of the mirror image, default is to probe if +# mode='existing', else the format of the source. # -# Returns: - nothing on success -# - If @device is not a valid block device, GenericError +# Errors: +# - If @device is not a valid block device, GenericError # # Since: 1.3 # # Example: # -# -> { "execute": "drive-mirror", -# "arguments": { "device": "ide-hd0", -# "target": "/some/place/my-image", -# "sync": "full", -# "format": "qcow2" } } -# <- { "return": {} } -# +# -> { "execute": "drive-mirror", +# "arguments": { "device": "ide-hd0", +# "target": "/some/place/my-image", +# "sync": "full", +# "format": "qcow2" } } +# <- { "return": {} } ## { 'command': 'drive-mirror', 'boxed': true, - 'data': 'DriveMirror' } + 'data': 'DriveMirror', + 'allow-preconfig': true } ## # @DriveMirror: # # A set of parameters describing drive mirror setup. # -# @job-id: identifier for the newly-created block job. If -# omitted, the device name will be used. (Since 2.7) +# @job-id: identifier for the newly-created block job. If omitted, +# the device name will be used. (Since 2.7) # -# @device: the device name or node-name of a root node whose writes should be -# mirrored. +# @device: the device name or node-name of a root node whose writes +# should be mirrored. # -# @target: the target of the new image. If the file exists, or if it -# is a device, the existing file/device will be used as the new -# destination. If it does not exist, a new file will be created. +# @target: the target of the new image. If the file exists, or if it +# is a device, the existing file/device will be used as the new +# destination. If it does not exist, a new file will be created. # -# @format: the format of the new destination, default is to -# probe if @mode is 'existing', else the format of the source +# @format: the format of the new destination, default is to probe if +# @mode is 'existing', else the format of the source # -# @node-name: the new block driver state node name in the graph -# (Since 2.1) +# @node-name: the new block driver state node name in the graph (Since +# 2.1) # # @replaces: with sync=full graph node name to be replaced by the new -# image when a whole image copy is done. This can be used to repair -# broken Quorum files. By default, @device is replaced, although -# implicitly created filters on it are kept. (Since 2.1) +# image when a whole image copy is done. This can be used to +# repair broken Quorum files. By default, @device is replaced, +# although implicitly created filters on it are kept. (Since 2.1) # # @mode: whether and how QEMU should create a new image, default is -# 'absolute-paths'. +# 'absolute-paths'. # -# @speed: the maximum speed, in bytes per second +# @speed: the maximum speed, in bytes per second # -# @sync: what parts of the disk image should be copied to the destination -# (all the disk, only the sectors allocated in the topmost image, or -# only new I/O). +# @sync: what parts of the disk image should be copied to the +# destination (all the disk, only the sectors allocated in the +# topmost image, or only new I/O). # -# @granularity: granularity of the dirty bitmap, default is 64K -# if the image format doesn't have clusters, 4K if the clusters -# are smaller than that, else the cluster size. Must be a -# power of 2 between 512 and 64M (since 1.4). +# @granularity: granularity of the dirty bitmap, default is 64K if the +# image format doesn't have clusters, 4K if the clusters are +# smaller than that, else the cluster size. Must be a power of 2 +# between 512 and 64M (since 1.4). # -# @buf-size: maximum amount of data in flight from source to -# target (since 1.4). +# @buf-size: maximum amount of data in flight from source to target +# (since 1.4). # # @on-source-error: the action to take on an error on the source, -# default 'report'. 'stop' and 'enospc' can only be used -# if the block device supports io-status (see BlockInfo). +# default 'report'. 'stop' and 'enospc' can only be used if the +# block device supports io-status (see BlockInfo). # # @on-target-error: the action to take on an error on the target, -# default 'report' (no limitations, since this applies to -# a different block device than @device). -# @unmap: Whether to try to unmap target sectors where source has -# only zero. If true, and target unallocated sectors will read as zero, -# target image sectors will be unmapped; otherwise, zeroes will be -# written. Both will result in identical contents. -# Default is true. (Since 2.4) -# -# @copy-mode: when to copy data to the destination; defaults to 'background' -# (Since: 3.0) -# -# @auto-finalize: When false, this job will wait in a PENDING state after it has -# finished its work, waiting for @block-job-finalize before -# making any block graph changes. -# When true, this job will automatically -# perform its abort or commit actions. -# Defaults to true. (Since 3.1) -# -# @auto-dismiss: When false, this job will wait in a CONCLUDED state after it -# has completely ceased all work, and awaits @block-job-dismiss. -# When true, this job will automatically disappear from the query -# list without user intervention. -# Defaults to true. (Since 3.1) +# default 'report' (no limitations, since this applies to a +# different block device than @device). +# +# @unmap: Whether to try to unmap target sectors where source has only +# zero. If true, and target unallocated sectors will read as +# zero, target image sectors will be unmapped; otherwise, zeroes +# will be written. Both will result in identical contents. +# Default is true. (Since 2.4) +# +# @copy-mode: when to copy data to the destination; defaults to +# 'background' (Since: 3.0) +# +# @auto-finalize: When false, this job will wait in a PENDING state +# after it has finished its work, waiting for @block-job-finalize +# before making any block graph changes. When true, this job will +# automatically perform its abort or commit actions. Defaults to +# true. (Since 3.1) +# +# @auto-dismiss: When false, this job will wait in a CONCLUDED state +# after it has completely ceased all work, and awaits +# @block-job-dismiss. When true, this job will automatically +# disappear from the query list without user intervention. +# Defaults to true. (Since 3.1) +# # Since: 1.3 ## { 'struct': 'DriveMirror', @@ -1989,16 +2243,16 @@ # @name: name of the dirty bitmap (must be less than 1024 bytes) # # @granularity: the bitmap granularity, default is 64k for -# block-dirty-bitmap-add +# block-dirty-bitmap-add # # @persistent: the bitmap is persistent, i.e. it will be saved to the -# corresponding block device image file on its close. For now only -# Qcow2 disks support persistent bitmaps. Default is false for -# block-dirty-bitmap-add. (Since: 2.10) +# corresponding block device image file on its close. For now +# only Qcow2 disks support persistent bitmaps. Default is false +# for block-dirty-bitmap-add. (Since: 2.10) # -# @disabled: the bitmap is created in the disabled state, which means that -# it will not track drive changes. The bitmap may be enabled with -# block-dirty-bitmap-enable. Default is false. (Since: 4.0) +# @disabled: the bitmap is created in the disabled state, which means +# that it will not track drive changes. The bitmap may be enabled +# with block-dirty-bitmap-enable. Default is false. (Since: 4.0) # # Since: 2.4 ## @@ -2007,15 +2261,16 @@ '*persistent': 'bool', '*disabled': 'bool' } } ## -# @BlockDirtyBitmapMergeSource: +# @BlockDirtyBitmapOrStr: # -# @local: name of the bitmap, attached to the same node as target bitmap. +# @local: name of the bitmap, attached to the same node as target +# bitmap. # # @external: bitmap with specified node # # Since: 4.1 ## -{ 'alternate': 'BlockDirtyBitmapMergeSource', +{ 'alternate': 'BlockDirtyBitmapOrStr', 'data': { 'local': 'str', 'external': 'BlockDirtyBitmap' } } @@ -2026,60 +2281,61 @@ # # @target: name of the destination dirty bitmap # -# @bitmaps: name(s) of the source dirty bitmap(s) at @node and/or fully -# specified BlockDirtyBitmap elements. The latter are supported -# since 4.1. +# @bitmaps: name(s) of the source dirty bitmap(s) at @node and/or +# fully specified BlockDirtyBitmap elements. The latter are +# supported since 4.1. # # Since: 4.0 ## { 'struct': 'BlockDirtyBitmapMerge', 'data': { 'node': 'str', 'target': 'str', - 'bitmaps': ['BlockDirtyBitmapMergeSource'] } } + 'bitmaps': ['BlockDirtyBitmapOrStr'] } } ## # @block-dirty-bitmap-add: # -# Create a dirty bitmap with a name on the node, and start tracking the writes. +# Create a dirty bitmap with a name on the node, and start tracking +# the writes. # -# Returns: - nothing on success -# - If @node is not a valid block device or node, DeviceNotFound -# - If @name is already taken, GenericError with an explanation +# Errors: +# - If @node is not a valid block device or node, DeviceNotFound +# - If @name is already taken, GenericError with an explanation # # Since: 2.4 # # Example: # -# -> { "execute": "block-dirty-bitmap-add", -# "arguments": { "node": "drive0", "name": "bitmap0" } } -# <- { "return": {} } -# +# -> { "execute": "block-dirty-bitmap-add", +# "arguments": { "node": "drive0", "name": "bitmap0" } } +# <- { "return": {} } ## { 'command': 'block-dirty-bitmap-add', - 'data': 'BlockDirtyBitmapAdd' } + 'data': 'BlockDirtyBitmapAdd', + 'allow-preconfig': true } ## # @block-dirty-bitmap-remove: # # Stop write tracking and remove the dirty bitmap that was created -# with block-dirty-bitmap-add. If the bitmap is persistent, remove it from its -# storage too. +# with block-dirty-bitmap-add. If the bitmap is persistent, remove it +# from its storage too. # -# Returns: - nothing on success -# - If @node is not a valid block device or node, DeviceNotFound -# - If @name is not found, GenericError with an explanation -# - if @name is frozen by an operation, GenericError +# Errors: +# - If @node is not a valid block device or node, DeviceNotFound +# - If @name is not found, GenericError with an explanation +# - if @name is frozen by an operation, GenericError # # Since: 2.4 # # Example: # -# -> { "execute": "block-dirty-bitmap-remove", -# "arguments": { "node": "drive0", "name": "bitmap0" } } -# <- { "return": {} } -# +# -> { "execute": "block-dirty-bitmap-remove", +# "arguments": { "node": "drive0", "name": "bitmap0" } } +# <- { "return": {} } ## { 'command': 'block-dirty-bitmap-remove', - 'data': 'BlockDirtyBitmap' } + 'data': 'BlockDirtyBitmap', + 'allow-preconfig': true } ## # @block-dirty-bitmap-clear: @@ -2088,95 +2344,96 @@ # backup from this point in time forward will only backup clusters # modified after this clear operation. # -# Returns: - nothing on success -# - If @node is not a valid block device, DeviceNotFound -# - If @name is not found, GenericError with an explanation +# Errors: +# - If @node is not a valid block device, DeviceNotFound +# - If @name is not found, GenericError with an explanation # # Since: 2.4 # # Example: # -# -> { "execute": "block-dirty-bitmap-clear", -# "arguments": { "node": "drive0", "name": "bitmap0" } } -# <- { "return": {} } -# +# -> { "execute": "block-dirty-bitmap-clear", +# "arguments": { "node": "drive0", "name": "bitmap0" } } +# <- { "return": {} } ## { 'command': 'block-dirty-bitmap-clear', - 'data': 'BlockDirtyBitmap' } + 'data': 'BlockDirtyBitmap', + 'allow-preconfig': true } ## # @block-dirty-bitmap-enable: # # Enables a dirty bitmap so that it will begin tracking disk changes. # -# Returns: - nothing on success -# - If @node is not a valid block device, DeviceNotFound -# - If @name is not found, GenericError with an explanation +# Errors: +# - If @node is not a valid block device, DeviceNotFound +# - If @name is not found, GenericError with an explanation # # Since: 4.0 # # Example: # -# -> { "execute": "block-dirty-bitmap-enable", -# "arguments": { "node": "drive0", "name": "bitmap0" } } -# <- { "return": {} } -# +# -> { "execute": "block-dirty-bitmap-enable", +# "arguments": { "node": "drive0", "name": "bitmap0" } } +# <- { "return": {} } ## { 'command': 'block-dirty-bitmap-enable', - 'data': 'BlockDirtyBitmap' } + 'data': 'BlockDirtyBitmap', + 'allow-preconfig': true } ## # @block-dirty-bitmap-disable: # # Disables a dirty bitmap so that it will stop tracking disk changes. # -# Returns: - nothing on success -# - If @node is not a valid block device, DeviceNotFound -# - If @name is not found, GenericError with an explanation +# Errors: +# - If @node is not a valid block device, DeviceNotFound +# - If @name is not found, GenericError with an explanation # # Since: 4.0 # # Example: # -# -> { "execute": "block-dirty-bitmap-disable", -# "arguments": { "node": "drive0", "name": "bitmap0" } } -# <- { "return": {} } -# +# -> { "execute": "block-dirty-bitmap-disable", +# "arguments": { "node": "drive0", "name": "bitmap0" } } +# <- { "return": {} } ## { 'command': 'block-dirty-bitmap-disable', - 'data': 'BlockDirtyBitmap' } + 'data': 'BlockDirtyBitmap', + 'allow-preconfig': true } ## # @block-dirty-bitmap-merge: # # Merge dirty bitmaps listed in @bitmaps to the @target dirty bitmap. -# Dirty bitmaps in @bitmaps will be unchanged, except if it also appears -# as the @target bitmap. Any bits already set in @target will still be -# set after the merge, i.e., this operation does not clear the target. -# On error, @target is unchanged. -# -# The resulting bitmap will count as dirty any clusters that were dirty in any -# of the source bitmaps. This can be used to achieve backup checkpoints, or in -# simpler usages, to copy bitmaps. -# -# Returns: - nothing on success -# - If @node is not a valid block device, DeviceNotFound -# - If any bitmap in @bitmaps or @target is not found, GenericError -# - If any of the bitmaps have different sizes or granularities, -# GenericError +# Dirty bitmaps in @bitmaps will be unchanged, except if it also +# appears as the @target bitmap. Any bits already set in @target will +# still be set after the merge, i.e., this operation does not clear +# the target. On error, @target is unchanged. +# +# The resulting bitmap will count as dirty any clusters that were +# dirty in any of the source bitmaps. This can be used to achieve +# backup checkpoints, or in simpler usages, to copy bitmaps. +# +# Errors: +# - If @node is not a valid block device, DeviceNotFound +# - If any bitmap in @bitmaps or @target is not found, +# GenericError +# - If any of the bitmaps have different sizes or granularities, +# GenericError # # Since: 4.0 # # Example: # -# -> { "execute": "block-dirty-bitmap-merge", -# "arguments": { "node": "drive0", "target": "bitmap0", -# "bitmaps": ["bitmap1"] } } -# <- { "return": {} } -# +# -> { "execute": "block-dirty-bitmap-merge", +# "arguments": { "node": "drive0", "target": "bitmap0", +# "bitmaps": ["bitmap1"] } } +# <- { "return": {} } ## { 'command': 'block-dirty-bitmap-merge', - 'data': 'BlockDirtyBitmapMerge' } + 'data': 'BlockDirtyBitmapMerge', + 'allow-preconfig': true } ## # @BlockDirtyBitmapSha256: @@ -2195,89 +2452,94 @@ # # Get bitmap SHA256. # -# Returns: - BlockDirtyBitmapSha256 on success -# - If @node is not a valid block device, DeviceNotFound -# - If @name is not found or if hashing has failed, GenericError with an -# explanation +# Features: +# +# @unstable: This command is meant for debugging. +# +# Returns: +# BlockDirtyBitmapSha256 +# +# Errors: +# - If @node is not a valid block device, DeviceNotFound +# - If @name is not found or if hashing has failed, GenericError +# with an explanation # # Since: 2.10 ## { 'command': 'x-debug-block-dirty-bitmap-sha256', - 'data': 'BlockDirtyBitmap', 'returns': 'BlockDirtyBitmapSha256' } + 'data': 'BlockDirtyBitmap', 'returns': 'BlockDirtyBitmapSha256', + 'features': [ 'unstable' ], + 'allow-preconfig': true } ## # @blockdev-mirror: # # Start mirroring a block device's writes to a new destination. # -# @job-id: identifier for the newly-created block job. If -# omitted, the device name will be used. (Since 2.7) +# @job-id: identifier for the newly-created block job. If omitted, +# the device name will be used. (Since 2.7) # -# @device: The device name or node-name of a root node whose writes should be -# mirrored. +# @device: The device name or node-name of a root node whose writes +# should be mirrored. # -# @target: the id or node-name of the block device to mirror to. This mustn't be -# attached to guest. +# @target: the id or node-name of the block device to mirror to. This +# mustn't be attached to guest. # # @replaces: with sync=full graph node name to be replaced by the new -# image when a whole image copy is done. This can be used to repair -# broken Quorum files. By default, @device is replaced, although -# implicitly created filters on it are kept. +# image when a whole image copy is done. This can be used to +# repair broken Quorum files. By default, @device is replaced, +# although implicitly created filters on it are kept. # -# @speed: the maximum speed, in bytes per second +# @speed: the maximum speed, in bytes per second # -# @sync: what parts of the disk image should be copied to the destination -# (all the disk, only the sectors allocated in the topmost image, or -# only new I/O). +# @sync: what parts of the disk image should be copied to the +# destination (all the disk, only the sectors allocated in the +# topmost image, or only new I/O). # -# @granularity: granularity of the dirty bitmap, default is 64K -# if the image format doesn't have clusters, 4K if the clusters -# are smaller than that, else the cluster size. Must be a -# power of 2 between 512 and 64M +# @granularity: granularity of the dirty bitmap, default is 64K if the +# image format doesn't have clusters, 4K if the clusters are +# smaller than that, else the cluster size. Must be a power of 2 +# between 512 and 64M # -# @buf-size: maximum amount of data in flight from source to -# target +# @buf-size: maximum amount of data in flight from source to target # # @on-source-error: the action to take on an error on the source, -# default 'report'. 'stop' and 'enospc' can only be used -# if the block device supports io-status (see BlockInfo). +# default 'report'. 'stop' and 'enospc' can only be used if the +# block device supports io-status (see BlockInfo). # # @on-target-error: the action to take on an error on the target, -# default 'report' (no limitations, since this applies to -# a different block device than @device). +# default 'report' (no limitations, since this applies to a +# different block device than @device). # # @filter-node-name: the node name that should be assigned to the -# filter driver that the mirror job inserts into the graph -# above @device. If this option is not given, a node name is -# autogenerated. (Since: 2.9) -# -# @copy-mode: when to copy data to the destination; defaults to 'background' -# (Since: 3.0) -# -# @auto-finalize: When false, this job will wait in a PENDING state after it has -# finished its work, waiting for @block-job-finalize before -# making any block graph changes. -# When true, this job will automatically -# perform its abort or commit actions. -# Defaults to true. (Since 3.1) -# -# @auto-dismiss: When false, this job will wait in a CONCLUDED state after it -# has completely ceased all work, and awaits @block-job-dismiss. -# When true, this job will automatically disappear from the query -# list without user intervention. -# Defaults to true. (Since 3.1) -# Returns: nothing on success. +# filter driver that the mirror job inserts into the graph above +# @device. If this option is not given, a node name is +# autogenerated. (Since: 2.9) +# +# @copy-mode: when to copy data to the destination; defaults to +# 'background' (Since: 3.0) +# +# @auto-finalize: When false, this job will wait in a PENDING state +# after it has finished its work, waiting for @block-job-finalize +# before making any block graph changes. When true, this job will +# automatically perform its abort or commit actions. Defaults to +# true. (Since 3.1) +# +# @auto-dismiss: When false, this job will wait in a CONCLUDED state +# after it has completely ceased all work, and awaits +# @block-job-dismiss. When true, this job will automatically +# disappear from the query list without user intervention. +# Defaults to true. (Since 3.1) # # Since: 2.6 # # Example: # -# -> { "execute": "blockdev-mirror", -# "arguments": { "device": "ide-hd0", -# "target": "target0", -# "sync": "full" } } -# <- { "return": {} } -# +# -> { "execute": "blockdev-mirror", +# "arguments": { "device": "ide-hd0", +# "target": "target0", +# "sync": "full" } } +# <- { "return": {} } ## { 'command': 'blockdev-mirror', 'data': { '*job-id': 'str', 'device': 'str', 'target': 'str', @@ -2288,7 +2550,8 @@ '*on-target-error': 'BlockdevOnError', '*filter-node-name': 'str', '*copy-mode': 'MirrorCopyMode', - '*auto-finalize': 'bool', '*auto-dismiss': 'bool' } } + '*auto-finalize': 'bool', '*auto-dismiss': 'bool' }, + 'allow-preconfig': true } ## # @BlockIOThrottle: @@ -2311,59 +2574,53 @@ # # @iops_wr: write I/O operations per second # -# @bps_max: total throughput limit during bursts, -# in bytes (Since 1.7) +# @bps_max: total throughput limit during bursts, in bytes (Since 1.7) # -# @bps_rd_max: read throughput limit during bursts, -# in bytes (Since 1.7) +# @bps_rd_max: read throughput limit during bursts, in bytes (Since +# 1.7) # -# @bps_wr_max: write throughput limit during bursts, -# in bytes (Since 1.7) +# @bps_wr_max: write throughput limit during bursts, in bytes (Since +# 1.7) # -# @iops_max: total I/O operations per second during bursts, -# in bytes (Since 1.7) +# @iops_max: total I/O operations per second during bursts, in bytes +# (Since 1.7) # -# @iops_rd_max: read I/O operations per second during bursts, -# in bytes (Since 1.7) +# @iops_rd_max: read I/O operations per second during bursts, in bytes +# (Since 1.7) # -# @iops_wr_max: write I/O operations per second during bursts, -# in bytes (Since 1.7) +# @iops_wr_max: write I/O operations per second during bursts, in +# bytes (Since 1.7) # -# @bps_max_length: maximum length of the @bps_max burst -# period, in seconds. It must only -# be set if @bps_max is set as well. -# Defaults to 1. (Since 2.6) +# @bps_max_length: maximum length of the @bps_max burst period, in +# seconds. It must only be set if @bps_max is set as well. +# Defaults to 1. (Since 2.6) # -# @bps_rd_max_length: maximum length of the @bps_rd_max -# burst period, in seconds. It must only -# be set if @bps_rd_max is set as well. -# Defaults to 1. (Since 2.6) +# @bps_rd_max_length: maximum length of the @bps_rd_max burst period, +# in seconds. It must only be set if @bps_rd_max is set as well. +# Defaults to 1. (Since 2.6) # -# @bps_wr_max_length: maximum length of the @bps_wr_max -# burst period, in seconds. It must only -# be set if @bps_wr_max is set as well. -# Defaults to 1. (Since 2.6) +# @bps_wr_max_length: maximum length of the @bps_wr_max burst period, +# in seconds. It must only be set if @bps_wr_max is set as well. +# Defaults to 1. (Since 2.6) # -# @iops_max_length: maximum length of the @iops burst -# period, in seconds. It must only -# be set if @iops_max is set as well. -# Defaults to 1. (Since 2.6) +# @iops_max_length: maximum length of the @iops burst period, in +# seconds. It must only be set if @iops_max is set as well. +# Defaults to 1. (Since 2.6) # -# @iops_rd_max_length: maximum length of the @iops_rd_max -# burst period, in seconds. It must only -# be set if @iops_rd_max is set as well. -# Defaults to 1. (Since 2.6) +# @iops_rd_max_length: maximum length of the @iops_rd_max burst +# period, in seconds. It must only be set if @iops_rd_max is set +# as well. Defaults to 1. (Since 2.6) # -# @iops_wr_max_length: maximum length of the @iops_wr_max -# burst period, in seconds. It must only -# be set if @iops_wr_max is set as well. -# Defaults to 1. (Since 2.6) +# @iops_wr_max_length: maximum length of the @iops_wr_max burst +# period, in seconds. It must only be set if @iops_wr_max is set +# as well. Defaults to 1. (Since 2.6) # # @iops_size: an I/O size in bytes (Since 1.7) # # @group: throttle group name (Since 2.4) # # Features: +# # @deprecated: Member @device is deprecated. Use @id instead. # # Since: 1.1 @@ -2383,35 +2640,55 @@ ## # @ThrottleLimits: # -# Limit parameters for throttling. -# Since some limit combinations are illegal, limits should always be set in one -# transaction. All fields are optional. When setting limits, if a field is -# missing the current value is not changed. +# Limit parameters for throttling. Since some limit combinations are +# illegal, limits should always be set in one transaction. All fields +# are optional. When setting limits, if a field is missing the +# current value is not changed. # # @iops-total: limit total I/O operations per second +# # @iops-total-max: I/O operations burst -# @iops-total-max-length: length of the iops-total-max burst period, in seconds -# It must only be set if @iops-total-max is set as well. +# +# @iops-total-max-length: length of the iops-total-max burst period, +# in seconds It must only be set if @iops-total-max is set as +# well. +# # @iops-read: limit read operations per second +# # @iops-read-max: I/O operations read burst -# @iops-read-max-length: length of the iops-read-max burst period, in seconds -# It must only be set if @iops-read-max is set as well. +# +# @iops-read-max-length: length of the iops-read-max burst period, in +# seconds It must only be set if @iops-read-max is set as well. +# # @iops-write: limit write operations per second +# # @iops-write-max: I/O operations write burst -# @iops-write-max-length: length of the iops-write-max burst period, in seconds -# It must only be set if @iops-write-max is set as well. +# +# @iops-write-max-length: length of the iops-write-max burst period, +# in seconds It must only be set if @iops-write-max is set as +# well. +# # @bps-total: limit total bytes per second +# # @bps-total-max: total bytes burst -# @bps-total-max-length: length of the bps-total-max burst period, in seconds. -# It must only be set if @bps-total-max is set as well. +# +# @bps-total-max-length: length of the bps-total-max burst period, in +# seconds. It must only be set if @bps-total-max is set as well. +# # @bps-read: limit read bytes per second +# # @bps-read-max: total bytes read burst -# @bps-read-max-length: length of the bps-read-max burst period, in seconds -# It must only be set if @bps-read-max is set as well. +# +# @bps-read-max-length: length of the bps-read-max burst period, in +# seconds It must only be set if @bps-read-max is set as well. +# # @bps-write: limit write bytes per second +# # @bps-write-max: total bytes write burst -# @bps-write-max-length: length of the bps-write-max burst period, in seconds -# It must only be set if @bps-write-max is set as well. +# +# @bps-write-max-length: length of the bps-write-max burst period, in +# seconds It must only be set if @bps-write-max is set as well. +# # @iops-size: when limiting by iops max size of an I/O in bytes # # Since: 2.11 @@ -2433,134 +2710,170 @@ # # Properties for throttle-group objects. # -# The options starting with x- are aliases for the same key without x- in -# the @limits object. As indicated by the x- prefix, this is not a stable -# interface and may be removed or changed incompatibly in the future. Use -# @limits for a supported stable interface. -# # @limits: limits to apply for this throttle group # +# Features: +# +# @unstable: All members starting with x- are aliases for the same key +# without x- in the @limits object. This is not a stable +# interface and may be removed or changed incompatibly in the +# future. Use @limits for a supported stable interface. +# # Since: 2.11 ## { 'struct': 'ThrottleGroupProperties', 'data': { '*limits': 'ThrottleLimits', - '*x-iops-total' : 'int', '*x-iops-total-max' : 'int', - '*x-iops-total-max-length' : 'int', '*x-iops-read' : 'int', - '*x-iops-read-max' : 'int', '*x-iops-read-max-length' : 'int', - '*x-iops-write' : 'int', '*x-iops-write-max' : 'int', - '*x-iops-write-max-length' : 'int', '*x-bps-total' : 'int', - '*x-bps-total-max' : 'int', '*x-bps-total-max-length' : 'int', - '*x-bps-read' : 'int', '*x-bps-read-max' : 'int', - '*x-bps-read-max-length' : 'int', '*x-bps-write' : 'int', - '*x-bps-write-max' : 'int', '*x-bps-write-max-length' : 'int', - '*x-iops-size' : 'int' } } + '*x-iops-total': { 'type': 'int', + 'features': [ 'unstable' ] }, + '*x-iops-total-max': { 'type': 'int', + 'features': [ 'unstable' ] }, + '*x-iops-total-max-length': { 'type': 'int', + 'features': [ 'unstable' ] }, + '*x-iops-read': { 'type': 'int', + 'features': [ 'unstable' ] }, + '*x-iops-read-max': { 'type': 'int', + 'features': [ 'unstable' ] }, + '*x-iops-read-max-length': { 'type': 'int', + 'features': [ 'unstable' ] }, + '*x-iops-write': { 'type': 'int', + 'features': [ 'unstable' ] }, + '*x-iops-write-max': { 'type': 'int', + 'features': [ 'unstable' ] }, + '*x-iops-write-max-length': { 'type': 'int', + 'features': [ 'unstable' ] }, + '*x-bps-total': { 'type': 'int', + 'features': [ 'unstable' ] }, + '*x-bps-total-max': { 'type': 'int', + 'features': [ 'unstable' ] }, + '*x-bps-total-max-length': { 'type': 'int', + 'features': [ 'unstable' ] }, + '*x-bps-read': { 'type': 'int', + 'features': [ 'unstable' ] }, + '*x-bps-read-max': { 'type': 'int', + 'features': [ 'unstable' ] }, + '*x-bps-read-max-length': { 'type': 'int', + 'features': [ 'unstable' ] }, + '*x-bps-write': { 'type': 'int', + 'features': [ 'unstable' ] }, + '*x-bps-write-max': { 'type': 'int', + 'features': [ 'unstable' ] }, + '*x-bps-write-max-length': { 'type': 'int', + 'features': [ 'unstable' ] }, + '*x-iops-size': { 'type': 'int', + 'features': [ 'unstable' ] } } } ## # @block-stream: # # Copy data from a backing file into a block device. # -# The block streaming operation is performed in the background until the entire -# backing file has been copied. This command returns immediately once streaming -# has started. The status of ongoing block streaming operations can be checked -# with query-block-jobs. The operation can be stopped before it has completed -# using the block-job-cancel command. -# -# The node that receives the data is called the top image, can be located in -# any part of the chain (but always above the base image; see below) and can be -# specified using its device or node name. Earlier qemu versions only allowed -# 'device' to name the top level node; presence of the 'base-node' parameter -# during introspection can be used as a witness of the enhanced semantics -# of 'device'. -# -# If a base file is specified then sectors are not copied from that base file and -# its backing chain. This can be used to stream a subset of the backing file -# chain instead of flattening the entire image. -# When streaming completes the image file will have the base file as its backing -# file, unless that node was changed while the job was running. In that case, -# base's parent's backing (or filtered, whichever exists) child (i.e., base at -# the beginning of the job) will be the new backing file. -# -# On successful completion the image file is updated to drop the backing file -# and the BLOCK_JOB_COMPLETED event is emitted. -# -# In case @device is a filter node, block-stream modifies the first non-filter -# overlay node below it to point to the new backing node instead of modifying -# @device itself. -# -# @job-id: identifier for the newly-created block job. If -# omitted, the device name will be used. (Since 2.7) +# The block streaming operation is performed in the background until +# the entire backing file has been copied. This command returns +# immediately once streaming has started. The status of ongoing block +# streaming operations can be checked with query-block-jobs. The +# operation can be stopped before it has completed using the +# block-job-cancel command. +# +# The node that receives the data is called the top image, can be +# located in any part of the chain (but always above the base image; +# see below) and can be specified using its device or node name. +# Earlier qemu versions only allowed 'device' to name the top level +# node; presence of the 'base-node' parameter during introspection can +# be used as a witness of the enhanced semantics of 'device'. +# +# If a base file is specified then sectors are not copied from that +# base file and its backing chain. This can be used to stream a +# subset of the backing file chain instead of flattening the entire +# image. When streaming completes the image file will have the base +# file as its backing file, unless that node was changed while the job +# was running. In that case, base's parent's backing (or filtered, +# whichever exists) child (i.e., base at the beginning of the job) +# will be the new backing file. +# +# On successful completion the image file is updated to drop the +# backing file and the BLOCK_JOB_COMPLETED event is emitted. +# +# In case @device is a filter node, block-stream modifies the first +# non-filter overlay node below it to point to the new backing node +# instead of modifying @device itself. +# +# @job-id: identifier for the newly-created block job. If omitted, +# the device name will be used. (Since 2.7) # # @device: the device or node name of the top image # -# @base: the common backing file name. -# It cannot be set if @base-node or @bottom is also set. +# @base: the common backing file name. It cannot be set if @base-node +# or @bottom is also set. # -# @base-node: the node name of the backing file. -# It cannot be set if @base or @bottom is also set. (Since 2.8) +# @base-node: the node name of the backing file. It cannot be set if +# @base or @bottom is also set. (Since 2.8) # # @bottom: the last node in the chain that should be streamed into -# top. It cannot be set if @base or @base-node is also set. -# It cannot be filter node. (Since 6.0) +# top. It cannot be set if @base or @base-node is also set. It +# cannot be filter node. (Since 6.0) # -# @backing-file: The backing file string to write into the top -# image. This filename is not validated. +# @backing-file: The backing file string to write into the top image. +# This filename is not validated. # -# If a pathname string is such that it cannot be -# resolved by QEMU, that means that subsequent QMP or -# HMP commands must use node-names for the image in -# question, as filename lookup methods will fail. +# If a pathname string is such that it cannot be resolved by QEMU, +# that means that subsequent QMP or HMP commands must use +# node-names for the image in question, as filename lookup methods +# will fail. # -# If not specified, QEMU will automatically determine -# the backing file string to use, or error out if there -# is no obvious choice. Care should be taken when -# specifying the string, to specify a valid filename or -# protocol. -# (Since 2.1) +# If not specified, QEMU will automatically determine the backing +# file string to use, or error out if there is no obvious choice. +# Care should be taken when specifying the string, to specify a +# valid filename or protocol. (Since 2.1) +# +# @backing-mask-protocol: If true, replace any protocol mentioned in +# the 'backing file format' with 'raw', rather than storing the +# protocol name as the backing format. Can be used even when no +# image header will be updated (default false; since 9.0). # # @speed: the maximum speed, in bytes per second # -# @on-error: the action to take on an error (default report). -# 'stop' and 'enospc' can only be used if the block device -# supports io-status (see BlockInfo). Since 1.3. +# @on-error: the action to take on an error (default report). 'stop' +# and 'enospc' can only be used if the block device supports +# io-status (see BlockInfo). (Since 1.3) # # @filter-node-name: the node name that should be assigned to the -# filter driver that the stream job inserts into the graph -# above @device. If this option is not given, a node name is -# autogenerated. (Since: 6.0) -# -# @auto-finalize: When false, this job will wait in a PENDING state after it has -# finished its work, waiting for @block-job-finalize before -# making any block graph changes. -# When true, this job will automatically -# perform its abort or commit actions. -# Defaults to true. (Since 3.1) -# -# @auto-dismiss: When false, this job will wait in a CONCLUDED state after it -# has completely ceased all work, and awaits @block-job-dismiss. -# When true, this job will automatically disappear from the query -# list without user intervention. -# Defaults to true. (Since 3.1) -# -# Returns: - Nothing on success. -# - If @device does not exist, DeviceNotFound. +# filter driver that the stream job inserts into the graph above +# @device. If this option is not given, a node name is +# autogenerated. (Since: 6.0) +# +# @auto-finalize: When false, this job will wait in a PENDING state +# after it has finished its work, waiting for @block-job-finalize +# before making any block graph changes. When true, this job will +# automatically perform its abort or commit actions. Defaults to +# true. (Since 3.1) +# +# @auto-dismiss: When false, this job will wait in a CONCLUDED state +# after it has completely ceased all work, and awaits +# @block-job-dismiss. When true, this job will automatically +# disappear from the query list without user intervention. +# Defaults to true. (Since 3.1) +# +# Errors: +# - If @device does not exist, DeviceNotFound. # # Since: 1.1 # # Example: # -# -> { "execute": "block-stream", -# "arguments": { "device": "virtio0", -# "base": "/tmp/master.qcow2" } } -# <- { "return": {} } -# +# -> { "execute": "block-stream", +# "arguments": { "device": "virtio0", +# "base": "/tmp/master.qcow2" } } +# <- { "return": {} } ## { 'command': 'block-stream', 'data': { '*job-id': 'str', 'device': 'str', '*base': 'str', - '*base-node': 'str', '*backing-file': 'str', '*bottom': 'str', + '*base-node': 'str', '*backing-file': 'str', + '*backing-mask-protocol': 'bool', + '*bottom': 'str', '*speed': 'int', '*on-error': 'BlockdevOnError', '*filter-node-name': 'str', - '*auto-finalize': 'bool', '*auto-dismiss': 'bool' } } + '*auto-finalize': 'bool', '*auto-dismiss': 'bool' }, + 'allow-preconfig': true } ## # @block-job-set-speed: @@ -2571,171 +2884,220 @@ # # Throttling can be disabled by setting the speed to 0. # -# @device: The job identifier. This used to be a device name (hence -# the name of the parameter), but since QEMU 2.7 it can have -# other values. +# @device: The job identifier. This used to be a device name (hence +# the name of the parameter), but since QEMU 2.7 it can have other +# values. # # @speed: the maximum speed, in bytes per second, or 0 for unlimited. -# Defaults to 0. +# Defaults to 0. # -# Returns: - Nothing on success -# - If no background operation is active on this device, DeviceNotActive +# Errors: +# - If no background operation is active on this device, +# DeviceNotActive # # Since: 1.1 ## { 'command': 'block-job-set-speed', - 'data': { 'device': 'str', 'speed': 'int' } } + 'data': { 'device': 'str', 'speed': 'int' }, + 'allow-preconfig': true } ## # @block-job-cancel: # # Stop an active background block operation. # -# This command returns immediately after marking the active background block -# operation for cancellation. It is an error to call this command if no -# operation is in progress. +# This command returns immediately after marking the active background +# block operation for cancellation. It is an error to call this +# command if no operation is in progress. # # The operation will cancel as soon as possible and then emit the -# BLOCK_JOB_CANCELLED event. Before that happens the job is still visible when -# enumerated using query-block-jobs. -# -# Note that if you issue 'block-job-cancel' after 'drive-mirror' has indicated -# (via the event BLOCK_JOB_READY) that the source and destination are -# synchronized, then the event triggered by this command changes to -# BLOCK_JOB_COMPLETED, to indicate that the mirroring has ended and the -# destination now has a point-in-time copy tied to the time of the cancellation. -# -# For streaming, the image file retains its backing file unless the streaming -# operation happens to complete just as it is being cancelled. A new streaming -# operation can be started at a later time to finish copying all data from the -# backing file. -# -# @device: The job identifier. This used to be a device name (hence -# the name of the parameter), but since QEMU 2.7 it can have -# other values. -# -# @force: If true, and the job has already emitted the event BLOCK_JOB_READY, -# abandon the job immediately (even if it is paused) instead of waiting -# for the destination to complete its final synchronization (since 1.3) -# -# Returns: - Nothing on success -# - If no background operation is active on this device, DeviceNotActive +# BLOCK_JOB_CANCELLED event. Before that happens the job is still +# visible when enumerated using query-block-jobs. +# +# Note that if you issue 'block-job-cancel' after 'drive-mirror' has +# indicated (via the event BLOCK_JOB_READY) that the source and +# destination are synchronized, then the event triggered by this +# command changes to BLOCK_JOB_COMPLETED, to indicate that the +# mirroring has ended and the destination now has a point-in-time copy +# tied to the time of the cancellation. +# +# For streaming, the image file retains its backing file unless the +# streaming operation happens to complete just as it is being +# cancelled. A new streaming operation can be started at a later time +# to finish copying all data from the backing file. +# +# @device: The job identifier. This used to be a device name (hence +# the name of the parameter), but since QEMU 2.7 it can have other +# values. +# +# @force: If true, and the job has already emitted the event +# BLOCK_JOB_READY, abandon the job immediately (even if it is +# paused) instead of waiting for the destination to complete its +# final synchronization (since 1.3) +# +# Errors: +# - If no background operation is active on this device, +# DeviceNotActive # # Since: 1.1 ## -{ 'command': 'block-job-cancel', 'data': { 'device': 'str', '*force': 'bool' } } +{ 'command': 'block-job-cancel', 'data': { 'device': 'str', '*force': 'bool' }, + 'allow-preconfig': true } ## # @block-job-pause: # # Pause an active background block operation. # -# This command returns immediately after marking the active background block -# operation for pausing. It is an error to call this command if no -# operation is in progress or if the job is already paused. +# This command returns immediately after marking the active background +# block operation for pausing. It is an error to call this command if +# no operation is in progress or if the job is already paused. # -# The operation will pause as soon as possible. No event is emitted when -# the operation is actually paused. Cancelling a paused job automatically -# resumes it. +# The operation will pause as soon as possible. No event is emitted +# when the operation is actually paused. Cancelling a paused job +# automatically resumes it. # -# @device: The job identifier. This used to be a device name (hence -# the name of the parameter), but since QEMU 2.7 it can have -# other values. +# @device: The job identifier. This used to be a device name (hence +# the name of the parameter), but since QEMU 2.7 it can have other +# values. # -# Returns: - Nothing on success -# - If no background operation is active on this device, DeviceNotActive +# Errors: +# - If no background operation is active on this device, +# DeviceNotActive # # Since: 1.3 ## -{ 'command': 'block-job-pause', 'data': { 'device': 'str' } } +{ 'command': 'block-job-pause', 'data': { 'device': 'str' }, + 'allow-preconfig': true } ## # @block-job-resume: # # Resume an active background block operation. # -# This command returns immediately after resuming a paused background block -# operation. It is an error to call this command if no operation is in -# progress or if the job is not paused. +# This command returns immediately after resuming a paused background +# block operation. It is an error to call this command if no +# operation is in progress or if the job is not paused. # # This command also clears the error status of the job. # -# @device: The job identifier. This used to be a device name (hence -# the name of the parameter), but since QEMU 2.7 it can have -# other values. +# @device: The job identifier. This used to be a device name (hence +# the name of the parameter), but since QEMU 2.7 it can have other +# values. # -# Returns: - Nothing on success -# - If no background operation is active on this device, DeviceNotActive +# Errors: +# - If no background operation is active on this device, +# DeviceNotActive # # Since: 1.3 ## -{ 'command': 'block-job-resume', 'data': { 'device': 'str' } } +{ 'command': 'block-job-resume', 'data': { 'device': 'str' }, + 'allow-preconfig': true } ## # @block-job-complete: # -# Manually trigger completion of an active background block operation. This -# is supported for drive mirroring, where it also switches the device to -# write to the target path only. The ability to complete is signaled with -# a BLOCK_JOB_READY event. +# Manually trigger completion of an active background block operation. +# This is supported for drive mirroring, where it also switches the +# device to write to the target path only. The ability to complete is +# signaled with a BLOCK_JOB_READY event. # -# This command completes an active background block operation synchronously. -# The ordering of this command's return with the BLOCK_JOB_COMPLETED event -# is not defined. Note that if an I/O error occurs during the processing of -# this command: 1) the command itself will fail; 2) the error will be processed -# according to the rerror/werror arguments that were specified when starting -# the operation. +# This command completes an active background block operation +# synchronously. The ordering of this command's return with the +# BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error +# occurs during the processing of this command: 1) the command itself +# will fail; 2) the error will be processed according to the +# rerror/werror arguments that were specified when starting the +# operation. # # A cancelled or paused job cannot be completed. # -# @device: The job identifier. This used to be a device name (hence -# the name of the parameter), but since QEMU 2.7 it can have -# other values. +# @device: The job identifier. This used to be a device name (hence +# the name of the parameter), but since QEMU 2.7 it can have other +# values. # -# Returns: - Nothing on success -# - If no background operation is active on this device, DeviceNotActive +# Errors: +# - If no background operation is active on this device, +# DeviceNotActive # # Since: 1.3 ## -{ 'command': 'block-job-complete', 'data': { 'device': 'str' } } +{ 'command': 'block-job-complete', 'data': { 'device': 'str' }, + 'allow-preconfig': true } ## # @block-job-dismiss: # -# For jobs that have already concluded, remove them from the block-job-query -# list. This command only needs to be run for jobs which were started with -# QEMU 2.12+ job lifetime management semantics. +# For jobs that have already concluded, remove them from the +# block-job-query list. This command only needs to be run for jobs +# which were started with QEMU 2.12+ job lifetime management +# semantics. # -# 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 the -# BLOCK_JOB_READY event, block-job-cancel or block-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 the BLOCK_JOB_READY event, block-job-cancel or +# block-job-complete will still need to be used as appropriate. # # @id: The job identifier. # -# Returns: Nothing on success -# # Since: 2.12 ## -{ 'command': 'block-job-dismiss', 'data': { 'id': 'str' } } +{ 'command': 'block-job-dismiss', 'data': { 'id': 'str' }, + 'allow-preconfig': true } ## # @block-job-finalize: # # Once a job that has manual=true reaches the pending state, it can be -# instructed to finalize any graph changes and do any necessary cleanup -# via this command. -# 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. +# instructed to finalize any graph changes and do any necessary +# cleanup via this command. 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 job identifier. # -# Returns: Nothing on success -# # Since: 2.12 ## -{ 'command': 'block-job-finalize', 'data': { 'id': 'str' } } +{ 'command': 'block-job-finalize', 'data': { 'id': 'str' }, + 'allow-preconfig': true } + +## +# @BlockJobChangeOptionsMirror: +# +# @copy-mode: Switch to this copy mode. Currently, only the switch +# from 'background' to 'write-blocking' is implemented. +# +# Since: 8.2 +## +{ 'struct': 'BlockJobChangeOptionsMirror', + 'data': { 'copy-mode' : 'MirrorCopyMode' } } + +## +# @BlockJobChangeOptions: +# +# Block job options that can be changed after job creation. +# +# @id: The job identifier +# +# @type: The job type +# +# Since: 8.2 +## +{ 'union': 'BlockJobChangeOptions', + 'base': { 'id': 'str', 'type': 'JobType' }, + 'discriminator': 'type', + 'data': { 'mirror': 'BlockJobChangeOptionsMirror' } } + +## +# @block-job-change: +# +# Change the block job's options. +# +# Since: 8.2 +## +{ 'command': 'block-job-change', + 'data': 'BlockJobChangeOptions', 'boxed': true } ## # @BlockdevDiscardOptions: @@ -2743,6 +3105,7 @@ # Determines how to handle discard requests. # # @ignore: Ignore the request +# # @unmap: Forward as an unmap request # # Since: 2.9 @@ -2754,12 +3117,16 @@ # @BlockdevDetectZeroesOptions: # # Describes the operation mode for the automatic conversion of plain -# zero writes by the OS to driver specific optimized zero write commands. +# zero writes by the OS to driver specific optimized zero write +# commands. # # @off: Disabled (default) +# # @on: Enabled -# @unmap: Enabled and even try to unmap blocks if possible. This requires -# also that @BlockdevDiscardOptions is set to unmap for this device. +# +# @unmap: Enabled and even try to unmap blocks if possible. This +# requires also that @BlockdevDiscardOptions is set to unmap for +# this device. # # Since: 2.1 ## @@ -2772,14 +3139,16 @@ # Selects the AIO backend to handle I/O requests # # @threads: Use qemu's thread pool +# # @native: Use native AIO backend (only Linux and Windows) +# # @io_uring: Use linux io_uring (since 5.0) # # Since: 2.9 ## { 'enum': 'BlockdevAioOptions', 'data': [ 'threads', 'native', - { 'name': 'io_uring', 'if': 'defined(CONFIG_LINUX_IO_URING)' } ] } + { 'name': 'io_uring', 'if': 'CONFIG_LINUX_IO_URING' } ] } ## # @BlockdevCacheOptions: @@ -2787,9 +3156,9 @@ # Includes cache-related options for block devices # # @direct: enables use of O_DIRECT (bypass the host page cache; -# default: false) -# @no-flush: ignore any flush requests for the device (default: -# false) +# default: false) +# +# @no-flush: ignore any flush requests for the device (default: false) # # Since: 2.9 ## @@ -2803,23 +3172,42 @@ # Drivers that are supported in block device operations. # # @throttle: Since 2.11 +# # @nvme: Since 2.12 +# # @copy-on-read: Since 3.0 +# # @blklogwrites: Since 3.0 +# # @blkreplay: Since 4.2 +# # @compress: Since 5.0 # +# @copy-before-write: Since 6.2 +# +# @snapshot-access: Since 7.0 +# # Since: 2.9 ## { 'enum': 'BlockdevDriver', 'data': [ 'blkdebug', 'blklogwrites', 'blkreplay', 'blkverify', 'bochs', - 'cloop', 'compress', 'copy-on-read', 'dmg', 'file', 'ftp', 'ftps', - 'gluster', 'host_cdrom', 'host_device', 'http', 'https', 'iscsi', - 'luks', 'nbd', 'nfs', 'null-aio', 'null-co', 'nvme', 'parallels', - 'preallocate', 'qcow', 'qcow2', 'qed', 'quorum', 'raw', 'rbd', - { 'name': 'replication', 'if': 'defined(CONFIG_REPLICATION)' }, - 'sheepdog', - 'ssh', 'throttle', 'vdi', 'vhdx', 'vmdk', 'vpc', 'vvfat' ] } + 'cloop', 'compress', 'copy-before-write', 'copy-on-read', 'dmg', + 'file', 'snapshot-access', 'ftp', 'ftps', 'gluster', + {'name': 'host_cdrom', 'if': 'HAVE_HOST_BLOCK_DEVICE' }, + {'name': 'host_device', 'if': 'HAVE_HOST_BLOCK_DEVICE' }, + 'http', 'https', + { 'name': 'io_uring', 'if': 'CONFIG_BLKIO' }, + 'iscsi', + 'luks', 'nbd', 'nfs', 'null-aio', 'null-co', 'nvme', + { 'name': 'nvme-io_uring', 'if': 'CONFIG_BLKIO' }, + 'parallels', 'preallocate', 'qcow', 'qcow2', 'qed', 'quorum', + 'raw', 'rbd', + { 'name': 'replication', 'if': 'CONFIG_REPLICATION' }, + 'ssh', 'throttle', 'vdi', 'vhdx', + { 'name': 'virtio-blk-vfio-pci', 'if': 'CONFIG_BLKIO' }, + { 'name': 'virtio-blk-vhost-user', 'if': 'CONFIG_BLKIO' }, + { 'name': 'virtio-blk-vhost-vdpa', 'if': 'CONFIG_BLKIO' }, + 'vmdk', 'vpc', 'vvfat' ] } ## # @BlockdevOptionsFile: @@ -2827,30 +3215,44 @@ # Driver specific block device options for the file backend. # # @filename: path to the image file -# @pr-manager: the id for the object that will handle persistent reservations -# for this device (default: none, forward the commands via SG_IO; -# since 2.11) +# +# @pr-manager: the id for the object that will handle persistent +# reservations for this device (default: none, forward the +# commands via SG_IO; since 2.11) +# # @aio: AIO backend (default: threads) (since: 2.8) -# @locking: whether to enable file locking. If set to 'auto', only enable -# when Open File Descriptor (OFD) locking API is available -# (default: auto, since 2.10) -# @drop-cache: invalidate page cache during live migration. This prevents -# stale data on the migration destination with cache.direct=off. -# Currently only supported on Linux hosts. -# (default: on, since: 4.0) -# @x-check-cache-dropped: whether to check that page cache was dropped on live -# migration. May cause noticeable delays if the image -# file is large, do not use in production. -# (default: off) (since: 3.0) +# +# @aio-max-batch: maximum number of requests to batch together into a +# single submission in the AIO backend. The smallest value +# between this and the aio-max-batch value of the IOThread object +# is chosen. 0 means that the AIO backend will handle it +# automatically. (default: 0, since 6.2) +# +# @locking: whether to enable file locking. If set to 'auto', only +# enable when Open File Descriptor (OFD) locking API is available +# (default: auto, since 2.10) +# +# @drop-cache: invalidate page cache during live migration. This +# prevents stale data on the migration destination with +# cache.direct=off. Currently only supported on Linux hosts. +# (default: on, since: 4.0) +# +# @x-check-cache-dropped: whether to check that page cache was dropped +# on live migration. May cause noticeable delays if the image +# file is large, do not use in production. (default: off) +# (since: 3.0) # # Features: -# @dynamic-auto-read-only: If present, enabled auto-read-only means that the -# driver will open the image read-only at first, -# dynamically reopen the image file read-write when -# the first writer is attached to the node and reopen -# read-only when the last writer is detached. This -# allows giving QEMU write permissions only on demand -# when an operation actually needs write access. +# +# @dynamic-auto-read-only: If present, enabled auto-read-only means +# that the driver will open the image read-only at first, +# dynamically reopen the image file read-write when the first +# writer is attached to the node and reopen read-only when the +# last writer is detached. This allows giving QEMU write +# permissions only on demand when an operation actually needs +# write access. +# +# @unstable: Member x-check-cache-dropped is meant for debugging. # # Since: 2.9 ## @@ -2859,11 +3261,13 @@ '*pr-manager': 'str', '*locking': 'OnOffAuto', '*aio': 'BlockdevAioOptions', + '*aio-max-batch': 'int', '*drop-cache': {'type': 'bool', - 'if': 'defined(CONFIG_LINUX)'}, - '*x-check-cache-dropped': 'bool' }, + 'if': 'CONFIG_LINUX'}, + '*x-check-cache-dropped': { 'type': 'bool', + 'features': [ 'unstable' ] } }, 'features': [ { 'name': 'dynamic-auto-read-only', - 'if': 'defined(CONFIG_POSIX)' } ] } + 'if': 'CONFIG_POSIX' } ] } ## # @BlockdevOptionsNull: @@ -2871,11 +3275,14 @@ # Driver specific block device options for the null backend. # # @size: size of the device in bytes. +# # @latency-ns: emulated latency (in nanoseconds) in processing -# requests. Default to zero which completes requests immediately. -# (Since 2.4) -# @read-zeroes: if true, reads from the device produce zeroes; if false, the -# buffer is left unchanged. (default: false; since: 4.1) +# requests. Default to zero which completes requests immediately. +# (Since 2.4) +# +# @read-zeroes: if true, reads from the device produce zeroes; if +# false, the buffer is left unchanged. +# (default: false; since: 4.1) # # Since: 2.9 ## @@ -2887,8 +3294,9 @@ # # Driver specific block device options for the NVMe backend. # -# @device: PCI controller address of the NVMe device in -# format hhhh:bb:ss.f (host:bus:slot.function) +# @device: PCI controller address of the NVMe device in format +# hhhh:bb:ss.f (host:bus:slot.function) +# # @namespace: namespace number of the device, starting from 1. # # Note that the PCI @device must have been unbound from any host @@ -2905,13 +3313,17 @@ # Driver specific block device options for the vvfat protocol. # # @dir: directory to be exported as FAT image +# # @fat-type: FAT type: 12, 16 or 32 -# @floppy: whether to export a floppy image (true) or -# partitioned hard disk (false; default) -# @label: set the volume label, limited to 11 bytes. FAT16 and -# FAT32 traditionally have some restrictions on labels, which are -# ignored by most operating systems. Defaults to "QEMU VVFAT". -# (since 2.4) +# +# @floppy: whether to export a floppy image (true) or partitioned hard +# disk (false; default) +# +# @label: set the volume label, limited to 11 bytes. FAT16 and FAT32 +# traditionally have some restrictions on labels, which are +# ignored by most operating systems. Defaults to "QEMU VVFAT". +# (since 2.4) +# # @rw: whether to allow write operations (default: false) # # Since: 2.9 @@ -2923,8 +3335,8 @@ ## # @BlockdevOptionsGenericFormat: # -# Driver specific block device options for image format that have no option -# besides their data source. +# Driver specific block device options for image format that have no +# option besides their data source. # # @file: reference to or definition of the data source block device # @@ -2938,26 +3350,28 @@ # # Driver specific block device options for LUKS. # -# @key-secret: the ID of a QCryptoSecret object providing -# the decryption key (since 2.6). Mandatory except when -# doing a metadata-only probe of the image. +# @key-secret: the ID of a QCryptoSecret object providing the +# decryption key (since 2.6). Mandatory except when doing a +# metadata-only probe of the image. +# +# @header: block device holding a detached LUKS header. (since 9.0) # # Since: 2.9 ## { 'struct': 'BlockdevOptionsLUKS', 'base': 'BlockdevOptionsGenericFormat', - 'data': { '*key-secret': 'str' } } - + 'data': { '*key-secret': 'str', + '*header': 'BlockdevRef'} } ## # @BlockdevOptionsGenericCOWFormat: # -# Driver specific block device options for image format that have no option -# besides their data source and an optional backing file. +# Driver specific block device options for image format that have no +# option besides their data source and an optional backing file. # # @backing: reference to or definition of the backing file block -# device, null disables the backing file entirely. -# Defaults to the backing file stored the image file. +# device, null disables the backing file entirely. Defaults to +# the backing file stored the image file. # # Since: 2.9 ## @@ -2972,11 +3386,11 @@ # # @none: Do not perform any checks # -# @constant: Perform only checks which can be done in constant time and -# without reading anything from disk +# @constant: Perform only checks which can be done in constant time +# and without reading anything from disk # -# @cached: Perform only checks which can be done without reading anything -# from disk +# @cached: Perform only checks which can be done without reading +# anything from disk # # @all: Perform all available overlap checks # @@ -2988,14 +3402,32 @@ ## # @Qcow2OverlapCheckFlags: # -# Structure of flags for each metadata structure. Setting a field to 'true' -# makes qemu guard that structure against unintended overwriting. The default -# value is chosen according to the template given. +# Structure of flags for each metadata structure. Setting a field to +# 'true' makes QEMU guard that Qcow2 format structure against +# unintended overwriting. See Qcow2 format specification for detailed +# information on these structures. The default value is chosen +# according to the template given. +# +# @template: Specifies a template mode which can be adjusted using the +# other flags, defaults to 'cached' +# +# @main-header: Qcow2 format header +# +# @active-l1: Qcow2 active L1 table +# +# @active-l2: Qcow2 active L2 table # -# @template: Specifies a template mode which can be adjusted using the other -# flags, defaults to 'cached' +# @refcount-table: Qcow2 refcount table # -# @bitmap-directory: since 3.0 +# @refcount-block: Qcow2 refcount blocks +# +# @snapshot-table: Qcow2 snapshot table +# +# @inactive-l1: Qcow2 inactive L1 tables +# +# @inactive-l2: Qcow2 inactive L2 tables +# +# @bitmap-directory: Qcow2 bitmap directory (since 3.0) # # Since: 2.9 ## @@ -3014,11 +3446,11 @@ ## # @Qcow2OverlapChecks: # -# Specifies which metadata structures should be guarded against unintended -# overwriting. +# Specifies which metadata structures should be guarded against +# unintended overwriting. # -# @flags: set of flags for separate specification of each metadata structure -# type +# @flags: set of flags for separate specification of each metadata +# structure type # # @mode: named mode which chooses a specific set of flags # @@ -3041,6 +3473,8 @@ ## # @BlockdevQcowEncryption: # +# @format: encryption format +# # Since: 2.10 ## { 'union': 'BlockdevQcowEncryption', @@ -3053,9 +3487,8 @@ # # Driver specific block device options for qcow. # -# @encrypt: Image decryption options. Mandatory for -# encrypted images, except when doing a metadata-only -# probe of the image. +# @encrypt: Image decryption options. Mandatory for encrypted images, +# except when doing a metadata-only probe of the image. # # Since: 2.10 ## @@ -3063,10 +3496,9 @@ 'base': 'BlockdevOptionsGenericCOWFormat', 'data': { '*encrypt': 'BlockdevQcowEncryption' } } - - ## # @BlockdevQcow2EncryptionFormat: +# # @aes: AES-CBC with plain64 initialization vectors # # Since: 2.10 @@ -3077,6 +3509,8 @@ ## # @BlockdevQcow2Encryption: # +# @format: encryption format +# # Since: 2.10 ## { 'union': 'BlockdevQcow2Encryption', @@ -3088,11 +3522,11 @@ ## # @BlockdevOptionsPreallocate: # -# Filter driver intended to be inserted between format and protocol node -# and do preallocation in protocol node on write. +# Filter driver intended to be inserted between format and protocol +# node and do preallocation in protocol node on write. # # @prealloc-align: on preallocation, align file length to this number, -# default 1048576 (1M) +# default 1048576 (1M) # # @prealloc-size: how much to preallocate, default 134217728 (128M) # @@ -3107,51 +3541,63 @@ # # Driver specific block device options for qcow2. # -# @lazy-refcounts: whether to enable the lazy refcounts -# feature (default is taken from the image file) +# @lazy-refcounts: whether to enable the lazy refcounts feature +# (default is taken from the image file) # -# @pass-discard-request: whether discard requests to the qcow2 -# device should be forwarded to the data source +# @pass-discard-request: whether discard requests to the qcow2 device +# should be forwarded to the data source # # @pass-discard-snapshot: whether discard requests for the data source -# should be issued when a snapshot operation (e.g. -# deleting a snapshot) frees clusters in the qcow2 file +# should be issued when a snapshot operation (e.g. deleting a +# snapshot) frees clusters in the qcow2 file # # @pass-discard-other: whether discard requests for the data source -# should be issued on other occasions where a cluster -# gets freed -# -# @overlap-check: which overlap checks to perform for writes -# to the image, defaults to 'cached' (since 2.2) -# -# @cache-size: the maximum total size of the L2 table and -# refcount block caches in bytes (since 2.2) -# -# @l2-cache-size: the maximum size of the L2 table cache in -# bytes (since 2.2) +# should be issued on other occasions where a cluster gets freed +# +# @discard-no-unref: when enabled, data clusters will remain +# preallocated when they are no longer used, e.g. because they are +# discarded or converted to zero clusters. As usual, whether the +# old data is discarded or kept on the protocol level (i.e. in the +# image file) depends on the setting of the pass-discard-request +# option. Keeping the clusters preallocated prevents qcow2 +# fragmentation that would otherwise be caused by freeing and +# re-allocating them later. Besides potential performance +# degradation, such fragmentation can lead to increased allocation +# of clusters past the end of the image file, resulting in image +# files whose file length can grow much larger than their guest +# disk size would suggest. If image file length is of concern +# (e.g. when storing qcow2 images directly on block devices), you +# should consider enabling this option. (since 8.1) +# +# @overlap-check: which overlap checks to perform for writes to the +# image, defaults to 'cached' (since 2.2) +# +# @cache-size: the maximum total size of the L2 table and refcount +# block caches in bytes (since 2.2) +# +# @l2-cache-size: the maximum size of the L2 table cache in bytes +# (since 2.2) # # @l2-cache-entry-size: the size of each entry in the L2 cache in -# bytes. It must be a power of two between 512 -# and the cluster size. The default value is -# the cluster size (since 2.12) +# bytes. It must be a power of two between 512 and the cluster +# size. The default value is the cluster size (since 2.12) # # @refcount-cache-size: the maximum size of the refcount block cache -# in bytes (since 2.2) +# in bytes (since 2.2) # # @cache-clean-interval: clean unused entries in the L2 and refcount -# caches. The interval is in seconds. The default value -# is 600 on supporting platforms, and 0 on other -# platforms. 0 disables this feature. (since 2.5) +# caches. The interval is in seconds. The default value is 600 +# on supporting platforms, and 0 on other platforms. 0 disables +# this feature. (since 2.5) # -# @encrypt: Image decryption options. Mandatory for -# encrypted images, except when doing a metadata-only -# probe of the image. (since 2.10) +# @encrypt: Image decryption options. Mandatory for encrypted images, +# except when doing a metadata-only probe of the image. (since +# 2.10) # # @data-file: reference to or definition of the external data file. -# This may only be specified for images that require an -# external data file. If it is not specified for such -# an image, the data file name is loaded from the image -# file. (since 4.0) +# This may only be specified for images that require an external +# data file. If it is not specified for such an image, the data +# file name is loaded from the image file. (since 4.0) # # Since: 2.9 ## @@ -3161,6 +3607,7 @@ '*pass-discard-request': 'bool', '*pass-discard-snapshot': 'bool', '*pass-discard-other': 'bool', + '*discard-no-unref': 'bool', '*overlap-check': 'Qcow2OverlapChecks', '*cache-size': 'int', '*l2-cache-size': 'int', @@ -3174,7 +3621,9 @@ # @SshHostKeyCheckMode: # # @none: Don't check the host key at all +# # @hash: Compare the host key with a given hash +# # @known_hosts: Check the host key against the known_hosts file # # Since: 2.12 @@ -3186,17 +3635,21 @@ # @SshHostKeyCheckHashType: # # @md5: The given hash is an md5 hash +# # @sha1: The given hash is an sha1 hash # +# @sha256: The given hash is an sha256 hash +# # Since: 2.12 ## { 'enum': 'SshHostKeyCheckHashType', - 'data': [ 'md5', 'sha1' ] } + 'data': [ 'md5', 'sha1', 'sha256' ] } ## # @SshHostKeyHash: # # @type: The hash algorithm used for the hash +# # @hash: The expected hash value # # Since: 2.12 @@ -3208,6 +3661,8 @@ ## # @SshHostKeyCheck: # +# @mode: How to check the host key +# # Since: 2.12 ## { 'union': 'SshHostKeyCheck', @@ -3218,15 +3673,14 @@ ## # @BlockdevOptionsSsh: # -# @server: host address +# @server: host address # -# @path: path to the image on the host +# @path: path to the image on the host # -# @user: user as which to connect, defaults to current -# local user name +# @user: user as which to connect, defaults to current local user name # -# @host-key-check: Defines how and what to check the host key against -# (default: known_hosts) +# @host-key-check: Defines how and what to check the host key against +# (default: known_hosts) # # Since: 2.9 ## @@ -3236,20 +3690,20 @@ '*user': 'str', '*host-key-check': 'SshHostKeyCheck' } } - ## # @BlkdebugEvent: # # Trigger events supported by blkdebug. # # @l1_shrink_write_table: write zeros to the l1 table to shrink image. -# (since 2.11) +# (since 2.11) # -# @l1_shrink_free_l2_clusters: discard the l2 tables. (since 2.11) +# @l1_shrink_free_l2_clusters: discard the l2 tables. (since 2.11) # # @cor_write: a write due to copy-on-read (since 2.11) # -# @cluster_alloc_space: an allocation of file space for a cluster (since 4.1) +# @cluster_alloc_space: an allocation of file space for a cluster +# (since 4.1) # # @none: triggers once at creation of the blkdebug node (since 4.1) # @@ -3303,23 +3757,20 @@ # # @event: trigger event # -# @state: the state identifier blkdebug needs to be in to -# actually trigger the event; defaults to "any" +# @state: the state identifier blkdebug needs to be in to actually +# trigger the event; defaults to "any" # -# @iotype: the type of I/O operations on which this error should -# be injected; defaults to "all read, write, -# write-zeroes, discard, and flush operations" -# (since: 4.1) +# @iotype: the type of I/O operations on which this error should be +# injected; defaults to "all read, write, write-zeroes, discard, +# and flush operations" (since: 4.1) # -# @errno: error identifier (errno) to be returned; defaults to -# EIO +# @errno: error identifier (errno) to be returned; defaults to EIO # -# @sector: specifies the sector index which has to be affected -# in order to actually trigger the event; defaults to "any -# sector" +# @sector: specifies the sector index which has to be affected in +# order to actually trigger the event; defaults to "any sector" # -# @once: disables further events after this one has been -# triggered; defaults to false +# @once: disables further events after this one has been triggered; +# defaults to false # # @immediately: fail immediately; defaults to false # @@ -3342,10 +3793,10 @@ # @event: trigger event # # @state: the current state identifier blkdebug needs to be in; -# defaults to "any" +# defaults to "any" # # @new_state: the state identifier blkdebug is supposed to assume if -# this event is triggered +# this event is triggered # # Since: 2.9 ## @@ -3363,47 +3814,45 @@ # # @config: filename of the configuration file # -# @align: required alignment for requests in bytes, must be -# positive power of 2, or 0 for default +# @align: required alignment for requests in bytes, must be positive +# power of 2, or 0 for default # # @max-transfer: maximum size for I/O transfers in bytes, must be -# positive multiple of @align and of the underlying -# file's request alignment (but need not be a power of -# 2), or 0 for default (since 2.10) +# positive multiple of @align and of the underlying file's request +# alignment (but need not be a power of 2), or 0 for default +# (since 2.10) # -# @opt-write-zero: preferred alignment for write zero requests in bytes, -# must be positive multiple of @align and of the -# underlying file's request alignment (but need not be a -# power of 2), or 0 for default (since 2.10) +# @opt-write-zero: preferred alignment for write zero requests in +# bytes, must be positive multiple of @align and of the underlying +# file's request alignment (but need not be a power of 2), or 0 +# for default (since 2.10) # -# @max-write-zero: maximum size for write zero requests in bytes, must be -# positive multiple of @align, of @opt-write-zero, and of -# the underlying file's request alignment (but need not -# be a power of 2), or 0 for default (since 2.10) +# @max-write-zero: maximum size for write zero requests in bytes, must +# be positive multiple of @align, of @opt-write-zero, and of the +# underlying file's request alignment (but need not be a power of +# 2), or 0 for default (since 2.10) # -# @opt-discard: preferred alignment for discard requests in bytes, must -# be positive multiple of @align and of the underlying -# file's request alignment (but need not be a power of -# 2), or 0 for default (since 2.10) +# @opt-discard: preferred alignment for discard requests in bytes, +# must be positive multiple of @align and of the underlying file's +# request alignment (but need not be a power of 2), or 0 for +# default (since 2.10) # # @max-discard: maximum size for discard requests in bytes, must be -# positive multiple of @align, of @opt-discard, and of -# the underlying file's request alignment (but need not -# be a power of 2), or 0 for default (since 2.10) +# positive multiple of @align, of @opt-discard, and of the +# underlying file's request alignment (but need not be a power of +# 2), or 0 for default (since 2.10) # # @inject-error: array of error injection descriptions # # @set-state: array of state-change descriptions # # @take-child-perms: Permissions to take on @image in addition to what -# is necessary anyway (which depends on how the -# blkdebug node is used). Defaults to none. -# (since 5.0) +# is necessary anyway (which depends on how the blkdebug node is +# used). Defaults to none. (since 5.0) # # @unshare-child-perms: Permissions not to share on @image in addition -# to what cannot be shared anyway (which depends -# on how the blkdebug node is used). Defaults -# to none. (since 5.0) +# to what cannot be shared anyway (which depends on how the +# blkdebug node is used). Defaults to none. (since 5.0) # # Since: 2.9 ## @@ -3427,13 +3876,14 @@ # # @log: block device used to log writes to @file # -# @log-sector-size: sector size used in logging writes to @file, determines -# granularity of offsets and sizes of writes (default: 512) +# @log-sector-size: sector size used in logging writes to @file, +# determines granularity of offsets and sizes of writes +# (default: 512) # # @log-append: append to an existing log (default: false) # -# @log-super-update-interval: interval of write requests after which the log -# super block is updated to disk (default: 4096) +# @log-super-update-interval: interval of write requests after which +# the log super block is updated to disk (default: 4096) # # Since: 3.0 ## @@ -3489,18 +3939,18 @@ # # Driver specific block device options for Quorum # -# @blkverify: true if the driver must print content mismatch -# set to false by default +# @blkverify: true if the driver must print content mismatch set to +# false by default # # @children: the children block devices to use # # @vote-threshold: the vote limit under which a read will fail # # @rewrite-corrupted: rewrite corrupted data when quorum is reached -# (Since 2.1) +# (Since 2.1) # # @read-pattern: choose read pattern and set to quorum by default -# (Since 2.2) +# (Since 2.2) # # Since: 2.9 ## @@ -3522,8 +3972,7 @@ # # @server: gluster servers description # -# @debug: libgfapi log level (default '4' which is Error) -# (Since 2.8) +# @debug: libgfapi log level (default '4' which is Error) (Since 2.8) # # @logfile: libgfapi log file (default /dev/stderr) (Since 2.8) # @@ -3537,6 +3986,82 @@ '*logfile': 'str' } } ## +# @BlockdevOptionsIoUring: +# +# Driver specific block device options for the io_uring backend. +# +# @filename: path to the image file +# +# Since: 7.2 +## +{ 'struct': 'BlockdevOptionsIoUring', + 'data': { 'filename': 'str' }, + 'if': 'CONFIG_BLKIO' } + +## +# @BlockdevOptionsNvmeIoUring: +# +# Driver specific block device options for the nvme-io_uring backend. +# +# @path: path to the NVMe namespace's character device (e.g. +# /dev/ng0n1). +# +# Since: 7.2 +## +{ 'struct': 'BlockdevOptionsNvmeIoUring', + 'data': { 'path': 'str' }, + 'if': 'CONFIG_BLKIO' } + +## +# @BlockdevOptionsVirtioBlkVfioPci: +# +# Driver specific block device options for the virtio-blk-vfio-pci +# backend. +# +# @path: path to the PCI device's sysfs directory (e.g. +# /sys/bus/pci/devices/0000:00:01.0). +# +# Since: 7.2 +## +{ 'struct': 'BlockdevOptionsVirtioBlkVfioPci', + 'data': { 'path': 'str' }, + 'if': 'CONFIG_BLKIO' } + +## +# @BlockdevOptionsVirtioBlkVhostUser: +# +# Driver specific block device options for the virtio-blk-vhost-user +# backend. +# +# @path: path to the vhost-user UNIX domain socket. +# +# Since: 7.2 +## +{ 'struct': 'BlockdevOptionsVirtioBlkVhostUser', + 'data': { 'path': 'str' }, + 'if': 'CONFIG_BLKIO' } + +## +# @BlockdevOptionsVirtioBlkVhostVdpa: +# +# Driver specific block device options for the virtio-blk-vhost-vdpa +# backend. +# +# @path: path to the vhost-vdpa character device. +# +# Features: +# @fdset: Member @path supports the special "/dev/fdset/N" path +# (since 8.1) +# +# Since: 7.2 +## +{ 'struct': 'BlockdevOptionsVirtioBlkVhostVdpa', + 'data': { 'path': 'str' }, + 'features': [ { 'name' :'fdset', + 'if': 'CONFIG_BLKIO_VHOST_VDPA_FD' } ], + 'if': 'CONFIG_BLKIO' } + +## # @IscsiTransport: # # An enumeration of libiscsi transport types @@ -3560,32 +4085,31 @@ ## # @BlockdevOptionsIscsi: # +# Driver specific block device options for iscsi +# # @transport: The iscsi transport type # # @portal: The address of the iscsi portal # # @target: The target iqn name # -# @lun: LUN to connect to. Defaults to 0. -# -# @user: User name to log in with. If omitted, no CHAP -# authentication is performed. +# @lun: LUN to connect to. Defaults to 0. # -# @password-secret: The ID of a QCryptoSecret object providing -# the password for the login. This option is required if -# @user is specified. +# @user: User name to log in with. If omitted, no CHAP authentication +# is performed. # -# @initiator-name: The iqn name we want to identify to the target -# as. If this option is not specified, an initiator name is -# generated automatically. +# @password-secret: The ID of a QCryptoSecret object providing the +# password for the login. This option is required if @user is +# specified. # -# @header-digest: The desired header digest. Defaults to -# none-crc32c. +# @initiator-name: The iqn name we want to identify to the target as. +# If this option is not specified, an initiator name is generated +# automatically. # -# @timeout: Timeout in seconds after which a request will -# timeout. 0 means no timeout and is the default. +# @header-digest: The desired header digest. Defaults to none-crc32c. # -# Driver specific block device options for iscsi +# @timeout: Timeout in seconds after which a request will timeout. 0 +# means no timeout and is the default. # # Since: 2.9 ## @@ -3600,7 +4124,6 @@ '*header-digest': 'IscsiHeaderDigest', '*timeout': 'int' } } - ## # @RbdAuthMode: # @@ -3610,33 +4133,143 @@ 'data': [ 'cephx', 'none' ] } ## +# @RbdImageEncryptionFormat: +# +# @luks-any: Used for opening either luks or luks2 (Since 8.0) +# +# Since: 6.1 +## +{ 'enum': 'RbdImageEncryptionFormat', + 'data': [ 'luks', 'luks2', 'luks-any' ] } + +## +# @RbdEncryptionOptionsLUKSBase: +# +# @key-secret: ID of a QCryptoSecret object providing a passphrase for +# unlocking the encryption +# +# Since: 6.1 +## +{ 'struct': 'RbdEncryptionOptionsLUKSBase', + 'data': { 'key-secret': 'str' } } + +## +# @RbdEncryptionCreateOptionsLUKSBase: +# +# @cipher-alg: The encryption algorithm +# +# Since: 6.1 +## +{ 'struct': 'RbdEncryptionCreateOptionsLUKSBase', + 'base': 'RbdEncryptionOptionsLUKSBase', + 'data': { '*cipher-alg': 'QCryptoCipherAlgorithm' } } + +## +# @RbdEncryptionOptionsLUKS: +# +# Since: 6.1 +## +{ 'struct': 'RbdEncryptionOptionsLUKS', + 'base': 'RbdEncryptionOptionsLUKSBase', + 'data': { } } + +## +# @RbdEncryptionOptionsLUKS2: +# +# Since: 6.1 +## +{ 'struct': 'RbdEncryptionOptionsLUKS2', + 'base': 'RbdEncryptionOptionsLUKSBase', + 'data': { } } + +## +# @RbdEncryptionOptionsLUKSAny: +# +# Since: 8.0 +## +{ 'struct': 'RbdEncryptionOptionsLUKSAny', + 'base': 'RbdEncryptionOptionsLUKSBase', + 'data': { } } + +## +# @RbdEncryptionCreateOptionsLUKS: +# +# Since: 6.1 +## +{ 'struct': 'RbdEncryptionCreateOptionsLUKS', + 'base': 'RbdEncryptionCreateOptionsLUKSBase', + 'data': { } } + +## +# @RbdEncryptionCreateOptionsLUKS2: +# +# Since: 6.1 +## +{ 'struct': 'RbdEncryptionCreateOptionsLUKS2', + 'base': 'RbdEncryptionCreateOptionsLUKSBase', + 'data': { } } + +## +# @RbdEncryptionOptions: +# +# @format: Encryption format. +# +# @parent: Parent image encryption options (for cloned images). Can +# be left unspecified if this cloned image is encrypted using the +# same format and secret as its parent image (i.e. not explicitly +# formatted) or if its parent image is not encrypted. (Since 8.0) +# +# Since: 6.1 +## +{ 'union': 'RbdEncryptionOptions', + 'base': { 'format': 'RbdImageEncryptionFormat', + '*parent': 'RbdEncryptionOptions' }, + 'discriminator': 'format', + 'data': { 'luks': 'RbdEncryptionOptionsLUKS', + 'luks2': 'RbdEncryptionOptionsLUKS2', + 'luks-any': 'RbdEncryptionOptionsLUKSAny'} } + +## +# @RbdEncryptionCreateOptions: +# +# @format: Encryption format. +# +# Since: 6.1 +## +{ 'union': 'RbdEncryptionCreateOptions', + 'base': { 'format': 'RbdImageEncryptionFormat' }, + 'discriminator': 'format', + 'data': { 'luks': 'RbdEncryptionCreateOptionsLUKS', + 'luks2': 'RbdEncryptionCreateOptionsLUKS2' } } + +## # @BlockdevOptionsRbd: # # @pool: Ceph pool name. # -# @namespace: Rados namespace name in the Ceph pool. (Since 5.0) +# @namespace: Rados namespace name in the Ceph pool. (Since 5.0) # # @image: Image name in the Ceph pool. # -# @conf: path to Ceph configuration file. Values -# in the configuration file will be overridden by -# options specified via QAPI. +# @conf: path to Ceph configuration file. Values in the configuration +# file will be overridden by options specified via QAPI. # # @snapshot: Ceph snapshot name. # +# @encrypt: Image encryption options. (Since 6.1) +# # @user: Ceph id name. # -# @auth-client-required: Acceptable authentication modes. -# This maps to Ceph configuration option -# "auth_client_required". (Since 3.0) +# @auth-client-required: Acceptable authentication modes. This maps +# to Ceph configuration option "auth_client_required". (Since +# 3.0) # -# @key-secret: ID of a QCryptoSecret object providing a key -# for cephx authentication. -# This maps to Ceph configuration option -# "key". (Since 3.0) +# @key-secret: ID of a QCryptoSecret object providing a key for cephx +# authentication. This maps to Ceph configuration option "key". +# (Since 3.0) # -# @server: Monitor host address and port. This maps -# to the "mon_host" Ceph option. +# @server: Monitor host address and port. This maps to the "mon_host" +# Ceph option. # # Since: 2.9 ## @@ -3646,44 +4279,27 @@ 'image': 'str', '*conf': 'str', '*snapshot': 'str', + '*encrypt': 'RbdEncryptionOptions', '*user': 'str', '*auth-client-required': ['RbdAuthMode'], '*key-secret': 'str', '*server': ['InetSocketAddressBase'] } } ## -# @BlockdevOptionsSheepdog: -# -# Driver specific block device options for sheepdog -# -# @vdi: Virtual disk image name -# @server: The Sheepdog server to connect to -# @snap-id: Snapshot ID -# @tag: Snapshot tag name -# -# Only one of @snap-id and @tag may be present. -# -# Since: 2.9 -## -{ 'struct': 'BlockdevOptionsSheepdog', - 'data': { 'server': 'SocketAddress', - 'vdi': 'str', - '*snap-id': 'uint32', - '*tag': 'str' } } - -## # @ReplicationMode: # # An enumeration of replication modes. # -# @primary: Primary mode, the vm's state will be sent to secondary QEMU. +# @primary: Primary mode, the vm's state will be sent to secondary +# QEMU. # -# @secondary: Secondary mode, receive the vm's state from primary QEMU. +# @secondary: Secondary mode, receive the vm's state from primary +# QEMU. # # Since: 2.9 ## { 'enum' : 'ReplicationMode', 'data' : [ 'primary', 'secondary' ], - 'if': 'defined(CONFIG_REPLICATION)' } + 'if': 'CONFIG_REPLICATION' } ## # @BlockdevOptionsReplication: @@ -3692,9 +4308,9 @@ # # @mode: the replication mode # -# @top-id: In secondary mode, node name or device ID of the root -# node who owns the replication node chain. Must not be given in -# primary mode. +# @top-id: In secondary mode, node name or device ID of the root node +# who owns the replication node chain. Must not be given in +# primary mode. # # Since: 2.9 ## @@ -3702,7 +4318,7 @@ 'base': 'BlockdevOptionsGenericFormat', 'data': { 'mode': 'ReplicationMode', '*top-id': 'str' }, - 'if': 'defined(CONFIG_REPLICATION)' } + 'if': 'CONFIG_REPLICATION' } ## # @NFSTransport: @@ -3740,25 +4356,22 @@ # # @path: path of the image on the host # -# @user: UID value to use when talking to the -# server (defaults to 65534 on Windows and getuid() -# on unix) +# @user: UID value to use when talking to the server (defaults to +# 65534 on Windows and getuid() on unix) # -# @group: GID value to use when talking to the -# server (defaults to 65534 on Windows and getgid() -# in unix) +# @group: GID value to use when talking to the server (defaults to +# 65534 on Windows and getgid() in unix) # -# @tcp-syn-count: number of SYNs during the session -# establishment (defaults to libnfs default) +# @tcp-syn-count: number of SYNs during the session establishment +# (defaults to libnfs default) # -# @readahead-size: set the readahead size in bytes (defaults -# to libnfs default) +# @readahead-size: set the readahead size in bytes (defaults to libnfs +# default) # -# @page-cache-size: set the pagecache size in bytes (defaults -# to libnfs default) +# @page-cache-size: set the pagecache size in bytes (defaults to +# libnfs default) # -# @debug: set the NFS debug level (max 2) (defaults -# to libnfs default) +# @debug: set the NFS debug level (max 2) (defaults to libnfs default) # # Since: 2.9 ## @@ -3775,25 +4388,26 @@ ## # @BlockdevOptionsCurlBase: # -# Driver specific block device options shared by all protocols supported by the -# curl backend. +# Driver specific block device options shared by all protocols +# supported by the curl backend. # # @url: URL of the image file # -# @readahead: Size of the read-ahead cache; must be a multiple of -# 512 (defaults to 256 kB) +# @readahead: Size of the read-ahead cache; must be a multiple of 512 +# (defaults to 256 kB) # # @timeout: Timeout for connections, in seconds (defaults to 5) # # @username: Username for authentication (defaults to none) # # @password-secret: ID of a QCryptoSecret object providing a password -# for authentication (defaults to no password) +# for authentication (defaults to no password) # -# @proxy-username: Username for proxy authentication (defaults to none) +# @proxy-username: Username for proxy authentication (defaults to +# none) # -# @proxy-password-secret: ID of a QCryptoSecret object providing a password -# for proxy authentication (defaults to no password) +# @proxy-password-secret: ID of a QCryptoSecret object providing a +# password for proxy authentication (defaults to no password) # # Since: 2.9 ## @@ -3809,15 +4423,15 @@ ## # @BlockdevOptionsCurlHttp: # -# Driver specific block device options for HTTP connections over the curl -# backend. URLs must start with "http://". +# Driver specific block device options for HTTP connections over the +# curl backend. URLs must start with "http://". # -# @cookie: List of cookies to set; format is -# "name1=content1; name2=content2;" as explained by -# CURLOPT_COOKIE(3). Defaults to no cookies. +# @cookie: List of cookies to set; format is "name1=content1; +# name2=content2;" as explained by CURLOPT_COOKIE(3). Defaults to +# no cookies. # -# @cookie-secret: ID of a QCryptoSecret object providing the cookie data in a -# secure way. See @cookie for the format. (since 2.10) +# @cookie-secret: ID of a QCryptoSecret object providing the cookie +# data in a secure way. See @cookie for the format. (since 2.10) # # Since: 2.9 ## @@ -3829,18 +4443,18 @@ ## # @BlockdevOptionsCurlHttps: # -# Driver specific block device options for HTTPS connections over the curl -# backend. URLs must start with "https://". +# Driver specific block device options for HTTPS connections over the +# curl backend. URLs must start with "https://". # -# @cookie: List of cookies to set; format is -# "name1=content1; name2=content2;" as explained by -# CURLOPT_COOKIE(3). Defaults to no cookies. +# @cookie: List of cookies to set; format is "name1=content1; +# name2=content2;" as explained by CURLOPT_COOKIE(3). Defaults to +# no cookies. # -# @sslverify: Whether to verify the SSL certificate's validity (defaults to -# true) +# @sslverify: Whether to verify the SSL certificate's validity +# (defaults to true) # -# @cookie-secret: ID of a QCryptoSecret object providing the cookie data in a -# secure way. See @cookie for the format. (since 2.10) +# @cookie-secret: ID of a QCryptoSecret object providing the cookie +# data in a secure way. See @cookie for the format. (since 2.10) # # Since: 2.9 ## @@ -3853,8 +4467,8 @@ ## # @BlockdevOptionsCurlFtp: # -# Driver specific block device options for FTP connections over the curl -# backend. URLs must start with "ftp://". +# Driver specific block device options for FTP connections over the +# curl backend. URLs must start with "ftp://". # # Since: 2.9 ## @@ -3865,11 +4479,11 @@ ## # @BlockdevOptionsCurlFtps: # -# Driver specific block device options for FTPS connections over the curl -# backend. URLs must start with "ftps://". +# Driver specific block device options for FTPS connections over the +# curl backend. URLs must start with "ftps://". # -# @sslverify: Whether to verify the SSL certificate's validity (defaults to -# true) +# @sslverify: Whether to verify the SSL certificate's validity +# (defaults to true) # # Since: 2.9 ## @@ -3888,20 +4502,32 @@ # # @tls-creds: TLS credentials ID # -# @x-dirty-bitmap: A metadata context name such as "qemu:dirty-bitmap:NAME" -# or "qemu:allocation-depth" to query in place of the -# traditional "base:allocation" block status (see -# NBD_OPT_LIST_META_CONTEXT in the NBD protocol; and -# yes, naming this option x-context would have made -# more sense) (since 3.0) -# -# @reconnect-delay: On an unexpected disconnect, the nbd client tries to -# connect again until succeeding or encountering a serious -# error. During the first @reconnect-delay seconds, all -# requests are paused and will be rerun on a successful -# reconnect. After that time, any delayed requests and all -# future requests before a successful reconnect will -# immediately fail. Default 0 (Since 4.2) +# @tls-hostname: TLS hostname override for certificate validation +# (Since 7.0) +# +# @x-dirty-bitmap: A metadata context name such as +# "qemu:dirty-bitmap:NAME" or "qemu:allocation-depth" to query in +# place of the traditional "base:allocation" block status (see +# NBD_OPT_LIST_META_CONTEXT in the NBD protocol; and yes, naming +# this option x-context would have made more sense) (since 3.0) +# +# @reconnect-delay: On an unexpected disconnect, the nbd client tries +# to connect again until succeeding or encountering a serious +# error. During the first @reconnect-delay seconds, all requests +# are paused and will be rerun on a successful reconnect. After +# that time, any delayed requests and all future requests before a +# successful reconnect will immediately fail. Default 0 (Since +# 4.2) +# +# @open-timeout: In seconds. If zero, the nbd driver tries the +# connection only once, and fails to open if the connection fails. +# If non-zero, the nbd driver will repeat connection attempts +# until successful or until @open-timeout seconds have elapsed. +# Default 0 (Since 7.0) +# +# Features: +# +# @unstable: Member @x-dirty-bitmap is experimental. # # Since: 2.9 ## @@ -3909,8 +4535,10 @@ 'data': { 'server': 'SocketAddress', '*export': 'str', '*tls-creds': 'str', - '*x-dirty-bitmap': 'str', - '*reconnect-delay': 'uint32' } } + '*tls-hostname': 'str', + '*x-dirty-bitmap': { 'type': 'str', 'features': [ 'unstable' ] }, + '*reconnect-delay': 'uint32', + '*open-timeout': 'uint32' } } ## # @BlockdevOptionsRaw: @@ -3918,6 +4546,7 @@ # Driver specific block device options for the raw driver. # # @offset: position where the block device starts +# # @size: the assumed size of the device # # Since: 2.9 @@ -3931,9 +4560,11 @@ # # Driver specific block device options for the throttle driver # -# @throttle-group: the name of the throttle-group object to use. It -# must already exist. +# @throttle-group: the name of the throttle-group object to use. It +# must already exist. +# # @file: reference to or definition of the data source block device +# # Since: 2.11 ## { 'struct': 'BlockdevOptionsThrottle', @@ -3946,11 +4577,11 @@ # # Driver specific block device options for the copy-on-read driver. # -# @bottom: The name of a non-filter node (allocation-bearing layer) that -# limits the COR operations in the backing chain (inclusive), so -# that no data below this node will be copied by this filter. -# If option is absent, the limit is not applied, so that data -# from all backing layers may be copied. +# @bottom: The name of a non-filter node (allocation-bearing layer) +# that limits the COR operations in the backing chain (inclusive), +# so that no data below this node will be copied by this filter. +# If option is absent, the limit is not applied, so that data from +# all backing layers may be copied. # # Since: 6.0 ## @@ -3959,36 +4590,97 @@ 'data': { '*bottom': 'str' } } ## +# @OnCbwError: +# +# An enumeration of possible behaviors for copy-before-write operation +# failures. +# +# @break-guest-write: report the error to the guest. This way, the +# guest will not be able to overwrite areas that cannot be backed +# up, so the backup process remains valid. +# +# @break-snapshot: continue guest write. Doing so will make the +# provided snapshot state invalid and any backup or export process +# based on it will finally fail. +# +# Since: 7.1 +## +{ 'enum': 'OnCbwError', + 'data': [ 'break-guest-write', 'break-snapshot' ] } + +## +# @BlockdevOptionsCbw: +# +# Driver specific block device options for the copy-before-write +# driver, which does so called copy-before-write operations: when data +# is written to the filter, the filter first reads corresponding +# blocks from its file child and copies them to @target child. After +# successfully copying, the write request is propagated to file child. +# If copying fails, the original write request is failed too and no +# data is written to file child. +# +# @target: The target for copy-before-write operations. +# +# @bitmap: If specified, copy-before-write filter will do +# copy-before-write operations only for dirty regions of the +# bitmap. Bitmap size must be equal to length of file and target +# child of the filter. Note also, that bitmap is used only to +# initialize internal bitmap of the process, so further +# modifications (or removing) of specified bitmap doesn't +# influence the filter. (Since 7.0) +# +# @on-cbw-error: Behavior on failure of copy-before-write operation. +# Default is @break-guest-write. (Since 7.1) +# +# @cbw-timeout: Zero means no limit. Non-zero sets the timeout in +# seconds for copy-before-write operation. When a timeout occurs, +# the respective copy-before-write operation will fail, and the +# @on-cbw-error parameter will decide how this failure is handled. +# Default 0. (Since 7.1) +# +# Since: 6.2 +## +{ 'struct': 'BlockdevOptionsCbw', + 'base': 'BlockdevOptionsGenericFormat', + 'data': { 'target': 'BlockdevRef', '*bitmap': 'BlockDirtyBitmap', + '*on-cbw-error': 'OnCbwError', '*cbw-timeout': 'uint32' } } + +## # @BlockdevOptions: # -# Options for creating a block device. Many options are available for all -# block devices, independent of the block driver: +# Options for creating a block device. Many options are available for +# all block devices, independent of the block driver: # # @driver: block driver name -# @node-name: the node name of the new node (Since 2.0). -# This option is required on the top level of blockdev-add. -# Valid node names start with an alphabetic character and may -# contain only alphanumeric characters, '-', '.' and '_'. Their -# maximum length is 31 characters. +# +# @node-name: the node name of the new node (Since 2.0). This option +# is required on the top level of blockdev-add. Valid node names +# start with an alphabetic character and may contain only +# alphanumeric characters, '-', '.' and '_'. Their maximum length +# is 31 characters. +# # @discard: discard-related options (default: ignore) +# # @cache: cache-related options -# @read-only: whether the block device should be read-only (default: false). -# Note that some block drivers support only read-only access, -# either generally or in certain configurations. In this case, -# the default value does not work and the option must be -# specified explicitly. -# @auto-read-only: if true and @read-only is false, QEMU may automatically -# decide not to open the image read-write as requested, but -# fall back to read-only instead (and switch between the modes -# later), e.g. depending on whether the image file is writable -# or whether a writing user is attached to the node -# (default: false, since 3.1) +# +# @read-only: whether the block device should be read-only (default: +# false). Note that some block drivers support only read-only +# access, either generally or in certain configurations. In this +# case, the default value does not work and the option must be +# specified explicitly. +# +# @auto-read-only: if true and @read-only is false, QEMU may +# automatically decide not to open the image read-write as +# requested, but fall back to read-only instead (and switch +# between the modes later), e.g. depending on whether the image +# file is writable or whether a writing user is attached to the +# node (default: false, since 3.1) +# # @detect-zeroes: detect and optimize zero writes (Since 2.1) -# (default: off) -# @force-share: force share all permission on added nodes. -# Requires read-only=true. (Since 2.10) +# (default: off) # -# Remaining options are determined by the block driver. +# @force-share: force share all permission on added nodes. Requires +# read-only=true. (Since 2.10) # # Since: 2.9 ## @@ -4010,16 +4702,21 @@ 'bochs': 'BlockdevOptionsGenericFormat', 'cloop': 'BlockdevOptionsGenericFormat', 'compress': 'BlockdevOptionsGenericFormat', + 'copy-before-write':'BlockdevOptionsCbw', 'copy-on-read':'BlockdevOptionsCor', 'dmg': 'BlockdevOptionsGenericFormat', 'file': 'BlockdevOptionsFile', 'ftp': 'BlockdevOptionsCurlFtp', 'ftps': 'BlockdevOptionsCurlFtps', 'gluster': 'BlockdevOptionsGluster', - 'host_cdrom': 'BlockdevOptionsFile', - 'host_device':'BlockdevOptionsFile', + 'host_cdrom': { 'type': 'BlockdevOptionsFile', + 'if': 'HAVE_HOST_BLOCK_DEVICE' }, + 'host_device': { 'type': 'BlockdevOptionsFile', + 'if': 'HAVE_HOST_BLOCK_DEVICE' }, 'http': 'BlockdevOptionsCurlHttp', 'https': 'BlockdevOptionsCurlHttps', + 'io_uring': { 'type': 'BlockdevOptionsIoUring', + 'if': 'CONFIG_BLKIO' }, 'iscsi': 'BlockdevOptionsIscsi', 'luks': 'BlockdevOptionsLUKS', 'nbd': 'BlockdevOptionsNbd', @@ -4027,6 +4724,8 @@ 'null-aio': 'BlockdevOptionsNull', 'null-co': 'BlockdevOptionsNull', 'nvme': 'BlockdevOptionsNVMe', + 'nvme-io_uring': { 'type': 'BlockdevOptionsNvmeIoUring', + 'if': 'CONFIG_BLKIO' }, 'parallels': 'BlockdevOptionsGenericFormat', 'preallocate':'BlockdevOptionsPreallocate', 'qcow2': 'BlockdevOptionsQcow2', @@ -4036,12 +4735,21 @@ 'raw': 'BlockdevOptionsRaw', 'rbd': 'BlockdevOptionsRbd', 'replication': { 'type': 'BlockdevOptionsReplication', - 'if': 'defined(CONFIG_REPLICATION)' }, - 'sheepdog': 'BlockdevOptionsSheepdog', + 'if': 'CONFIG_REPLICATION' }, + 'snapshot-access': 'BlockdevOptionsGenericFormat', 'ssh': 'BlockdevOptionsSsh', 'throttle': 'BlockdevOptionsThrottle', 'vdi': 'BlockdevOptionsGenericFormat', 'vhdx': 'BlockdevOptionsGenericFormat', + 'virtio-blk-vfio-pci': + { 'type': 'BlockdevOptionsVirtioBlkVfioPci', + 'if': 'CONFIG_BLKIO' }, + 'virtio-blk-vhost-user': + { 'type': 'BlockdevOptionsVirtioBlkVhostUser', + 'if': 'CONFIG_BLKIO' }, + 'virtio-blk-vhost-vdpa': + { 'type': 'BlockdevOptionsVirtioBlkVhostVdpa', + 'if': 'CONFIG_BLKIO' }, 'vmdk': 'BlockdevOptionsGenericCOWFormat', 'vpc': 'BlockdevOptionsGenericFormat', 'vvfat': 'BlockdevOptionsVVFAT' @@ -4053,6 +4761,7 @@ # Reference to a block device. # # @definition: defines a new block device inline +# # @reference: references the ID of an existing block device # # Since: 2.9 @@ -4067,9 +4776,11 @@ # Reference to a block device. # # @definition: defines a new block device inline -# @reference: references the ID of an existing block device. -# An empty string means that no block device should -# be referenced. Deprecated; use null instead. +# +# @reference: references the ID of an existing block device. An empty +# string means that no block device should be referenced. +# Deprecated; use null instead. +# # @null: No block device should be referenced (since 2.10) # # Since: 2.9 @@ -4086,63 +4797,64 @@ # # Since: 2.9 # -# Example: +# Examples: # -# 1. -# -> { "execute": "blockdev-add", -# "arguments": { -# "driver": "qcow2", -# "node-name": "test1", -# "file": { -# "driver": "file", -# "filename": "test.qcow2" -# } -# } -# } -# <- { "return": {} } -# -# 2. -# -> { "execute": "blockdev-add", -# "arguments": { -# "driver": "qcow2", -# "node-name": "node0", -# "discard": "unmap", -# "cache": { -# "direct": true -# }, -# "file": { -# "driver": "file", -# "filename": "/tmp/test.qcow2" -# }, -# "backing": { -# "driver": "raw", +# -> { "execute": "blockdev-add", +# "arguments": { +# "driver": "qcow2", +# "node-name": "test1", # "file": { +# "driver": "file", +# "filename": "test.qcow2" +# } +# } +# } +# <- { "return": {} } +# +# -> { "execute": "blockdev-add", +# "arguments": { +# "driver": "qcow2", +# "node-name": "node0", +# "discard": "unmap", +# "cache": { +# "direct": true +# }, +# "file": { # "driver": "file", -# "filename": "/dev/fdset/4" +# "filename": "/tmp/test.qcow2" +# }, +# "backing": { +# "driver": "raw", +# "file": { +# "driver": "file", +# "filename": "/dev/fdset/4" +# } # } # } -# } -# } -# -# <- { "return": {} } +# } # +# <- { "return": {} } ## -{ 'command': 'blockdev-add', 'data': 'BlockdevOptions', 'boxed': true } +{ 'command': 'blockdev-add', 'data': 'BlockdevOptions', 'boxed': true, + 'allow-preconfig': true } ## -# @x-blockdev-reopen: +# @blockdev-reopen: # -# Reopens a block device using the given set of options. Any option -# not specified will be reset to its default value regardless of its -# previous status. If an option cannot be changed or a particular -# driver does not support reopening then the command will return an -# error. +# Reopens one or more block devices using the given set of options. +# Any option not specified will be reset to its default value +# regardless of its previous status. If an option cannot be changed +# or a particular driver does not support reopening then the command +# will return an error. All devices in the list are reopened in one +# transaction, so if one of them fails then the whole transaction is +# cancelled. # -# The top-level @node-name option (from BlockdevOptions) must be -# specified and is used to select the block device to be reopened. -# Other @node-name options must be either omitted or set to the -# current name of the appropriate node. This command won't change any -# node name and any attempt to do it will result in an error. +# The command receives a list of block devices to reopen. For each +# one of them, the top-level @node-name option (from BlockdevOptions) +# must be specified and is used to select the block device to be +# reopened. Other @node-name options must be either omitted or set to +# the current name of the appropriate node. This command won't change +# any node name and any attempt to do it will result in an error. # # In the case of options that refer to child nodes, the behavior of # this command depends on the value: @@ -4158,24 +4870,25 @@ # # 4) NULL: the current child (if any) is detached. # -# Options (1) and (2) are supported in all cases, but at the moment -# only @backing allows replacing or detaching an existing child. +# Options (1) and (2) are supported in all cases. Option (3) is +# supported for @file and @backing, and option (4) for @backing only. # # Unlike with blockdev-add, the @backing option must always be present # unless the node being reopened does not have a backing file and its # image does not have a default backing file name as part of its # metadata. # -# Since: 4.0 +# Since: 6.1 ## -{ 'command': 'x-blockdev-reopen', - 'data': 'BlockdevOptions', 'boxed': true } +{ 'command': 'blockdev-reopen', + 'data': { 'options': ['BlockdevOptions'] }, + 'allow-preconfig': true } ## # @blockdev-del: # -# Deletes a block device that has been added using blockdev-add. -# The command will fail if the node is attached to a device or is +# Deletes a block device that has been added using blockdev-add. The +# command will fail if the node is attached to a device or is # otherwise being used. # # @node-name: Name of the graph node to delete. @@ -4184,25 +4897,25 @@ # # Example: # -# -> { "execute": "blockdev-add", -# "arguments": { -# "driver": "qcow2", -# "node-name": "node0", -# "file": { -# "driver": "file", -# "filename": "test.qcow2" -# } -# } -# } -# <- { "return": {} } -# -# -> { "execute": "blockdev-del", -# "arguments": { "node-name": "node0" } -# } -# <- { "return": {} } +# -> { "execute": "blockdev-add", +# "arguments": { +# "driver": "qcow2", +# "node-name": "node0", +# "file": { +# "driver": "file", +# "filename": "test.qcow2" +# } +# } +# } +# <- { "return": {} } # +# -> { "execute": "blockdev-del", +# "arguments": { "node-name": "node0" } +# } +# <- { "return": {} } ## -{ 'command': 'blockdev-del', 'data': { 'node-name': 'str' } } +{ 'command': 'blockdev-del', 'data': { 'node-name': 'str' }, + 'allow-preconfig': true } ## # @BlockdevCreateOptionsFile: @@ -4210,14 +4923,17 @@ # Driver specific image creation options for file. # # @filename: Filename for the new image file +# # @size: Size of the virtual disk in bytes +# # @preallocation: Preallocation mode for the new image (default: off; -# allowed values: off, -# falloc (if defined CONFIG_POSIX_FALLOCATE), -# full (if defined CONFIG_POSIX)) +# allowed values: off, falloc (if CONFIG_POSIX_FALLOCATE), full +# (if CONFIG_POSIX)) +# # @nocow: Turn off copy-on-write (valid only on btrfs; default: off) -# @extent-size-hint: Extent size hint to add to the image file; 0 for not -# adding an extent size hint (default: 1 MB, since 5.1) +# +# @extent-size-hint: Extent size hint to add to the image file; 0 for +# not adding an extent size hint (default: 1 MB, since 5.1) # # Since: 2.12 ## @@ -4234,11 +4950,12 @@ # Driver specific image creation options for gluster. # # @location: Where to store the new image file +# # @size: Size of the virtual disk in bytes +# # @preallocation: Preallocation mode for the new image (default: off; -# allowed values: off, -# falloc (if defined CONFIG_GLUSTERFS_FALLOCATE), -# full (if defined CONFIG_GLUSTERFS_ZEROFILL)) +# allowed values: off, falloc (if CONFIG_GLUSTERFS_FALLOCATE), +# full (if CONFIG_GLUSTERFS_ZEROFILL)) # # Since: 2.12 ## @@ -4252,17 +4969,22 @@ # # Driver specific image creation options for LUKS. # -# @file: Node to create the image format on +# @file: Node to create the image format on, mandatory except when +# 'preallocation' is not requested +# +# @header: Block device holding a detached LUKS header. (since 9.0) +# # @size: Size of the virtual disk in bytes -# @preallocation: Preallocation mode for the new image -# (since: 4.2) -# (default: off; allowed values: off, metadata, falloc, full) +# +# @preallocation: Preallocation mode for the new image (since: 4.2) +# (default: off; allowed values: off, metadata, falloc, full) # # Since: 2.12 ## { 'struct': 'BlockdevCreateOptionsLUKS', 'base': 'QCryptoBlockCreateOptionsLUKS', - 'data': { 'file': 'BlockdevRef', + 'data': { '*file': 'BlockdevRef', + '*header': 'BlockdevRef', 'size': 'size', '*preallocation': 'PreallocMode' } } @@ -4272,6 +4994,7 @@ # Driver specific image creation options for NFS. # # @location: Where to store the new image file +# # @size: Size of the virtual disk in bytes # # Since: 2.12 @@ -4286,7 +5009,9 @@ # Driver specific image creation options for parallels. # # @file: Node to create the image format on +# # @size: Size of the virtual disk in bytes +# # @cluster-size: Cluster size in bytes (default: 1 MB) # # Since: 2.12 @@ -4302,9 +5027,12 @@ # Driver specific image creation options for qcow. # # @file: Node to create the image format on +# # @size: Size of the virtual disk in bytes +# # @backing-file: File name of the backing file if a backing file -# should be used +# should be used +# # @encrypt: Encryption options if the image should be encrypted # # Since: 2.12 @@ -4318,27 +5046,29 @@ ## # @BlockdevQcow2Version: # -# @v2: The original QCOW2 format as introduced in qemu 0.10 (version 2) -# @v3: The extended QCOW2 format as introduced in qemu 1.1 (version 3) +# @v2: The original QCOW2 format as introduced in qemu 0.10 (version +# 2) +# +# @v3: The extended QCOW2 format as introduced in qemu 1.1 (version 3) # # Since: 2.12 ## { 'enum': 'BlockdevQcow2Version', 'data': [ 'v2', 'v3' ] } - ## # @Qcow2CompressionType: # # Compression type used in qcow2 image file # # @zlib: zlib compression, see <http://zlib.net/> +# # @zstd: zstd compression, see <http://github.com/facebook/zstd> # # Since: 5.1 ## { 'enum': 'Qcow2CompressionType', - 'data': [ 'zlib', { 'name': 'zstd', 'if': 'defined(CONFIG_ZSTD)' } ] } + 'data': [ 'zlib', { 'name': 'zstd', 'if': 'CONFIG_ZSTD' } ] } ## # @BlockdevCreateOptionsQcow2: @@ -4346,27 +5076,41 @@ # Driver specific image creation options for qcow2. # # @file: Node to create the image format on +# # @data-file: Node to use as an external data file in which all guest -# data is stored so that only metadata remains in the qcow2 -# file (since: 4.0) +# data is stored so that only metadata remains in the qcow2 file +# (since: 4.0) +# # @data-file-raw: True if the external data file must stay valid as a -# standalone (read-only) raw image without looking at qcow2 -# metadata (default: false; since: 4.0) +# standalone (read-only) raw image without looking at qcow2 +# metadata (default: false; since: 4.0) +# # @extended-l2: True to make the image have extended L2 entries -# (default: false; since 5.2) +# (default: false; since 5.2) +# # @size: Size of the virtual disk in bytes +# # @version: Compatibility level (default: v3) +# # @backing-file: File name of the backing file if a backing file -# should be used +# should be used +# # @backing-fmt: Name of the block driver to use for the backing file +# # @encrypt: Encryption options if the image should be encrypted +# # @cluster-size: qcow2 cluster size in bytes (default: 65536) +# # @preallocation: Preallocation mode for the new image (default: off; -# allowed values: off, falloc, full, metadata) -# @lazy-refcounts: True if refcounts may be updated lazily (default: off) +# allowed values: off, falloc, full, metadata) +# +# @lazy-refcounts: True if refcounts may be updated lazily +# (default: off) +# # @refcount-bits: Width of reference counts in bits (default: 16) +# # @compression-type: The image cluster compression method -# (default: zlib, since 5.1) +# (default: zlib, since 5.1) # # Since: 2.12 ## @@ -4392,11 +5136,16 @@ # Driver specific image creation options for qed. # # @file: Node to create the image format on +# # @size: Size of the virtual disk in bytes +# # @backing-file: File name of the backing file if a backing file -# should be used +# should be used +# # @backing-fmt: Name of the block driver to use for the backing file +# # @cluster-size: Cluster size in bytes (default: 65536) +# # @table-size: L1/L2 table size (in clusters) # # Since: 2.12 @@ -4414,35 +5163,40 @@ # # Driver specific image creation options for rbd/Ceph. # -# @location: Where to store the new image file. This location cannot -# point to a snapshot. +# @location: Where to store the new image file. This location cannot +# point to a snapshot. +# # @size: Size of the virtual disk in bytes +# # @cluster-size: RBD object size # +# @encrypt: Image encryption options. (Since 6.1) +# # Since: 2.12 ## { 'struct': 'BlockdevCreateOptionsRbd', 'data': { 'location': 'BlockdevOptionsRbd', 'size': 'size', - '*cluster-size' : 'size' } } + '*cluster-size' : 'size', + '*encrypt' : 'RbdEncryptionCreateOptions' } } ## # @BlockdevVmdkSubformat: # # Subformat options for VMDK images # -# @monolithicSparse: Single file image with sparse cluster allocation +# @monolithicSparse: Single file image with sparse cluster allocation # -# @monolithicFlat: Single flat data image and a descriptor file +# @monolithicFlat: Single flat data image and a descriptor file # -# @twoGbMaxExtentSparse: Data is split into 2GB (per virtual LBA) sparse extent -# files, in addition to a descriptor file +# @twoGbMaxExtentSparse: Data is split into 2GB (per virtual LBA) +# sparse extent files, in addition to a descriptor file # -# @twoGbMaxExtentFlat: Data is split into 2GB (per virtual LBA) flat extent -# files, in addition to a descriptor file +# @twoGbMaxExtentFlat: Data is split into 2GB (per virtual LBA) flat +# extent files, in addition to a descriptor file # -# @streamOptimized: Single file image sparse cluster allocation, optimized -# for streaming over network. +# @streamOptimized: Single file image sparse cluster allocation, +# optimized for streaming over network. # # Since: 4.0 ## @@ -4465,23 +5219,36 @@ # # Driver specific image creation options for VMDK. # -# @file: Where to store the new image file. This refers to the image -# file for monolithcSparse and streamOptimized format, or the -# descriptor file for other formats. +# @file: Where to store the new image file. This refers to the image +# file for monolithcSparse and streamOptimized format, or the +# descriptor file for other formats. +# # @size: Size of the virtual disk in bytes -# @extents: Where to store the data extents. Required for monolithcFlat, -# twoGbMaxExtentSparse and twoGbMaxExtentFlat formats. For -# monolithicFlat, only one entry is required; for -# twoGbMaxExtent* formats, the number of entries required is -# calculated as extent_number = virtual_size / 2GB. Providing -# more extents than will be used is an error. -# @subformat: The subformat of the VMDK image. Default: "monolithicSparse". -# @backing-file: The path of backing file. Default: no backing file is used. -# @adapter-type: The adapter type used to fill in the descriptor. Default: ide. -# @hwversion: Hardware version. The meaningful options are "4" or "6". -# Default: "4". -# @zeroed-grain: Whether to enable zeroed-grain feature for sparse subformats. -# Default: false. +# +# @extents: Where to store the data extents. Required for +# monolithcFlat, twoGbMaxExtentSparse and twoGbMaxExtentFlat +# formats. For monolithicFlat, only one entry is required; for +# twoGbMaxExtent* formats, the number of entries required is +# calculated as extent_number = virtual_size / 2GB. Providing more +# extents than will be used is an error. +# +# @subformat: The subformat of the VMDK image. Default: +# "monolithicSparse". +# +# @backing-file: The path of backing file. Default: no backing file +# is used. +# +# @adapter-type: The adapter type used to fill in the descriptor. +# Default: ide. +# +# @hwversion: Hardware version. The meaningful options are "4" or +# "6". Default: "4". +# +# @toolsversion: VMware guest tools version. Default: "2147483647" +# (Since 6.2) +# +# @zeroed-grain: Whether to enable zeroed-grain feature for sparse +# subformats. Default: false. # # Since: 4.0 ## @@ -4493,83 +5260,16 @@ '*backing-file': 'str', '*adapter-type': 'BlockdevVmdkAdapterType', '*hwversion': 'str', + '*toolsversion': 'str', '*zeroed-grain': 'bool' } } - -## -# @SheepdogRedundancyType: -# -# @full: Create a fully replicated vdi with x copies -# @erasure-coded: Create an erasure coded vdi with x data strips and -# y parity strips -# -# Since: 2.12 -## -{ 'enum': 'SheepdogRedundancyType', - 'data': [ 'full', 'erasure-coded' ] } - -## -# @SheepdogRedundancyFull: -# -# @copies: Number of copies to use (between 1 and 31) -# -# Since: 2.12 -## -{ 'struct': 'SheepdogRedundancyFull', - 'data': { 'copies': 'int' }} - -## -# @SheepdogRedundancyErasureCoded: -# -# @data-strips: Number of data strips to use (one of {2,4,8,16}) -# @parity-strips: Number of parity strips to use (between 1 and 15) -# -# Since: 2.12 -## -{ 'struct': 'SheepdogRedundancyErasureCoded', - 'data': { 'data-strips': 'int', - 'parity-strips': 'int' }} - -## -# @SheepdogRedundancy: -# -# Since: 2.12 -## -{ 'union': 'SheepdogRedundancy', - 'base': { 'type': 'SheepdogRedundancyType' }, - 'discriminator': 'type', - 'data': { 'full': 'SheepdogRedundancyFull', - 'erasure-coded': 'SheepdogRedundancyErasureCoded' } } - -## -# @BlockdevCreateOptionsSheepdog: -# -# Driver specific image creation options for Sheepdog. -# -# @location: Where to store the new image file -# @size: Size of the virtual disk in bytes -# @backing-file: File name of a base image -# @preallocation: Preallocation mode for the new image (default: off; -# allowed values: off, full) -# @redundancy: Redundancy of the image -# @object-size: Object size of the image -# -# Since: 2.12 -## -{ 'struct': 'BlockdevCreateOptionsSheepdog', - 'data': { 'location': 'BlockdevOptionsSheepdog', - 'size': 'size', - '*backing-file': 'str', - '*preallocation': 'PreallocMode', - '*redundancy': 'SheepdogRedundancy', - '*object-size': 'size' } } - ## # @BlockdevCreateOptionsSsh: # # Driver specific image creation options for SSH. # # @location: Where to store the new image file +# # @size: Size of the virtual disk in bytes # # Since: 2.12 @@ -4584,9 +5284,11 @@ # Driver specific image creation options for VDI. # # @file: Node to create the image format on +# # @size: Size of the virtual disk in bytes +# # @preallocation: Preallocation mode for the new image (default: off; -# allowed values: off, metadata) +# allowed values: off, metadata) # # Since: 2.12 ## @@ -4599,7 +5301,8 @@ # @BlockdevVhdxSubformat: # # @dynamic: Growing image file -# @fixed: Preallocated fixed-size image file +# +# @fixed: Preallocated fixed-size image file # # Since: 2.12 ## @@ -4612,16 +5315,21 @@ # Driver specific image creation options for vhdx. # # @file: Node to create the image format on +# # @size: Size of the virtual disk in bytes -# @log-size: Log size in bytes, must be a multiple of 1 MB -# (default: 1 MB) +# +# @log-size: Log size in bytes, must be a multiple of 1 MB (default: 1 +# MB) +# # @block-size: Block size in bytes, must be a multiple of 1 MB and not -# larger than 256 MB (default: automatically choose a block -# size depending on the image size) +# larger than 256 MB (default: automatically choose a block size +# depending on the image size) +# # @subformat: vhdx subformat (default: dynamic) -# @block-state-zero: Force use of payload blocks of type 'ZERO'. Non-standard, -# but default. Do not set to 'off' when using 'qemu-img -# convert' with subformat=dynamic. +# +# @block-state-zero: Force use of payload blocks of type 'ZERO'. +# Non-standard, but default. Do not set to 'off' when using +# 'qemu-img convert' with subformat=dynamic. # # Since: 2.12 ## @@ -4637,7 +5345,8 @@ # @BlockdevVpcSubformat: # # @dynamic: Growing image file -# @fixed: Preallocated fixed-size image file +# +# @fixed: Preallocated fixed-size image file # # Since: 2.12 ## @@ -4650,11 +5359,14 @@ # Driver specific image creation options for vpc (VHD). # # @file: Node to create the image format on +# # @size: Size of the virtual disk in bytes +# # @subformat: vhdx subformat (default: dynamic) -# @force-size: Force use of the exact byte size instead of rounding to the -# next size that can be represented in CHS geometry -# (default: false) +# +# @force-size: Force use of the exact byte size instead of rounding to +# the next size that can be represented in CHS geometry +# (default: false) # # Since: 2.12 ## @@ -4687,7 +5399,6 @@ 'qcow2': 'BlockdevCreateOptionsQcow2', 'qed': 'BlockdevCreateOptionsQed', 'rbd': 'BlockdevCreateOptionsRbd', - 'sheepdog': 'BlockdevCreateOptionsSheepdog', 'ssh': 'BlockdevCreateOptionsSsh', 'vdi': 'BlockdevCreateOptionsVdi', 'vhdx': 'BlockdevCreateOptionsVhdx', @@ -4698,18 +5409,19 @@ ## # @blockdev-create: # -# Starts a job to create an image format on a given node. The job is +# Starts a job to create an image format on a given node. The job is # automatically finalized, but a manual job-dismiss is required. # -# @job-id: Identifier for the newly created job. +# @job-id: Identifier for the newly created job. # -# @options: Options for the image creation. +# @options: Options for the image creation. # # Since: 3.0 ## { 'command': 'blockdev-create', 'data': { 'job-id': 'str', - 'options': 'BlockdevCreateOptions' } } + 'options': 'BlockdevCreateOptions' }, + 'allow-preconfig': true } ## # @BlockdevAmendOptionsLUKS: @@ -4726,10 +5438,10 @@ ## # @BlockdevAmendOptionsQcow2: # -# Driver specific image amend options for qcow2. -# For now, only encryption options can be amended +# Driver specific image amend options for qcow2. For now, only +# encryption options can be amended # -# @encrypt Encryption options to be amended +# @encrypt: Encryption options to be amended # # Since: 5.1 ## @@ -4741,7 +5453,7 @@ # # Options for amending an image format # -# @driver: Block driver of the node to amend. +# @driver: Block driver of the node to amend. # # Since: 5.1 ## @@ -4756,20 +5468,24 @@ ## # @x-blockdev-amend: # -# Starts a job to amend format specific options of an existing open block device -# The job is automatically finalized, but a manual job-dismiss is required. +# Starts a job to amend format specific options of an existing open +# block device The job is automatically finalized, but a manual +# job-dismiss is required. # -# @job-id: Identifier for the newly created job. +# @job-id: Identifier for the newly created job. # -# @node-name: Name of the block node to work on +# @node-name: Name of the block node to work on # -# @options: Options (driver specific) +# @options: Options (driver specific) +# +# @force: Allow unsafe operations, format specific For luks that +# allows erase of the last active keyslot (permanent loss of +# data), and replacement of an active keyslot (possible loss of +# data if IO error happens) +# +# Features: # -# @force: Allow unsafe operations, format specific -# For luks that allows erase of the last active keyslot -# (permanent loss of data), -# and replacement of an active keyslot -# (possible loss of data if IO error happens) +# @unstable: This command is experimental. # # Since: 5.1 ## @@ -4777,7 +5493,9 @@ 'data': { 'job-id': 'str', 'node-name': 'str', 'options': 'BlockdevAmendOptions', - '*force': 'bool' } } + '*force': 'bool' }, + 'features': [ 'unstable' ], + 'allow-preconfig': true } ## # @BlockErrorAction: @@ -4795,45 +5513,43 @@ { 'enum': 'BlockErrorAction', 'data': [ 'ignore', 'report', 'stop' ] } - ## # @BLOCK_IMAGE_CORRUPTED: # -# Emitted when a disk image is being marked corrupt. The image can be -# identified by its device or node name. The 'device' field is always +# Emitted when a disk image is being marked corrupt. The image can be +# identified by its device or node name. The 'device' field is always # present for compatibility reasons, but it can be empty ("") if the # image does not have a device name associated. # -# @device: 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: device name. This is always present for compatibility +# reasons, but it can be empty ("") if the image does not have a +# device name associated. # # @node-name: node name (Since: 2.4) # # @msg: informative message for human consumption, such as the kind of -# corruption being detected. It should not be parsed by machine as it is -# not guaranteed to be stable +# corruption being detected. It should not be parsed by machine +# as it is not guaranteed to be stable # # @offset: if the corruption resulted from an image access, this is -# the host's access offset into the image +# the host's access offset into the image # -# @size: if the corruption resulted from an image access, this is -# the access size +# @size: if the corruption resulted from an image access, this is the +# access size # -# @fatal: if set, the image is marked corrupt and therefore unusable after this -# event and must be repaired (Since 2.2; before, every -# BLOCK_IMAGE_CORRUPTED event was fatal) +# @fatal: if set, the image is marked corrupt and therefore unusable +# after this event and must be repaired (Since 2.2; before, every +# BLOCK_IMAGE_CORRUPTED event was fatal) # # Note: If action is "stop", a STOP event will eventually follow the -# BLOCK_IO_ERROR event. +# BLOCK_IO_ERROR event. # # Example: # -# <- { "event": "BLOCK_IMAGE_CORRUPTED", -# "data": { "device": "ide0-hd0", "node-name": "node0", -# "msg": "Prevented active L1 table overwrite", "offset": 196608, -# "size": 65536 }, -# "timestamp": { "seconds": 1378126126, "microseconds": 966463 } } +# <- { "event": "BLOCK_IMAGE_CORRUPTED", +# "data": { "device": "", "node-name": "drive", "fatal": false, +# "msg": "L2 table offset 0x2a2a2a00 unaligned (L1 index: 0)" }, +# "timestamp": { "seconds": 1648243240, "microseconds": 906060 } } # # Since: 1.7 ## @@ -4850,42 +5566,42 @@ # # Emitted when a disk I/O error occurs # -# @device: 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: device name. This is always present for compatibility +# reasons, but it can be empty ("") if the image does not have a +# device name associated. # -# @node-name: node name. Note that errors may be reported for the root node -# that is directly attached to a guest device rather than for the -# node where the error occurred. The node name is not present if -# the drive is empty. (Since: 2.8) +# @node-name: node name. Note that errors may be reported for the +# root node that is directly attached to a guest device rather +# than for the node where the error occurred. The node name is +# not present if the drive is empty. (Since: 2.8) # # @operation: I/O operation # # @action: action that has been taken # -# @nospace: true if I/O error was caused due to a no-space -# condition. This key is only present if query-block's -# io-status is present, please see query-block documentation -# for more information (since: 2.2) +# @nospace: true if I/O error was caused due to a no-space condition. +# This key is only present if query-block's io-status is present, +# please see query-block documentation for more information +# (since: 2.2) # -# @reason: human readable string describing the error cause. -# (This field is a debugging aid for humans, it should not -# be parsed by applications) (since: 2.2) +# @reason: human readable string describing the error cause. (This +# field is a debugging aid for humans, it should not be parsed by +# applications) (since: 2.2) # # Note: If action is "stop", a STOP event will eventually follow the -# BLOCK_IO_ERROR event +# BLOCK_IO_ERROR event # # Since: 0.13 # # Example: # -# <- { "event": "BLOCK_IO_ERROR", -# "data": { "device": "ide0-hd1", -# "node-name": "#block212", -# "operation": "write", -# "action": "stop" }, -# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } -# +# <- { "event": "BLOCK_IO_ERROR", +# "data": { "device": "ide0-hd1", +# "node-name": "#block212", +# "operation": "write", +# "action": "stop", +# "reason": "No space left on device" }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } ## { 'event': 'BLOCK_IO_ERROR', 'data': { 'device': 'str', '*node-name': 'str', @@ -4900,31 +5616,30 @@ # # @type: job type # -# @device: The job identifier. Originally the device name but other -# values are allowed since QEMU 2.7 +# @device: The job identifier. Originally the device name but other +# values are allowed since QEMU 2.7 # # @len: maximum progress value # -# @offset: current progress value. On success this is equal to len. -# On failure this is less than len +# @offset: current progress value. On success this is equal to len. +# On failure this is less than len # # @speed: rate limit, bytes per second # -# @error: error message. Only present on failure. This field -# contains a human-readable error message. There are no semantics -# other than that streaming has failed and clients should not try to -# interpret the error string +# @error: error message. Only present on failure. This field +# contains a human-readable error message. There are no semantics +# other than that streaming has failed and clients should not try +# to interpret the error string # # Since: 1.1 # # Example: # -# <- { "event": "BLOCK_JOB_COMPLETED", -# "data": { "type": "stream", "device": "virtio-disk0", -# "len": 10737418240, "offset": 10737418240, -# "speed": 0 }, -# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } -# +# <- { "event": "BLOCK_JOB_COMPLETED", +# "data": { "type": "stream", "device": "virtio-disk0", +# "len": 10737418240, "offset": 10737418240, +# "speed": 0 }, +# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } ## { 'event': 'BLOCK_JOB_COMPLETED', 'data': { 'type' : 'JobType', @@ -4941,13 +5656,13 @@ # # @type: job type # -# @device: The job identifier. Originally the device name but other -# values are allowed since QEMU 2.7 +# @device: The job identifier. Originally the device name but other +# values are allowed since QEMU 2.7 # # @len: maximum progress value # -# @offset: current progress value. On success this is equal to len. -# On failure this is less than len +# @offset: current progress value. On success this is equal to len. +# On failure this is less than len # # @speed: rate limit, bytes per second # @@ -4955,12 +5670,11 @@ # # Example: # -# <- { "event": "BLOCK_JOB_CANCELLED", -# "data": { "type": "stream", "device": "virtio-disk0", -# "len": 10737418240, "offset": 134217728, -# "speed": 0 }, -# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } -# +# <- { "event": "BLOCK_JOB_CANCELLED", +# "data": { "type": "stream", "device": "virtio-disk0", +# "len": 10737418240, "offset": 134217728, +# "speed": 0 }, +# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } ## { 'event': 'BLOCK_JOB_CANCELLED', 'data': { 'type' : 'JobType', @@ -4974,8 +5688,8 @@ # # Emitted when a block job encounters an error # -# @device: The job identifier. Originally the device name but other -# values are allowed since QEMU 2.7 +# @device: The job identifier. Originally the device name but other +# values are allowed since QEMU 2.7 # # @operation: I/O operation # @@ -4985,12 +5699,11 @@ # # Example: # -# <- { "event": "BLOCK_JOB_ERROR", -# "data": { "device": "ide0-hd1", -# "operation": "write", -# "action": "stop" }, -# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } -# +# <- { "event": "BLOCK_JOB_ERROR", +# "data": { "device": "ide0-hd1", +# "operation": "write", +# "action": "stop" }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } ## { 'event': 'BLOCK_JOB_ERROR', 'data': { 'device' : 'str', @@ -5004,28 +5717,27 @@ # # @type: job type # -# @device: The job identifier. Originally the device name but other -# values are allowed since QEMU 2.7 +# @device: The job identifier. Originally the device name but other +# values are allowed since QEMU 2.7 # # @len: maximum progress value # -# @offset: current progress value. On success this is equal to len. -# On failure this is less than len +# @offset: current progress value. On success this is equal to len. +# On failure this is less than len # # @speed: rate limit, bytes per second # -# Note: The "ready to complete" status is always reset by a @BLOCK_JOB_ERROR -# event +# Note: The "ready to complete" status is always reset by a +# @BLOCK_JOB_ERROR event # # Since: 1.3 # # Example: # -# <- { "event": "BLOCK_JOB_READY", -# "data": { "device": "drive0", "type": "mirror", "speed": 0, -# "len": 2097152, "offset": 2097152 } -# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } -# +# <- { "event": "BLOCK_JOB_READY", +# "data": { "device": "drive0", "type": "mirror", "speed": 0, +# "len": 2097152, "offset": 2097152 }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } ## { 'event': 'BLOCK_JOB_READY', 'data': { 'type' : 'JobType', @@ -5037,9 +5749,10 @@ ## # @BLOCK_JOB_PENDING: # -# Emitted when a block job is awaiting explicit authorization to finalize graph -# changes via @block-job-finalize. If this job is part of a transaction, it will -# not emit this event until the transaction has converged first. +# Emitted when a block job is awaiting explicit authorization to +# finalize graph changes via @block-job-finalize. If this job is part +# of a transaction, it will not emit this event until the transaction +# has converged first. # # @type: job type # @@ -5049,10 +5762,9 @@ # # Example: # -# <- { "event": "BLOCK_JOB_WAITING", -# "data": { "device": "drive0", "type": "mirror" }, -# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } -# +# <- { "event": "BLOCK_JOB_PENDING", +# "data": { "type": "mirror", "id": "backup_1" }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } ## { 'event': 'BLOCK_JOB_PENDING', 'data': { 'type' : 'JobType', @@ -5064,13 +5776,16 @@ # Preallocation mode of QEMU image file # # @off: no preallocation +# # @metadata: preallocate only for metadata +# # @falloc: like @full preallocation but allocate disk space by -# posix_fallocate() rather than writing data. +# posix_fallocate() rather than writing data. +# # @full: preallocate all data by writing it to the device to ensure -# disk space is really available. This data may or may not be -# zero, depending on the image format and storage. -# @full preallocation also sets up metadata correctly. +# disk space is really available. This data may or may not be +# zero, depending on the image format and storage. @full +# preallocation also sets up metadata correctly. # # Since: 2.2 ## @@ -5081,15 +5796,15 @@ # @BLOCK_WRITE_THRESHOLD: # # Emitted when writes on block device reaches or exceeds the -# configured write threshold. For thin-provisioned devices, this -# means the device should be extended to avoid pausing for -# disk exhaustion. -# The event is one shot. Once triggered, it needs to be +# configured write threshold. For thin-provisioned devices, this +# means the device should be extended to avoid pausing for disk +# exhaustion. The event is one shot. Once triggered, it needs to be # re-registered with another block-set-write-threshold command. # # @node-name: graph node name on which the threshold was exceeded. # -# @amount-exceeded: amount of data which exceeded the threshold, in bytes. +# @amount-exceeded: amount of data which exceeded the threshold, in +# bytes. # # @write-threshold: last configured threshold, in bytes. # @@ -5103,43 +5818,43 @@ ## # @block-set-write-threshold: # -# Change the write threshold for a block drive. An event will be +# Change the write threshold for a block drive. An event will be # delivered if a write to this block drive crosses the configured -# threshold. The threshold is an offset, thus must be -# non-negative. Default is no write threshold. Setting the threshold -# to zero disables it. +# threshold. The threshold is an offset, thus must be non-negative. +# Default is no write threshold. Setting the threshold to zero +# disables it. # -# This is useful to transparently resize thin-provisioned drives without -# the guest OS noticing. +# This is useful to transparently resize thin-provisioned drives +# without the guest OS noticing. # # @node-name: graph node name on which the threshold must be set. # # @write-threshold: configured threshold for the block device, bytes. -# Use 0 to disable the threshold. +# Use 0 to disable the threshold. # # Since: 2.3 # # Example: # -# -> { "execute": "block-set-write-threshold", -# "arguments": { "node-name": "mydev", -# "write-threshold": 17179869184 } } -# <- { "return": {} } -# +# -> { "execute": "block-set-write-threshold", +# "arguments": { "node-name": "mydev", +# "write-threshold": 17179869184 } } +# <- { "return": {} } ## { 'command': 'block-set-write-threshold', - 'data': { 'node-name': 'str', 'write-threshold': 'uint64' } } + 'data': { 'node-name': 'str', 'write-threshold': 'uint64' }, + 'allow-preconfig': true } ## # @x-blockdev-change: # -# Dynamically reconfigure the block driver state graph. It can be used -# to add, remove, insert or replace a graph node. Currently only the -# Quorum driver implements this feature to add or remove its child. This -# is useful to fix a broken quorum child. +# Dynamically reconfigure the block driver state graph. It can be +# used to add, remove, insert or replace a graph node. Currently only +# the Quorum driver implements this feature to add or remove its +# child. This is useful to fix a broken quorum child. # -# If @node is specified, it will be inserted under @parent. @child -# may not be specified in this case. If both @parent and @child are +# If @node is specified, it will be inserted under @parent. @child +# may not be specified in this case. If both @parent and @child are # specified but @node is not, @child will be detached from @parent. # # @parent: the id or name of the parent node. @@ -5148,51 +5863,57 @@ # # @node: the name of the node that will be added. # -# Note: this command is experimental, and its API is not stable. It -# does not support all kinds of operations, all kinds of children, nor -# all block drivers. +# Features: +# +# @unstable: This command is experimental, and its API is not stable. +# It does not support all kinds of operations, all kinds of +# children, nor all block drivers. # -# FIXME Removing children from a quorum node means introducing gaps in the -# child indices. This cannot be represented in the 'children' list of -# BlockdevOptionsQuorum, as returned by .bdrv_refresh_filename(). +# FIXME Removing children from a quorum node means introducing +# gaps in the child indices. This cannot be represented in the +# 'children' list of BlockdevOptionsQuorum, as returned by +# .bdrv_refresh_filename(). # -# Warning: The data in a new quorum child MUST be consistent with that of -# the rest of the array. +# Warning: The data in a new quorum child MUST be consistent with +# that of the rest of the array. # # Since: 2.7 # -# Example: +# Examples: +# +# 1. Add a new node to a quorum # -# 1. Add a new node to a quorum -# -> { "execute": "blockdev-add", -# "arguments": { -# "driver": "raw", -# "node-name": "new_node", -# "file": { "driver": "file", -# "filename": "test.raw" } } } -# <- { "return": {} } -# -> { "execute": "x-blockdev-change", -# "arguments": { "parent": "disk1", -# "node": "new_node" } } -# <- { "return": {} } -# -# 2. Delete a quorum's node -# -> { "execute": "x-blockdev-change", -# "arguments": { "parent": "disk1", -# "child": "children.1" } } -# <- { "return": {} } +# -> { "execute": "blockdev-add", +# "arguments": { +# "driver": "raw", +# "node-name": "new_node", +# "file": { "driver": "file", +# "filename": "test.raw" } } } +# <- { "return": {} } +# -> { "execute": "x-blockdev-change", +# "arguments": { "parent": "disk1", +# "node": "new_node" } } +# <- { "return": {} } # +# 2. Delete a quorum's node +# +# -> { "execute": "x-blockdev-change", +# "arguments": { "parent": "disk1", +# "child": "children.1" } } +# <- { "return": {} } ## { 'command': 'x-blockdev-change', 'data' : { 'parent': 'str', '*child': 'str', - '*node': 'str' } } + '*node': 'str' }, + 'features': [ 'unstable' ], + 'allow-preconfig': true } ## # @x-blockdev-set-iothread: # -# Move @node and its children into the @iothread. If @iothread is null then -# move @node and its children into the main loop. +# Move @node and its children into the @iothread. If @iothread is +# null then move @node and its children into the main loop. # # The node must not be attached to a BlockBackend. # @@ -5200,33 +5921,38 @@ # # @iothread: the name of the IOThread object or null for the main loop # -# @force: true if the node and its children should be moved when a BlockBackend -# is already attached +# @force: true if the node and its children should be moved when a +# BlockBackend is already attached +# +# Features: # -# Note: this command is experimental and intended for test cases that need -# control over IOThreads only. +# @unstable: This command is experimental and intended for test cases +# that need control over IOThreads only. # # Since: 2.12 # -# Example: +# Examples: +# +# 1. Move a node into an IOThread # -# 1. Move a node into an IOThread -# -> { "execute": "x-blockdev-set-iothread", -# "arguments": { "node-name": "disk1", -# "iothread": "iothread0" } } -# <- { "return": {} } +# -> { "execute": "x-blockdev-set-iothread", +# "arguments": { "node-name": "disk1", +# "iothread": "iothread0" } } +# <- { "return": {} } # -# 2. Move a node into the main loop -# -> { "execute": "x-blockdev-set-iothread", -# "arguments": { "node-name": "disk1", -# "iothread": null } } -# <- { "return": {} } +# 2. Move a node into the main loop # +# -> { "execute": "x-blockdev-set-iothread", +# "arguments": { "node-name": "disk1", +# "iothread": null } } +# <- { "return": {} } ## { 'command': 'x-blockdev-set-iothread', 'data' : { 'node-name': 'str', 'iothread': 'StrOrNull', - '*force': 'bool' } } + '*force': 'bool' }, + 'features': [ 'unstable' ], + 'allow-preconfig': true } ## # @QuorumOpType: @@ -5261,10 +5987,9 @@ # # Example: # -# <- { "event": "QUORUM_FAILURE", -# "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 }, -# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } -# +# <- { "event": "QUORUM_FAILURE", +# "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 }, +# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } ## { 'event': 'QUORUM_FAILURE', 'data': { 'reference': 'str', 'sector-num': 'int', 'sectors-count': 'int' } } @@ -5276,10 +6001,10 @@ # # @type: quorum operation type (Since 2.6) # -# @error: error message. Only present on failure. This field -# contains a human-readable error message. There are no semantics other -# than that the block layer reported an error and clients should not -# try to interpret the error string. +# @error: error message. Only present on failure. This field +# contains a human-readable error message. There are no semantics +# other than that the block layer reported an error and clients +# should not try to interpret the error string. # # @node-name: the graph node name of the block driver state # @@ -5291,22 +6016,21 @@ # # Since: 2.0 # -# Example: -# -# 1. Read operation +# Examples: # -# { "event": "QUORUM_REPORT_BAD", -# "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5, -# "type": "read" }, -# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } +# 1. Read operation # -# 2. Flush operation +# <- { "event": "QUORUM_REPORT_BAD", +# "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5, +# "type": "read" }, +# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } # -# { "event": "QUORUM_REPORT_BAD", -# "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120, -# "type": "flush", "error": "Broken pipe" }, -# "timestamp": { "seconds": 1456406829, "microseconds": 291763 } } +# 2. Flush operation # +# <- { "event": "QUORUM_REPORT_BAD", +# "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120, +# "type": "flush", "error": "Broken pipe" }, +# "timestamp": { "seconds": 1456406829, "microseconds": 291763 } } ## { 'event': 'QUORUM_REPORT_BAD', 'data': { 'type': 'QuorumOpType', '*error': 'str', 'node-name': 'str', @@ -5315,14 +6039,14 @@ ## # @BlockdevSnapshotInternal: # -# @device: the device name or node-name of a root node to generate the snapshot -# from +# @device: the device name or node-name of a root node to generate the +# snapshot from # # @name: the name of the internal snapshot to be created # -# Notes: In transaction, if @name is empty, or any snapshot matching @name -# exists, the operation will fail. Only some image formats support it, -# for example, qcow2, rbd, and sheepdog. +# Notes: In transaction, if @name is empty, or any snapshot matching +# @name exists, the operation will fail. Only some image formats +# support it, for example, qcow2, and rbd. # # Since: 1.7 ## @@ -5333,76 +6057,90 @@ # @blockdev-snapshot-internal-sync: # # Synchronously take an internal snapshot of a block device, when the -# format of the image used supports it. If the name is an empty +# format of the image used supports it. If the name is an empty # string, or a snapshot with name already exists, the operation will # fail. # -# For the arguments, see the documentation of BlockdevSnapshotInternal. +# For the arguments, see the documentation of +# BlockdevSnapshotInternal. # -# Returns: - nothing on success -# - If @device is not a valid block device, GenericError -# - If any snapshot matching @name exists, or @name is empty, -# GenericError -# - If the format of the image used does not support it, -# BlockFormatFeatureNotSupported +# Errors: +# - If @device is not a valid block device, GenericError +# - If any snapshot matching @name exists, or @name is empty, +# GenericError +# - If the format of the image used does not support it, +# GenericError # # Since: 1.7 # # Example: # -# -> { "execute": "blockdev-snapshot-internal-sync", -# "arguments": { "device": "ide-hd0", -# "name": "snapshot0" } -# } -# <- { "return": {} } -# +# -> { "execute": "blockdev-snapshot-internal-sync", +# "arguments": { "device": "ide-hd0", +# "name": "snapshot0" } +# } +# <- { "return": {} } ## { 'command': 'blockdev-snapshot-internal-sync', - 'data': 'BlockdevSnapshotInternal' } + 'data': 'BlockdevSnapshotInternal', + 'allow-preconfig': true } ## # @blockdev-snapshot-delete-internal-sync: # -# Synchronously delete an internal snapshot of a block device, when the format -# of the image used support it. The snapshot is identified by name or id or -# both. One of the name or id is required. Return SnapshotInfo for the -# successfully deleted snapshot. +# Synchronously delete an internal snapshot of a block device, when +# the format of the image used support it. The snapshot is identified +# by name or id or both. One of the name or id is required. Return +# SnapshotInfo for the successfully deleted snapshot. # -# @device: the device name or node-name of a root node to delete the snapshot -# from +# @device: the device name or node-name of a root node to delete the +# snapshot from # # @id: optional the snapshot's ID to be deleted # # @name: optional the snapshot's name to be deleted # -# Returns: - SnapshotInfo on success -# - If @device is not a valid block device, GenericError -# - If snapshot not found, GenericError -# - If the format of the image used does not support it, -# BlockFormatFeatureNotSupported -# - If @id and @name are both not specified, GenericError +# Returns: +# SnapshotInfo +# +# Errors: +# - If @device is not a valid block device, GenericError +# - If snapshot not found, GenericError +# - If the format of the image used does not support it, +# GenericError +# - If @id and @name are both not specified, GenericError # # Since: 1.7 # # Example: # -# -> { "execute": "blockdev-snapshot-delete-internal-sync", -# "arguments": { "device": "ide-hd0", -# "name": "snapshot0" } -# } -# <- { "return": { -# "id": "1", -# "name": "snapshot0", -# "vm-state-size": 0, -# "date-sec": 1000012, -# "date-nsec": 10, -# "vm-clock-sec": 100, -# "vm-clock-nsec": 20, -# "icount": 220414 -# } -# } -# +# -> { "execute": "blockdev-snapshot-delete-internal-sync", +# "arguments": { "device": "ide-hd0", +# "name": "snapshot0" } +# } +# <- { "return": { +# "id": "1", +# "name": "snapshot0", +# "vm-state-size": 0, +# "date-sec": 1000012, +# "date-nsec": 10, +# "vm-clock-sec": 100, +# "vm-clock-nsec": 20, +# "icount": 220414 +# } +# } ## { 'command': 'blockdev-snapshot-delete-internal-sync', 'data': { 'device': 'str', '*id': 'str', '*name': 'str'}, - 'returns': 'SnapshotInfo' } + 'returns': 'SnapshotInfo', + 'allow-preconfig': true } + +## +# @DummyBlockCoreForceArrays: +# +# Not used by QMP; hack to let us use BlockGraphInfoList internally +# +# Since: 8.0 +## +{ 'struct': 'DummyBlockCoreForceArrays', + 'data': { 'unused-block-graph-info': ['BlockGraphInfo'] } } diff --git a/qapi/block-export.json b/qapi/block-export.json index e819e70cac..3919a2d5b9 100644 --- a/qapi/block-export.json +++ b/qapi/block-export.json @@ -6,22 +6,29 @@ ## { 'include': 'sockets.json' } +{ 'include': 'block-core.json' } ## # @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. (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 ## @@ -35,24 +42,31 @@ # @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. (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). # -# Returns: error if the server is already running. +# @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). +# +# Errors: +# - if the server is already running # # Since: 1.3 ## @@ -60,19 +74,20 @@ 'data': { 'addr': 'SocketAddressLegacy', '*tls-creds': 'str', '*tls-authz': 'str', - '*max-connections': 'uint32' } } + '*max-connections': 'uint32' }, + 'allow-preconfig': true } ## # @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 ## @@ -86,32 +101,37 @@ # 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. +# @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 ## { 'struct': 'BlockExportOptionsNbd', 'base': 'BlockExportOptionsNbdBase', - 'data': { '*bitmaps': ['str'], '*allocation-depth': 'bool' } } + 'data': { '*bitmaps': ['BlockDirtyBitmapOrStr'], + '*allocation-depth': 'bool' } } ## # @BlockExportOptionsVhostUserBlk: # # 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 ## @@ -121,23 +141,77 @@ '*num-queues': 'uint16'} } ## +# @FuseExportAllowOther: +# +# Possible allow_other modes for FUSE exports. +# +# @off: Do not pass allow_other as a mount option. +# +# @on: Pass allow_other as a mount option. +# +# @auto: Try mounting with allow_other first, and if that fails, retry +# without allow_other. +# +# Since: 6.1 +## +{ 'enum': 'FuseExportAllowOther', + 'data': ['off', 'on', 'auto'] } + +## # @BlockExportOptionsFuse: # # 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) # # Since: 6.0 ## { 'struct': 'BlockExportOptionsFuse', 'data': { 'mountpoint': 'str', - '*growable': 'bool' }, - 'if': 'defined(CONFIG_FUSE)' } + '*growable': 'bool', + '*allow-other': 'FuseExportAllowOther' }, + 'if': 'CONFIG_FUSE' } + +## +# @BlockExportOptionsVduseBlk: +# +# 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. +# +# Since: 7.1 +## +{ 'struct': 'BlockExportOptionsVduseBlk', + 'data': { 'name': 'str', + '*num-queues': 'uint16', + '*queue-size': 'uint16', + '*logical-block-size': 'size', + '*serial': 'str' } } ## # @NbdServerAddOptions: @@ -146,13 +220,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 ## @@ -166,35 +240,42 @@ # # 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. +# +# Errors: +# - if the server is not running +# - if an export with the same name already exists # # Since: 1.3 ## { 'command': 'nbd-server-add', - 'data': 'NbdServerAddOptions', 'boxed': true, 'features': ['deprecated'] } + 'data': 'NbdServerAddOptions', 'boxed': true, 'features': ['deprecated'], + 'allow-preconfig': true } ## # @BlockExportRemoveMode: # # 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: +# TODO: 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 ## @@ -207,32 +288,36 @@ # # @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. # -# Returns: error if -# - the server is not running -# - export is not found -# - mode is 'safe' and there are existing connections +# @deprecated: This command is deprecated. Use @block-export-del +# instead. +# +# Errors: +# - if the server is not running +# - if export is not found +# - if mode is 'safe' and there are existing connections # # Since: 2.12 ## { 'command': 'nbd-server-remove', 'data': {'name': 'str', '*mode': 'BlockExportRemoveMode'}, - 'features': ['deprecated'] } + 'features': ['deprecated'], + 'allow-preconfig': true } ## # @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 ## -{ 'command': 'nbd-server-stop' } +{ 'command': 'nbd-server-stop', + 'allow-preconfig': true } ## # @BlockExportType: @@ -240,40 +325,52 @@ # 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 ## { 'enum': 'BlockExportType', - 'data': [ 'nbd', 'vhost-user-blk', - { 'name': 'fuse', 'if': 'defined(CONFIG_FUSE)' } ] } + 'data': [ 'nbd', + { 'name': 'vhost-user-blk', + 'if': 'CONFIG_VHOST_USER_BLK_SERVER' }, + { 'name': 'fuse', 'if': 'CONFIG_FUSE' }, + { 'name': 'vduse-blk', 'if': 'CONFIG_VDUSE_BLK_EXPORT' } ] } ## # @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) +# @type: Block export type # -# @node-name: The node name of the block node to be exported (since: 5.2) +# @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) # # @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 ## @@ -288,9 +385,12 @@ 'discriminator': 'type', 'data': { 'nbd': 'BlockExportOptionsNbd', - 'vhost-user-blk': 'BlockExportOptionsVhostUserBlk', + 'vhost-user-blk': { 'type': 'BlockExportOptionsVhostUserBlk', + 'if': 'CONFIG_VHOST_USER_BLK_SERVER' }, 'fuse': { 'type': 'BlockExportOptionsFuse', - 'if': 'defined(CONFIG_FUSE)' } + 'if': 'CONFIG_FUSE' }, + 'vduse-blk': { 'type': 'BlockExportOptionsVduseBlk', + 'if': 'CONFIG_VDUSE_BLK_EXPORT' } } } ## @@ -301,27 +401,31 @@ # Since: 5.2 ## { 'command': 'block-export-add', - 'data': 'BlockExportOptions', 'boxed': true } + 'data': 'BlockExportOptions', 'boxed': true, + 'allow-preconfig': true } ## # @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) +# Errors: +# - if the export is not found +# - if @mode is 'safe' and the export is still in use (e.g. by +# existing client connections) # # Since: 5.2 ## { 'command': 'block-export-del', - 'data': { 'id': 'str', '*mode': 'BlockExportRemoveMode' } } + 'data': { 'id': 'str', '*mode': 'BlockExportRemoveMode' }, + 'allow-preconfig': true } ## # @BLOCK_EXPORT_DELETED: @@ -347,10 +451,9 @@ # @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 +# Since: 5.2 ## { 'struct': 'BlockExportInfo', 'data': { 'id': 'str', @@ -365,4 +468,5 @@ # # Since: 5.2 ## -{ 'command': 'query-block-exports', 'returns': ['BlockExportInfo'] } +{ 'command': 'query-block-exports', 'returns': ['BlockExportInfo'], + 'allow-preconfig': true } diff --git a/qapi/block.json b/qapi/block.json index 82fcf2c914..5de99fe09d 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -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 ## @@ -50,10 +50,14 @@ # # 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 +# @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,21 +104,23 @@ # @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 -# Notes: Ejecting a device with no media results in success +# Errors: +# - If @device is not a valid block device, DeviceNotFound +# +# Notes: Ejecting a device with no media results in success # # Since: 0.14 # # Example: # -# -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } } -# <- { "return": {} } +# -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } } +# <- { "return": {} } ## { 'command': 'eject', 'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] }, @@ -122,50 +130,50 @@ ## # @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 # # Example: # -# -> { "execute": "blockdev-open-tray", -# "arguments": { "id": "ide0-1-0" } } -# -# <- { "timestamp": { "seconds": 1418751016, -# "microseconds": 716996 }, -# "event": "DEVICE_TRAY_MOVED", -# "data": { "device": "ide1-cd0", -# "id": "ide0-1-0", -# "tray-open": true } } +# -> { "execute": "blockdev-open-tray", +# "arguments": { "id": "ide0-1-0" } } # -# <- { "return": {} } +# <- { "timestamp": { "seconds": 1418751016, +# "microseconds": 716996 }, +# "event": "DEVICE_TRAY_MOVED", +# "data": { "device": "ide1-cd0", +# "id": "ide0-1-0", +# "tray-open": true } } # +# <- { "return": {} } ## { 'command': 'blockdev-open-tray', 'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] }, @@ -175,9 +183,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. # @@ -186,24 +194,24 @@ # @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 # # Example: # -# -> { "execute": "blockdev-close-tray", -# "arguments": { "id": "ide0-1-0" } } -# -# <- { "timestamp": { "seconds": 1418751345, -# "microseconds": 272147 }, -# "event": "DEVICE_TRAY_MOVED", -# "data": { "device": "ide1-cd0", -# "id": "ide0-1-0", -# "tray-open": false } } +# -> { "execute": "blockdev-close-tray", +# "arguments": { "id": "ide0-1-0" } } # -# <- { "return": {} } +# <- { "timestamp": { "seconds": 1418751345, +# "microseconds": 272147 }, +# "event": "DEVICE_TRAY_MOVED", +# "data": { "device": "ide1-cd0", +# "id": "ide0-1-0", +# "tray-open": false } } # +# <- { "return": {} } ## { 'command': 'blockdev-close-tray', 'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] }, @@ -212,11 +220,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 # @@ -224,29 +233,28 @@ # # Example: # -# -> { "execute": "blockdev-remove-medium", -# "arguments": { "id": "ide0-1-0" } } +# -> { "execute": "blockdev-remove-medium", +# "arguments": { "id": "ide0-1-0" } } # -# <- { "error": { "class": "GenericError", -# "desc": "Tray of device 'ide0-1-0' is not open" } } +# <- { "error": { "class": "GenericError", +# "desc": "Tray of device 'ide0-1-0' is not open" } } # -# -> { "execute": "blockdev-open-tray", -# "arguments": { "id": "ide0-1-0" } } +# -> { "execute": "blockdev-open-tray", +# "arguments": { "id": "ide0-1-0" } } # -# <- { "timestamp": { "seconds": 1418751627, -# "microseconds": 549958 }, -# "event": "DEVICE_TRAY_MOVED", -# "data": { "device": "ide1-cd0", -# "id": "ide0-1-0", -# "tray-open": true } } +# <- { "timestamp": { "seconds": 1418751627, +# "microseconds": 549958 }, +# "event": "DEVICE_TRAY_MOVED", +# "data": { "device": "ide1-cd0", +# "id": "ide0-1-0", +# "tray-open": true } } # -# <- { "return": {} } +# <- { "return": {} } # -# -> { "execute": "blockdev-remove-medium", -# "arguments": { "id": "ide0-1-0" } } -# -# <- { "return": {} } +# -> { "execute": "blockdev-remove-medium", +# "arguments": { "id": "ide0-1-0" } } # +# <- { "return": {} } ## { 'command': 'blockdev-remove-medium', 'data': { 'id': 'str' } } @@ -254,9 +262,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 # @@ -266,26 +274,24 @@ # # Example: # -# -> { "execute": "blockdev-add", -# "arguments": { -# "node-name": "node0", -# "driver": "raw", -# "file": { "driver": "file", -# "filename": "fedora.iso" } } } -# <- { "return": {} } -# -# -> { "execute": "blockdev-insert-medium", -# "arguments": { "id": "ide0-1-0", -# "node-name": "node0" } } +# -> { "execute": "blockdev-add", +# "arguments": { +# "node-name": "node0", +# "driver": "raw", +# "file": { "driver": "file", +# "filename": "fedora.iso" } } } +# <- { "return": {} } # -# <- { "return": {} } +# -> { "execute": "blockdev-insert-medium", +# "arguments": { "id": "ide0-1-0", +# "node-name": "node0" } } # +# <- { "return": {} } ## { 'command': 'blockdev-insert-medium', 'data': { 'id': 'str', 'node-name': 'str'} } - ## # @BlockdevChangeReadOnlyMode: # @@ -299,102 +305,106 @@ # @read-write: Makes the device writable # # Since: 2.3 -# ## { 'enum': 'BlockdevChangeReadOnlyMode', 'data': ['retain', 'read-only', 'read-write'] } - ## # @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) # # Features: +# # @deprecated: Member @device is deprecated. Use @id instead. # # Since: 2.5 # # Examples: # -# 1. Change a removable medium -# -# -> { "execute": "blockdev-change-medium", -# "arguments": { "id": "ide0-1-0", -# "filename": "/srv/images/Fedora-12-x86_64-DVD.iso", -# "format": "raw" } } -# <- { "return": {} } +# 1. Change a removable medium # -# 2. Load a read-only medium into a writable drive +# -> { "execute": "blockdev-change-medium", +# "arguments": { "id": "ide0-1-0", +# "filename": "/srv/images/Fedora-12-x86_64-DVD.iso", +# "format": "raw" } } +# <- { "return": {} } # -# -> { "execute": "blockdev-change-medium", -# "arguments": { "id": "floppyA", -# "filename": "/srv/images/ro.img", -# "format": "raw", -# "read-only-mode": "retain" } } +# 2. Load a read-only medium into a writable drive # -# <- { "error": -# { "class": "GenericError", -# "desc": "Could not open '/srv/images/ro.img': Permission denied" } } +# -> { "execute": "blockdev-change-medium", +# "arguments": { "id": "floppyA", +# "filename": "/srv/images/ro.img", +# "format": "raw", +# "read-only-mode": "retain" } } # -# -> { "execute": "blockdev-change-medium", -# "arguments": { "id": "floppyA", -# "filename": "/srv/images/ro.img", -# "format": "raw", -# "read-only-mode": "read-only" } } +# <- { "error": +# { "class": "GenericError", +# "desc": "Could not open '/srv/images/ro.img': Permission denied" } } # -# <- { "return": {} } +# -> { "execute": "blockdev-change-medium", +# "arguments": { "id": "floppyA", +# "filename": "/srv/images/ro.img", +# "format": "raw", +# "read-only-mode": "read-only" } } # +# <- { "return": {} } ## { 'command': 'blockdev-change-medium', 'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] }, '*id': 'str', 'filename': 'str', '*format': 'str', + '*force': 'bool', '*read-only-mode': 'BlockdevChangeReadOnlyMode' } } - ## # @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 # # Example: # -# <- { "event": "DEVICE_TRAY_MOVED", -# "data": { "device": "ide1-cd0", -# "id": "/machine/unattached/device[22]", -# "tray-open": true -# }, -# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } -# +# <- { "event": "DEVICE_TRAY_MOVED", +# "data": { "device": "ide1-cd0", +# "id": "/machine/unattached/device[22]", +# "tray-open": true +# }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } ## { 'event': 'DEVICE_TRAY_MOVED', 'data': { 'device': 'str', 'id': 'str', 'tray-open': 'bool' } } @@ -413,12 +423,11 @@ # # Example: # -# <- { "event": "PR_MANAGER_STATUS_CHANGED", -# "data": { "id": "pr-helper0", -# "connected": true -# }, -# "timestamp": { "seconds": 1519840375, "microseconds": 450486 } } -# +# <- { "event": "PR_MANAGER_STATUS_CHANGED", +# "data": { "id": "pr-helper0", +# "connected": true +# }, +# "timestamp": { "seconds": 1519840375, "microseconds": 450486 } } ## { 'event': 'PR_MANAGER_STATUS_CHANGED', 'data': { 'id': 'str', 'connected': 'bool' } } @@ -433,140 +442,152 @@ # # 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 +# Errors: +# - If @device is not a valid block device, DeviceNotFound # # Since: 1.1 # -# Example: +# Examples: # -# -> { "execute": "block_set_io_throttle", -# "arguments": { "id": "virtio-blk-pci0/virtio-backend", -# "bps": 0, -# "bps_rd": 0, -# "bps_wr": 0, -# "iops": 512, -# "iops_rd": 0, -# "iops_wr": 0, -# "bps_max": 0, -# "bps_rd_max": 0, -# "bps_wr_max": 0, -# "iops_max": 0, -# "iops_rd_max": 0, -# "iops_wr_max": 0, -# "bps_max_length": 0, -# "iops_size": 0 } } -# <- { "return": {} } -# -# -> { "execute": "block_set_io_throttle", -# "arguments": { "id": "ide0-1-0", -# "bps": 1000000, -# "bps_rd": 0, -# "bps_wr": 0, -# "iops": 0, -# "iops_rd": 0, -# "iops_wr": 0, -# "bps_max": 8000000, -# "bps_rd_max": 0, -# "bps_wr_max": 0, -# "iops_max": 0, -# "iops_rd_max": 0, -# "iops_wr_max": 0, -# "bps_max_length": 60, -# "iops_size": 0 } } -# <- { "return": {} } +# -> { "execute": "block_set_io_throttle", +# "arguments": { "id": "virtio-blk-pci0/virtio-backend", +# "bps": 0, +# "bps_rd": 0, +# "bps_wr": 0, +# "iops": 512, +# "iops_rd": 0, +# "iops_wr": 0, +# "bps_max": 0, +# "bps_rd_max": 0, +# "bps_wr_max": 0, +# "iops_max": 0, +# "iops_rd_max": 0, +# "iops_wr_max": 0, +# "bps_max_length": 0, +# "iops_size": 0 } } +# <- { "return": {} } +# +# -> { "execute": "block_set_io_throttle", +# "arguments": { "id": "ide0-1-0", +# "bps": 1000000, +# "bps_rd": 0, +# "bps_wr": 0, +# "iops": 0, +# "iops_rd": 0, +# "iops_wr": 0, +# "bps_max": 8000000, +# "bps_rd_max": 0, +# "bps_wr_max": 0, +# "iops_max": 0, +# "iops_rd_max": 0, +# "iops_wr_max": 0, +# "bps_max_length": 60, +# "iops_size": 0 } } +# <- { "return": {} } ## { 'command': 'block_set_io_throttle', 'boxed': true, - 'data': 'BlockIOThrottle' } + 'data': 'BlockIOThrottle', + 'allow-preconfig': true } ## # @block-latency-histogram-set: # # 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-zap: list of interval boundary values for zone append +# write latency histogram. # -# Returns: error if device is not found or any boundary arrays are invalid. +# @boundaries-flush: list of interval boundary values for flush +# latency histogram. +# +# Errors: +# - 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): # -# -> { "execute": "block-latency-histogram-set", -# "arguments": { "id": "drive0", -# "boundaries": [10, 50, 100] } } -# <- { "return": {} } +# 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", +# "boundaries": [10, 50, 100] } } +# <- { "return": {} } # # Example: -# set new histogram only for write, other histograms will remain -# not changed (or not created): # -# -> { "execute": "block-latency-histogram-set", -# "arguments": { "id": "drive0", -# "boundaries-write": [10, 50, 100] } } -# <- { "return": {} } +# Set new histogram only for write, other histograms will remain +# not changed (or not created): +# +# -> { "execute": "block-latency-histogram-set", +# "arguments": { "id": "drive0", +# "boundaries-write": [10, 50, 100] } } +# <- { "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) # -# -> { "execute": "block-latency-histogram-set", -# "arguments": { "id": "drive0", -# "boundaries": [10, 50, 100], -# "boundaries-write": [1000, 5000] } } -# <- { "return": {} } +# 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", +# "boundaries": [10, 50, 100], +# "boundaries-write": [1000, 5000] } } +# <- { "return": {} } # # Example: -# remove all latency histograms: # -# -> { "execute": "block-latency-histogram-set", -# "arguments": { "id": "drive0" } } -# <- { "return": {} } +# Remove all latency histograms: +# +# -> { "execute": "block-latency-histogram-set", +# "arguments": { "id": "drive0" } } +# <- { "return": {} } ## { 'command': 'block-latency-histogram-set', 'data': {'id': 'str', '*boundaries': ['uint64'], '*boundaries-read': ['uint64'], '*boundaries-write': ['uint64'], - '*boundaries-flush': ['uint64'] } } + '*boundaries-zap': ['uint64'], + '*boundaries-flush': ['uint64'] }, + 'allow-preconfig': true } diff --git a/qapi/char.json b/qapi/char.json index 6413970fa7..777dde55d9 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -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 (e.g. 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 ## @@ -42,27 +42,26 @@ # # Example: # -# -> { "execute": "query-chardev" } -# <- { -# "return": [ -# { -# "label": "charchannel0", -# "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on", -# "frontend-open": false -# }, -# { -# "label": "charmonitor", -# "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on", -# "frontend-open": true -# }, -# { -# "label": "charserial0", -# "filename": "pty:/dev/pts/2", -# "frontend-open": true -# } -# ] -# } -# +# -> { "execute": "query-chardev" } +# <- { +# "return": [ +# { +# "label": "charchannel0", +# "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on", +# "frontend-open": false +# }, +# { +# "label": "charmonitor", +# "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on", +# "frontend-open": true +# }, +# { +# "label": "charserial0", +# "filename": "pty:/dev/pts/2", +# "frontend-open": true +# } +# ] +# } ## { 'command': 'query-chardev', 'returns': ['ChardevInfo'], 'allow-preconfig': true } @@ -89,24 +88,23 @@ # # Example: # -# -> { "execute": "query-chardev-backends" } -# <- { -# "return":[ -# { -# "name":"udp" -# }, -# { -# "name":"tcp" -# }, -# { -# "name":"unix" -# }, -# { -# "name":"spiceport" -# } -# ] -# } -# +# -> { "execute": "query-chardev-backends" } +# <- { +# "return":[ +# { +# "name":"udp" +# }, +# { +# "name":"tcp" +# }, +# { +# "name":"unix" +# }, +# { +# "name":"spiceport" +# } +# ] +# } ## { 'command': 'query-chardev-backends', 'returns': ['ChardevBackendInfo'] } @@ -135,24 +133,21 @@ # # @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. -# -# Returns: Nothing on success +# - 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. # # Since: 1.4 # # Example: # -# -> { "execute": "ringbuf-write", -# "arguments": { "device": "foo", -# "data": "abcdefgh", -# "format": "utf8" } } -# <- { "return": {} } -# +# -> { "execute": "ringbuf-write", +# "arguments": { "device": "foo", +# "data": "abcdefgh", +# "format": "utf8" } } +# <- { "return": {} } ## { 'command': 'ringbuf-write', 'data': { 'device': 'str', @@ -170,14 +165,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 # @@ -185,12 +179,11 @@ # # Example: # -# -> { "execute": "ringbuf-read", -# "arguments": { "device": "foo", -# "size": 1000, -# "format": "utf8" } } -# <- { "return": "abcdefgh" } -# +# -> { "execute": "ringbuf-read", +# "arguments": { "device": "foo", +# "size": 1000, +# "format": "utf8" } } +# <- { "return": "abcdefgh" } ## { 'command': 'ringbuf-read', 'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'}, @@ -202,8 +195,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 ## @@ -216,10 +210,12 @@ # # Configuration info for file chardevs. # -# @in: The name of the input file +# @in: The name of the input file +# # @out: The name of the output file -# @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 +230,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 +244,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 +296,7 @@ # Configuration info for datagram socket chardevs. # # @remote: remote address +# # @local: local address # # Since: 1.5 @@ -320,8 +324,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 ## @@ -329,7 +333,6 @@ 'data': { '*signal': 'bool' }, 'base': 'ChardevCommon' } - ## # @ChardevSpiceChannel: # @@ -342,7 +345,7 @@ { 'struct': 'ChardevSpiceChannel', 'data': { 'type': 'str' }, 'base': 'ChardevCommon', - 'if': 'defined(CONFIG_SPICE)' } + 'if': 'CONFIG_SPICE' } ## # @ChardevSpicePort: @@ -356,17 +359,38 @@ { 'struct': 'ChardevSpicePort', 'data': { 'fqdn': 'str' }, 'base': 'ChardevCommon', - 'if': 'defined(CONFIG_SPICE)' } + 'if': 'CONFIG_SPICE' } + +## +# @ChardevDBus: +# +# Configuration info for DBus chardevs. +# +# @name: name of the channel (following docs/spice-port-fqdn.txt) +# +# Since: 7.0 +## +{ 'struct': 'ChardevDBus', + 'data': { 'name': 'str' }, + 'base': 'ChardevCommon', + 'if': 'CONFIG_DBUS_DISPLAY' } ## # @ChardevVC: # # Configuration info for virtual console chardevs. # -# @width: console width, in pixels +# @width: console width, in pixels +# # @height: console height, in pixels -# @cols: console width, in chars -# @rows: console height, in chars +# +# @cols: console width, in chars +# +# @rows: console height, in chars +# +# Note: the options are only effective when the VNC or SDL graphical +# display backend is active. They are ignored with the GTK, +# Spice, VNC and D-Bus display backends. # # Since: 1.5 ## @@ -391,44 +415,271 @@ 'base': 'ChardevCommon' } ## +# @ChardevQemuVDAgent: +# +# Configuration info for qemu vdagent implementation. +# +# @mouse: enable/disable mouse, default is enabled. +# +# @clipboard: enable/disable clipboard, default is disabled. +# +# Since: 6.1 +## +{ 'struct': 'ChardevQemuVDAgent', + 'data': { '*mouse': 'bool', + '*clipboard': 'bool' }, + 'base': 'ChardevCommon', + 'if': 'CONFIG_SPICE_PROTOCOL' } + +## +# @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 +# +# Features: +# +# @deprecated: Member @memory is deprecated. Use @ringbuf instead. +# +# Since: 1.4 +## +{ 'enum': 'ChardevBackendKind', + 'data': [ 'file', + { 'name': 'serial', 'if': 'HAVE_CHARDEV_SERIAL' }, + { 'name': 'parallel', 'if': 'HAVE_CHARDEV_PARALLEL' }, + 'pipe', + 'socket', + 'udp', + 'pty', + 'null', + 'mux', + 'msmouse', + 'wctablet', + { 'name': 'braille', 'if': 'CONFIG_BRLAPI' }, + 'testdev', + 'stdio', + { 'name': 'console', 'if': 'CONFIG_WIN32' }, + { 'name': 'spicevmc', 'if': 'CONFIG_SPICE' }, + { 'name': 'spiceport', 'if': 'CONFIG_SPICE' }, + { 'name': 'qemu-vdagent', 'if': 'CONFIG_SPICE_PROTOCOL' }, + { 'name': 'dbus', 'if': 'CONFIG_DBUS_DISPLAY' }, + 'vc', + 'ringbuf', + { 'name': 'memory', 'features': [ 'deprecated' ] } ] } + +## +# @ChardevFileWrapper: +# +# @data: Configuration info for file chardevs +# +# Since: 1.4 +## +{ 'struct': 'ChardevFileWrapper', + 'data': { 'data': 'ChardevFile' } } + +## +# @ChardevHostdevWrapper: +# +# @data: Configuration info for device and pipe chardevs +# +# Since: 1.4 +## +{ 'struct': 'ChardevHostdevWrapper', + 'data': { 'data': 'ChardevHostdev' } } + +## +# @ChardevSocketWrapper: +# +# @data: Configuration info for (stream) socket chardevs +# +# Since: 1.4 +## +{ 'struct': 'ChardevSocketWrapper', + 'data': { 'data': 'ChardevSocket' } } + +## +# @ChardevUdpWrapper: +# +# @data: Configuration info for datagram socket chardevs +# +# Since: 1.5 +## +{ 'struct': 'ChardevUdpWrapper', + 'data': { 'data': 'ChardevUdp' } } + +## +# @ChardevCommonWrapper: +# +# @data: Configuration shared across all chardev backends +# +# Since: 2.6 +## +{ 'struct': 'ChardevCommonWrapper', + 'data': { 'data': 'ChardevCommon' } } + +## +# @ChardevMuxWrapper: +# +# @data: Configuration info for mux chardevs +# +# Since: 1.5 +## +{ 'struct': 'ChardevMuxWrapper', + 'data': { 'data': 'ChardevMux' } } + +## +# @ChardevStdioWrapper: +# +# @data: Configuration info for stdio chardevs +# +# Since: 1.5 +## +{ 'struct': 'ChardevStdioWrapper', + 'data': { 'data': 'ChardevStdio' } } + +## +# @ChardevSpiceChannelWrapper: +# +# @data: Configuration info for spice vm channel chardevs +# +# Since: 1.5 +## +{ 'struct': 'ChardevSpiceChannelWrapper', + 'data': { 'data': 'ChardevSpiceChannel' }, + 'if': 'CONFIG_SPICE' } + +## +# @ChardevSpicePortWrapper: +# +# @data: Configuration info for spice port chardevs +# +# Since: 1.5 +## +{ 'struct': 'ChardevSpicePortWrapper', + 'data': { 'data': 'ChardevSpicePort' }, + 'if': 'CONFIG_SPICE' } + +## +# @ChardevQemuVDAgentWrapper: +# +# @data: Configuration info for qemu vdagent implementation +# +# Since: 6.1 +## +{ 'struct': 'ChardevQemuVDAgentWrapper', + 'data': { 'data': 'ChardevQemuVDAgent' }, + 'if': 'CONFIG_SPICE_PROTOCOL' } + +## +# @ChardevDBusWrapper: +# +# @data: Configuration info for DBus chardevs +# +# Since: 7.0 +## +{ 'struct': 'ChardevDBusWrapper', + 'data': { 'data': 'ChardevDBus' }, + 'if': 'CONFIG_DBUS_DISPLAY' } + +## +# @ChardevVCWrapper: +# +# @data: Configuration info for virtual console chardevs +# +# Since: 1.5 +## +{ 'struct': 'ChardevVCWrapper', + 'data': { 'data': 'ChardevVC' } } + +## +# @ChardevRingbufWrapper: +# +# @data: Configuration info for ring buffer chardevs +# +# Since: 1.5 +## +{ 'struct': 'ChardevRingbufWrapper', + 'data': { 'data': 'ChardevRingbuf' } } + +## # @ChardevBackend: # # Configuration info for the new chardev backend. # -# Since: 1.4 (testdev since 2.2, wctablet since 2.9) +# @type: backend type +# +# Since: 1.4 ## { 'union': 'ChardevBackend', - 'data': { 'file': 'ChardevFile', - 'serial': 'ChardevHostdev', - 'parallel': 'ChardevHostdev', - 'pipe': 'ChardevHostdev', - 'socket': 'ChardevSocket', - 'udp': 'ChardevUdp', - 'pty': 'ChardevCommon', - 'null': 'ChardevCommon', - 'mux': 'ChardevMux', - 'msmouse': 'ChardevCommon', - 'wctablet': 'ChardevCommon', - 'braille': 'ChardevCommon', - 'testdev': 'ChardevCommon', - 'stdio': 'ChardevStdio', - 'console': 'ChardevCommon', - 'spicevmc': { 'type': 'ChardevSpiceChannel', - 'if': 'defined(CONFIG_SPICE)' }, - 'spiceport': { 'type': 'ChardevSpicePort', - 'if': 'defined(CONFIG_SPICE)' }, - 'vc': 'ChardevVC', - 'ringbuf': 'ChardevRingbuf', - # next one is just for compatibility - 'memory': 'ChardevRingbuf' } } + 'base': { 'type': 'ChardevBackendKind' }, + 'discriminator': 'type', + 'data': { 'file': 'ChardevFileWrapper', + 'serial': { 'type': 'ChardevHostdevWrapper', + 'if': 'HAVE_CHARDEV_SERIAL' }, + 'parallel': { 'type': 'ChardevHostdevWrapper', + 'if': 'HAVE_CHARDEV_PARALLEL' }, + 'pipe': 'ChardevHostdevWrapper', + 'socket': 'ChardevSocketWrapper', + 'udp': 'ChardevUdpWrapper', + 'pty': 'ChardevCommonWrapper', + 'null': 'ChardevCommonWrapper', + 'mux': 'ChardevMuxWrapper', + 'msmouse': 'ChardevCommonWrapper', + 'wctablet': 'ChardevCommonWrapper', + 'braille': { 'type': 'ChardevCommonWrapper', + 'if': 'CONFIG_BRLAPI' }, + 'testdev': 'ChardevCommonWrapper', + 'stdio': 'ChardevStdioWrapper', + 'console': { 'type': 'ChardevCommonWrapper', + 'if': 'CONFIG_WIN32' }, + 'spicevmc': { 'type': 'ChardevSpiceChannelWrapper', + 'if': 'CONFIG_SPICE' }, + 'spiceport': { 'type': 'ChardevSpicePortWrapper', + 'if': 'CONFIG_SPICE' }, + 'qemu-vdagent': { 'type': 'ChardevQemuVDAgentWrapper', + 'if': 'CONFIG_SPICE_PROTOCOL' }, + 'dbus': { 'type': 'ChardevDBusWrapper', + 'if': 'CONFIG_DBUS_DISPLAY' }, + 'vc': 'ChardevVCWrapper', + 'ringbuf': 'ChardevRingbufWrapper', + 'memory': 'ChardevRingbufWrapper' } } ## # @ChardevReturn: # # 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 ## @@ -441,30 +692,30 @@ # Add a character device backend # # @id: the chardev's ID, must be unique +# # @backend: backend type and parameters # # Returns: ChardevReturn. # # Since: 1.4 # -# Example: -# -# -> { "execute" : "chardev-add", -# "arguments" : { "id" : "foo", -# "backend" : { "type" : "null", "data" : {} } } } -# <- { "return": {} } +# Examples: # -# -> { "execute" : "chardev-add", -# "arguments" : { "id" : "bar", -# "backend" : { "type" : "file", -# "data" : { "out" : "/tmp/bar.log" } } } } -# <- { "return": {} } +# -> { "execute" : "chardev-add", +# "arguments" : { "id" : "foo", +# "backend" : { "type" : "null", "data" : {} } } } +# <- { "return": {} } # -# -> { "execute" : "chardev-add", -# "arguments" : { "id" : "baz", -# "backend" : { "type" : "pty", "data" : {} } } } -# <- { "return": { "pty" : "/dev/pty/42" } } +# -> { "execute" : "chardev-add", +# "arguments" : { "id" : "bar", +# "backend" : { "type" : "file", +# "data" : { "out" : "/tmp/bar.log" } } } } +# <- { "return": {} } # +# -> { "execute" : "chardev-add", +# "arguments" : { "id" : "baz", +# "backend" : { "type" : "pty", "data" : {} } } } +# <- { "return": { "pty" : "/dev/pty/42" } } ## { 'command': 'chardev-add', 'data': { 'id': 'str', @@ -477,35 +728,35 @@ # Change a character device backend # # @id: the chardev's ID, must exist +# # @backend: new backend type and parameters # # Returns: ChardevReturn. # # Since: 2.10 # -# Example: -# -# -> { "execute" : "chardev-change", -# "arguments" : { "id" : "baz", -# "backend" : { "type" : "pty", "data" : {} } } } -# <- { "return": { "pty" : "/dev/pty/42" } } -# -# -> {"execute" : "chardev-change", -# "arguments" : { -# "id" : "charchannel2", -# "backend" : { -# "type" : "socket", -# "data" : { -# "addr" : { -# "type" : "unix" , -# "data" : { -# "path" : "/tmp/charchannel2.socket" -# } -# }, -# "server" : true, -# "wait" : false }}}} -# <- {"return": {}} -# +# Examples: +# +# -> { "execute" : "chardev-change", +# "arguments" : { "id" : "baz", +# "backend" : { "type" : "pty", "data" : {} } } } +# <- { "return": { "pty" : "/dev/pty/42" } } +# +# -> {"execute" : "chardev-change", +# "arguments" : { +# "id" : "charchannel2", +# "backend" : { +# "type" : "socket", +# "data" : { +# "addr" : { +# "type" : "unix" , +# "data" : { +# "path" : "/tmp/charchannel2.socket" +# } +# }, +# "server" : true, +# "wait" : false }}}} +# <- {"return": {}} ## { 'command': 'chardev-change', 'data': { 'id': 'str', @@ -519,15 +770,12 @@ # # @id: the chardev's ID, must exist and not be in use # -# Returns: Nothing on success -# # Since: 1.4 # # Example: # -# -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } } -# <- { "return": {} } -# +# -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } } +# <- { "return": {} } ## { 'command': 'chardev-remove', 'data': { 'id': 'str' } } @@ -539,15 +787,12 @@ # # @id: the chardev's ID, must exist # -# Returns: Nothing on success -# # Since: 2.10 # # Example: # -# -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } } -# <- { "return": {} } -# +# -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } } +# <- { "return": {} } ## { 'command': 'chardev-send-break', 'data': { 'id': 'str' } } @@ -567,10 +812,9 @@ # # Example: # -# <- { "event": "VSERPORT_CHANGE", -# "data": { "id": "channel0", "open": true }, -# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } -# +# <- { "event": "VSERPORT_CHANGE", +# "data": { "id": "channel0", "open": true }, +# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } ## { 'event': 'VSERPORT_CHANGE', 'data': { 'id': 'str', diff --git a/qapi/common.json b/qapi/common.json index 7c976296f0..7558ce5430 100644 --- a/qapi/common.json +++ b/qapi/common.json @@ -52,17 +52,6 @@ 'data': [ 'on', 'off', 'split' ] } ## -# @String: -# -# A fat type wrapping 'str', to be embedded in lists. -# -# Since: 1.2 -## -{ 'struct': 'String', - 'data': { - 'str': 'str' } } - -## # @StrOrNull: # # This is a string value or the explicit lack of a string (null @@ -70,6 +59,7 @@ # has a different meaning. # # @s: the string value +# # @n: no string value # # Since: 2.10 @@ -117,10 +107,14 @@ # # @16: 16.0GT/s # +# @32: 32.0GT/s (since 9.0) +# +# @64: 64.0GT/s (since 9.0) +# # Since: 4.0 ## { 'enum': 'PCIELinkSpeed', - 'data': [ '2_5', '5', '8', '16' ] } + 'data': [ '2_5', '5', '8', '16', '32', '64' ] } ## # @PCIELinkWidth: @@ -155,11 +149,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 +163,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 ## @@ -192,8 +186,17 @@ # Keys to toggle input-linux between host and guest. # # Since: 4.0 -# ## { 'enum': 'GrabToggleKeys', 'data': [ 'ctrl-ctrl', 'alt-alt', 'shift-shift','meta-meta', 'scrolllock', 'ctrl-scrolllock' ] } + +## +# @HumanReadableText: +# +# @human-readable-text: Formatted output intended for humans. +# +# Since: 6.2 +## +{ 'struct': 'HumanReadableText', + 'data': { 'human-readable-text': 'str' } } diff --git a/qapi/compat.json b/qapi/compat.json index ae3afc22df..42034d9368 100644 --- a/qapi/compat.json +++ b/qapi/compat.json @@ -1,4 +1,5 @@ # -*- Mode: Python -*- +# vim: filetype=python ## # = Compatibility policy @@ -10,7 +11,9 @@ # Policy for handling "funny" input. # # @accept: Accept silently +# # @reject: Reject with an error +# # @crash: abort() the process # # Since: 6.0 @@ -24,6 +27,7 @@ # Policy for handling "funny" output. # # @accept: Pass on unchanged +# # @hide: Filter out # # Since: 6.0 @@ -39,14 +43,27 @@ # This is intended for testing users of the management interfaces. # # Limitation: covers only syntactic aspects of QMP, i.e. stuff tagged -# with feature 'deprecated'. We may want to extend it to cover -# semantic aspects, CLI, and experimental features. +# with feature 'deprecated' or 'unstable'. We may want to extend it +# to cover semantic aspects and CLI. +# +# Limitation: deprecated-output policy @hide is not implemented for +# enumeration values. They behave the same as with policy @accept. # # @deprecated-input: how to handle deprecated input (default 'accept') -# @deprecated-output: how to handle deprecated output (default 'accept') +# +# @deprecated-output: how to handle deprecated output (default +# 'accept') +# +# @unstable-input: how to handle unstable input (default 'accept') +# (since 6.2) +# +# @unstable-output: how to handle unstable output (default 'accept') +# (since 6.2) # # Since: 6.0 ## { 'struct': 'CompatPolicy', 'data': { '*deprecated-input': 'CompatPolicyInput', - '*deprecated-output': 'CompatPolicyOutput' } } + '*deprecated-output': 'CompatPolicyOutput', + '*unstable-input': 'CompatPolicyInput', + '*unstable-output': 'CompatPolicyOutput' } } diff --git a/qapi/control.json b/qapi/control.json index 71a838d49e..6bdbf077c2 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -11,29 +11,27 @@ # # Enable QMP capabilities. # -# 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: # -# -> { "execute": "qmp_capabilities", -# "arguments": { "enable": [ "oob" ] } } -# <- { "return": {} } +# -> { "execute": "qmp_capabilities", +# "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.rst) # -# 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 -# ## { 'command': 'qmp_capabilities', 'data': { '*enable': [ 'QMPCapability' ] }, @@ -45,11 +43,10 @@ # 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.rst for more information on OOB) # # Since: 2.12 -# ## { 'enum': 'QMPCapability', 'data': [ 'oob' ] } @@ -70,22 +67,21 @@ { 'struct': 'VersionTriple', 'data': {'major': 'int', 'minor': 'int', 'micro': 'int'} } - ## # @VersionInfo: # # 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 ## @@ -97,24 +93,24 @@ # # 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 # # Example: # -# -> { "execute": "query-version" } -# <- { -# "return":{ -# "qemu":{ -# "major":0, -# "minor":11, -# "micro":5 -# }, -# "package":"" -# } -# } -# +# -> { "execute": "query-version" } +# <- { +# "return":{ +# "qemu":{ +# "major":0, +# "minor":11, +# "micro":5 +# }, +# "package":"" +# } +# } ## { 'command': 'query-version', 'returns': 'VersionInfo', 'allow-preconfig': true } @@ -141,20 +137,20 @@ # # Example: # -# -> { "execute": "query-commands" } -# <- { -# "return":[ -# { -# "name":"query-balloon" -# }, -# { -# "name":"system_powerdown" -# } -# ] -# } -# -# Note: This example has been shortened as the real response is too long. -# +# -> { "execute": "query-commands" } +# <- { +# "return":[ +# { +# "name":"query-balloon" +# }, +# { +# "name":"system_powerdown" +# } +# ] +# } +# +# Note: This example has been shortened as the real response is too +# long. ## { 'command': 'query-commands', 'returns': ['CommandInfo'], 'allow-preconfig': true } @@ -162,17 +158,17 @@ ## # @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 # # Example: # -# -> { "execute": "quit" } -# <- { "return": {} } +# -> { "execute": "quit" } +# <- { "return": {} } ## { 'command': 'quit', 'allow-preconfig': true } @@ -195,14 +191,14 @@ # # Options to be used for adding a new monitor. # -# @id: Name of the monitor +# @id: Name of the monitor # -# @mode: Selects the monitor mode (default: readline in the system -# emulator, control in qemu-storage-daemon) +# @mode: Selects the monitor mode (default: readline in the system +# emulator, control in qemu-storage-daemon) # -# @pretty: Enables pretty printing (QMP only) +# @pretty: Enables pretty printing (QMP only) # -# @chardev: Name of a character device to expose the monitor on +# @chardev: Name of a character device to expose the monitor on # # Since: 5.0 ## diff --git a/qapi/crypto.json b/qapi/crypto.json index 7116ae9a46..e102be337b 100644 --- a/qapi/crypto.json +++ b/qapi/crypto.json @@ -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 # @@ -24,67 +23,89 @@ 'prefix': 'QCRYPTO_TLS_CREDS_ENDPOINT', 'data': ['client', 'server']} - ## # @QCryptoSecretFormat: # # 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 ## { 'enum': 'QCryptoSecretFormat', 'prefix': 'QCRYPTO_SECRET_FORMAT', 'data': ['raw', 'base64']} - ## # @QCryptoHashAlgorithm: # # 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) +# +# @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) +# +# @sha384: SHA-384. (since 2.7) +# +# @sha512: SHA-512. (since 2.7) +# +# @ripemd160: RIPEMD-160. (since 2.7) +# # Since: 2.6 ## { 'enum': 'QCryptoHashAlgorithm', 'prefix': 'QCRYPTO_HASH_ALG', 'data': ['md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512', 'ripemd160']} - ## # @QCryptoCipherAlgorithm: # # 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-rfb: RFB specific variant of single DES. Do not use except in VNC. +# +# @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 +# +# @sm4: SM4 with 128 bit / 16 byte keys (since 9.0) +# # Since: 2.6 ## { 'enum': 'QCryptoCipherAlgorithm', 'prefix': 'QCRYPTO_CIPHER_ALG', 'data': ['aes-128', 'aes-192', 'aes-256', - 'des-rfb', '3des', + 'des', '3des', 'cast5-128', 'serpent-128', 'serpent-192', 'serpent-256', - 'twofish-128', 'twofish-192', 'twofish-256']} - + 'twofish-128', 'twofish-192', 'twofish-256', + 'sm4']} ## # @QCryptoCipherMode: @@ -92,28 +113,34 @@ # 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 ## { 'enum': 'QCryptoCipherMode', 'prefix': 'QCRYPTO_CIPHER_MODE', 'data': ['ecb', 'cbc', 'xts', 'ctr']} - ## # @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 ## { 'enum': 'QCryptoIVGenAlgorithm', @@ -125,9 +152,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 +166,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 +181,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,32 +195,39 @@ # 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 ## { 'struct': 'QCryptoBlockOptionsLUKS', 'data': { '*key-secret': 'str' }} - ## # @QCryptoBlockCreateOptionsLUKS: # # 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) +# +# @detached-header: create a detached LUKS header. (since 9.0) +# # Since: 2.6 ## { 'struct': 'QCryptoBlockCreateOptionsLUKS', @@ -203,14 +237,14 @@ '*ivgen-alg': 'QCryptoIVGenAlgorithm', '*ivgen-hash-alg': 'QCryptoHashAlgorithm', '*hash-alg': 'QCryptoHashAlgorithm', - '*iter-time': 'int'}} - + '*iter-time': 'int', + '*detached-header': 'bool'}} ## # @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 ## @@ -220,12 +254,11 @@ 'data': { 'qcow': 'QCryptoBlockOptionsQCow', 'luks': 'QCryptoBlockOptionsLUKS' } } - ## # @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 ## @@ -235,12 +268,11 @@ 'data': { 'qcow': 'QCryptoBlockOptionsQCow', 'luks': 'QCryptoBlockCreateOptionsLUKS' } } - ## # @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 # @@ -249,16 +281,17 @@ { 'struct': 'QCryptoBlockInfoBase', 'data': { 'format': 'QCryptoBlockFormat' }} - ## # @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 @@ -269,20 +302,29 @@ '*stripes': 'int', 'key-offset': 'int' } } - ## # @QCryptoBlockInfoLUKS: # # 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 +# +# @detached-header: whether the LUKS header is detached (Since 9.0) +# # @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 @@ -293,6 +335,7 @@ 'ivgen-alg': 'QCryptoIVGenAlgorithm', '*ivgen-hash-alg': 'QCryptoHashAlgorithm', 'hash-alg': 'QCryptoHashAlgorithm', + 'detached-header': 'bool', 'payload-offset': 'int', 'master-key-iters': 'int', 'uuid': 'str', @@ -315,50 +358,49 @@ # # 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 +# @active: The slots contain the given password and marked as active +# +# @inactive: The slots are erased (contain garbage) and marked as +# inactive # # Since: 5.1 ## { 'enum': 'QCryptoBlockLUKSKeyslotState', 'data': [ 'active', 'inactive' ] } - ## # @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 -# -# @old-secret: Optional (for deactivation only) -# If given will deactivate all keyslots that -# match password located in QCryptoSecret with this ID +# @new-secret: The ID of a QCryptoSecret object providing the password +# to be written into added active keyslots # -# @iter-time: Optional (for activation only) -# Number of milliseconds to spend in -# PBKDF passphrase processing for the newly activated keyslot. -# Currently defaults to 2000. +# @old-secret: Optional (for deactivation only) If given will +# deactivate all keyslots that match password located in +# QCryptoSecret with this ID # -# @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. +# @iter-time: Optional (for activation only) Number of milliseconds to +# spend in PBKDF passphrase processing for the newly activated +# keyslot. Currently defaults to 2000. # -# For keyslot deactivation, this parameter specifies the exact -# keyslot to deactivate +# @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. # -# @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 +# 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 # -# Since 5.1 +# Since: 5.1 ## { 'struct': 'QCryptoBlockAmendOptionsLUKS', 'data': { 'state': 'QCryptoBlockLUKSKeyslotState', @@ -371,8 +413,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 ## @@ -387,22 +429,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 ## @@ -449,16 +496,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 ## @@ -473,13 +521,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 ## @@ -492,17 +542,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 ## @@ -516,22 +568,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 ## @@ -540,3 +594,71 @@ 'data': { '*loaded': { 'type': 'bool', 'features': ['deprecated'] }, '*sanity-check': 'bool', '*passwordid': 'str' } } +## +# @QCryptoAkCipherAlgorithm: +# +# The supported algorithms for asymmetric encryption ciphers +# +# @rsa: RSA algorithm +# +# Since: 7.1 +## +{ 'enum': 'QCryptoAkCipherAlgorithm', + 'prefix': 'QCRYPTO_AKCIPHER_ALG', + 'data': ['rsa']} + +## +# @QCryptoAkCipherKeyType: +# +# The type of asymmetric keys. +# +# Since: 7.1 +## +{ 'enum': 'QCryptoAkCipherKeyType', + 'prefix': 'QCRYPTO_AKCIPHER_KEY_TYPE', + 'data': ['public', 'private']} + +## +# @QCryptoRSAPaddingAlgorithm: +# +# The padding algorithm for RSA. +# +# @raw: no padding used +# +# @pkcs1: pkcs1#v1.5 +# +# Since: 7.1 +## +{ 'enum': 'QCryptoRSAPaddingAlgorithm', + 'prefix': 'QCRYPTO_RSA_PADDING_ALG', + 'data': ['raw', 'pkcs1']} + +## +# @QCryptoAkCipherOptionsRSA: +# +# Specific parameters for RSA algorithm. +# +# @hash-alg: QCryptoHashAlgorithm +# +# @padding-alg: QCryptoRSAPaddingAlgorithm +# +# Since: 7.1 +## +{ 'struct': 'QCryptoAkCipherOptionsRSA', + 'data': { 'hash-alg':'QCryptoHashAlgorithm', + 'padding-alg': 'QCryptoRSAPaddingAlgorithm'}} + +## +# @QCryptoAkCipherOptions: +# +# The options that are available for all asymmetric key algorithms +# when creating a new QCryptoAkCipher. +# +# @alg: encryption cipher algorithm +# +# Since: 7.1 +## +{ 'union': 'QCryptoAkCipherOptions', + 'base': { 'alg': 'QCryptoAkCipherAlgorithm' }, + 'discriminator': 'alg', + 'data': { 'rsa': 'QCryptoAkCipherOptionsRSA' }} diff --git a/qapi/cryptodev.json b/qapi/cryptodev.json new file mode 100644 index 0000000000..68289f4984 --- /dev/null +++ b/qapi/cryptodev.json @@ -0,0 +1,96 @@ +# -*- Mode: Python -*- +# vim: filetype=python +# +# This work is licensed under the terms of the GNU GPL, version 2 or later. +# See the COPYING file in the top-level directory. + +## +# = Cryptography devices +## + +## +# @QCryptodevBackendAlgType: +# +# The supported algorithm types of a crypto device. +# +# @sym: symmetric encryption +# +# @asym: asymmetric Encryption +# +# Since: 8.0 +## +{ 'enum': 'QCryptodevBackendAlgType', + 'prefix': 'QCRYPTODEV_BACKEND_ALG', + 'data': ['sym', 'asym']} + +## +# @QCryptodevBackendServiceType: +# +# The supported service types of a crypto device. +# +# Since: 8.0 +## +{ 'enum': 'QCryptodevBackendServiceType', + 'prefix': 'QCRYPTODEV_BACKEND_SERVICE', + 'data': ['cipher', 'hash', 'mac', 'aead', 'akcipher']} + +## +# @QCryptodevBackendType: +# +# The crypto device backend type +# +# @builtin: the QEMU builtin support +# +# @vhost-user: vhost-user +# +# @lkcf: Linux kernel cryptographic framework +# +# Since: 8.0 +## +{ 'enum': 'QCryptodevBackendType', + 'prefix': 'QCRYPTODEV_BACKEND_TYPE', + 'data': ['builtin', 'vhost-user', 'lkcf']} + +## +# @QCryptodevBackendClient: +# +# Information about a queue of crypto device. +# +# @queue: the queue index of the crypto device +# +# @type: the type of the crypto device +# +# Since: 8.0 +## +{ 'struct': 'QCryptodevBackendClient', + 'data': { 'queue': 'uint32', + 'type': 'QCryptodevBackendType' } } + +## +# @QCryptodevInfo: +# +# Information about a crypto device. +# +# @id: the id of the crypto device +# +# @service: supported service types of a crypto device +# +# @client: the additional information of the crypto device +# +# Since: 8.0 +## +{ 'struct': 'QCryptodevInfo', + 'data': { 'id': 'str', + 'service': ['QCryptodevBackendServiceType'], + 'client': ['QCryptodevBackendClient'] } } + +## +# @query-cryptodev: +# +# Returns information about current crypto devices. +# +# Returns: a list of @QCryptodevInfo +# +# Since: 8.0 +## +{ 'command': 'query-cryptodev', 'returns': ['QCryptodevInfo']} diff --git a/qapi/cxl.json b/qapi/cxl.json new file mode 100644 index 0000000000..4281726dec --- /dev/null +++ b/qapi/cxl.json @@ -0,0 +1,363 @@ +# -*- Mode: Python -*- +# vim: filetype=python + +## +# = CXL devices +## + +## +# @CxlEventLog: +# +# CXL has a number of separate event logs for different types of +# events. Each such event log is handled and signaled independently. +# +# @informational: Information Event Log +# +# @warning: Warning Event Log +# +# @failure: Failure Event Log +# +# @fatal: Fatal Event Log +# +# Since: 8.1 +## +{ 'enum': 'CxlEventLog', + 'data': ['informational', + 'warning', + 'failure', + 'fatal'] + } + +## +# @cxl-inject-general-media-event: +# +# Inject an event record for a General Media Event (CXL r3.0 +# 8.2.9.2.1.1). This event type is reported via one of the event logs +# specified via the log parameter. +# +# @path: CXL type 3 device canonical QOM path +# +# @log: event log to add the event to +# +# @flags: Event Record Flags. See CXL r3.0 Table 8-42 Common Event +# Record Format, Event Record Flags for subfield definitions. +# +# @dpa: Device Physical Address (relative to @path device). Note +# lower bits include some flags. See CXL r3.0 Table 8-43 General +# Media Event Record, Physical Address. +# +# @descriptor: Memory Event Descriptor with additional memory event +# information. See CXL r3.0 Table 8-43 General Media Event +# Record, Memory Event Descriptor for bit definitions. +# +# @type: Type of memory event that occurred. See CXL r3.0 Table 8-43 +# General Media Event Record, Memory Event Type for possible +# values. +# +# @transaction-type: Type of first transaction that caused the event +# to occur. See CXL r3.0 Table 8-43 General Media Event Record, +# Transaction Type for possible values. +# +# @channel: The channel of the memory event location. A channel is an +# interface that can be independently accessed for a transaction. +# +# @rank: The rank of the memory event location. A rank is a set of +# memory devices on a channel that together execute a transaction. +# +# @device: Bitmask that represents all devices in the rank associated +# with the memory event location. +# +# @component-id: Device specific component identifier for the event. +# May describe a field replaceable sub-component of the device. +# +# Since: 8.1 +## +{ 'command': 'cxl-inject-general-media-event', + 'data': { 'path': 'str', 'log': 'CxlEventLog', 'flags': 'uint8', + 'dpa': 'uint64', 'descriptor': 'uint8', + 'type': 'uint8', 'transaction-type': 'uint8', + '*channel': 'uint8', '*rank': 'uint8', + '*device': 'uint32', '*component-id': 'str' } } + +## +# @cxl-inject-dram-event: +# +# Inject an event record for a DRAM Event (CXL r3.0 8.2.9.2.1.2). +# This event type is reported via one of the event logs specified via +# the log parameter. +# +# @path: CXL type 3 device canonical QOM path +# +# @log: Event log to add the event to +# +# @flags: Event Record Flags. See CXL r3.0 Table 8-42 Common Event +# Record Format, Event Record Flags for subfield definitions. +# +# @dpa: Device Physical Address (relative to @path device). Note +# lower bits include some flags. See CXL r3.0 Table 8-44 DRAM +# Event Record, Physical Address. +# +# @descriptor: Memory Event Descriptor with additional memory event +# information. See CXL r3.0 Table 8-44 DRAM Event Record, Memory +# Event Descriptor for bit definitions. +# +# @type: Type of memory event that occurred. See CXL r3.0 Table 8-44 +# DRAM Event Record, Memory Event Type for possible values. +# +# @transaction-type: Type of first transaction that caused the event +# to occur. See CXL r3.0 Table 8-44 DRAM Event Record, +# Transaction Type for possible values. +# +# @channel: The channel of the memory event location. A channel is an +# interface that can be independently accessed for a transaction. +# +# @rank: The rank of the memory event location. A rank is a set of +# memory devices on a channel that together execute a transaction. +# +# @nibble-mask: Identifies one or more nibbles that the error affects +# +# @bank-group: Bank group of the memory event location, incorporating +# a number of Banks. +# +# @bank: Bank of the memory event location. A single bank is accessed +# per read or write of the memory. +# +# @row: Row address within the DRAM. +# +# @column: Column address within the DRAM. +# +# @correction-mask: Bits within each nibble. Used in order of bits +# set in the nibble-mask. Up to 4 nibbles may be covered. +# +# Since: 8.1 +## +{ 'command': 'cxl-inject-dram-event', + 'data': { 'path': 'str', 'log': 'CxlEventLog', 'flags': 'uint8', + 'dpa': 'uint64', 'descriptor': 'uint8', + 'type': 'uint8', 'transaction-type': 'uint8', + '*channel': 'uint8', '*rank': 'uint8', '*nibble-mask': 'uint32', + '*bank-group': 'uint8', '*bank': 'uint8', '*row': 'uint32', + '*column': 'uint16', '*correction-mask': [ 'uint64' ] + }} + +## +# @cxl-inject-memory-module-event: +# +# Inject an event record for a Memory Module Event (CXL r3.0 +# 8.2.9.2.1.3). This event includes a copy of the Device Health info +# at the time of the event. +# +# @path: CXL type 3 device canonical QOM path +# +# @log: Event Log to add the event to +# +# @flags: Event Record Flags. See CXL r3.0 Table 8-42 Common Event +# Record Format, Event Record Flags for subfield definitions. +# +# @type: Device Event Type. See CXL r3.0 Table 8-45 Memory Module +# Event Record for bit definitions for bit definiions. +# +# @health-status: Overall health summary bitmap. See CXL r3.0 Table +# 8-100 Get Health Info Output Payload, Health Status for bit +# definitions. +# +# @media-status: Overall media health summary. See CXL r3.0 Table +# 8-100 Get Health Info Output Payload, Media Status for bit +# definitions. +# +# @additional-status: See CXL r3.0 Table 8-100 Get Health Info Output +# Payload, Additional Status for subfield definitions. +# +# @life-used: Percentage (0-100) of factory expected life span. +# +# @temperature: Device temperature in degrees Celsius. +# +# @dirty-shutdown-count: Number of times the device has been unable to +# determine whether data loss may have occurred. +# +# @corrected-volatile-error-count: Total number of correctable errors +# in volatile memory. +# +# @corrected-persistent-error-count: Total number of correctable +# errors in persistent memory +# +# Since: 8.1 +## +{ 'command': 'cxl-inject-memory-module-event', + 'data': { 'path': 'str', 'log': 'CxlEventLog', 'flags' : 'uint8', + 'type': 'uint8', 'health-status': 'uint8', + 'media-status': 'uint8', 'additional-status': 'uint8', + 'life-used': 'uint8', 'temperature' : 'int16', + 'dirty-shutdown-count': 'uint32', + 'corrected-volatile-error-count': 'uint32', + 'corrected-persistent-error-count': 'uint32' + }} + +## +# @cxl-inject-poison: +# +# Poison records indicate that a CXL memory device knows that a +# particular memory region may be corrupted. This may be because of +# locally detected errors (e.g. ECC failure) or poisoned writes +# received from other components in the system. This injection +# mechanism enables testing of the OS handling of poison records which +# may be queried via the CXL mailbox. +# +# @path: CXL type 3 device canonical QOM path +# +# @start: Start address; must be 64 byte aligned. +# +# @length: Length of poison to inject; must be a multiple of 64 bytes. +# +# Since: 8.1 +## +{ 'command': 'cxl-inject-poison', + 'data': { 'path': 'str', 'start': 'uint64', 'length': 'size' }} + +## +# @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. +# +# @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-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) +# +# @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 +## + +{ 'enum': 'CxlUncorErrorType', + 'data': ['cache-data-parity', + 'cache-address-parity', + 'cache-be-parity', + 'cache-data-ecc', + 'mem-data-parity', + 'mem-address-parity', + 'mem-be-parity', + 'mem-data-ecc', + 'reinit-threshold', + 'rsvd-encoding', + 'poison-received', + 'receiver-overflow', + 'internal', + 'cxl-ide-tx', + 'cxl-ide-rx' + ] + } + +## +# @CXLUncorErrorRecord: +# +# Record of a single error including header log. +# +# @type: Type of error +# +# @header: 16 DWORD of header. +# +# Since: 8.0 +## +{ 'struct': 'CXLUncorErrorRecord', + 'data': { + 'type': 'CxlUncorErrorType', + 'header': [ 'uint32' ] + } +} + +## +# @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. +# +# @path: CXL Type 3 device canonical QOM path +# +# @errors: Errors to inject +# +# Since: 8.0 +## +{ 'command': 'cxl-inject-uncorrectable-errors', + 'data': { 'path': 'str', + 'errors': [ 'CXLUncorErrorRecord' ] }} + +## +# @CxlCorErrorType: +# +# 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. +# +# @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 +## +{ 'enum': 'CxlCorErrorType', + 'data': ['cache-data-ecc', + 'mem-data-ecc', + 'crc-threshold', + 'retry-threshold', + 'cache-poison-received', + 'mem-poison-received', + 'physical'] +} + +## +# @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. +# +# @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'}} diff --git a/qapi/dump.json b/qapi/dump.json index f7c4267e3f..2fa9504d86 100644 --- a/qapi/dump.json +++ b/qapi/dump.json @@ -15,77 +15,90 @@ # # @elf: elf format # -# @kdump-zlib: kdump-compressed format with zlib-compressed +# @kdump-zlib: makedumpfile flattened, kdump-compressed format with +# zlib compression # -# @kdump-lzo: kdump-compressed format with lzo-compressed +# @kdump-lzo: makedumpfile flattened, kdump-compressed format with lzo +# compression # -# @kdump-snappy: kdump-compressed format with snappy-compressed +# @kdump-snappy: makedumpfile flattened, kdump-compressed format with +# snappy compression # -# @win-dmp: Windows full crashdump format, -# can be used instead of ELF converting (since 2.13) +# @kdump-raw-zlib: raw assembled kdump-compressed format with zlib +# compression (since 8.2) +# +# @kdump-raw-lzo: raw assembled kdump-compressed format with lzo +# compression (since 8.2) +# +# @kdump-raw-snappy: raw assembled kdump-compressed format with snappy +# compression (since 8.2) +# +# @win-dmp: Windows full crashdump format, can be used instead of ELF +# converting (since 2.13) # # Since: 2.0 ## { 'enum': 'DumpGuestMemoryFormat', - 'data': [ 'elf', 'kdump-zlib', 'kdump-lzo', 'kdump-snappy', 'win-dmp' ] } + 'data': [ + 'elf', + 'kdump-zlib', 'kdump-lzo', 'kdump-snappy', + 'kdump-raw-zlib', 'kdump-raw-lzo', 'kdump-raw-snappy', + 'win-dmp' ] } ## # @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 # -# Returns: nothing on success -# # Since: 1.2 # # Example: # -# -> { "execute": "dump-guest-memory", -# "arguments": { "protocol": "fd:dump" } } -# <- { "return": {} } -# +# -> { "execute": "dump-guest-memory", +# "arguments": { "paging": false, "protocol": "fd:dump" } } +# <- { "return": {} } ## { 'command': 'dump-guest-memory', 'data': { 'paging': 'bool', 'protocol': 'str', '*detach': 'bool', @@ -139,10 +152,9 @@ # # Example: # -# -> { "execute": "query-dump" } -# <- { "return": { "status": "active", "completed": 1024000, -# "total": 2048000 } } -# +# -> { "execute": "query-dump" } +# <- { "return": { "status": "active", "completed": 1024000, +# "total": 2048000 } } ## { 'command': 'query-dump', 'returns': 'DumpQueryResult' } @@ -153,18 +165,18 @@ # # @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 # # Example: # -# { "event": "DUMP_COMPLETED", -# "data": {"result": {"total": 1090650112, "status": "completed", -# "completed": 1090650112} } } -# +# <- { "event": "DUMP_COMPLETED", +# "data": { "result": { "total": 1090650112, "status": "completed", +# "completed": 1090650112 } }, +# "timestamp": { "seconds": 1648244171, "microseconds": 950316 } } ## { 'event': 'DUMP_COMPLETED' , 'data': { 'result': 'DumpQueryResult', '*error': 'str' } } @@ -172,7 +184,7 @@ ## # @DumpGuestMemoryCapability: # -# A list of the available formats for dump-guest-memory +# @formats: the available formats for dump-guest-memory # # Since: 2.0 ## @@ -185,17 +197,16 @@ # # 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 # # Example: # -# -> { "execute": "query-dump-guest-memory-capability" } -# <- { "return": { "formats": -# ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } -# +# -> { "execute": "query-dump-guest-memory-capability" } +# <- { "return": { "formats": +# ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } } ## { 'command': 'query-dump-guest-memory-capability', 'returns': 'DumpGuestMemoryCapability' } diff --git a/qapi/ebpf.json b/qapi/ebpf.json new file mode 100644 index 0000000000..e500b5a744 --- /dev/null +++ b/qapi/ebpf.json @@ -0,0 +1,64 @@ +# -*- Mode: Python -*- +# vim: filetype=python +# +# This work is licensed under the terms of the GNU GPL, version 2 or later. +# See the COPYING file in the top-level directory. + +## +# = eBPF Objects +# +# eBPF object is an ELF binary that contains the eBPF program and eBPF +# map description(BTF). Overall, eBPF object should contain the +# program and enough metadata to create/load eBPF with libbpf. As the +# eBPF maps/program should correspond to QEMU, the eBPF can't be used +# from different QEMU build. +# +# Currently, there is a possible eBPF for receive-side scaling (RSS). +## + +## +# @EbpfObject: +# +# An eBPF ELF object. +# +# @object: the eBPF object encoded in base64 +# +# Since: 9.0 +## +{ 'struct': 'EbpfObject', + 'data': {'object': 'str'}, + 'if': 'CONFIG_EBPF' } + +## +# @EbpfProgramID: +# +# The eBPF programs that can be gotten with request-ebpf. +# +# @rss: Receive side scaling, technology that allows steering traffic +# between queues by calculation hash. Users may set up +# indirection table and hash/packet types configurations. Used +# with virtio-net. +# +# Since: 9.0 +## +{ 'enum': 'EbpfProgramID', + 'if': 'CONFIG_EBPF', + 'data': [ { 'name': 'rss' } ] } + +## +# @request-ebpf: +# +# Retrieve an eBPF object that can be loaded with libbpf. Management +# applications (e.g. libvirt) may load it and pass file descriptors to +# QEMU, so they can run running QEMU without BPF capabilities. +# +# @id: The ID of the program to return. +# +# Returns: eBPF object encoded in base64. +# +# Since: 9.0 +## +{ 'command': 'request-ebpf', + 'data': { 'id': 'EbpfProgramID' }, + 'returns': 'EbpfObject', + 'if': 'CONFIG_EBPF' } diff --git a/qapi/error.json b/qapi/error.json index 94a6502de9..135c1e8231 100644 --- a/qapi/error.json +++ b/qapi/error.json @@ -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 ## diff --git a/qapi/introspect.json b/qapi/introspect.json index 39bd303778..b041b02ba8 100644 --- a/qapi/introspect.json +++ b/qapi/introspect.json @@ -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,22 +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) -# -# Additional members depend on the value of @meta-type. +# particular order. (since 4.1 for object types, 4.2 for +# commands, 5.0 for the rest) # # Since: 2.5 ## @@ -142,14 +138,40 @@ # # Additional SchemaInfo members for meta-type 'enum'. # -# @values: the enumeration type's values, in no particular order. +# @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. +# +# Features: +# +# @deprecated: Member @values is deprecated. Use @members instead. # # Values of this type are JSON string on the wire. # # Since: 2.5 ## { 'struct': 'SchemaInfoEnum', - 'data': { 'values': ['str'] } } + 'data': { 'members': [ 'SchemaInfoEnumMember' ], + 'values': { 'type': [ 'str' ], + 'features': [ 'deprecated' ] } } } + +## +# @SchemaInfoEnumMember: +# +# An object member. +# +# @name: the member's name, as defined in the QAPI schema. +# +# @features: names of features associated with the member, in no +# particular order. +# +# Since: 6.2 +## +{ 'struct': 'SchemaInfoEnumMember', + 'data': { 'name': 'str', '*features': [ 'str' ] } } ## # @SchemaInfoArray: @@ -170,16 +192,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. # @@ -199,16 +221,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 ## @@ -225,7 +245,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 ## @@ -237,9 +257,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 +# :doc:`/devel/qapi-code-gen` section Alternate types. # # On the wire, this can be any of the members. # @@ -266,14 +286,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 ## @@ -287,7 +308,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 ## diff --git a/qapi/job.json b/qapi/job.json index 1a6ef03451..b3957207a4 100644 --- a/qapi/job.json +++ b/qapi/job.json @@ -2,7 +2,7 @@ # vim: filetype=python ## -# == Background jobs +# = Background jobs ## ## @@ -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 ## @@ -100,11 +105,13 @@ # # @finalize: see @job-finalize # +# @change: see @block-job-change (since 8.2) +# # Since: 2.12 ## { 'enum': 'JobVerb', 'data': ['cancel', 'pause', 'resume', 'set-speed', 'complete', 'dismiss', - 'finalize' ] } + 'finalize', 'change' ] } ## # @JOB_STATUS_CHANGE: @@ -112,6 +119,7 @@ # Emitted when a job transitions to a different status. # # @id: The job identifier +# # @status: The new job status # # Since: 3.0 @@ -125,12 +133,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,10 +153,10 @@ # # 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. +# @id: The job identifier. # # Since: 3.0 ## @@ -161,11 +169,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. # @@ -173,7 +181,6 @@ ## { 'command': 'job-cancel', 'data': { 'id': 'str' } } - ## # @job-complete: # @@ -188,12 +195,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. # @@ -204,16 +213,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 ## @@ -230,22 +240,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 ## diff --git a/qapi/machine-common.json b/qapi/machine-common.json new file mode 100644 index 0000000000..fa6bd71d12 --- /dev/null +++ b/qapi/machine-common.json @@ -0,0 +1,21 @@ +# -*- Mode: Python -*- +# vim: filetype=python +# +# This work is licensed under the terms of the GNU GPL, version 2 or later. +# See the COPYING file in the top-level directory. + +## +# = Machines S390 data types +## + +## +# @CpuS390Entitlement: +# +# An enumeration of CPU entitlements that can be assumed by a virtual +# S390 CPU +# +# Since: 8.2 +## +{ 'enum': 'CpuS390Entitlement', + 'prefix': 'S390_CPU_ENTITLEMENT', + 'data': [ 'auto', 'low', 'medium', 'high' ] } diff --git a/qapi/machine-target.json b/qapi/machine-target.json index e7811654b7..29e695aa06 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -4,17 +4,20 @@ # This work is licensed under the terms of the GNU GPL, version 2 or later. # See the COPYING file in the top-level directory. +{ 'include': 'machine-common.json' } + ## # @CpuModelInfo: # # 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,50 +31,53 @@ # # 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. -# -# 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). +# @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. +# +# 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 ## { 'enum': 'CpuModelExpansionType', 'data': [ 'static', 'full' ] } - ## # @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 ## @@ -89,7 +95,7 @@ ## { 'struct': 'CpuModelBaselineInfo', 'data': { 'model': 'CpuModelInfo' }, - 'if': 'defined(TARGET_S390X)' } + 'if': 'TARGET_S390X' } ## # @CpuModelCompareInfo: @@ -97,102 +103,129 @@ # 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 ## { 'struct': 'CpuModelCompareInfo', 'data': { 'result': 'CpuModelCompareResult', 'responsible-properties': ['str'] }, - 'if': 'defined(TARGET_S390X)' } + 'if': 'TARGET_S390X' } ## # @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. +# Compares two CPU models, @modela and @modelb, 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. # -# 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. -# -# 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. +# * 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. +# +# @modela: description of the first CPU model to compare, referred to as +# "model A" in CpuModelCompareResult +# +# @modelb: description of the second CPU model to compare, referred to as +# "model B" in CpuModelCompareResult +# +# Returns: a CpuModelCompareInfo describing how both CPU models +# compare +# +# Errors: +# - 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 ## { 'command': 'query-cpu-model-comparison', 'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' }, 'returns': 'CpuModelCompareInfo', - 'if': 'defined(TARGET_S390X)' } + 'if': 'TARGET_S390X' } ## # @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, @modela and @modelb, 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. -# -# 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. +# * 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. +# +# @modela: description of the first CPU model to baseline +# +# @modelb: description of the second CPU model to baseline +# +# Returns: a CpuModelBaselineInfo describing the baselined CPU model +# +# Errors: +# - 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 ## @@ -200,7 +233,7 @@ 'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' }, 'returns': 'CpuModelBaselineInfo', - 'if': 'defined(TARGET_S390X)' } + 'if': 'TARGET_S390X' } ## # @CpuModelExpansionInfo: @@ -213,38 +246,53 @@ ## { 'struct': 'CpuModelExpansionInfo', 'data': { 'model': 'CpuModelInfo' }, - 'if': 'defined(TARGET_S390X) || defined(TARGET_I386) || defined(TARGET_ARM)' } + 'if': { 'any': [ 'TARGET_S390X', + 'TARGET_I386', + 'TARGET_ARM', + 'TARGET_LOONGARCH64', + 'TARGET_RISCV' ] } } ## # @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, @model, (or a combination of CPU model + +# additional options) to different granularities, specified by +# @type, 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. -# -# 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. +# * 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". +# +# @model: description of the CPU model to expand +# +# @type: expansion type, specifying how to expand the CPU model +# +# Returns: a CpuModelExpansionInfo describing the expanded CPU model +# +# Errors: +# - 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 +# - if an expansion type is not supported # # Since: 2.8 ## @@ -252,7 +300,11 @@ 'data': { 'type': 'CpuModelExpansionType', 'model': 'CpuModelInfo' }, 'returns': 'CpuModelExpansionInfo', - 'if': 'defined(TARGET_S390X) || defined(TARGET_I386) || defined(TARGET_ARM)' } + 'if': { 'any': [ 'TARGET_S390X', + 'TARGET_I386', + 'TARGET_ARM', + 'TARGET_LOONGARCH64', + 'TARGET_RISCV' ] } } ## # @CpuDefinitionInfo: @@ -262,49 +314,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) -# -# @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) -# -# @alias-of: Name of CPU model this model is an alias for. The target of the -# CPU model alias may change depending on the machine type. -# Management software is supposed to translate CPU model aliases -# in the VM configuration, because aliases may stop being -# migration-safe in the future (since 4.1) -# -# @deprecated: If true, this CPU model is deprecated and may be removed in -# in some future version of QEMU according to the QEMU deprecation -# policy. (since 5.2) -# -# @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. +# 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) +# +# @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) +# +# @alias-of: Name of CPU model this model is an alias for. The target +# of the CPU model alias may change depending on the machine type. +# Management software is supposed to translate CPU model aliases +# in the VM configuration, because aliases may stop being +# migration-safe in the future (since 4.1) +# +# @deprecated: If true, this CPU model is deprecated and may be +# removed in in some future version of QEMU according to the QEMU +# deprecation policy. (since 5.2) +# +# @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 ## @@ -316,16 +367,147 @@ 'typename': 'str', '*alias-of' : 'str', 'deprecated' : 'bool' }, - 'if': 'defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386) || defined(TARGET_S390X) || defined(TARGET_MIPS)' } + 'if': { 'any': [ 'TARGET_PPC', + 'TARGET_ARM', + 'TARGET_I386', + 'TARGET_S390X', + 'TARGET_MIPS', + 'TARGET_LOONGARCH64', + 'TARGET_RISCV' ] } } ## # @query-cpu-definitions: # # Return a list of supported virtual CPU definitions # -# Returns: a list of CpuDefInfo +# Returns: a list of CpuDefinitionInfo # # Since: 1.2 ## { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'], - 'if': 'defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386) || defined(TARGET_S390X) || defined(TARGET_MIPS)' } + 'if': { 'any': [ 'TARGET_PPC', + 'TARGET_ARM', + 'TARGET_I386', + 'TARGET_S390X', + 'TARGET_MIPS', + 'TARGET_LOONGARCH64', + 'TARGET_RISCV' ] } } + +## +# @CpuS390Polarization: +# +# An enumeration of CPU polarization that can be assumed by a virtual +# S390 CPU +# +# Since: 8.2 +## +{ 'enum': 'CpuS390Polarization', + 'prefix': 'S390_CPU_POLARIZATION', + 'data': [ 'horizontal', 'vertical' ], + 'if': 'TARGET_S390X' +} + +## +# @set-cpu-topology: +# +# Modify the topology by moving the CPU inside the topology tree, or +# by changing a modifier attribute of a CPU. Absent values will not +# be modified. +# +# @core-id: the vCPU ID to be moved +# +# @socket-id: destination socket to move the vCPU to +# +# @book-id: destination book to move the vCPU to +# +# @drawer-id: destination drawer to move the vCPU to +# +# @entitlement: entitlement to set +# +# @dedicated: whether the provisioning of real to virtual CPU is +# dedicated +# +# Features: +# +# @unstable: This command is experimental. +# +# Since: 8.2 +## +{ 'command': 'set-cpu-topology', + 'data': { + 'core-id': 'uint16', + '*socket-id': 'uint16', + '*book-id': 'uint16', + '*drawer-id': 'uint16', + '*entitlement': 'CpuS390Entitlement', + '*dedicated': 'bool' + }, + 'features': [ 'unstable' ], + 'if': { 'all': [ 'TARGET_S390X' , 'CONFIG_KVM' ] } +} + +## +# @CPU_POLARIZATION_CHANGE: +# +# Emitted when the guest asks to change the polarization. +# +# The guest can tell the host (via the PTF instruction) whether the +# CPUs should be provisioned using horizontal or vertical +# polarization. +# +# On horizontal polarization the host is expected to provision all +# vCPUs equally. +# +# On vertical polarization the host can provision each vCPU +# differently. The guest will get information on the details of the +# provisioning the next time it uses the STSI(15) instruction. +# +# @polarization: polarization specified by the guest +# +# Features: +# +# @unstable: This event is experimental. +# +# Since: 8.2 +# +# Example: +# +# <- { "event": "CPU_POLARIZATION_CHANGE", +# "data": { "polarization": "horizontal" }, +# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } +## +{ 'event': 'CPU_POLARIZATION_CHANGE', + 'data': { 'polarization': 'CpuS390Polarization' }, + 'features': [ 'unstable' ], + 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } +} + +## +# @CpuPolarizationInfo: +# +# The result of a CPU polarization query. +# +# @polarization: the CPU polarization +# +# Since: 8.2 +## +{ 'struct': 'CpuPolarizationInfo', + 'data': { 'polarization': 'CpuS390Polarization' }, + 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } +} + +## +# @query-s390x-cpu-polarization: +# +# Features: +# +# @unstable: This command is experimental. +# +# Returns: the machine's CPU polarization +# +# Since: 8.2 +## +{ 'command': 'query-s390x-cpu-polarization', 'returns': 'CpuPolarizationInfo', + 'features': [ 'unstable' ], + 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } +} diff --git a/qapi/machine.json b/qapi/machine.json index 6e90d463fc..e8b60641f2 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -9,38 +9,40 @@ ## { 'include': 'common.json' } +{ 'include': 'machine-common.json' } ## # @SysEmuTarget: # # The comprehensive enumeration of QEMU system emulation ("softmmu") -# targets. Run "./configure --help" in the project root directory, and -# look for the \*-softmmu targets near the "--target-list" option. The -# individual target constants are not documented here, for the time -# being. +# targets. Run "./configure --help" in the project root directory, +# and look for the \*-softmmu targets near the "--target-list" option. +# The individual target constants are not documented here, for the +# time being. # # @rx: since 5.0 +# # @avr: since 5.1 # -# Notes: The resulting QMP strings can be appended to the "qemu-system-" -# prefix to produce the corresponding QEMU executable name. This -# is true even for "qemu-system-x86_64". +# Notes: The resulting QMP strings can be appended to the +# "qemu-system-" prefix to produce the corresponding QEMU +# executable name. This is true even for "qemu-system-x86_64". # # Since: 3.0 ## { 'enum' : 'SysEmuTarget', - 'data' : [ 'aarch64', 'alpha', 'arm', 'avr', 'cris', 'hppa', 'i386', 'lm32', - 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64', - 'mips64el', 'mipsel', 'moxie', 'nios2', 'or1k', 'ppc', + 'data' : [ 'aarch64', 'alpha', 'arm', 'avr', 'cris', 'hppa', 'i386', + 'loongarch64', 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64', + 'mips64el', 'mipsel', 'nios2', 'or1k', 'ppc', 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4', - 'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32', + 'sh4eb', 'sparc', 'sparc64', 'tricore', 'x86_64', 'xtensa', 'xtensaeb' ] } ## # @CpuS390State: # -# An enumeration of cpu states that can be assumed by a virtual -# S390 CPU +# An enumeration of cpu states that can be assumed by a virtual S390 +# CPU # # Since: 2.12 ## @@ -55,9 +57,16 @@ # # @cpu-state: the virtual CPU's state # +# @dedicated: the virtual CPU's dedication (since 8.2) +# +# @entitlement: the virtual CPU's entitlement (since 8.2) +# # Since: 2.12 ## -{ 'struct': 'CpuInfoS390', 'data': { 'cpu-state': 'CpuS390State' } } +{ 'struct': 'CpuInfoS390', + 'data': { 'cpu-state': 'CpuS390State', + '*dedicated': 'bool', + '*entitlement': 'CpuS390Entitlement' } } ## # @CpuInfoFast: @@ -70,14 +79,12 @@ # # @thread-id: ID of the underlying host thread # -# @props: properties describing to which node/socket/core/thread -# virtual CPU belongs to, provided if supported by board +# @props: properties associated with a virtual CPU, e.g. the socket id # # @target: the QEMU system emulation target, which determines which -# additional fields will be listed (since 3.0) +# additional fields will be listed (since 3.0) # # Since: 2.12 -# ## { 'union' : 'CpuInfoFast', 'base' : { 'cpu-index' : 'int', @@ -99,34 +106,32 @@ # # Example: # -# -> { "execute": "query-cpus-fast" } -# <- { "return": [ -# { -# "thread-id": 25627, -# "props": { -# "core-id": 0, -# "thread-id": 0, -# "socket-id": 0 -# }, -# "qom-path": "/machine/unattached/device[0]", -# "arch":"x86", -# "target":"x86_64", -# "cpu-index": 0 -# }, -# { -# "thread-id": 25628, -# "props": { -# "core-id": 0, -# "thread-id": 0, -# "socket-id": 1 +# -> { "execute": "query-cpus-fast" } +# <- { "return": [ +# { +# "thread-id": 25627, +# "props": { +# "core-id": 0, +# "thread-id": 0, +# "socket-id": 0 +# }, +# "qom-path": "/machine/unattached/device[0]", +# "target":"x86_64", +# "cpu-index": 0 # }, -# "qom-path": "/machine/unattached/device[2]", -# "arch":"x86", -# "target":"x86_64", -# "cpu-index": 1 -# } -# ] -# } +# { +# "thread-id": 25628, +# "props": { +# "core-id": 0, +# "thread-id": 0, +# "socket-id": 1 +# }, +# "qom-path": "/machine/unattached/device[2]", +# "target":"x86_64", +# "cpu-index": 1 +# } +# ] +# } ## { 'command': 'query-cpus-fast', 'returns': [ 'CpuInfoFast' ] } @@ -142,21 +147,24 @@ # @is-default: whether the machine is default # # @cpu-max: maximum number of CPUs supported by the machine type -# (since 1.5) +# (since 1.5) # # @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7) # # @numa-mem-supported: true if '-numa node,mem' option is supported by -# the machine type and false otherwise (since 4.1) +# the machine type and false otherwise (since 4.1) +# +# @deprecated: if true, the machine type is deprecated and may be +# removed in future versions of QEMU according to the QEMU +# deprecation policy (since 4.1) # -# @deprecated: if true, the machine type is deprecated and may be removed -# in future versions of QEMU according to the QEMU deprecation -# policy (since 4.1) +# @default-cpu-type: default CPU model typename if none is requested +# via the -cpu argument. (since 4.2) # -# @default-cpu-type: default CPU model typename if none is requested via -# the -cpu argument. (since 4.2) +# @default-ram-id: the default ID of initial RAM memory backend (since +# 5.2) # -# @default-ram-id: the default ID of initial RAM memory backend (since 5.2) +# @acpi: machine type supports ACPI (since 8.0) # # Since: 1.2 ## @@ -165,7 +173,7 @@ '*is-default': 'bool', 'cpu-max': 'int', 'hotpluggable-cpus': 'bool', 'numa-mem-supported': 'bool', 'deprecated': 'bool', '*default-cpu-type': 'str', - '*default-ram-id': 'str' } } + '*default-ram-id': 'str', 'acpi': 'bool' } } ## # @query-machines: @@ -184,7 +192,7 @@ # Information describing the running machine parameters. # # @wakeup-suspend-support: true if the machine supports wake up from -# suspend +# suspend # # Since: 4.0 ## @@ -234,7 +242,8 @@ # # Since: 0.14 # -# Notes: If no UUID was specified for the guest, a null UUID is returned. +# Notes: If no UUID was specified for the guest, a null UUID is +# returned. ## { 'struct': 'UuidInfo', 'data': {'UUID': 'str'} } @@ -249,9 +258,8 @@ # # Example: # -# -> { "execute": "query-uuid" } -# <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } } -# +# -> { "execute": "query-uuid" } +# <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } } ## { 'command': 'query-uuid', 'returns': 'UuidInfo', 'allow-preconfig': true } @@ -284,9 +292,8 @@ # # Example: # -# -> { "execute": "system_reset" } -# <- { "return": {} } -# +# -> { "execute": "system_reset" } +# <- { "return": {} } ## { 'command': 'system_reset' } @@ -298,66 +305,63 @@ # Since: 0.14 # # Notes: A guest may or may not respond to this command. This command -# returning does not indicate that a guest has accepted the request or -# that it has shut down. Many guests will respond to this command by -# prompting the user in some way. -# Example: +# returning does not indicate that a guest has accepted the +# request or that it has shut down. Many guests will respond to +# this command by prompting the user in some way. # -# -> { "execute": "system_powerdown" } -# <- { "return": {} } +# Example: # +# -> { "execute": "system_powerdown" } +# <- { "return": {} } ## { 'command': 'system_powerdown' } ## # @system_wakeup: # -# Wake up guest from suspend. If the guest has wake-up from suspend +# Wake up guest from suspend. If the guest has wake-up from suspend # support enabled (wakeup-suspend-support flag from # query-current-machine), wake-up guest from suspend if the guest is -# in SUSPENDED state. Return an error otherwise. -# -# Since: 1.1 +# in SUSPENDED state. Return an error otherwise. # -# Returns: nothing. +# Since: 1.1 # # Note: prior to 4.0, this command does nothing in case the guest -# isn't suspended. +# isn't suspended. # # Example: # -# -> { "execute": "system_wakeup" } -# <- { "return": {} } -# +# -> { "execute": "system_wakeup" } +# <- { "return": {} } ## { 'command': 'system_wakeup' } ## # @LostTickPolicy: # -# Policy for handling lost ticks in timer devices. Ticks end up getting -# lost when, for example, the guest is paused. -# -# @discard: throw away the missed ticks and continue with future injection -# normally. The guest OS will see the timer jump ahead by a -# potentially quite significant amount all at once, as if the -# intervening chunk of time had simply not existed; needless to -# say, such a sudden jump can easily confuse a guest OS which is -# not specifically prepared to deal with it. Assuming the guest -# OS can deal correctly with the time jump, the time in the guest -# and in the host should now match. -# -# @delay: continue to deliver ticks at the normal rate. The guest OS will -# not notice anything is amiss, as from its point of view time will -# have continued to flow normally. The time in the guest should now -# be behind the time in the host by exactly the amount of time during -# which ticks have been missed. -# -# @slew: deliver ticks at a higher rate to catch up with the missed ticks. -# The guest OS will not notice anything is amiss, as from its point -# of view time will have continued to flow normally. Once the timer -# has managed to catch up with all the missing ticks, the time in -# the guest and in the host should match. +# Policy for handling lost ticks in timer devices. Ticks end up +# getting lost when, for example, the guest is paused. +# +# @discard: throw away the missed ticks and continue with future +# injection normally. The guest OS will see the timer jump ahead +# by a potentially quite significant amount all at once, as if the +# intervening chunk of time had simply not existed; needless to +# say, such a sudden jump can easily confuse a guest OS which is +# not specifically prepared to deal with it. Assuming the guest +# OS can deal correctly with the time jump, the time in the guest +# and in the host should now match. +# +# @delay: continue to deliver ticks at the normal rate. The guest OS +# will not notice anything is amiss, as from its point of view +# time will have continued to flow normally. The time in the +# guest should now be behind the time in the host by exactly the +# amount of time during which ticks have been missed. +# +# @slew: deliver ticks at a higher rate to catch up with the missed +# ticks. The guest OS will not notice anything is amiss, as from +# its point of view time will have continued to flow normally. +# Once the timer has managed to catch up with all the missing +# ticks, the time in the guest and in the host should match. # # Since: 2.0 ## @@ -367,20 +371,19 @@ ## # @inject-nmi: # -# Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all CPUs (ppc64). -# The command fails when the guest doesn't support injecting. +# Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or +# all CPUs (ppc64). The command fails when the guest doesn't support +# injecting. # -# Returns: If successful, nothing -# -# Since: 0.14 +# Since: 0.14 # -# Note: prior to 2.1, this command was only supported for x86 and s390 VMs +# Note: prior to 2.1, this command was only supported for x86 and s390 +# VMs # # Example: # -# -> { "execute": "inject-nmi" } -# <- { "return": {} } -# +# -> { "execute": "inject-nmi" } +# <- { "return": {} } ## { 'command': 'inject-nmi' } @@ -408,9 +411,8 @@ # # Example: # -# -> { "execute": "query-kvm" } -# <- { "return": { "enabled": true, "present": true } } -# +# -> { "execute": "query-kvm" } +# <- { "return": { "enabled": true, "present": true } } ## { 'command': 'query-kvm', 'returns': 'KvmInfo' } @@ -435,7 +437,9 @@ ## # @NumaOptions: # -# A discriminated record of NUMA options. (for OptsVisitor) +# A discriminated record of NUMA options. (for OptsVisitor) +# +# @type: NUMA option type # # Since: 2.1 ## @@ -452,26 +456,25 @@ ## # @NumaNodeOptions: # -# Create a guest NUMA node. (for OptsVisitor) +# Create a guest NUMA node. (for OptsVisitor) # # @nodeid: NUMA node ID (increase by 1 from 0 if omitted) # -# @cpus: VCPUs belonging to this node (assign VCPUS round-robin -# if omitted) +# @cpus: VCPUs belonging to this node (assign VCPUS round-robin if +# omitted) # # @mem: memory size of this node; mutually exclusive with @memdev. -# Equally divide total memory among nodes if both @mem and @memdev are -# omitted. +# Equally divide total memory among nodes if both @mem and @memdev +# are omitted. # -# @memdev: memory backend object. If specified for one node, -# it must be specified for all nodes. +# @memdev: memory backend object. If specified for one node, it must +# be specified for all nodes. # -# @initiator: defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145, -# points to the nodeid which has the memory controller -# responsible for this NUMA node. This field provides -# additional information as to the initiator node that -# is closest (as in directly attached) to this node, and -# therefore has the best performance (since 5.0) +# @initiator: defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145, points +# to the nodeid which has the memory controller responsible for +# this NUMA node. This field provides additional information as +# to the initiator node that is closest (as in directly attached) +# to this node, and therefore has the best performance (since 5.0) # # Since: 2.1 ## @@ -492,9 +495,9 @@ # # @dst: destination NUMA node. # -# @val: NUMA distance from source node to destination node. -# When a node is unreachable from another node, set the distance -# between them to 255. +# @val: NUMA distance from source node to destination node. When a +# node is unreachable from another node, set the distance between +# them to 255. # # Since: 2.10 ## @@ -505,6 +508,42 @@ 'val': 'uint8' }} ## +# @CXLFixedMemoryWindowOptions: +# +# Create a CXL Fixed Memory Window +# +# @size: Size of the Fixed Memory Window in bytes. Must be a multiple +# of 256MiB. +# +# @interleave-granularity: Number of contiguous bytes for which +# accesses will go to a given interleave target. Accepted values +# [256, 512, 1k, 2k, 4k, 8k, 16k] +# +# @targets: Target root bridge IDs from -device ...,id=<ID> for each +# root bridge. +# +# Since: 7.1 +## +{ 'struct': 'CXLFixedMemoryWindowOptions', + 'data': { + 'size': 'size', + '*interleave-granularity': 'size', + 'targets': ['str'] }} + +## +# @CXLFMWProperties: +# +# List of CXL Fixed Memory Windows. +# +# @cxl-fmw: List of CXLFixedMemoryWindowOptions +# +# Since: 7.1 +## +{ 'struct' : 'CXLFMWProperties', + 'data': { 'cxl-fmw': ['CXLFixedMemoryWindowOptions'] } +} + +## # @X86CPURegister32: # # A X86 32-bit register @@ -519,10 +558,11 @@ # # Information about a X86 CPU feature word # -# @cpuid-input-eax: Input EAX value for CPUID instruction for that feature word +# @cpuid-input-eax: Input EAX value for CPUID instruction for that +# feature word # # @cpuid-input-ecx: Input ECX value for CPUID instruction for that -# feature word +# feature word # # @cpuid-register: Output register containing the feature bits # @@ -539,7 +579,8 @@ ## # @DummyForceArrays: # -# Not used by QMP; hack to let us use X86CPUFeatureWordInfoList internally +# Not used by QMP; hack to let us use X86CPUFeatureWordInfoList +# internally # # Since: 2.5 ## @@ -549,8 +590,8 @@ ## # @NumaCpuOptions: # -# Option "-numa cpu" overrides default cpu to node mapping. -# It accepts the same set of cpu properties as returned by +# Option "-numa cpu" overrides default cpu to node mapping. It +# accepts the same set of cpu properties as returned by # query-hotpluggable-cpus[].props, where node-id could be used to # override default node mapping. # @@ -585,11 +626,11 @@ ## # @HmatLBDataType: # -# Data type in the System Locality Latency and Bandwidth -# Information Structure of HMAT (Heterogeneous Memory Attribute Table) +# Data type in the System Locality Latency and Bandwidth Information +# Structure of HMAT (Heterogeneous Memory Attribute Table) # -# For more information about @HmatLBDataType, see chapter -# 5.2.27.4: Table 5-146: Field "Data Type" of ACPI 6.3 spec. +# For more information about @HmatLBDataType, see chapter 5.2.27.4: +# Table 5-146: Field "Data Type" of ACPI 6.3 spec. # # @access-latency: access latency (nanoseconds) # @@ -612,28 +653,27 @@ ## # @NumaHmatLBOptions: # -# Set the system locality latency and bandwidth information -# between Initiator and Target proximity Domains. +# Set the system locality latency and bandwidth information between +# Initiator and Target proximity Domains. # -# For more information about @NumaHmatLBOptions, see chapter -# 5.2.27.4: Table 5-146 of ACPI 6.3 spec. +# For more information about @NumaHmatLBOptions, see chapter 5.2.27.4: +# Table 5-146 of ACPI 6.3 spec. # # @initiator: the Initiator Proximity Domain. # # @target: the Target Proximity Domain. # -# @hierarchy: the Memory Hierarchy. Indicates the performance -# of memory or side cache. +# @hierarchy: the Memory Hierarchy. Indicates the performance of +# memory or side cache. # -# @data-type: presents the type of data, access/read/write -# latency or hit latency. +# @data-type: presents the type of data, access/read/write latency or +# hit latency. # -# @latency: the value of latency from @initiator to @target -# proximity domain, the latency unit is "ns(nanosecond)". +# @latency: the value of latency from @initiator to @target proximity +# domain, the latency unit is "ns(nanosecond)". # # @bandwidth: the value of bandwidth between @initiator and @target -# proximity domain, the bandwidth unit is -# "Bytes per second". +# proximity domain, the bandwidth unit is "Bytes per second". # # Since: 5.0 ## @@ -655,8 +695,8 @@ # For more information of @HmatCacheAssociativity, see chapter # 5.2.27.5: Table 5-147 of ACPI 6.3 spec. # -# @none: None (no memory side cache in this proximity domain, -# or cache associativity unknown) +# @none: None (no memory side cache in this proximity domain, or cache +# associativity unknown) # # @direct: Direct Mapped # @@ -670,14 +710,14 @@ ## # @HmatCacheWritePolicy: # -# Cache write policy in the Memory Side Cache Information Structure -# of HMAT +# Cache write policy in the Memory Side Cache Information Structure of +# HMAT # -# For more information of @HmatCacheWritePolicy, see chapter -# 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec. +# For more information of @HmatCacheWritePolicy, see chapter 5.2.27.5: +# Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec. # -# @none: None (no memory side cache in this proximity domain, -# or cache write policy unknown) +# @none: None (no memory side cache in this proximity domain, or cache +# write policy unknown) # # @write-back: Write Back (WB) # @@ -693,8 +733,8 @@ # # Set the memory side cache information for a given memory domain. # -# For more information of @NumaHmatCacheOptions, see chapter -# 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec. +# For more information of @NumaHmatCacheOptions, see chapter 5.2.27.5: +# Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec. # # @node-id: the memory proximity domain to which the memory belongs. # @@ -703,7 +743,7 @@ # @level: the cache level described in this structure. # # @associativity: the cache associativity, -# none/direct-mapped/complex(complex cache indexing). +# none/direct-mapped/complex(complex cache indexing). # # @policy: the write policy, none/write-back/write-through. # @@ -732,9 +772,7 @@ # @filename: the file to save the memory to as binary data # # @cpu-index: the index of the virtual CPU to use for translating the -# virtual address (defaults to CPU 0) -# -# Returns: Nothing on success +# virtual address (defaults to CPU 0) # # Since: 0.14 # @@ -742,12 +780,11 @@ # # Example: # -# -> { "execute": "memsave", -# "arguments": { "val": 10, -# "size": 100, -# "filename": "/tmp/virtual-mem-dump" } } -# <- { "return": {} } -# +# -> { "execute": "memsave", +# "arguments": { "val": 10, +# "size": 100, +# "filename": "/tmp/virtual-mem-dump" } } +# <- { "return": {} } ## { 'command': 'memsave', 'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} } @@ -763,20 +800,17 @@ # # @filename: the file to save the memory to as binary data # -# Returns: Nothing on success -# # Since: 0.14 # # Notes: Errors were not reliably returned until 1.1 # # Example: # -# -> { "execute": "pmemsave", -# "arguments": { "val": 10, -# "size": 100, -# "filename": "/tmp/physical-mem-dump" } } -# <- { "return": {} } -# +# -> { "execute": "pmemsave", +# "arguments": { "val": 10, +# "size": 100, +# "filename": "/tmp/physical-mem-dump" } } +# <- { "return": {} } ## { 'command': 'pmemsave', 'data': {'val': 'int', 'size': 'int', 'filename': 'str'} } @@ -790,11 +824,19 @@ # # @size: memory backend size # -# @merge: enables or disables memory merge support +# @merge: whether memory merge support is enabled # -# @dump: includes memory backend's memory in a core dump or not +# @dump: whether memory backend's memory is included in a core dump # -# @prealloc: enables or disables memory preallocation +# @prealloc: whether memory was preallocated +# +# @share: whether memory is private to QEMU or shared (since 6.1) +# +# @reserve: whether swap space (or huge pages) was reserved if +# applicable. This corresponds to the user configuration and not +# the actual behavior implemented in the OS to perform the +# reservation. For example, Linux will never reserve swap space +# for shared file mappings. (since 6.1) # # @host-nodes: host nodes for its memory policy # @@ -809,6 +851,8 @@ 'merge': 'bool', 'dump': 'bool', 'prealloc': 'bool', + 'share': 'bool', + '*reserve': 'bool', 'host-nodes': ['uint16'], 'policy': 'HostMemPolicy' }} @@ -823,56 +867,81 @@ # # Example: # -# -> { "execute": "query-memdev" } -# <- { "return": [ -# { -# "id": "mem1", -# "size": 536870912, -# "merge": false, -# "dump": true, -# "prealloc": false, -# "host-nodes": [0, 1], -# "policy": "bind" -# }, -# { -# "size": 536870912, -# "merge": false, -# "dump": true, -# "prealloc": true, -# "host-nodes": [2, 3], -# "policy": "preferred" +# -> { "execute": "query-memdev" } +# <- { "return": [ +# { +# "id": "mem1", +# "size": 536870912, +# "merge": false, +# "dump": true, +# "prealloc": false, +# "share": false, +# "host-nodes": [0, 1], +# "policy": "bind" +# }, +# { +# "size": 536870912, +# "merge": false, +# "dump": true, +# "prealloc": true, +# "share": false, +# "host-nodes": [2, 3], +# "policy": "preferred" +# } +# ] # } -# ] -# } -# ## { 'command': 'query-memdev', 'returns': ['Memdev'], 'allow-preconfig': true } ## # @CpuInstanceProperties: # -# List of properties to be used for hotplugging a CPU instance, -# it should be passed by management with device_add command when -# a CPU is being hotplugged. +# List of properties to be used for hotplugging a CPU instance, it +# should be passed by management with device_add command when a CPU is +# being hotplugged. +# +# Which members are optional and which mandatory depends on the +# architecture and board. +# +# For s390x see :ref:`cpu-topology-s390x`. +# +# The ids other than the node-id specify the position of the CPU +# within the CPU topology (as defined by the machine property "smp", +# thus see also type @SMPConfiguration) # # @node-id: NUMA node ID the CPU belongs to -# @socket-id: socket number within node/board the CPU belongs to -# @die-id: die number within node/board the CPU belongs to (Since 4.1) -# @core-id: core number within die the CPU belongs to -# @thread-id: thread number within core the CPU belongs to # -# Note: currently there are 5 properties that could be present -# but management should be prepared to pass through other -# properties with device_add command to allow for future -# interface extension. This also requires the filed names to be kept in -# sync with the properties passed to -device/device_add. +# @drawer-id: drawer number within CPU topology the CPU belongs to +# (since 8.2) +# +# @book-id: book number within parent container the CPU belongs to +# (since 8.2) +# +# @socket-id: socket number within parent container the CPU belongs to +# +# @die-id: die number within the parent container the CPU belongs to +# (since 4.1) +# +# @cluster-id: cluster number within the parent container the CPU +# belongs to (since 7.1) +# +# @core-id: core number within the parent container the CPU belongs to +# +# @thread-id: thread number within the core the CPU belongs to +# +# Note: management should be prepared to pass through additional +# properties with device_add. # # Since: 2.7 ## { 'struct': 'CpuInstanceProperties', + # Keep these in sync with the properties device_add accepts 'data': { '*node-id': 'int', + '*drawer-id': 'int', + '*book-id': 'int', '*socket-id': 'int', '*die-id': 'int', + '*cluster-id': 'int', '*core-id': 'int', '*thread-id': 'int' } @@ -882,10 +951,14 @@ # @HotpluggableCPU: # # @type: CPU object type for usage with device_add command +# # @props: list of properties to be used for hotplugging CPU -# @vcpus-count: number of logical VCPU threads @HotpluggableCPU provides -# @qom-path: link to existing CPU object if CPU is present or -# omitted if CPU is not present. +# +# @vcpus-count: number of logical VCPU threads @HotpluggableCPU +# provides +# +# @qom-path: link to existing CPU object if CPU is present or omitted +# if CPU is not present. # # Since: 2.7 ## @@ -906,49 +979,49 @@ # # Since: 2.7 # -# Example: +# Examples: +# +# For pseries machine type started with -smp 2,cores=2,maxcpus=4 +# -cpu POWER8: # -# For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8: -# -# -> { "execute": "query-hotpluggable-cpus" } -# <- {"return": [ -# { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core", -# "vcpus-count": 1 }, -# { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core", -# "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"} -# ]}' -# -# For pc machine type started with -smp 1,maxcpus=2: -# -# -> { "execute": "query-hotpluggable-cpus" } -# <- {"return": [ -# { -# "type": "qemu64-x86_64-cpu", "vcpus-count": 1, -# "props": {"core-id": 0, "socket-id": 1, "thread-id": 0} -# }, -# { -# "qom-path": "/machine/unattached/device[0]", -# "type": "qemu64-x86_64-cpu", "vcpus-count": 1, -# "props": {"core-id": 0, "socket-id": 0, "thread-id": 0} -# } -# ]} -# -# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu -# (Since: 2.11): -# -# -> { "execute": "query-hotpluggable-cpus" } -# <- {"return": [ -# { -# "type": "qemu-s390x-cpu", "vcpus-count": 1, -# "props": { "core-id": 1 } -# }, -# { -# "qom-path": "/machine/unattached/device[0]", -# "type": "qemu-s390x-cpu", "vcpus-count": 1, -# "props": { "core-id": 0 } -# } -# ]} +# -> { "execute": "query-hotpluggable-cpus" } +# <- {"return": [ +# { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core", +# "vcpus-count": 1 }, +# { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core", +# "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"} +# ]}' # +# For pc machine type started with -smp 1,maxcpus=2: +# +# -> { "execute": "query-hotpluggable-cpus" } +# <- {"return": [ +# { +# "type": "qemu64-x86_64-cpu", "vcpus-count": 1, +# "props": {"core-id": 0, "socket-id": 1, "thread-id": 0} +# }, +# { +# "qom-path": "/machine/unattached/device[0]", +# "type": "qemu64-x86_64-cpu", "vcpus-count": 1, +# "props": {"core-id": 0, "socket-id": 0, "thread-id": 0} +# } +# ]} +# +# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 +# -cpu qemu (Since: 2.11): +# +# -> { "execute": "query-hotpluggable-cpus" } +# <- {"return": [ +# { +# "type": "qemu-s390x-cpu", "vcpus-count": 1, +# "props": { "core-id": 1 } +# }, +# { +# "qom-path": "/machine/unattached/device[0]", +# "type": "qemu-s390x-cpu", "vcpus-count": 1, +# "props": { "core-id": 0 } +# } +# ]} ## { 'command': 'query-hotpluggable-cpus', 'returns': ['HotpluggableCPU'], 'allow-preconfig': true } @@ -956,11 +1029,10 @@ ## # @set-numa-node: # -# Runtime equivalent of '-numa' CLI option, available at -# preconfigure stage to configure numa mapping before initializing -# machine. +# Runtime equivalent of '-numa' CLI option, available at preconfigure +# stage to configure numa mapping before initializing machine. # -# Since 3.0 +# Since: 3.0 ## { 'command': 'set-numa-node', 'boxed': true, 'data': 'NumaOptions', @@ -972,31 +1044,30 @@ # # Request the balloon driver to change its balloon size. # -# @value: the target logical size of the VM in bytes. -# We can deduce the size of the balloon using this formula: +# @value: the target logical size of the VM in bytes. We can deduce +# the size of the balloon using this formula: # -# logical_vm_size = vm_ram_size - balloon_size +# logical_vm_size = vm_ram_size - balloon_size # -# From it we have: balloon_size = vm_ram_size - @value +# From it we have: balloon_size = vm_ram_size - @value # -# Returns: - Nothing on success -# - If the balloon driver is enabled but not functional because the KVM -# kernel module cannot support it, KvmMissingCap -# - If no balloon device is present, DeviceNotActive +# Errors: +# - If the balloon driver is enabled but not functional because +# the KVM kernel module cannot support it, KVMMissingCap +# - If no balloon device is present, DeviceNotActive # -# Notes: This command just issues a request to the guest. When it returns, -# the balloon size may not have changed. A guest can change the balloon -# size independent of this command. +# Notes: This command just issues a request to the guest. When it +# returns, the balloon size may not have changed. A guest can +# change the balloon size independent of this command. # # Since: 0.14 # # Example: # -# -> { "execute": "balloon", "arguments": { "value": 536870912 } } -# <- { "return": {} } -# -# With a 2.5GiB guest this command inflated the ballon to 3GiB. +# -> { "execute": "balloon", "arguments": { "value": 536870912 } } +# <- { "return": {} } # +# With a 2.5GiB guest this command inflated the ballon to 3GiB. ## { 'command': 'balloon', 'data': {'value': 'int'} } @@ -1005,11 +1076,10 @@ # # Information about the guest balloon device. # -# @actual: the logical size of the VM in bytes -# Formula used: logical_vm_size = vm_ram_size - balloon_size +# @actual: the logical size of the VM in bytes Formula used: +# logical_vm_size = vm_ram_size - balloon_size # # Since: 0.14 -# ## { 'struct': 'BalloonInfo', 'data': {'actual': 'int' } } @@ -1018,32 +1088,35 @@ # # Return information about the balloon device. # -# Returns: - @BalloonInfo on success -# - If the balloon driver is enabled but not functional because the KVM -# kernel module cannot support it, KvmMissingCap -# - If no balloon device is present, DeviceNotActive +# Returns: +# @BalloonInfo +# +# Errors: +# - If the balloon driver is enabled but not functional because +# the KVM kernel module cannot support it, KVMMissingCap +# - If no balloon device is present, DeviceNotActive # # Since: 0.14 # # Example: # -# -> { "execute": "query-balloon" } -# <- { "return": { -# "actual": 1073741824, -# } -# } -# +# -> { "execute": "query-balloon" } +# <- { "return": { +# "actual": 1073741824 +# } +# } ## { 'command': 'query-balloon', 'returns': 'BalloonInfo' } ## # @BALLOON_CHANGE: # -# Emitted when the guest changes the actual BALLOON level. This value is -# equivalent to the @actual field return by the 'query-balloon' command +# Emitted when the guest changes the actual BALLOON level. This value +# is equivalent to the @actual field return by the 'query-balloon' +# command # -# @actual: the logical size of the VM in bytes -# Formula used: logical_vm_size = vm_ram_size - balloon_size +# @actual: the logical size of the VM in bytes Formula used: +# logical_vm_size = vm_ram_size - balloon_size # # Note: this event is rate-limited. # @@ -1051,25 +1124,87 @@ # # Example: # -# <- { "event": "BALLOON_CHANGE", -# "data": { "actual": 944766976 }, -# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } -# +# <- { "event": "BALLOON_CHANGE", +# "data": { "actual": 944766976 }, +# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } ## { 'event': 'BALLOON_CHANGE', 'data': { 'actual': 'int' } } ## +# @HvBalloonInfo: +# +# hv-balloon guest-provided memory status information. +# +# @committed: the amount of memory in use inside the guest plus the +# amount of the memory unusable inside the guest (ballooned out, +# offline, etc.) +# +# @available: the amount of the memory inside the guest available for +# new allocations ("free") +# +# Since: 8.2 +## +{ 'struct': 'HvBalloonInfo', + 'data': { 'committed': 'size', 'available': 'size' } } + +## +# @query-hv-balloon-status-report: +# +# Returns the hv-balloon driver data contained in the last received +# "STATUS" message from the guest. +# +# Returns: +# @HvBalloonInfo +# +# Errors: +# - If no hv-balloon device is present, guest memory status +# reporting is not enabled or no guest memory status report +# received yet, GenericError +# +# Since: 8.2 +# +# Example: +# +# -> { "execute": "query-hv-balloon-status-report" } +# <- { "return": { +# "committed": 816640000, +# "available": 3333054464 +# } +# } +## +{ 'command': 'query-hv-balloon-status-report', 'returns': 'HvBalloonInfo' } + +## +# @HV_BALLOON_STATUS_REPORT: +# +# Emitted when the hv-balloon driver receives a "STATUS" message from +# the guest. +# +# Note: this event is rate-limited. +# +# Since: 8.2 +# +# Example: +# +# <- { "event": "HV_BALLOON_STATUS_REPORT", +# "data": { "committed": 816640000, "available": 3333054464 }, +# "timestamp": { "seconds": 1600295492, "microseconds": 661044 } } +## +{ 'event': 'HV_BALLOON_STATUS_REPORT', + 'data': 'HvBalloonInfo' } + +## # @MemoryInfo: # # Actual memory information in bytes. # # @base-memory: size of "base" memory specified with command line -# option -m. +# option -m. # -# @plugged-memory: size of memory that can be hot-unplugged. This field -# is omitted if target doesn't support memory hotplug -# (i.e. CONFIG_MEM_DEVICE not defined at build time). +# @plugged-memory: size of memory that can be hot-unplugged. This +# field is omitted if target doesn't support memory hotplug (i.e. +# CONFIG_MEM_DEVICE not defined at build time). # # Since: 2.11 ## @@ -1079,13 +1214,13 @@ ## # @query-memory-size-summary: # -# Return the amount of initially allocated and present hotpluggable (if -# enabled) memory in bytes. +# Return the amount of initially allocated and present hotpluggable +# (if enabled) memory in bytes. # # Example: # -# -> { "execute": "query-memory-size-summary" } -# <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } } +# -> { "execute": "query-memory-size-summary" } +# <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } } # # Since: 2.11 ## @@ -1110,7 +1245,8 @@ # # @hotplugged: true if device was hotplugged # -# @hotpluggable: true if device if could be added/removed while machine is running +# @hotpluggable: true if device if could be added/removed while +# machine is running # # Since: 2.1 ## @@ -1185,24 +1321,175 @@ } ## +# @SgxEPCDeviceInfo: +# +# Sgx EPC state information +# +# @id: device's ID +# +# @memaddr: physical address in memory, where device is mapped +# +# @size: size of memory that the device provides +# +# @memdev: memory backend linked with device +# +# @node: the numa node (Since: 7.0) +# +# Since: 6.2 +## +{ 'struct': 'SgxEPCDeviceInfo', + 'data': { '*id': 'str', + 'memaddr': 'size', + 'size': 'size', + 'node': 'int', + 'memdev': 'str' + } +} + +## +# @HvBalloonDeviceInfo: +# +# hv-balloon provided memory state information +# +# @id: device's ID +# +# @memaddr: physical address in memory, where device is mapped +# +# @max-size: the maximum size of memory that the device can provide +# +# @memdev: memory backend linked with device +# +# Since: 8.2 +## +{ 'struct': 'HvBalloonDeviceInfo', + 'data': { '*id': 'str', + '*memaddr': 'size', + 'max-size': 'size', + '*memdev': 'str' + } +} + +## +# @MemoryDeviceInfoKind: +# +# @nvdimm: since 2.12 +# +# @virtio-pmem: since 4.1 +# +# @virtio-mem: since 5.1 +# +# @sgx-epc: since 6.2. +# +# @hv-balloon: since 8.2. +# +# Since: 2.1 +## +{ 'enum': 'MemoryDeviceInfoKind', + 'data': [ 'dimm', 'nvdimm', 'virtio-pmem', 'virtio-mem', 'sgx-epc', + 'hv-balloon' ] } + +## +# @PCDIMMDeviceInfoWrapper: +# +# @data: PCDIMMDevice state information +# +# Since: 2.1 +## +{ 'struct': 'PCDIMMDeviceInfoWrapper', + 'data': { 'data': 'PCDIMMDeviceInfo' } } + +## +# @VirtioPMEMDeviceInfoWrapper: +# +# @data: VirtioPMEM state information +# +# Since: 2.1 +## +{ 'struct': 'VirtioPMEMDeviceInfoWrapper', + 'data': { 'data': 'VirtioPMEMDeviceInfo' } } + +## +# @VirtioMEMDeviceInfoWrapper: +# +# @data: VirtioMEMDevice state information +# +# Since: 2.1 +## +{ 'struct': 'VirtioMEMDeviceInfoWrapper', + 'data': { 'data': 'VirtioMEMDeviceInfo' } } + +## +# @SgxEPCDeviceInfoWrapper: +# +# @data: Sgx EPC state information +# +# Since: 6.2 +## +{ 'struct': 'SgxEPCDeviceInfoWrapper', + 'data': { 'data': 'SgxEPCDeviceInfo' } } + +## +# @HvBalloonDeviceInfoWrapper: +# +# @data: hv-balloon provided memory state information +# +# Since: 8.2 +## +{ 'struct': 'HvBalloonDeviceInfoWrapper', + 'data': { 'data': 'HvBalloonDeviceInfo' } } + +## # @MemoryDeviceInfo: # # Union containing information about a memory device # -# nvdimm is included since 2.12. virtio-pmem is included since 4.1. -# virtio-mem is included since 5.1. +# @type: memory device type # # Since: 2.1 ## { 'union': 'MemoryDeviceInfo', - 'data': { 'dimm': 'PCDIMMDeviceInfo', - 'nvdimm': 'PCDIMMDeviceInfo', - 'virtio-pmem': 'VirtioPMEMDeviceInfo', - 'virtio-mem': 'VirtioMEMDeviceInfo' + 'base': { 'type': 'MemoryDeviceInfoKind' }, + 'discriminator': 'type', + 'data': { 'dimm': 'PCDIMMDeviceInfoWrapper', + 'nvdimm': 'PCDIMMDeviceInfoWrapper', + 'virtio-pmem': 'VirtioPMEMDeviceInfoWrapper', + 'virtio-mem': 'VirtioMEMDeviceInfoWrapper', + 'sgx-epc': 'SgxEPCDeviceInfoWrapper', + 'hv-balloon': 'HvBalloonDeviceInfoWrapper' + } +} + +## +# @SgxEPC: +# +# Sgx EPC cmdline information +# +# @memdev: memory backend linked with device +# +# @node: the numa node (Since: 7.0) +# +# Since: 6.2 +## +{ 'struct': 'SgxEPC', + 'data': { 'memdev': 'str', + 'node': 'int' } } ## +# @SgxEPCProperties: +# +# SGX properties of machine types. +# +# @sgx-epc: list of ids of memory-backend-epc objects. +# +# Since: 6.2 +## +{ 'struct': 'SgxEPCProperties', + 'data': { 'sgx-epc': ['SgxEPC'] } +} + +## # @query-memory-devices: # # Lists available memory devices and their state @@ -1211,46 +1498,47 @@ # # Example: # -# -> { "execute": "query-memory-devices" } -# <- { "return": [ { "data": -# { "addr": 5368709120, -# "hotpluggable": true, -# "hotplugged": true, -# "id": "d1", -# "memdev": "/objects/memX", -# "node": 0, -# "size": 1073741824, -# "slot": 0}, -# "type": "dimm" -# } ] } -# +# -> { "execute": "query-memory-devices" } +# <- { "return": [ { "data": +# { "addr": 5368709120, +# "hotpluggable": true, +# "hotplugged": true, +# "id": "d1", +# "memdev": "/objects/memX", +# "node": 0, +# "size": 1073741824, +# "slot": 0}, +# "type": "dimm" +# } ] } ## { 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] } ## # @MEMORY_DEVICE_SIZE_CHANGE: # -# Emitted when the size of a memory device changes. Only emitted for memory -# devices that can actually change the size (e.g., virtio-mem due to guest -# action). +# Emitted when the size of a memory device changes. Only emitted for +# memory devices that can actually change the size (e.g., virtio-mem +# due to guest action). # # @id: device's ID +# # @size: the new size of memory that the device provides # +# @qom-path: path to the device object in the QOM tree (since 6.2) +# # Note: this event is rate-limited. # # Since: 5.1 # # Example: # -# <- { "event": "MEMORY_DEVICE_SIZE_CHANGE", -# "data": { "id": "vm0", "size": 1073741824}, -# "timestamp": { "seconds": 1588168529, "microseconds": 201316 } } -# +# <- { "event": "MEMORY_DEVICE_SIZE_CHANGE", +# "data": { "id": "vm0", "size": 1073741824, +# "qom-path": "/machine/unattached/device[2]" }, +# "timestamp": { "seconds": 1588168529, "microseconds": 201316 } } ## { 'event': 'MEMORY_DEVICE_SIZE_CHANGE', - 'data': { '*id': 'str', 'size': 'size' } } - + 'data': { '*id': 'str', 'size': 'size', 'qom-path' : 'str'} } ## # @MEM_UNPLUG_ERROR: @@ -1261,16 +1549,293 @@ # # @msg: Informative message # +# Features: +# +# @deprecated: This event is deprecated. Use +# @DEVICE_UNPLUG_GUEST_ERROR instead. +# # Since: 2.4 # # Example: # -# <- { "event": "MEM_UNPLUG_ERROR" -# "data": { "device": "dimm1", -# "msg": "acpi: device unplug for unsupported device" -# }, -# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } -# +# <- { "event": "MEM_UNPLUG_ERROR", +# "data": { "device": "dimm1", +# "msg": "acpi: device unplug for unsupported device" +# }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } ## { 'event': 'MEM_UNPLUG_ERROR', - 'data': { 'device': 'str', 'msg': 'str' } } + 'data': { 'device': 'str', 'msg': 'str' }, + 'features': ['deprecated'] } + +## +# @BootConfiguration: +# +# Schema for virtual machine boot configuration. +# +# @order: Boot order (a=floppy, c=hard disk, d=CD-ROM, n=network) +# +# @once: Boot order to apply on first boot +# +# @menu: Whether to show a boot menu +# +# @splash: The name of the file to be passed to the firmware as logo +# picture, if @menu is true. +# +# @splash-time: How long to show the logo picture, in milliseconds +# +# @reboot-timeout: Timeout before guest reboots after boot fails +# +# @strict: Whether to attempt booting from devices not included in the +# boot order +# +# Since: 7.1 +## +{ 'struct': 'BootConfiguration', 'data': { + '*order': 'str', + '*once': 'str', + '*menu': 'bool', + '*splash': 'str', + '*splash-time': 'int', + '*reboot-timeout': 'int', + '*strict': 'bool' } } + +## +# @SMPConfiguration: +# +# Schema for CPU topology configuration. A missing value lets QEMU +# figure out a suitable value based on the ones that are provided. +# +# The members other than @cpus and @maxcpus define a topology of +# containers. +# +# The ordering from highest/coarsest to lowest/finest is: +# @drawers, @books, @sockets, @dies, @clusters, @cores, @threads. +# +# Different architectures support different subsets of topology +# containers. +# +# For example, s390x does not have clusters and dies, and the socket +# is the parent container of cores. +# +# @cpus: number of virtual CPUs in the virtual machine +# +# @maxcpus: maximum number of hotpluggable virtual CPUs in the virtual +# machine +# +# @drawers: number of drawers in the CPU topology (since 8.2) +# +# @books: number of books in the CPU topology (since 8.2) +# +# @sockets: number of sockets per parent container +# +# @dies: number of dies per parent container +# +# @clusters: number of clusters per parent container (since 7.0) +# +# @cores: number of cores per parent container +# +# @threads: number of threads per core +# +# Since: 6.1 +## +{ 'struct': 'SMPConfiguration', 'data': { + '*cpus': 'int', + '*drawers': 'int', + '*books': 'int', + '*sockets': 'int', + '*dies': 'int', + '*clusters': 'int', + '*cores': 'int', + '*threads': 'int', + '*maxcpus': 'int' } } + +## +# @x-query-irq: +# +# Query interrupt statistics +# +# Features: +# +# @unstable: This command is meant for debugging. +# +# Returns: interrupt statistics +# +# Since: 6.2 +## +{ 'command': 'x-query-irq', + 'returns': 'HumanReadableText', + 'features': [ 'unstable' ] } + +## +# @x-query-jit: +# +# Query TCG compiler statistics +# +# Features: +# +# @unstable: This command is meant for debugging. +# +# Returns: TCG compiler statistics +# +# Since: 6.2 +## +{ 'command': 'x-query-jit', + 'returns': 'HumanReadableText', + 'if': 'CONFIG_TCG', + 'features': [ 'unstable' ] } + +## +# @x-query-numa: +# +# Query NUMA topology information +# +# Features: +# +# @unstable: This command is meant for debugging. +# +# Returns: topology information +# +# Since: 6.2 +## +{ 'command': 'x-query-numa', + 'returns': 'HumanReadableText', + 'features': [ 'unstable' ] } + +## +# @x-query-opcount: +# +# Query TCG opcode counters +# +# Features: +# +# @unstable: This command is meant for debugging. +# +# Returns: TCG opcode counters +# +# Since: 6.2 +## +{ 'command': 'x-query-opcount', + 'returns': 'HumanReadableText', + 'if': 'CONFIG_TCG', + 'features': [ 'unstable' ] } + +## +# @x-query-ramblock: +# +# Query system ramblock information +# +# Features: +# +# @unstable: This command is meant for debugging. +# +# Returns: system ramblock information +# +# Since: 6.2 +## +{ 'command': 'x-query-ramblock', + 'returns': 'HumanReadableText', + 'features': [ 'unstable' ] } + +## +# @x-query-rdma: +# +# Query RDMA state +# +# Features: +# +# @unstable: This command is meant for debugging. +# +# Returns: RDMA state +# +# Since: 6.2 +## +{ 'command': 'x-query-rdma', + 'returns': 'HumanReadableText', + 'features': [ 'unstable' ] } + +## +# @x-query-roms: +# +# Query information on the registered ROMS +# +# Features: +# +# @unstable: This command is meant for debugging. +# +# Returns: registered ROMs +# +# Since: 6.2 +## +{ 'command': 'x-query-roms', + 'returns': 'HumanReadableText', + 'features': [ 'unstable' ] } + +## +# @x-query-usb: +# +# Query information on the USB devices +# +# Features: +# +# @unstable: This command is meant for debugging. +# +# Returns: USB device information +# +# Since: 6.2 +## +{ 'command': 'x-query-usb', + 'returns': 'HumanReadableText', + 'features': [ 'unstable' ] } + +## +# @SmbiosEntryPointType: +# +# @32: SMBIOS version 2.1 (32-bit) Entry Point +# +# @64: SMBIOS version 3.0 (64-bit) Entry Point +# +# @auto: Either 2.x or 3.x SMBIOS version, 2.x if configuration can be +# described by it and 3.x otherwise (since: 9.0) +# +# Since: 7.0 +## +{ 'enum': 'SmbiosEntryPointType', + 'data': [ '32', '64', 'auto' ] } + +## +# @MemorySizeConfiguration: +# +# Schema for memory size configuration. +# +# @size: memory size in bytes +# +# @max-size: maximum hotpluggable memory size in bytes +# +# @slots: number of available memory slots for hotplug +# +# Since: 7.1 +## +{ 'struct': 'MemorySizeConfiguration', 'data': { + '*size': 'size', + '*max-size': 'size', + '*slots': 'uint64' } } + +## +# @dumpdtb: +# +# Save the FDT in dtb format. +# +# @filename: name of the dtb file to be created +# +# Since: 7.2 +# +# Example: +# +# -> { "execute": "dumpdtb" } +# "arguments": { "filename": "fdt.dtb" } } +# <- { "return": {} } +## +{ 'command': 'dumpdtb', + 'data': { 'filename': 'str' }, + 'if': 'CONFIG_FDT' } diff --git a/qapi/meson.build b/qapi/meson.build index 376f4ceafe..375d564277 100644 --- a/qapi/meson.build +++ b/qapi/meson.build @@ -2,6 +2,7 @@ util_ss.add(files( 'opts-visitor.c', 'qapi-clone-visitor.c', 'qapi-dealloc-visitor.c', + 'qapi-forward-visitor.c', 'qapi-util.c', 'qapi-visit-core.c', 'qobject-input-visitor.c', @@ -9,7 +10,10 @@ util_ss.add(files( 'string-input-visitor.c', 'string-output-visitor.c', )) -if have_system or have_tools +if have_system + util_ss.add(files('qapi-type-helpers.c')) +endif +if have_system or have_tools or have_ga util_ss.add(files( 'qmp-dispatch.c', 'qmp-event.c', @@ -27,10 +31,13 @@ qapi_all_modules = [ 'compat', 'control', 'crypto', + 'cxl', 'dump', + 'ebpf', 'error', 'introspect', 'job', + 'machine-common', 'machine', 'machine-target', 'migration', @@ -42,14 +49,17 @@ qapi_all_modules = [ 'replay', 'run-state', 'sockets', + 'stats', 'trace', 'transaction', + 'virtio', 'yank', ] if have_system qapi_all_modules += [ 'acpi', 'audio', + 'cryptodev', 'qdev', 'pci', 'rdma', @@ -63,21 +73,6 @@ if have_system or have_tools ] endif -qapi_storage_daemon_modules = [ - 'block-core', - 'block-export', - 'char', - 'common', - 'control', - 'crypto', - 'introspect', - 'job', - 'qom', - 'sockets', - 'pragma', - 'transaction', -] - qapi_nonmodule_outputs = [ 'qapi-introspect.c', 'qapi-introspect.h', 'qapi-types.c', 'qapi-types.h', @@ -110,6 +105,7 @@ foreach module : qapi_all_modules 'qapi-events-@0@.h'.format(module), 'qapi-commands-@0@.c'.format(module), 'qapi-commands-@0@.h'.format(module), + 'qapi-commands-@0@.trace-events'.format(module), ] endif if module.endswith('-target') @@ -133,6 +129,9 @@ foreach output : qapi_util_outputs if output.endswith('.h') genh += qapi_files[i] endif + if output.endswith('.trace-events') + qapi_trace_events += qapi_files[i] + endif util_ss.add(qapi_files[i]) i = i + 1 endforeach @@ -141,6 +140,9 @@ foreach output : qapi_specific_outputs + qapi_nonmodule_outputs if output.endswith('.h') genh += qapi_files[i] endif - specific_ss.add(when: 'CONFIG_SOFTMMU', if_true: qapi_files[i]) + if output.endswith('.trace-events') + qapi_trace_events += qapi_files[i] + endif + specific_ss.add(when: 'CONFIG_SYSTEM_ONLY', if_true: qapi_files[i]) i = i + 1 endforeach diff --git a/qapi/migration.json b/qapi/migration.json index 0b17cce46b..8c65b90328 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -16,45 +16,71 @@ # # @transferred: amount of bytes already transferred to the target VM # -# @remaining: amount of bytes remaining to be transferred to the target VM +# @remaining: amount of bytes remaining to be transferred to the +# target VM # # @total: total amount of bytes involved in the migration process # # @duplicate: number of duplicate (zero) pages (since 1.2) # -# @skipped: number of skipped zero pages (since 1.5) +# @skipped: number of skipped zero pages. Always zero, only provided +# for compatibility (since 1.5) # # @normal: number of normal pages (since 1.2) # # @normal-bytes: number of normal bytes sent (since 1.2) # -# @dirty-pages-rate: number of pages dirtied by second by the -# guest (since 1.3) +# @dirty-pages-rate: number of pages dirtied by second by the guest +# (since 1.3) # -# @mbps: throughput in megabits/sec. (since 1.6) +# @mbps: throughput in megabits/sec. (since 1.6) # -# @dirty-sync-count: number of times that dirty ram was synchronized (since 2.1) +# @dirty-sync-count: number of times that dirty ram was synchronized +# (since 2.1) # -# @postcopy-requests: The number of page requests received from the destination -# (since 2.7) +# @postcopy-requests: The number of page requests received from the +# destination (since 2.7) # # @page-size: The number of bytes per page for the various page-based -# statistics (since 2.10) +# statistics (since 2.10) # # @multifd-bytes: The number of bytes sent through multifd (since 3.0) # # @pages-per-second: the number of memory pages transferred per second -# (Since 4.0) +# (Since 4.0) +# +# @precopy-bytes: The number of bytes sent in the pre-copy phase +# (since 7.0). +# +# @downtime-bytes: The number of bytes sent while the guest is paused +# (since 7.0). +# +# @postcopy-bytes: The number of bytes sent during the post-copy phase +# (since 7.0). +# +# @dirty-sync-missed-zero-copy: Number of times dirty RAM +# synchronization could not avoid copying dirty pages. This is +# between 0 and @dirty-sync-count * @multifd-channels. (since +# 7.1) +# +# Features: +# +# @deprecated: Member @skipped is always zero since 1.5.3 # # Since: 0.14 ## { 'struct': 'MigrationStats', 'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' , - 'duplicate': 'int', 'skipped': 'int', 'normal': 'int', - 'normal-bytes': 'int', 'dirty-pages-rate' : 'int', - 'mbps' : 'number', 'dirty-sync-count' : 'int', - 'postcopy-requests' : 'int', 'page-size' : 'int', - 'multifd-bytes' : 'uint64', 'pages-per-second' : 'uint64' } } + 'duplicate': 'int', + 'skipped': { 'type': 'int', 'features': [ 'deprecated' ] }, + 'normal': 'int', + 'normal-bytes': 'int', 'dirty-pages-rate': 'int', + 'mbps': 'number', 'dirty-sync-count': 'int', + 'postcopy-requests': 'int', 'page-size': 'int', + 'multifd-bytes': 'uint64', 'pages-per-second': 'uint64', + 'precopy-bytes': 'uint64', 'downtime-bytes': 'uint64', + 'postcopy-bytes': 'uint64', + 'dirty-sync-missed-zero-copy': 'uint64' } } ## # @XBZRLECacheStats: @@ -89,7 +115,8 @@ # # @pages: amount of pages compressed and transferred to the target VM # -# @busy: count of times that no free thread was available to compress data +# @busy: count of times that no free thread was available to compress +# data # # @busy-rate: rate of thread busy # @@ -118,29 +145,31 @@ # # @active: in the process of doing migration. # -# @postcopy-active: like active, but now in postcopy mode. (since 2.5) +# @postcopy-active: like active, but now in postcopy mode. (since +# 2.5) # -# @postcopy-paused: during postcopy but paused. (since 3.0) +# @postcopy-paused: during postcopy but paused. (since 3.0) # -# @postcopy-recover: trying to recover from a paused postcopy. (since 3.0) +# @postcopy-recover: trying to recover from a paused postcopy. (since +# 3.0) # # @completed: migration is finished. # # @failed: some error occurred during migration process. # -# @colo: VM is in the process of fault tolerance, VM can not get into this -# state unless colo capability is enabled for migration. (since 2.8) +# @colo: VM is in the process of fault tolerance, VM can not get into +# this state unless colo capability is enabled for migration. +# (since 2.8) # -# @pre-switchover: Paused before device serialisation. (since 2.11) +# @pre-switchover: Paused before device serialisation. (since 2.11) # -# @device: During device serialisation when pause-before-switchover is enabled -# (since 2.11) +# @device: During device serialisation when pause-before-switchover is +# enabled (since 2.11) # -# @wait-unplug: wait for device unplug request by guest OS to be completed. -# (since 4.2) +# @wait-unplug: wait for device unplug request by guest OS to be +# completed. (since 4.2) # # Since: 2.3 -# ## { 'enum': 'MigrationStatus', 'data': [ 'none', 'setup', 'cancelling', 'cancelled', @@ -152,10 +181,10 @@ # # Detailed VFIO devices migration statistics # -# @transferred: amount of bytes transferred to the target VM by VFIO devices +# @transferred: amount of bytes transferred to the target VM by VFIO +# devices # # Since: 5.2 -# ## { 'struct': 'VfioStats', 'data': {'transferred': 'int' } } @@ -166,78 +195,92 @@ # Information about current migration process. # # @status: @MigrationStatus describing the current migration status. -# If this field is not returned, no migration process -# has been initiated +# If this field is not returned, no migration process has been +# initiated # -# @ram: @MigrationStats containing detailed migration -# status, only returned if status is 'active' or -# 'completed'(since 1.2) +# @ram: @MigrationStats containing detailed migration status, only +# returned if status is 'active' or 'completed'(since 1.2) # -# @disk: @MigrationStats containing detailed disk migration -# status, only returned if status is 'active' and it is a block -# migration +# @disk: @MigrationStats containing detailed disk migration status, +# only returned if status is 'active' and it is a block migration # # @xbzrle-cache: @XBZRLECacheStats containing detailed XBZRLE -# migration statistics, only returned if XBZRLE feature is on and -# status is 'active' or 'completed' (since 1.2) +# migration statistics, only returned if XBZRLE feature is on and +# status is 'active' or 'completed' (since 1.2) # # @total-time: total amount of milliseconds since migration started. -# If migration has ended, it returns the total migration -# time. (since 1.2) +# If migration has ended, it returns the total migration time. +# (since 1.2) # -# @downtime: only present when migration finishes correctly -# total downtime in milliseconds for the guest. -# (since 1.3) +# @downtime: only present when migration finishes correctly total +# downtime in milliseconds for the guest. (since 1.3) # -# @expected-downtime: only present while migration is active -# expected downtime in milliseconds for the guest in last walk -# of the dirty bitmap. (since 1.3) +# @expected-downtime: only present while migration is active expected +# downtime in milliseconds for the guest in last walk of the dirty +# bitmap. (since 1.3) # # @setup-time: amount of setup time in milliseconds *before* the -# iterations begin but *after* the QMP command is issued. This is designed -# to provide an accounting of any activities (such as RDMA pinning) which -# may be expensive, but do not actually occur during the iterative -# migration rounds themselves. (since 1.6) +# iterations begin but *after* the QMP command is issued. This is +# designed to provide an accounting of any activities (such as +# RDMA pinning) which may be expensive, but do not actually occur +# during the iterative migration rounds themselves. (since 1.6) # # @cpu-throttle-percentage: percentage of time guest cpus are being -# throttled during auto-converge. This is only present when auto-converge -# has started throttling guest cpus. (Since 2.7) +# throttled during auto-converge. This is only present when +# auto-converge has started throttling guest cpus. (Since 2.7) # -# @error-desc: the human readable error description string, when -# @status is 'failed'. Clients should not attempt to parse the -# error strings. (Since 2.7) +# @error-desc: the human readable error description string. Clients +# should not attempt to parse the error strings. (Since 2.7) # -# @postcopy-blocktime: total time when all vCPU were blocked during postcopy -# live migration. This is only present when the postcopy-blocktime -# migration capability is enabled. (Since 3.0) +# @postcopy-blocktime: total time when all vCPU were blocked during +# postcopy live migration. This is only present when the +# postcopy-blocktime migration capability is enabled. (Since 3.0) # -# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. This is -# only present when the postcopy-blocktime migration capability -# is enabled. (Since 3.0) +# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. +# This is only present when the postcopy-blocktime migration +# capability is enabled. (Since 3.0) # -# @compression: migration compression statistics, only returned if compression -# feature is on and status is 'active' or 'completed' (Since 3.1) +# @compression: migration compression statistics, only returned if +# compression feature is on and status is 'active' or 'completed' +# (Since 3.1) # -# @socket-address: Only used for tcp, to know what the real port is (Since 4.0) +# @socket-address: Only used for tcp, to know what the real port is +# (Since 4.0) # -# @vfio: @VfioStats containing detailed VFIO devices migration statistics, -# only returned if VFIO device is present, migration is supported by all -# VFIO devices and status is 'active' or 'completed' (since 5.2) +# @vfio: @VfioStats containing detailed VFIO devices migration +# statistics, only returned if VFIO device is present, migration +# is supported by all VFIO devices and status is 'active' or +# 'completed' (since 5.2) # -# @blocked-reasons: A list of reasons an outgoing migration is blocked. -# Present and non-empty when migration is blocked. -# (since 6.0) +# @blocked-reasons: A list of reasons an outgoing migration is +# blocked. Present and non-empty when migration is blocked. +# (since 6.0) # -# @blocked: True if outgoing migration is blocked (since 6.0) +# @dirty-limit-throttle-time-per-round: Maximum throttle time +# (in microseconds) of virtual CPUs each dirty ring full round, +# which shows how MigrationCapability dirty-limit affects the +# guest during live migration. (Since 8.1) +# +# @dirty-limit-ring-full-time: Estimated average dirty ring full time +# (in microseconds) for each dirty ring full round. The value +# equals the dirty ring memory size divided by the average dirty +# page rate of the virtual CPU, which can be used to observe the +# average memory load of the virtual CPU indirectly. Note that +# zero means guest doesn't dirty memory. (Since 8.1) # # Features: -# @deprecated: Member @blocked is deprecated. Use @blocked-reasons instead. +# +# @deprecated: Member @disk is deprecated because block migration is. +# Member @compression is deprecated because it is unreliable and +# untested. It is recommended to use multifd migration, which +# offers an alternative compression implementation that is +# reliable and tested. # # Since: 0.14 ## { 'struct': 'MigrationInfo', 'data': {'*status': 'MigrationStatus', '*ram': 'MigrationStats', - '*disk': 'MigrationStats', + '*disk': { 'type': 'MigrationStats', 'features': [ 'deprecated' ] }, '*vfio': 'VfioStats', '*xbzrle-cache': 'XBZRLECacheStats', '*total-time': 'int', @@ -246,17 +289,18 @@ '*setup-time': 'int', '*cpu-throttle-percentage': 'int', '*error-desc': 'str', - 'blocked': { 'type': 'bool', 'features': [ 'deprecated' ] }, '*blocked-reasons': ['str'], - '*postcopy-blocktime' : 'uint32', + '*postcopy-blocktime': 'uint32', '*postcopy-vcpu-blocktime': ['uint32'], - '*compression': 'CompressionStats', - '*socket-address': ['SocketAddress'] } } + '*compression': { 'type': 'CompressionStats', 'features': [ 'deprecated' ] }, + '*socket-address': ['SocketAddress'], + '*dirty-limit-throttle-time-per-round': 'uint64', + '*dirty-limit-ring-full-time': 'uint64'} } ## # @query-migrate: # -# Returns information about current migration process. If migration +# Returns information about current migration process. If migration # is active there will be another json-object with RAM migration # status and if block migration is active another one with block # migration status. @@ -265,115 +309,114 @@ # # Since: 0.14 # -# Example: -# -# 1. Before the first migration -# -# -> { "execute": "query-migrate" } -# <- { "return": {} } -# -# 2. Migration is done and has succeeded -# -# -> { "execute": "query-migrate" } -# <- { "return": { -# "status": "completed", -# "total-time":12345, -# "setup-time":12345, -# "downtime":12345, -# "ram":{ -# "transferred":123, -# "remaining":123, -# "total":246, -# "duplicate":123, -# "normal":123, -# "normal-bytes":123456, -# "dirty-sync-count":15 -# } -# } -# } -# -# 3. Migration is done and has failed -# -# -> { "execute": "query-migrate" } -# <- { "return": { "status": "failed" } } -# -# 4. Migration is being performed and is not a block migration: -# -# -> { "execute": "query-migrate" } -# <- { -# "return":{ -# "status":"active", -# "total-time":12345, -# "setup-time":12345, -# "expected-downtime":12345, -# "ram":{ -# "transferred":123, -# "remaining":123, -# "total":246, -# "duplicate":123, -# "normal":123, -# "normal-bytes":123456, -# "dirty-sync-count":15 +# Examples: +# +# 1. Before the first migration +# +# -> { "execute": "query-migrate" } +# <- { "return": {} } +# +# 2. Migration is done and has succeeded +# +# -> { "execute": "query-migrate" } +# <- { "return": { +# "status": "completed", +# "total-time":12345, +# "setup-time":12345, +# "downtime":12345, +# "ram":{ +# "transferred":123, +# "remaining":123, +# "total":246, +# "duplicate":123, +# "normal":123, +# "normal-bytes":123456, +# "dirty-sync-count":15 +# } # } -# } -# } -# -# 5. Migration is being performed and is a block migration: -# -# -> { "execute": "query-migrate" } -# <- { -# "return":{ -# "status":"active", -# "total-time":12345, -# "setup-time":12345, -# "expected-downtime":12345, -# "ram":{ -# "total":1057024, -# "remaining":1053304, -# "transferred":3720, -# "duplicate":123, -# "normal":123, -# "normal-bytes":123456, -# "dirty-sync-count":15 -# }, -# "disk":{ -# "total":20971520, -# "remaining":20880384, -# "transferred":91136 -# } -# } -# } -# -# 6. Migration is being performed and XBZRLE is active: -# -# -> { "execute": "query-migrate" } -# <- { -# "return":{ -# "status":"active", -# "total-time":12345, -# "setup-time":12345, -# "expected-downtime":12345, -# "ram":{ -# "total":1057024, -# "remaining":1053304, -# "transferred":3720, -# "duplicate":10, -# "normal":3333, -# "normal-bytes":3412992, -# "dirty-sync-count":15 -# }, -# "xbzrle-cache":{ -# "cache-size":67108864, -# "bytes":20971520, -# "pages":2444343, -# "cache-miss":2244, -# "cache-miss-rate":0.123, -# "encoding-rate":80.1, -# "overflow":34434 -# } -# } -# } -# +# } +# +# 3. Migration is done and has failed +# +# -> { "execute": "query-migrate" } +# <- { "return": { "status": "failed" } } +# +# 4. Migration is being performed and is not a block migration: +# +# -> { "execute": "query-migrate" } +# <- { +# "return":{ +# "status":"active", +# "total-time":12345, +# "setup-time":12345, +# "expected-downtime":12345, +# "ram":{ +# "transferred":123, +# "remaining":123, +# "total":246, +# "duplicate":123, +# "normal":123, +# "normal-bytes":123456, +# "dirty-sync-count":15 +# } +# } +# } +# +# 5. Migration is being performed and is a block migration: +# +# -> { "execute": "query-migrate" } +# <- { +# "return":{ +# "status":"active", +# "total-time":12345, +# "setup-time":12345, +# "expected-downtime":12345, +# "ram":{ +# "total":1057024, +# "remaining":1053304, +# "transferred":3720, +# "duplicate":123, +# "normal":123, +# "normal-bytes":123456, +# "dirty-sync-count":15 +# }, +# "disk":{ +# "total":20971520, +# "remaining":20880384, +# "transferred":91136 +# } +# } +# } +# +# 6. Migration is being performed and XBZRLE is active: +# +# -> { "execute": "query-migrate" } +# <- { +# "return":{ +# "status":"active", +# "total-time":12345, +# "setup-time":12345, +# "expected-downtime":12345, +# "ram":{ +# "total":1057024, +# "remaining":1053304, +# "transferred":3720, +# "duplicate":10, +# "normal":3333, +# "normal-bytes":3412992, +# "dirty-sync-count":15 +# }, +# "xbzrle-cache":{ +# "cache-size":67108864, +# "bytes":20971520, +# "pages":2444343, +# "cache-miss":2244, +# "cache-miss-rate":0.123, +# "encoding-rate":80.1, +# "overflow":34434 +# } +# } +# } ## { 'command': 'query-migrate', 'returns': 'MigrationInfo' } @@ -382,90 +425,140 @@ # # Migration capabilities enumeration # -# @xbzrle: Migration supports xbzrle (Xor Based Zero Run Length Encoding). -# This feature allows us to minimize migration traffic for certain work -# loads, by sending compressed difference of the pages -# -# @rdma-pin-all: Controls whether or not the entire VM memory footprint is -# mlock()'d on demand or all at once. Refer to docs/rdma.txt for usage. -# Disabled by default. (since 2.0) -# -# @zero-blocks: During storage migration encode blocks of zeroes efficiently. This -# essentially saves 1MB of zeroes per block on the wire. Enabling requires -# source and target VM to support this feature. To enable it is sufficient -# to enable the capability on the source VM. The feature is disabled by -# default. (since 1.6) -# -# @compress: Use multiple compression threads to accelerate live migration. -# This feature can help to reduce the migration traffic, by sending -# compressed pages. Please note that if compress and xbzrle are both -# on, compress only takes effect in the ram bulk stage, after that, -# it will be disabled and only xbzrle takes effect, this can help to -# minimize migration traffic. The feature is disabled by default. -# (since 2.4 ) -# -# @events: generate events for each migration state change -# (since 2.4 ) -# -# @auto-converge: If enabled, QEMU will automatically throttle down the guest -# to speed up convergence of RAM migration. (since 1.6) -# -# @postcopy-ram: Start executing on the migration target before all of RAM has -# been migrated, pulling the remaining pages along as needed. The -# capacity must have the same setting on both source and target -# or migration will not even start. NOTE: If the migration fails during -# postcopy the VM will fail. (since 2.6) -# -# @x-colo: If enabled, migration will never end, and the state of the VM on the -# primary side will be migrated continuously to the VM on secondary -# side, this process is called COarse-Grain LOck Stepping (COLO) for -# Non-stop Service. (since 2.8) -# -# @release-ram: if enabled, qemu will free the migrated ram pages on the source -# during postcopy-ram migration. (since 2.9) +# @xbzrle: Migration supports xbzrle (Xor Based Zero Run Length +# Encoding). This feature allows us to minimize migration traffic +# for certain work loads, by sending compressed difference of the +# pages +# +# @rdma-pin-all: Controls whether or not the entire VM memory +# footprint is mlock()'d on demand or all at once. Refer to +# docs/rdma.txt for usage. Disabled by default. (since 2.0) +# +# @zero-blocks: During storage migration encode blocks of zeroes +# efficiently. This essentially saves 1MB of zeroes per block on +# the wire. Enabling requires source and target VM to support +# this feature. To enable it is sufficient to enable the +# capability on the source VM. The feature is disabled by default. +# (since 1.6) +# +# @compress: Use multiple compression threads to accelerate live +# migration. This feature can help to reduce the migration +# traffic, by sending compressed pages. Please note that if +# compress and xbzrle are both on, compress only takes effect in +# the ram bulk stage, after that, it will be disabled and only +# xbzrle takes effect, this can help to minimize migration +# traffic. The feature is disabled by default. (since 2.4) +# +# @events: generate events for each migration state change (since 2.4) +# +# @auto-converge: If enabled, QEMU will automatically throttle down +# the guest to speed up convergence of RAM migration. (since 1.6) +# +# @postcopy-ram: Start executing on the migration target before all of +# RAM has been migrated, pulling the remaining pages along as +# needed. The capacity must have the same setting on both source +# and target or migration will not even start. NOTE: If the +# migration fails during postcopy the VM will fail. (since 2.6) +# +# @x-colo: If enabled, migration will never end, and the state of the +# VM on the primary side will be migrated continuously to the VM +# on secondary side, this process is called COarse-Grain LOck +# Stepping (COLO) for Non-stop Service. (since 2.8) +# +# @release-ram: if enabled, qemu will free the migrated ram pages on +# the source during postcopy-ram migration. (since 2.9) # # @block: If enabled, QEMU will also migrate the contents of all block -# devices. Default is disabled. A possible alternative uses -# mirror jobs to a builtin NBD server on the destination, which -# offers more flexibility. -# (Since 2.10) +# devices. Default is disabled. A possible alternative uses +# mirror jobs to a builtin NBD server on the destination, which +# offers more flexibility. (Since 2.10) # # @return-path: If enabled, migration will use the return path even -# for precopy. (since 2.10) +# for precopy. (since 2.10) # -# @pause-before-switchover: Pause outgoing migration before serialising device -# state and before disabling block IO (since 2.11) +# @pause-before-switchover: Pause outgoing migration before +# serialising device state and before disabling block IO (since +# 2.11) # # @multifd: Use more than one fd for migration (since 4.0) # # @dirty-bitmaps: If enabled, QEMU will migrate named dirty bitmaps. -# (since 2.12) +# (since 2.12) # # @postcopy-blocktime: Calculate downtime for postcopy live migration -# (since 3.0) +# (since 3.0) # -# @late-block-activate: If enabled, the destination will not activate block -# devices (and thus take locks) immediately at the end of migration. -# (since 3.0) +# @late-block-activate: If enabled, the destination will not activate +# block devices (and thus take locks) immediately at the end of +# migration. (since 3.0) # -# @x-ignore-shared: If enabled, QEMU will not migrate shared memory (since 4.0) +# @x-ignore-shared: If enabled, QEMU will not migrate shared memory +# that is accessible on the destination machine. (since 4.0) # # @validate-uuid: Send the UUID of the source to allow the destination -# to ensure it is the same. (since 4.2) +# to ensure it is the same. (since 4.2) +# +# @background-snapshot: If enabled, the migration stream will be a +# snapshot of the VM exactly at the point when the migration +# procedure starts. The VM RAM is saved with running VM. +# (since 6.0) +# +# @zero-copy-send: Controls behavior on sending memory pages on +# migration. When true, enables a zero-copy mechanism for sending +# memory pages, if host supports it. Requires that QEMU be +# permitted to use locked memory for guest RAM pages. (since 7.1) +# +# @postcopy-preempt: If enabled, the migration process will allow +# postcopy requests to preempt precopy stream, so postcopy +# requests will be handled faster. This is a performance feature +# and should not affect the correctness of postcopy migration. +# (since 7.1) +# +# @switchover-ack: If enabled, migration will not stop the source VM +# and complete the migration until an ACK is received from the +# destination that it's OK to do so. Exactly when this ACK is +# sent depends on the migrated devices that use this feature. For +# example, a device can use it to make sure some of its data is +# sent and loaded in the destination before doing switchover. +# This can reduce downtime if devices that support this capability +# are present. 'return-path' capability must be enabled to use +# it. (since 8.1) +# +# @dirty-limit: If enabled, migration will throttle vCPUs as needed to +# keep their dirty page rate within @vcpu-dirty-limit. This can +# improve responsiveness of large guests during live migration, +# and can result in more stable read performance. Requires KVM +# with accelerator property "dirty-ring-size" set. (Since 8.1) +# +# @mapped-ram: Migrate using fixed offsets in the migration file for +# each RAM page. Requires a migration URI that supports seeking, +# such as a file. (since 9.0) +# +# Features: +# +# @deprecated: Member @block is deprecated. Use blockdev-mirror with +# NBD instead. Member @compress is deprecated because it is +# unreliable and untested. It is recommended to use multifd +# migration, which offers an alternative compression +# implementation that is reliable and tested. # -# @background-snapshot: If enabled, the migration stream will be a snapshot -# of the VM exactly at the point when the migration -# procedure starts. The VM RAM is saved with running VM. -# (since 6.0) +# @unstable: Members @x-colo and @x-ignore-shared are experimental. # # Since: 1.2 ## { 'enum': 'MigrationCapability', 'data': ['xbzrle', 'rdma-pin-all', 'auto-converge', 'zero-blocks', - 'compress', 'events', 'postcopy-ram', 'x-colo', 'release-ram', - 'block', 'return-path', 'pause-before-switchover', 'multifd', + { 'name': 'compress', 'features': [ 'deprecated' ] }, + 'events', 'postcopy-ram', + { 'name': 'x-colo', 'features': [ 'unstable' ] }, + 'release-ram', + { 'name': 'block', 'features': [ 'deprecated' ] }, + 'return-path', 'pause-before-switchover', 'multifd', 'dirty-bitmaps', 'postcopy-blocktime', 'late-block-activate', - 'x-ignore-shared', 'validate-uuid', 'background-snapshot'] } + { 'name': 'x-ignore-shared', 'features': [ 'unstable' ] }, + 'validate-uuid', 'background-snapshot', + 'zero-copy-send', 'postcopy-preempt', 'switchover-ack', + 'dirty-limit', 'mapped-ram'] } ## # @MigrationCapabilityStatus: @@ -479,7 +572,7 @@ # Since: 1.2 ## { 'struct': 'MigrationCapabilityStatus', - 'data': { 'capability' : 'MigrationCapability', 'state' : 'bool' } } + 'data': { 'capability': 'MigrationCapability', 'state': 'bool' } } ## # @migrate-set-capabilities: @@ -492,9 +585,9 @@ # # Example: # -# -> { "execute": "migrate-set-capabilities" , "arguments": -# { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } -# +# -> { "execute": "migrate-set-capabilities" , "arguments": +# { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } +# <- { "return": {} } ## { 'command': 'migrate-set-capabilities', 'data': { 'capabilities': ['MigrationCapabilityStatus'] } } @@ -504,24 +597,23 @@ # # Returns information about the current migration capabilities status # -# Returns: @MigrationCapabilitiesStatus +# Returns: @MigrationCapabilityStatus # # Since: 1.2 # # Example: # -# -> { "execute": "query-migrate-capabilities" } -# <- { "return": [ -# {"state": false, "capability": "xbzrle"}, -# {"state": false, "capability": "rdma-pin-all"}, -# {"state": false, "capability": "auto-converge"}, -# {"state": false, "capability": "zero-blocks"}, -# {"state": false, "capability": "compress"}, -# {"state": true, "capability": "events"}, -# {"state": false, "capability": "postcopy-ram"}, -# {"state": false, "capability": "x-colo"} -# ]} -# +# -> { "execute": "query-migrate-capabilities" } +# <- { "return": [ +# {"state": false, "capability": "xbzrle"}, +# {"state": false, "capability": "rdma-pin-all"}, +# {"state": false, "capability": "auto-converge"}, +# {"state": false, "capability": "zero-blocks"}, +# {"state": false, "capability": "compress"}, +# {"state": true, "capability": "events"}, +# {"state": false, "capability": "postcopy-ram"}, +# {"state": false, "capability": "x-colo"} +# ]} ## { 'command': 'query-migrate-capabilities', 'returns': ['MigrationCapabilityStatus']} @@ -531,21 +623,73 @@ # An enumeration of multifd compression methods. # # @none: no compression. +# # @zlib: use zlib compression method. +# # @zstd: use zstd compression method. # # Since: 5.0 -# ## { 'enum': 'MultiFDCompression', 'data': [ 'none', 'zlib', - { 'name': 'zstd', 'if': 'defined(CONFIG_ZSTD)' } ] } + { 'name': 'zstd', 'if': 'CONFIG_ZSTD' } ] } + +## +# @MigMode: +# +# @normal: the original form of migration. (since 8.2) +# +# @cpr-reboot: The migrate command stops the VM and saves state to the +# URI. After quitting QEMU, the user resumes by running QEMU +# -incoming. +# +# This mode allows the user to quit QEMU, optionally update and +# reboot the OS, and restart QEMU. If the user reboots, the URI +# must persist across the reboot, such as by using a file. +# +# Unlike normal mode, the use of certain local storage options +# does not block the migration, but the user must not modify the +# contents of guest block devices between the quit and restart. +# +# This mode supports VFIO devices provided the user first puts the +# guest in the suspended runstate, such as by issuing +# guest-suspend-ram to the QEMU guest agent. +# +# Best performance is achieved when the memory backend is shared +# and the @x-ignore-shared migration capability is set, but this +# is not required. Further, if the user reboots before restarting +# such a configuration, the shared memory must persist across the +# reboot, such as by backing it with a dax device. +# +# @cpr-reboot may not be used with postcopy, background-snapshot, +# or COLO. +# +# (since 8.2) +## +{ 'enum': 'MigMode', + 'data': [ 'normal', 'cpr-reboot' ] } + +## +# @ZeroPageDetection: +# +# @none: Do not perform zero page checking. +# +# @legacy: Perform zero page checking in main migration thread. +# +# @multifd: Perform zero page checking in multifd sender thread if +# multifd migration is enabled, else in the main migration thread +# as for @legacy. +# +# Since: 9.0 +## +{ 'enum': 'ZeroPageDetection', + 'data': [ 'none', 'legacy', 'multifd' ] } ## # @BitmapMigrationBitmapAliasTransform: # -# @persistent: If present, the bitmap will be made persistent -# or transient depending on this parameter. +# @persistent: If present, the bitmap will be made persistent or +# transient depending on this parameter. # # Since: 6.0 ## @@ -560,10 +704,10 @@ # @name: The name of the bitmap. # # @alias: An alias name for migration (for example the bitmap name on -# the opposite site). +# the opposite site). # -# @transform: Allows the modification of the migrated bitmap. -# (since 6.0) +# @transform: Allows the modification of the migrated bitmap. (since +# 6.0) # # Since: 5.2 ## @@ -582,8 +726,8 @@ # # @node-name: A block node name. # -# @alias: An alias block node name for migration (for example the -# node name on the opposite site). +# @alias: An alias block node name for migration (for example the node +# name on the opposite site). # # @bitmaps: Mappings for the bitmaps on this node. # @@ -601,327 +745,411 @@ # # Migration parameters enumeration # -# @announce-initial: Initial delay (in milliseconds) before sending the first -# announce (Since 4.0) +# @announce-initial: Initial delay (in milliseconds) before sending +# the first announce (Since 4.0) # -# @announce-max: Maximum delay (in milliseconds) between packets in the -# announcement (Since 4.0) +# @announce-max: Maximum delay (in milliseconds) between packets in +# the announcement (Since 4.0) # -# @announce-rounds: Number of self-announce packets sent after migration -# (Since 4.0) +# @announce-rounds: Number of self-announce packets sent after +# migration (Since 4.0) # -# @announce-step: Increase in delay (in milliseconds) between subsequent -# packets in the announcement (Since 4.0) +# @announce-step: Increase in delay (in milliseconds) between +# subsequent packets in the announcement (Since 4.0) # -# @compress-level: Set the compression level to be used in live migration, -# the compression level is an integer between 0 and 9, where 0 means -# no compression, 1 means the best compression speed, and 9 means best -# compression ratio which will consume more CPU. +# @compress-level: Set the compression level to be used in live +# migration, the compression level is an integer between 0 and 9, +# where 0 means no compression, 1 means the best compression +# speed, and 9 means best compression ratio which will consume +# more CPU. # -# @compress-threads: Set compression thread count to be used in live migration, -# the compression thread count is an integer between 1 and 255. +# @compress-threads: Set compression thread count to be used in live +# migration, the compression thread count is an integer between 1 +# and 255. # -# @compress-wait-thread: Controls behavior when all compression threads are -# currently busy. If true (default), wait for a free -# compression thread to become available; otherwise, -# send the page uncompressed. (Since 3.1) +# @compress-wait-thread: Controls behavior when all compression +# threads are currently busy. If true (default), wait for a free +# compression thread to become available; otherwise, send the page +# uncompressed. (Since 3.1) # -# @decompress-threads: Set decompression thread count to be used in live -# migration, the decompression thread count is an integer between 1 -# and 255. Usually, decompression is at least 4 times as fast as -# compression, so set the decompress-threads to the number about 1/4 -# of compress-threads is adequate. +# @decompress-threads: Set decompression thread count to be used in +# live migration, the decompression thread count is an integer +# between 1 and 255. Usually, decompression is at least 4 times as +# fast as compression, so set the decompress-threads to the number +# about 1/4 of compress-threads is adequate. # -# @throttle-trigger-threshold: The ratio of bytes_dirty_period and bytes_xfer_period -# to trigger throttling. It is expressed as percentage. -# The default value is 50. (Since 5.0) +# @throttle-trigger-threshold: The ratio of bytes_dirty_period and +# bytes_xfer_period to trigger throttling. It is expressed as +# percentage. The default value is 50. (Since 5.0) # -# @cpu-throttle-initial: Initial percentage of time guest cpus are throttled -# when migration auto-converge is activated. The -# default value is 20. (Since 2.7) +# @cpu-throttle-initial: Initial percentage of time guest cpus are +# throttled when migration auto-converge is activated. The +# default value is 20. (Since 2.7) # # @cpu-throttle-increment: throttle percentage increase each time -# auto-converge detects that migration is not making -# progress. The default value is 10. (Since 2.7) -# -# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage -# At the tail stage of throttling, the Guest is very -# sensitive to CPU percentage while the @cpu-throttle -# -increment is excessive usually at tail stage. -# If this parameter is true, we will compute the ideal -# CPU percentage used by the Guest, which may exactly make -# the dirty rate match the dirty rate threshold. Then we -# will choose a smaller throttle increment between the -# one specified by @cpu-throttle-increment and the one -# generated by ideal CPU percentage. -# Therefore, it is compatible to traditional throttling, -# meanwhile the throttle increment won't be excessive -# at tail stage. -# The default value is false. (Since 5.1) -# -# @tls-creds: ID of the 'tls-creds' object that provides credentials for -# establishing a TLS connection over the migration data channel. -# On the outgoing side of the migration, the credentials must -# be for a 'client' endpoint, while for the incoming side the -# credentials must be for a 'server' endpoint. Setting this -# will enable TLS for all migrations. The default is unset, -# resulting in unsecured migration at the QEMU level. (Since 2.7) -# -# @tls-hostname: hostname of the target host for the migration. This is -# required when using x509 based TLS credentials and the -# migration URI does not already include a hostname. For -# example if using fd: or exec: based migration, the -# hostname must be provided so that the server's x509 -# certificate identity can be validated. (Since 2.7) -# -# @tls-authz: ID of the 'authz' object subclass that provides access control -# checking of the TLS x509 certificate distinguished name. -# This object is only resolved at time of use, so can be deleted -# and recreated on the fly while the migration server is active. -# If missing, it will default to denying access (Since 4.0) -# -# @max-bandwidth: to set maximum speed for migration. maximum speed in -# bytes per second. (Since 2.8) -# -# @downtime-limit: set maximum tolerated downtime for migration. maximum -# downtime in milliseconds (Since 2.8) -# -# @x-checkpoint-delay: The delay time (in ms) between two COLO checkpoints in -# periodic mode. (Since 2.8) +# auto-converge detects that migration is not making progress. +# The default value is 10. (Since 2.7) +# +# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At +# the tail stage of throttling, the Guest is very sensitive to CPU +# percentage while the @cpu-throttle -increment is excessive +# usually at tail stage. If this parameter is true, we will +# compute the ideal CPU percentage used by the Guest, which may +# exactly make the dirty rate match the dirty rate threshold. +# Then we will choose a smaller throttle increment between the one +# specified by @cpu-throttle-increment and the one generated by +# ideal CPU percentage. Therefore, it is compatible to +# traditional throttling, meanwhile the throttle increment won't +# be excessive at tail stage. The default value is false. (Since +# 5.1) +# +# @tls-creds: ID of the 'tls-creds' object that provides credentials +# for establishing a TLS connection over the migration data +# channel. On the outgoing side of the migration, the credentials +# must be for a 'client' endpoint, while for the incoming side the +# credentials must be for a 'server' endpoint. Setting this to a +# non-empty string enables TLS for all migrations. An empty +# string means that QEMU will use plain text mode for migration, +# rather than TLS. (Since 2.7) +# +# @tls-hostname: migration target's hostname for validating the +# server's x509 certificate identity. If empty, QEMU will use the +# hostname from the migration URI, if any. A non-empty value is +# required when using x509 based TLS credentials and the migration +# URI does not include a hostname, such as fd: or exec: based +# migration. (Since 2.7) +# +# Note: empty value works only since 2.9. +# +# @tls-authz: ID of the 'authz' object subclass that provides access +# control checking of the TLS x509 certificate distinguished name. +# This object is only resolved at time of use, so can be deleted +# and recreated on the fly while the migration server is active. +# If missing, it will default to denying access (Since 4.0) +# +# @max-bandwidth: maximum speed for migration, in bytes per second. +# (Since 2.8) +# +# @avail-switchover-bandwidth: to set the available bandwidth that +# migration can use during switchover phase. NOTE! This does not +# limit the bandwidth during switchover, but only for calculations +# when making decisions to switchover. By default, this value is +# zero, which means QEMU will estimate the bandwidth +# automatically. This can be set when the estimated value is not +# accurate, while the user is able to guarantee such bandwidth is +# available when switching over. When specified correctly, this +# can make the switchover decision much more accurate. +# (Since 8.2) +# +# @downtime-limit: set maximum tolerated downtime for migration. +# maximum downtime in milliseconds (Since 2.8) +# +# @x-checkpoint-delay: The delay time (in ms) between two COLO +# checkpoints in periodic mode. (Since 2.8) # # @block-incremental: Affects how much storage is migrated when the -# block migration capability is enabled. When false, the entire -# storage backing chain is migrated into a flattened image at -# the destination; when true, only the active qcow2 layer is -# migrated and the destination must already have access to the -# same backing chain as was used on the source. (since 2.10) +# block migration capability is enabled. When false, the entire +# storage backing chain is migrated into a flattened image at the +# destination; when true, only the active qcow2 layer is migrated +# and the destination must already have access to the same backing +# chain as was used on the source. (since 2.10) # # @multifd-channels: Number of channels used to migrate data in -# parallel. This is the same number that the -# number of sockets used for migration. The -# default value is 2 (since 4.0) +# parallel. This is the same number that the number of sockets +# used for migration. The default value is 2 (since 4.0) # # @xbzrle-cache-size: cache size to be used by XBZRLE migration. It -# needs to be a multiple of the target page size -# and a power of 2 -# (Since 2.11) +# needs to be a multiple of the target page size and a power of 2 +# (Since 2.11) # -# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy. -# Defaults to 0 (unlimited). In bytes per second. -# (Since 3.0) +# @max-postcopy-bandwidth: Background transfer bandwidth during +# postcopy. Defaults to 0 (unlimited). In bytes per second. +# (Since 3.0) # -# @max-cpu-throttle: maximum cpu throttle percentage. -# Defaults to 99. (Since 3.1) +# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. +# (Since 3.1) # -# @multifd-compression: Which compression method to use. -# Defaults to none. (Since 5.0) +# @multifd-compression: Which compression method to use. Defaults to +# none. (Since 5.0) # # @multifd-zlib-level: Set the compression level to be used in live -# migration, the compression level is an integer between 0 -# and 9, where 0 means no compression, 1 means the best -# compression speed, and 9 means best compression ratio which -# will consume more CPU. -# Defaults to 1. (Since 5.0) +# migration, the compression level is an integer between 0 and 9, +# where 0 means no compression, 1 means the best compression +# speed, and 9 means best compression ratio which will consume +# more CPU. Defaults to 1. (Since 5.0) # # @multifd-zstd-level: Set the compression level to be used in live -# migration, the compression level is an integer between 0 -# and 20, where 0 means no compression, 1 means the best -# compression speed, and 20 means best compression ratio which -# will consume more CPU. -# Defaults to 1. (Since 5.0) +# migration, the compression level is an integer between 0 and 20, +# where 0 means no compression, 1 means the best compression +# speed, and 20 means best compression ratio which will consume +# more CPU. Defaults to 1. (Since 5.0) # # @block-bitmap-mapping: Maps block nodes and bitmaps on them to -# aliases for the purpose of dirty bitmap migration. Such -# aliases may for example be the corresponding names on the -# opposite site. -# The mapping must be one-to-one, but not necessarily -# complete: On the source, unmapped bitmaps and all bitmaps -# on unmapped nodes will be ignored. On the destination, -# encountering an unmapped alias in the incoming migration -# stream will result in a report, and all further bitmap -# migration data will then be discarded. -# Note that the destination does not know about bitmaps it -# does not receive, so there is no limitation or requirement -# regarding the number of bitmaps received, or how they are -# named, or on which nodes they are placed. -# By default (when this parameter has never been set), bitmap -# names are mapped to themselves. Nodes are mapped to their -# block device name if there is one, and to their node name -# otherwise. (Since 5.2) +# aliases for the purpose of dirty bitmap migration. Such aliases +# may for example be the corresponding names on the opposite site. +# The mapping must be one-to-one, but not necessarily complete: On +# the source, unmapped bitmaps and all bitmaps on unmapped nodes +# will be ignored. On the destination, encountering an unmapped +# alias in the incoming migration stream will result in a report, +# and all further bitmap migration data will then be discarded. +# Note that the destination does not know about bitmaps it does +# not receive, so there is no limitation or requirement regarding +# the number of bitmaps received, or how they are named, or on +# which nodes they are placed. By default (when this parameter +# has never been set), bitmap names are mapped to themselves. +# Nodes are mapped to their block device name if there is one, and +# to their node name otherwise. (Since 5.2) +# +# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty +# limit during live migration. Should be in the range 1 to +# 1000ms. Defaults to 1000ms. (Since 8.1) +# +# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. +# Defaults to 1. (Since 8.1) +# +# @mode: Migration mode. See description in @MigMode. Default is +# 'normal'. (Since 8.2) +# +# @zero-page-detection: Whether and how to detect zero pages. +# See description in @ZeroPageDetection. Default is 'multifd'. +# (since 9.0) +# +# Features: +# +# @deprecated: Member @block-incremental is deprecated. Use +# blockdev-mirror with NBD instead. Members @compress-level, +# @compress-threads, @decompress-threads and @compress-wait-thread +# are deprecated because @compression is deprecated. +# +# @unstable: Members @x-checkpoint-delay and +# @x-vcpu-dirty-limit-period are experimental. # # Since: 2.4 ## { 'enum': 'MigrationParameter', 'data': ['announce-initial', 'announce-max', 'announce-rounds', 'announce-step', - 'compress-level', 'compress-threads', 'decompress-threads', - 'compress-wait-thread', 'throttle-trigger-threshold', + { 'name': 'compress-level', 'features': [ 'deprecated' ] }, + { 'name': 'compress-threads', 'features': [ 'deprecated' ] }, + { 'name': 'decompress-threads', 'features': [ 'deprecated' ] }, + { 'name': 'compress-wait-thread', 'features': [ 'deprecated' ] }, + 'throttle-trigger-threshold', 'cpu-throttle-initial', 'cpu-throttle-increment', 'cpu-throttle-tailslow', 'tls-creds', 'tls-hostname', 'tls-authz', 'max-bandwidth', - 'downtime-limit', 'x-checkpoint-delay', 'block-incremental', + 'avail-switchover-bandwidth', 'downtime-limit', + { 'name': 'x-checkpoint-delay', 'features': [ 'unstable' ] }, + { 'name': 'block-incremental', 'features': [ 'deprecated' ] }, 'multifd-channels', 'xbzrle-cache-size', 'max-postcopy-bandwidth', 'max-cpu-throttle', 'multifd-compression', - 'multifd-zlib-level' ,'multifd-zstd-level', - 'block-bitmap-mapping' ] } + 'multifd-zlib-level', 'multifd-zstd-level', + 'block-bitmap-mapping', + { 'name': 'x-vcpu-dirty-limit-period', 'features': ['unstable'] }, + 'vcpu-dirty-limit', + 'mode', + 'zero-page-detection'] } ## # @MigrateSetParameters: # -# @announce-initial: Initial delay (in milliseconds) before sending the first -# announce (Since 4.0) +# @announce-initial: Initial delay (in milliseconds) before sending +# the first announce (Since 4.0) # -# @announce-max: Maximum delay (in milliseconds) between packets in the -# announcement (Since 4.0) +# @announce-max: Maximum delay (in milliseconds) between packets in +# the announcement (Since 4.0) # -# @announce-rounds: Number of self-announce packets sent after migration -# (Since 4.0) +# @announce-rounds: Number of self-announce packets sent after +# migration (Since 4.0) # -# @announce-step: Increase in delay (in milliseconds) between subsequent -# packets in the announcement (Since 4.0) +# @announce-step: Increase in delay (in milliseconds) between +# subsequent packets in the announcement (Since 4.0) # -# @compress-level: compression level +# @compress-level: Set the compression level to be used in live +# migration, the compression level is an integer between 0 and 9, +# where 0 means no compression, 1 means the best compression +# speed, and 9 means best compression ratio which will consume +# more CPU. # -# @compress-threads: compression thread count +# @compress-threads: Set compression thread count to be used in live +# migration, the compression thread count is an integer between 1 +# and 255. # -# @compress-wait-thread: Controls behavior when all compression threads are -# currently busy. If true (default), wait for a free -# compression thread to become available; otherwise, -# send the page uncompressed. (Since 3.1) +# @compress-wait-thread: Controls behavior when all compression +# threads are currently busy. If true (default), wait for a free +# compression thread to become available; otherwise, send the page +# uncompressed. (Since 3.1) # -# @decompress-threads: decompression thread count +# @decompress-threads: Set decompression thread count to be used in +# live migration, the decompression thread count is an integer +# between 1 and 255. Usually, decompression is at least 4 times as +# fast as compression, so set the decompress-threads to the number +# about 1/4 of compress-threads is adequate. # -# @throttle-trigger-threshold: The ratio of bytes_dirty_period and bytes_xfer_period -# to trigger throttling. It is expressed as percentage. -# The default value is 50. (Since 5.0) +# @throttle-trigger-threshold: The ratio of bytes_dirty_period and +# bytes_xfer_period to trigger throttling. It is expressed as +# percentage. The default value is 50. (Since 5.0) # # @cpu-throttle-initial: Initial percentage of time guest cpus are -# throttled when migration auto-converge is activated. -# The default value is 20. (Since 2.7) +# throttled when migration auto-converge is activated. The +# default value is 20. (Since 2.7) # # @cpu-throttle-increment: throttle percentage increase each time -# auto-converge detects that migration is not making -# progress. The default value is 10. (Since 2.7) -# -# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage -# At the tail stage of throttling, the Guest is very -# sensitive to CPU percentage while the @cpu-throttle -# -increment is excessive usually at tail stage. -# If this parameter is true, we will compute the ideal -# CPU percentage used by the Guest, which may exactly make -# the dirty rate match the dirty rate threshold. Then we -# will choose a smaller throttle increment between the -# one specified by @cpu-throttle-increment and the one -# generated by ideal CPU percentage. -# Therefore, it is compatible to traditional throttling, -# meanwhile the throttle increment won't be excessive -# at tail stage. -# The default value is false. (Since 5.1) +# auto-converge detects that migration is not making progress. +# The default value is 10. (Since 2.7) +# +# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At +# the tail stage of throttling, the Guest is very sensitive to CPU +# percentage while the @cpu-throttle -increment is excessive +# usually at tail stage. If this parameter is true, we will +# compute the ideal CPU percentage used by the Guest, which may +# exactly make the dirty rate match the dirty rate threshold. +# Then we will choose a smaller throttle increment between the one +# specified by @cpu-throttle-increment and the one generated by +# ideal CPU percentage. Therefore, it is compatible to +# traditional throttling, meanwhile the throttle increment won't +# be excessive at tail stage. The default value is false. (Since +# 5.1) # # @tls-creds: ID of the 'tls-creds' object that provides credentials -# for establishing a TLS connection over the migration data -# channel. On the outgoing side of the migration, the credentials -# must be for a 'client' endpoint, while for the incoming side the -# credentials must be for a 'server' endpoint. Setting this -# to a non-empty string enables TLS for all migrations. -# An empty string means that QEMU will use plain text mode for -# migration, rather than TLS (Since 2.9) -# Previously (since 2.7), this was reported by omitting -# tls-creds instead. -# -# @tls-hostname: hostname of the target host for the migration. This -# is required when using x509 based TLS credentials and the -# migration URI does not already include a hostname. For -# example if using fd: or exec: based migration, the -# hostname must be provided so that the server's x509 -# certificate identity can be validated. (Since 2.7) -# An empty string means that QEMU will use the hostname -# associated with the migration URI, if any. (Since 2.9) -# Previously (since 2.7), this was reported by omitting -# tls-hostname instead. -# -# @max-bandwidth: to set maximum speed for migration. maximum speed in -# bytes per second. (Since 2.8) -# -# @downtime-limit: set maximum tolerated downtime for migration. maximum -# downtime in milliseconds (Since 2.8) -# -# @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8) +# for establishing a TLS connection over the migration data +# channel. On the outgoing side of the migration, the credentials +# must be for a 'client' endpoint, while for the incoming side the +# credentials must be for a 'server' endpoint. Setting this to a +# non-empty string enables TLS for all migrations. An empty +# string means that QEMU will use plain text mode for migration, +# rather than TLS. This is the default. (Since 2.7) +# +# @tls-hostname: migration target's hostname for validating the +# server's x509 certificate identity. If empty, QEMU will use the +# hostname from the migration URI, if any. A non-empty value is +# required when using x509 based TLS credentials and the migration +# URI does not include a hostname, such as fd: or exec: based +# migration. (Since 2.7) +# +# Note: empty value works only since 2.9. +# +# @tls-authz: ID of the 'authz' object subclass that provides access +# control checking of the TLS x509 certificate distinguished name. +# This object is only resolved at time of use, so can be deleted +# and recreated on the fly while the migration server is active. +# If missing, it will default to denying access (Since 4.0) +# +# @max-bandwidth: maximum speed for migration, in bytes per second. +# (Since 2.8) +# +# @avail-switchover-bandwidth: to set the available bandwidth that +# migration can use during switchover phase. NOTE! This does not +# limit the bandwidth during switchover, but only for calculations +# when making decisions to switchover. By default, this value is +# zero, which means QEMU will estimate the bandwidth +# automatically. This can be set when the estimated value is not +# accurate, while the user is able to guarantee such bandwidth is +# available when switching over. When specified correctly, this +# can make the switchover decision much more accurate. +# (Since 8.2) +# +# @downtime-limit: set maximum tolerated downtime for migration. +# maximum downtime in milliseconds (Since 2.8) +# +# @x-checkpoint-delay: The delay time (in ms) between two COLO +# checkpoints in periodic mode. (Since 2.8) # # @block-incremental: Affects how much storage is migrated when the -# block migration capability is enabled. When false, the entire -# storage backing chain is migrated into a flattened image at -# the destination; when true, only the active qcow2 layer is -# migrated and the destination must already have access to the -# same backing chain as was used on the source. (since 2.10) +# block migration capability is enabled. When false, the entire +# storage backing chain is migrated into a flattened image at the +# destination; when true, only the active qcow2 layer is migrated +# and the destination must already have access to the same backing +# chain as was used on the source. (since 2.10) # # @multifd-channels: Number of channels used to migrate data in -# parallel. This is the same number that the -# number of sockets used for migration. The -# default value is 2 (since 4.0) +# parallel. This is the same number that the number of sockets +# used for migration. The default value is 2 (since 4.0) # # @xbzrle-cache-size: cache size to be used by XBZRLE migration. It -# needs to be a multiple of the target page size -# and a power of 2 -# (Since 2.11) +# needs to be a multiple of the target page size and a power of 2 +# (Since 2.11) # -# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy. -# Defaults to 0 (unlimited). In bytes per second. -# (Since 3.0) +# @max-postcopy-bandwidth: Background transfer bandwidth during +# postcopy. Defaults to 0 (unlimited). In bytes per second. +# (Since 3.0) # -# @max-cpu-throttle: maximum cpu throttle percentage. -# The default value is 99. (Since 3.1) +# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. +# (Since 3.1) # -# @multifd-compression: Which compression method to use. -# Defaults to none. (Since 5.0) +# @multifd-compression: Which compression method to use. Defaults to +# none. (Since 5.0) # # @multifd-zlib-level: Set the compression level to be used in live -# migration, the compression level is an integer between 0 -# and 9, where 0 means no compression, 1 means the best -# compression speed, and 9 means best compression ratio which -# will consume more CPU. -# Defaults to 1. (Since 5.0) +# migration, the compression level is an integer between 0 and 9, +# where 0 means no compression, 1 means the best compression +# speed, and 9 means best compression ratio which will consume +# more CPU. Defaults to 1. (Since 5.0) # # @multifd-zstd-level: Set the compression level to be used in live -# migration, the compression level is an integer between 0 -# and 20, where 0 means no compression, 1 means the best -# compression speed, and 20 means best compression ratio which -# will consume more CPU. -# Defaults to 1. (Since 5.0) +# migration, the compression level is an integer between 0 and 20, +# where 0 means no compression, 1 means the best compression +# speed, and 20 means best compression ratio which will consume +# more CPU. Defaults to 1. (Since 5.0) # # @block-bitmap-mapping: Maps block nodes and bitmaps on them to -# aliases for the purpose of dirty bitmap migration. Such -# aliases may for example be the corresponding names on the -# opposite site. -# The mapping must be one-to-one, but not necessarily -# complete: On the source, unmapped bitmaps and all bitmaps -# on unmapped nodes will be ignored. On the destination, -# encountering an unmapped alias in the incoming migration -# stream will result in a report, and all further bitmap -# migration data will then be discarded. -# Note that the destination does not know about bitmaps it -# does not receive, so there is no limitation or requirement -# regarding the number of bitmaps received, or how they are -# named, or on which nodes they are placed. -# By default (when this parameter has never been set), bitmap -# names are mapped to themselves. Nodes are mapped to their -# block device name if there is one, and to their node name -# otherwise. (Since 5.2) +# aliases for the purpose of dirty bitmap migration. Such aliases +# may for example be the corresponding names on the opposite site. +# The mapping must be one-to-one, but not necessarily complete: On +# the source, unmapped bitmaps and all bitmaps on unmapped nodes +# will be ignored. On the destination, encountering an unmapped +# alias in the incoming migration stream will result in a report, +# and all further bitmap migration data will then be discarded. +# Note that the destination does not know about bitmaps it does +# not receive, so there is no limitation or requirement regarding +# the number of bitmaps received, or how they are named, or on +# which nodes they are placed. By default (when this parameter +# has never been set), bitmap names are mapped to themselves. +# Nodes are mapped to their block device name if there is one, and +# to their node name otherwise. (Since 5.2) +# +# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty +# limit during live migration. Should be in the range 1 to +# 1000ms. Defaults to 1000ms. (Since 8.1) +# +# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. +# Defaults to 1. (Since 8.1) +# +# @mode: Migration mode. See description in @MigMode. Default is +# 'normal'. (Since 8.2) +# +# @zero-page-detection: Whether and how to detect zero pages. +# See description in @ZeroPageDetection. Default is 'multifd'. +# (since 9.0) +# +# Features: +# +# @deprecated: Member @block-incremental is deprecated. Use +# blockdev-mirror with NBD instead. Members @compress-level, +# @compress-threads, @decompress-threads and @compress-wait-thread +# are deprecated because @compression is deprecated. +# +# @unstable: Members @x-checkpoint-delay and +# @x-vcpu-dirty-limit-period are experimental. +# +# TODO: either fuse back into MigrationParameters, or make +# MigrationParameters members mandatory # # Since: 2.4 ## -# TODO either fuse back into MigrationParameters, or make -# MigrationParameters members mandatory { 'struct': 'MigrateSetParameters', 'data': { '*announce-initial': 'size', '*announce-max': 'size', '*announce-rounds': 'size', '*announce-step': 'size', - '*compress-level': 'uint8', - '*compress-threads': 'uint8', - '*compress-wait-thread': 'bool', - '*decompress-threads': 'uint8', + '*compress-level': { 'type': 'uint8', + 'features': [ 'deprecated' ] }, + '*compress-threads': { 'type': 'uint8', + 'features': [ 'deprecated' ] }, + '*compress-wait-thread': { 'type': 'bool', + 'features': [ 'deprecated' ] }, + '*decompress-threads': { 'type': 'uint8', + 'features': [ 'deprecated' ] }, '*throttle-trigger-threshold': 'uint8', '*cpu-throttle-initial': 'uint8', '*cpu-throttle-increment': 'uint8', @@ -930,9 +1158,12 @@ '*tls-hostname': 'StrOrNull', '*tls-authz': 'StrOrNull', '*max-bandwidth': 'size', + '*avail-switchover-bandwidth': 'size', '*downtime-limit': 'uint64', - '*x-checkpoint-delay': 'uint32', - '*block-incremental': 'bool', + '*x-checkpoint-delay': { 'type': 'uint32', + 'features': [ 'unstable' ] }, + '*block-incremental': { 'type': 'bool', + 'features': [ 'deprecated' ] }, '*multifd-channels': 'uint8', '*xbzrle-cache-size': 'size', '*max-postcopy-bandwidth': 'size', @@ -940,7 +1171,12 @@ '*multifd-compression': 'MultiFDCompression', '*multifd-zlib-level': 'uint8', '*multifd-zstd-level': 'uint8', - '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ] } } + '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ], + '*x-vcpu-dirty-limit-period': { 'type': 'uint64', + 'features': [ 'unstable' ] }, + '*vcpu-dirty-limit': 'uint64', + '*mode': 'MigMode', + '*zero-page-detection': 'ZeroPageDetection'} } ## # @migrate-set-parameters: @@ -951,9 +1187,9 @@ # # Example: # -# -> { "execute": "migrate-set-parameters" , -# "arguments": { "compress-level": 1 } } -# +# -> { "execute": "migrate-set-parameters" , +# "arguments": { "multifd-channels": 5 } } +# <- { "return": {} } ## { 'command': 'migrate-set-parameters', 'boxed': true, 'data': 'MigrateSetParameters' } @@ -963,147 +1199,170 @@ # # The optional members aren't actually optional. # -# @announce-initial: Initial delay (in milliseconds) before sending the -# first announce (Since 4.0) +# @announce-initial: Initial delay (in milliseconds) before sending +# the first announce (Since 4.0) # -# @announce-max: Maximum delay (in milliseconds) between packets in the -# announcement (Since 4.0) +# @announce-max: Maximum delay (in milliseconds) between packets in +# the announcement (Since 4.0) # -# @announce-rounds: Number of self-announce packets sent after migration -# (Since 4.0) +# @announce-rounds: Number of self-announce packets sent after +# migration (Since 4.0) # -# @announce-step: Increase in delay (in milliseconds) between subsequent -# packets in the announcement (Since 4.0) +# @announce-step: Increase in delay (in milliseconds) between +# subsequent packets in the announcement (Since 4.0) # # @compress-level: compression level # # @compress-threads: compression thread count # -# @compress-wait-thread: Controls behavior when all compression threads are -# currently busy. If true (default), wait for a free -# compression thread to become available; otherwise, -# send the page uncompressed. (Since 3.1) +# @compress-wait-thread: Controls behavior when all compression +# threads are currently busy. If true (default), wait for a free +# compression thread to become available; otherwise, send the page +# uncompressed. (Since 3.1) # # @decompress-threads: decompression thread count # -# @throttle-trigger-threshold: The ratio of bytes_dirty_period and bytes_xfer_period -# to trigger throttling. It is expressed as percentage. -# The default value is 50. (Since 5.0) +# @throttle-trigger-threshold: The ratio of bytes_dirty_period and +# bytes_xfer_period to trigger throttling. It is expressed as +# percentage. The default value is 50. (Since 5.0) # # @cpu-throttle-initial: Initial percentage of time guest cpus are -# throttled when migration auto-converge is activated. -# (Since 2.7) +# throttled when migration auto-converge is activated. (Since +# 2.7) # # @cpu-throttle-increment: throttle percentage increase each time -# auto-converge detects that migration is not making -# progress. (Since 2.7) -# -# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage -# At the tail stage of throttling, the Guest is very -# sensitive to CPU percentage while the @cpu-throttle -# -increment is excessive usually at tail stage. -# If this parameter is true, we will compute the ideal -# CPU percentage used by the Guest, which may exactly make -# the dirty rate match the dirty rate threshold. Then we -# will choose a smaller throttle increment between the -# one specified by @cpu-throttle-increment and the one -# generated by ideal CPU percentage. -# Therefore, it is compatible to traditional throttling, -# meanwhile the throttle increment won't be excessive -# at tail stage. -# The default value is false. (Since 5.1) +# auto-converge detects that migration is not making progress. +# (Since 2.7) +# +# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At +# the tail stage of throttling, the Guest is very sensitive to CPU +# percentage while the @cpu-throttle -increment is excessive +# usually at tail stage. If this parameter is true, we will +# compute the ideal CPU percentage used by the Guest, which may +# exactly make the dirty rate match the dirty rate threshold. +# Then we will choose a smaller throttle increment between the one +# specified by @cpu-throttle-increment and the one generated by +# ideal CPU percentage. Therefore, it is compatible to +# traditional throttling, meanwhile the throttle increment won't +# be excessive at tail stage. The default value is false. (Since +# 5.1) # # @tls-creds: ID of the 'tls-creds' object that provides credentials -# for establishing a TLS connection over the migration data -# channel. On the outgoing side of the migration, the credentials -# must be for a 'client' endpoint, while for the incoming side the -# credentials must be for a 'server' endpoint. -# An empty string means that QEMU will use plain text mode for -# migration, rather than TLS (Since 2.7) -# Note: 2.8 reports this by omitting tls-creds instead. -# -# @tls-hostname: hostname of the target host for the migration. This -# is required when using x509 based TLS credentials and the -# migration URI does not already include a hostname. For -# example if using fd: or exec: based migration, the -# hostname must be provided so that the server's x509 -# certificate identity can be validated. (Since 2.7) -# An empty string means that QEMU will use the hostname -# associated with the migration URI, if any. (Since 2.9) -# Note: 2.8 reports this by omitting tls-hostname instead. -# -# @tls-authz: ID of the 'authz' object subclass that provides access control -# checking of the TLS x509 certificate distinguished name. (Since -# 4.0) -# -# @max-bandwidth: to set maximum speed for migration. maximum speed in -# bytes per second. (Since 2.8) -# -# @downtime-limit: set maximum tolerated downtime for migration. maximum -# downtime in milliseconds (Since 2.8) -# -# @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8) +# for establishing a TLS connection over the migration data +# channel. On the outgoing side of the migration, the credentials +# must be for a 'client' endpoint, while for the incoming side the +# credentials must be for a 'server' endpoint. An empty string +# means that QEMU will use plain text mode for migration, rather +# than TLS. (Since 2.7) +# +# Note: 2.8 omits empty @tls-creds instead. +# +# @tls-hostname: migration target's hostname for validating the +# server's x509 certificate identity. If empty, QEMU will use the +# hostname from the migration URI, if any. (Since 2.7) +# +# Note: 2.8 omits empty @tls-hostname instead. +# +# @tls-authz: ID of the 'authz' object subclass that provides access +# control checking of the TLS x509 certificate distinguished name. +# (Since 4.0) +# +# @max-bandwidth: maximum speed for migration, in bytes per second. +# (Since 2.8) +# +# @avail-switchover-bandwidth: to set the available bandwidth that +# migration can use during switchover phase. NOTE! This does not +# limit the bandwidth during switchover, but only for calculations +# when making decisions to switchover. By default, this value is +# zero, which means QEMU will estimate the bandwidth +# automatically. This can be set when the estimated value is not +# accurate, while the user is able to guarantee such bandwidth is +# available when switching over. When specified correctly, this +# can make the switchover decision much more accurate. +# (Since 8.2) +# +# @downtime-limit: set maximum tolerated downtime for migration. +# maximum downtime in milliseconds (Since 2.8) +# +# @x-checkpoint-delay: the delay time between two COLO checkpoints. +# (Since 2.8) # # @block-incremental: Affects how much storage is migrated when the -# block migration capability is enabled. When false, the entire -# storage backing chain is migrated into a flattened image at -# the destination; when true, only the active qcow2 layer is -# migrated and the destination must already have access to the -# same backing chain as was used on the source. (since 2.10) +# block migration capability is enabled. When false, the entire +# storage backing chain is migrated into a flattened image at the +# destination; when true, only the active qcow2 layer is migrated +# and the destination must already have access to the same backing +# chain as was used on the source. (since 2.10) # # @multifd-channels: Number of channels used to migrate data in -# parallel. This is the same number that the -# number of sockets used for migration. -# The default value is 2 (since 4.0) +# parallel. This is the same number that the number of sockets +# used for migration. The default value is 2 (since 4.0) # # @xbzrle-cache-size: cache size to be used by XBZRLE migration. It -# needs to be a multiple of the target page size -# and a power of 2 -# (Since 2.11) +# needs to be a multiple of the target page size and a power of 2 +# (Since 2.11) # -# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy. -# Defaults to 0 (unlimited). In bytes per second. -# (Since 3.0) +# @max-postcopy-bandwidth: Background transfer bandwidth during +# postcopy. Defaults to 0 (unlimited). In bytes per second. +# (Since 3.0) # -# @max-cpu-throttle: maximum cpu throttle percentage. -# Defaults to 99. -# (Since 3.1) +# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. +# (Since 3.1) # -# @multifd-compression: Which compression method to use. -# Defaults to none. (Since 5.0) +# @multifd-compression: Which compression method to use. Defaults to +# none. (Since 5.0) # # @multifd-zlib-level: Set the compression level to be used in live -# migration, the compression level is an integer between 0 -# and 9, where 0 means no compression, 1 means the best -# compression speed, and 9 means best compression ratio which -# will consume more CPU. -# Defaults to 1. (Since 5.0) +# migration, the compression level is an integer between 0 and 9, +# where 0 means no compression, 1 means the best compression +# speed, and 9 means best compression ratio which will consume +# more CPU. Defaults to 1. (Since 5.0) # # @multifd-zstd-level: Set the compression level to be used in live -# migration, the compression level is an integer between 0 -# and 20, where 0 means no compression, 1 means the best -# compression speed, and 20 means best compression ratio which -# will consume more CPU. -# Defaults to 1. (Since 5.0) +# migration, the compression level is an integer between 0 and 20, +# where 0 means no compression, 1 means the best compression +# speed, and 20 means best compression ratio which will consume +# more CPU. Defaults to 1. (Since 5.0) # # @block-bitmap-mapping: Maps block nodes and bitmaps on them to -# aliases for the purpose of dirty bitmap migration. Such -# aliases may for example be the corresponding names on the -# opposite site. -# The mapping must be one-to-one, but not necessarily -# complete: On the source, unmapped bitmaps and all bitmaps -# on unmapped nodes will be ignored. On the destination, -# encountering an unmapped alias in the incoming migration -# stream will result in a report, and all further bitmap -# migration data will then be discarded. -# Note that the destination does not know about bitmaps it -# does not receive, so there is no limitation or requirement -# regarding the number of bitmaps received, or how they are -# named, or on which nodes they are placed. -# By default (when this parameter has never been set), bitmap -# names are mapped to themselves. Nodes are mapped to their -# block device name if there is one, and to their node name -# otherwise. (Since 5.2) +# aliases for the purpose of dirty bitmap migration. Such aliases +# may for example be the corresponding names on the opposite site. +# The mapping must be one-to-one, but not necessarily complete: On +# the source, unmapped bitmaps and all bitmaps on unmapped nodes +# will be ignored. On the destination, encountering an unmapped +# alias in the incoming migration stream will result in a report, +# and all further bitmap migration data will then be discarded. +# Note that the destination does not know about bitmaps it does +# not receive, so there is no limitation or requirement regarding +# the number of bitmaps received, or how they are named, or on +# which nodes they are placed. By default (when this parameter +# has never been set), bitmap names are mapped to themselves. +# Nodes are mapped to their block device name if there is one, and +# to their node name otherwise. (Since 5.2) +# +# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty +# limit during live migration. Should be in the range 1 to +# 1000ms. Defaults to 1000ms. (Since 8.1) +# +# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. +# Defaults to 1. (Since 8.1) +# +# @mode: Migration mode. See description in @MigMode. Default is +# 'normal'. (Since 8.2) +# +# @zero-page-detection: Whether and how to detect zero pages. +# See description in @ZeroPageDetection. Default is 'multifd'. +# (since 9.0) +# +# Features: +# +# @deprecated: Member @block-incremental is deprecated. Use +# blockdev-mirror with NBD instead. Members @compress-level, +# @compress-threads, @decompress-threads and @compress-wait-thread +# are deprecated because @compression is deprecated. +# +# @unstable: Members @x-checkpoint-delay and +# @x-vcpu-dirty-limit-period are experimental. # # Since: 2.4 ## @@ -1112,10 +1371,14 @@ '*announce-max': 'size', '*announce-rounds': 'size', '*announce-step': 'size', - '*compress-level': 'uint8', - '*compress-threads': 'uint8', - '*compress-wait-thread': 'bool', - '*decompress-threads': 'uint8', + '*compress-level': { 'type': 'uint8', + 'features': [ 'deprecated' ] }, + '*compress-threads': { 'type': 'uint8', + 'features': [ 'deprecated' ] }, + '*compress-wait-thread': { 'type': 'bool', + 'features': [ 'deprecated' ] }, + '*decompress-threads': { 'type': 'uint8', + 'features': [ 'deprecated' ] }, '*throttle-trigger-threshold': 'uint8', '*cpu-throttle-initial': 'uint8', '*cpu-throttle-increment': 'uint8', @@ -1124,9 +1387,12 @@ '*tls-hostname': 'str', '*tls-authz': 'str', '*max-bandwidth': 'size', + '*avail-switchover-bandwidth': 'size', '*downtime-limit': 'uint64', - '*x-checkpoint-delay': 'uint32', - '*block-incremental': 'bool', + '*x-checkpoint-delay': { 'type': 'uint32', + 'features': [ 'unstable' ] }, + '*block-incremental': { 'type': 'bool', + 'features': [ 'deprecated' ] }, '*multifd-channels': 'uint8', '*xbzrle-cache-size': 'size', '*max-postcopy-bandwidth': 'size', @@ -1134,7 +1400,12 @@ '*multifd-compression': 'MultiFDCompression', '*multifd-zlib-level': 'uint8', '*multifd-zstd-level': 'uint8', - '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ] } } + '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ], + '*x-vcpu-dirty-limit-period': { 'type': 'uint64', + 'features': [ 'unstable' ] }, + '*vcpu-dirty-limit': 'uint64', + '*mode': 'MigMode', + '*zero-page-detection': 'ZeroPageDetection'} } ## # @query-migrate-parameters: @@ -1147,64 +1418,32 @@ # # Example: # -# -> { "execute": "query-migrate-parameters" } -# <- { "return": { -# "decompress-threads": 2, -# "cpu-throttle-increment": 10, -# "compress-threads": 8, -# "compress-level": 1, -# "cpu-throttle-initial": 20, -# "max-bandwidth": 33554432, -# "downtime-limit": 300 -# } -# } -# +# -> { "execute": "query-migrate-parameters" } +# <- { "return": { +# "multifd-channels": 2, +# "cpu-throttle-increment": 10, +# "cpu-throttle-initial": 20, +# "max-bandwidth": 33554432, +# "downtime-limit": 300 +# } +# } ## { 'command': 'query-migrate-parameters', 'returns': 'MigrationParameters' } ## -# @client_migrate_info: -# -# Set migration information for remote display. This makes the server -# ask the client to automatically reconnect using the new parameters -# once migration finished successfully. Only implemented for SPICE. -# -# @protocol: must be "spice" -# @hostname: migration target hostname -# @port: spice tcp port for plaintext channels -# @tls-port: spice tcp port for tls-secured channels -# @cert-subject: server certificate subject -# -# Since: 0.14 -# -# Example: -# -# -> { "execute": "client_migrate_info", -# "arguments": { "protocol": "spice", -# "hostname": "virt42.lab.kraxel.org", -# "port": 1234 } } -# <- { "return": {} } -# -## -{ 'command': 'client_migrate_info', - 'data': { 'protocol': 'str', 'hostname': 'str', '*port': 'int', - '*tls-port': 'int', '*cert-subject': 'str' } } - -## # @migrate-start-postcopy: # -# Followup to a migration command to switch the migration to postcopy mode. -# The postcopy-ram capability must be set on both source and destination -# before the original migration command. +# Followup to a migration command to switch the migration to postcopy +# mode. The postcopy-ram capability must be set on both source and +# destination before the original migration command. # # Since: 2.5 # # Example: # -# -> { "execute": "migrate-start-postcopy" } -# <- { "return": {} } -# +# -> { "execute": "migrate-start-postcopy" } +# <- { "return": {} } ## { 'command': 'migrate-start-postcopy' } @@ -1219,10 +1458,9 @@ # # Example: # -# <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001}, -# "event": "MIGRATION", -# "data": {"status": "completed"} } -# +# <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001}, +# "event": "MIGRATION", +# "data": {"status": "completed"} } ## { 'event': 'MIGRATION', 'data': {'status': 'MigrationStatus'}} @@ -1230,8 +1468,8 @@ ## # @MIGRATION_PASS: # -# Emitted from the source side of a migration at the start of each pass -# (when it syncs the dirty bitmap) +# Emitted from the source side of a migration at the start of each +# pass (when it syncs the dirty bitmap) # # @pass: An incrementing count (starting at 1 on the first pass) # @@ -1239,9 +1477,8 @@ # # Example: # -# { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, -# "event": "MIGRATION_PASS", "data": {"pass": 2} } -# +# <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, +# "event": "MIGRATION_PASS", "data": {"pass": 2} } ## { 'event': 'MIGRATION_PASS', 'data': { 'pass': 'int' } } @@ -1253,7 +1490,8 @@ # # @checkpoint-ready: Secondary VM (SVM) is ready for checkpointing # -# @checkpoint-request: Primary VM (PVM) tells SVM to prepare for checkpointing +# @checkpoint-request: Primary VM (PVM) tells SVM to prepare for +# checkpointing # # @checkpoint-reply: SVM gets PVM's checkpoint request # @@ -1301,7 +1539,8 @@ # # @completed: finish the process of failover # -# @relaunch: restart the failover process, from 'none' -> 'completed' (Since 2.9) +# @relaunch: restart the failover process, from 'none' -> 'completed' +# (Since 2.9) # # Since: 2.8 ## @@ -1322,9 +1561,8 @@ # # Example: # -# <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172}, -# "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } } -# +# <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172}, +# "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } } ## { 'event': 'COLO_EXIT', 'data': {'mode': 'COLOMode', 'reason': 'COLOExitReason' } } @@ -1334,9 +1572,9 @@ # # The reason for a COLO exit. # -# @none: failover has never happened. This state does not occur -# in the COLO_EXIT event, and is only visible in the result of -# query-colo-status. +# @none: failover has never happened. This state does not occur in +# the COLO_EXIT event, and is only visible in the result of +# query-colo-status. # # @request: COLO exit is due to an external request. # @@ -1352,37 +1590,41 @@ ## # @x-colo-lost-heartbeat: # -# Tell qemu that heartbeat is lost, request it to do takeover procedures. -# If this command is sent to the PVM, the Primary side will exit COLO mode. -# If sent to the Secondary, the Secondary side will run failover work, -# then takes over server operation to become the service VM. +# Tell qemu that heartbeat is lost, request it to do takeover +# procedures. If this command is sent to the PVM, the Primary side +# will exit COLO mode. If sent to the Secondary, the Secondary side +# will run failover work, then takes over server operation to become +# the service VM. +# +# Features: +# +# @unstable: This command is experimental. # # Since: 2.8 # # Example: # -# -> { "execute": "x-colo-lost-heartbeat" } -# <- { "return": {} } -# +# -> { "execute": "x-colo-lost-heartbeat" } +# <- { "return": {} } ## -{ 'command': 'x-colo-lost-heartbeat' } +{ 'command': 'x-colo-lost-heartbeat', + 'features': [ 'unstable' ], + 'if': 'CONFIG_REPLICATION' } ## # @migrate_cancel: # # Cancel the current executing migration process. # -# Returns: nothing on success -# -# Notes: This command succeeds even if there is no migration process running. +# Notes: This command succeeds even if there is no migration process +# running. # # Since: 0.14 # # Example: # -# -> { "execute": "migrate_cancel" } -# <- { "return": {} } -# +# -> { "execute": "migrate_cancel" } +# <- { "return": {} } ## { 'command': 'migrate_cancel' } @@ -1393,112 +1635,282 @@ # # @state: The state the migration is currently expected to be in # -# Returns: nothing on success # Since: 2.11 +# # Example: # -# -> { "execute": "migrate-continue" , "arguments": -# { "state": "pre-switchover" } } -# <- { "return": {} } +# -> { "execute": "migrate-continue" , "arguments": +# { "state": "pre-switchover" } } +# <- { "return": {} } ## { 'command': 'migrate-continue', 'data': {'state': 'MigrationStatus'} } ## +# @MigrationAddressType: +# +# The migration stream transport mechanisms. +# +# @socket: Migrate via socket. +# +# @exec: Direct the migration stream to another process. +# +# @rdma: Migrate via RDMA. +# +# @file: Direct the migration stream to a file. +# +# Since: 8.2 +## +{ 'enum': 'MigrationAddressType', + 'data': [ 'socket', 'exec', 'rdma', 'file' ] } + +## +# @FileMigrationArgs: +# +# @filename: The file to receive the migration stream +# +# @offset: The file offset where the migration stream will start +# +# Since: 8.2 +## +{ 'struct': 'FileMigrationArgs', + 'data': { 'filename': 'str', + 'offset': 'uint64' } } + +## +# @MigrationExecCommand: +# +# @args: command (list head) and arguments to execute. +# +# Since: 8.2 +## +{ 'struct': 'MigrationExecCommand', + 'data': {'args': [ 'str' ] } } + +## +# @MigrationAddress: +# +# Migration endpoint configuration. +# +# @transport: The migration stream transport mechanism +# +# Since: 8.2 +## +{ 'union': 'MigrationAddress', + 'base': { 'transport' : 'MigrationAddressType'}, + 'discriminator': 'transport', + 'data': { + 'socket': 'SocketAddress', + 'exec': 'MigrationExecCommand', + 'rdma': 'InetSocketAddress', + 'file': 'FileMigrationArgs' } } + +## +# @MigrationChannelType: +# +# The migration channel-type request options. +# +# @main: Main outbound migration channel. +# +# Since: 8.1 +## +{ 'enum': 'MigrationChannelType', + 'data': [ 'main' ] } + +## +# @MigrationChannel: +# +# Migration stream channel parameters. +# +# @channel-type: Channel type for transferring packet information. +# +# @addr: Migration endpoint configuration on destination interface. +# +# Since: 8.1 +## +{ 'struct': 'MigrationChannel', + 'data': { + 'channel-type': 'MigrationChannelType', + 'addr': 'MigrationAddress' } } + +## # @migrate: # # Migrates the current running guest to another Virtual Machine. # # @uri: the Uniform Resource Identifier of the destination VM # +# @channels: list of migration stream channels with each stream in the +# list connected to a destination interface endpoint. +# # @blk: do block migration (full disk copy) # # @inc: incremental disk copy migration # -# @detach: this argument exists only for compatibility reasons and -# is ignored by QEMU +# @detach: this argument exists only for compatibility reasons and is +# ignored by QEMU # -# @resume: resume one paused migration, default "off". (since 3.0) +# @resume: resume one paused migration, default "off". (since 3.0) +# +# Features: # -# Returns: nothing on success +# @deprecated: Members @inc and @blk are deprecated. Use +# blockdev-mirror with NBD instead. # # Since: 0.14 # # Notes: # -# 1. The 'query-migrate' command should be used to check migration's progress -# and final result (this information is provided by the 'status' member) +# 1. The 'query-migrate' command should be used to check +# migration's progress and final result (this information is +# provided by the 'status' member) # -# 2. All boolean arguments default to false +# 2. All boolean arguments default to false # -# 3. The user Monitor's "detach" argument is invalid in QMP and should not -# be used +# 3. The user Monitor's "detach" argument is invalid in QMP and +# should not be used +# +# 4. The uri argument should have the Uniform Resource Identifier +# of default destination VM. This connection will be bound to +# default network. +# +# 5. For now, number of migration streams is restricted to one, +# i.e. number of items in 'channels' list is just 1. +# +# 6. The 'uri' and 'channels' arguments are mutually exclusive; +# exactly one of the two should be present. # # Example: # -# -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } -# <- { "return": {} } +# -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } +# <- { "return": {} } +# +# -> { "execute": "migrate", +# "arguments": { +# "channels": [ { "channel-type": "main", +# "addr": { "transport": "socket", +# "type": "inet", +# "host": "10.12.34.9", +# "port": "1050" } } ] } } +# <- { "return": {} } +# +# -> { "execute": "migrate", +# "arguments": { +# "channels": [ { "channel-type": "main", +# "addr": { "transport": "exec", +# "args": [ "/bin/nc", "-p", "6000", +# "/some/sock" ] } } ] } } +# <- { "return": {} } +# +# -> { "execute": "migrate", +# "arguments": { +# "channels": [ { "channel-type": "main", +# "addr": { "transport": "rdma", +# "host": "10.12.34.9", +# "port": "1050" } } ] } } +# <- { "return": {} } +# +# -> { "execute": "migrate", +# "arguments": { +# "channels": [ { "channel-type": "main", +# "addr": { "transport": "file", +# "filename": "/tmp/migfile", +# "offset": "0x1000" } } ] } } +# <- { "return": {} } # ## { 'command': 'migrate', - 'data': {'uri': 'str', '*blk': 'bool', '*inc': 'bool', + 'data': {'*uri': 'str', + '*channels': [ 'MigrationChannel' ], + '*blk': { 'type': 'bool', 'features': [ 'deprecated' ] }, + '*inc': { 'type': 'bool', 'features': [ 'deprecated' ] }, '*detach': 'bool', '*resume': 'bool' } } ## # @migrate-incoming: # -# Start an incoming migration, the qemu must have been started -# with -incoming defer +# Start an incoming migration, the qemu must have been started with +# -incoming defer # # @uri: The Uniform Resource Identifier identifying the source or -# address to listen on +# address to listen on # -# Returns: nothing on success +# @channels: list of migration stream channels with each stream in the +# list connected to a destination interface endpoint. # # Since: 2.3 # # Notes: # -# 1. It's a bad idea to use a string for the uri, but it needs to stay -# compatible with -incoming and the format of the uri is already exposed -# above libvirt. +# 1. It's a bad idea to use a string for the uri, but it needs to +# stay compatible with -incoming and the format of the uri is +# already exposed above libvirt. # -# 2. QEMU must be started with -incoming defer to allow migrate-incoming to -# be used. +# 2. QEMU must be started with -incoming defer to allow +# migrate-incoming to be used. # -# 3. The uri format is the same as for -incoming +# 3. The uri format is the same as for -incoming # -# Example: +# 4. For now, number of migration streams is restricted to one, +# i.e. number of items in 'channels' list is just 1. # -# -> { "execute": "migrate-incoming", -# "arguments": { "uri": "tcp::4446" } } -# <- { "return": {} } +# 5. The 'uri' and 'channels' arguments are mutually exclusive; +# exactly one of the two should be present. # -## -{ 'command': 'migrate-incoming', 'data': {'uri': 'str' } } +# Example: +# +# -> { "execute": "migrate-incoming", +# "arguments": { "uri": "tcp:0:4446" } } +# <- { "return": {} } +# +# -> { "execute": "migrate-incoming", +# "arguments": { +# "channels": [ { "channel-type": "main", +# "addr": { "transport": "socket", +# "type": "inet", +# "host": "10.12.34.9", +# "port": "1050" } } ] } } +# <- { "return": {} } +# +# -> { "execute": "migrate-incoming", +# "arguments": { +# "channels": [ { "channel-type": "main", +# "addr": { "transport": "exec", +# "args": [ "/bin/nc", "-p", "6000", +# "/some/sock" ] } } ] } } +# <- { "return": {} } +# +# -> { "execute": "migrate-incoming", +# "arguments": { +# "channels": [ { "channel-type": "main", +# "addr": { "transport": "rdma", +# "host": "10.12.34.9", +# "port": "1050" } } ] } } +# <- { "return": {} } +## +{ 'command': 'migrate-incoming', + 'data': {'*uri': 'str', + '*channels': [ 'MigrationChannel' ] } } ## # @xen-save-devices-state: # -# Save the state of all devices to file. The RAM and the block devices -# of the VM are not saved by this command. +# Save the state of all devices to file. The RAM and the block +# devices of the VM are not saved by this command. # # @filename: the file to save the state of the devices to as binary -# data. See xen-save-devices-state.txt for a description of the binary -# format. -# -# @live: Optional argument to ask QEMU to treat this command as part of a live -# migration. Default to true. (since 2.11) +# data. See xen-save-devices-state.txt for a description of the +# binary format. # -# Returns: Nothing on success +# @live: Optional argument to ask QEMU to treat this command as part +# of a live migration. Default to true. (since 2.11) # # Since: 1.1 # # Example: # -# -> { "execute": "xen-save-devices-state", -# "arguments": { "filename": "/tmp/save" } } -# <- { "return": {} } -# +# -> { "execute": "xen-save-devices-state", +# "arguments": { "filename": "/tmp/save" } } +# <- { "return": {} } ## { 'command': 'xen-save-devices-state', 'data': {'filename': 'str', '*live':'bool' } } @@ -1510,37 +1922,33 @@ # # @enable: true to enable, false to disable. # -# Returns: nothing -# # Since: 1.3 # # Example: # -# -> { "execute": "xen-set-global-dirty-log", -# "arguments": { "enable": true } } -# <- { "return": {} } -# +# -> { "execute": "xen-set-global-dirty-log", +# "arguments": { "enable": true } } +# <- { "return": {} } ## { 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } } ## # @xen-load-devices-state: # -# Load the state of all devices from file. The RAM and the block devices -# of the VM are not loaded by this command. +# Load the state of all devices from file. The RAM and the block +# devices of the VM are not loaded by this command. # # @filename: the file to load the state of the devices from as binary -# data. See xen-save-devices-state.txt for a description of the binary -# format. +# data. See xen-save-devices-state.txt for a description of the +# binary format. # # Since: 2.7 # # Example: # -# -> { "execute": "xen-load-devices-state", -# "arguments": { "filename": "/tmp/resume" } } -# <- { "return": {} } -# +# -> { "execute": "xen-load-devices-state", +# "arguments": { "filename": "/tmp/resume" } } +# <- { "return": {} } ## { 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} } @@ -1553,22 +1961,20 @@ # # @primary: true for primary or false for secondary. # -# @failover: true to do failover, false to stop. but cannot be -# specified if 'enable' is true. default value is false. -# -# Returns: nothing. +# @failover: true to do failover, false to stop. Cannot be specified +# if 'enable' is true. Default value is false. # # Example: # -# -> { "execute": "xen-set-replication", -# "arguments": {"enable": true, "primary": false} } -# <- { "return": {} } +# -> { "execute": "xen-set-replication", +# "arguments": {"enable": true, "primary": false} } +# <- { "return": {} } # # Since: 2.9 ## { 'command': 'xen-set-replication', - 'data': { 'enable': 'bool', 'primary': 'bool', '*failover' : 'bool' }, - 'if': 'defined(CONFIG_REPLICATION)' } + 'data': { 'enable': 'bool', 'primary': 'bool', '*failover': 'bool' }, + 'if': 'CONFIG_REPLICATION' } ## # @ReplicationStatus: @@ -1577,61 +1983,59 @@ # # @error: true if an error happened, false if replication is normal. # -# @desc: the human readable error description string, when -# @error is 'true'. +# @desc: the human readable error description string, when @error is +# 'true'. # # Since: 2.9 ## { 'struct': 'ReplicationStatus', 'data': { 'error': 'bool', '*desc': 'str' }, - 'if': 'defined(CONFIG_REPLICATION)' } + 'if': 'CONFIG_REPLICATION' } ## # @query-xen-replication-status: # # Query replication status while the vm is running. # -# Returns: A @ReplicationResult object showing the status. +# Returns: A @ReplicationStatus object showing the status. # # Example: # -# -> { "execute": "query-xen-replication-status" } -# <- { "return": { "error": false } } +# -> { "execute": "query-xen-replication-status" } +# <- { "return": { "error": false } } # # Since: 2.9 ## { 'command': 'query-xen-replication-status', 'returns': 'ReplicationStatus', - 'if': 'defined(CONFIG_REPLICATION)' } + 'if': 'CONFIG_REPLICATION' } ## # @xen-colo-do-checkpoint: # # Xen uses this command to notify replication to trigger a checkpoint. # -# Returns: nothing. -# # Example: # -# -> { "execute": "xen-colo-do-checkpoint" } -# <- { "return": {} } +# -> { "execute": "xen-colo-do-checkpoint" } +# <- { "return": {} } # # Since: 2.9 ## { 'command': 'xen-colo-do-checkpoint', - 'if': 'defined(CONFIG_REPLICATION)' } + 'if': 'CONFIG_REPLICATION' } ## # @COLOStatus: # # The result format for 'query-colo-status'. # -# @mode: COLO running mode. If COLO is running, this field will return -# 'primary' or 'secondary'. +# @mode: COLO running mode. If COLO is running, this field will +# return 'primary' or 'secondary'. # -# @last-mode: COLO last running mode. If COLO is running, this field -# will return same like mode field, after failover we can -# use this field to get last colo mode. (since 4.0) +# @last-mode: COLO last running mode. If COLO is running, this field +# will return same like mode field, after failover we can use this +# field to get last colo mode. (since 4.0) # # @reason: describes the reason for the COLO exit. # @@ -1639,7 +2043,8 @@ ## { 'struct': 'COLOStatus', 'data': { 'mode': 'COLOMode', 'last-mode': 'COLOMode', - 'reason': 'COLOExitReason' } } + 'reason': 'COLOExitReason' }, + 'if': 'CONFIG_REPLICATION' } ## # @query-colo-status: @@ -1650,13 +2055,14 @@ # # Example: # -# -> { "execute": "query-colo-status" } -# <- { "return": { "mode": "primary", "reason": "request" } } +# -> { "execute": "query-colo-status" } +# <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } } # # Since: 3.1 ## { 'command': 'query-colo-status', - 'returns': 'COLOStatus' } + 'returns': 'COLOStatus', + 'if': 'CONFIG_REPLICATION' } ## # @migrate-recover: @@ -1665,13 +2071,11 @@ # # @uri: the URI to be used for the recovery of migration stream. # -# Returns: nothing. -# # Example: # -# -> { "execute": "migrate-recover", -# "arguments": { "uri": "tcp:192.168.1.200:12345" } } -# <- { "return": {} } +# -> { "execute": "migrate-recover", +# "arguments": { "uri": "tcp:192.168.1.200:12345" } } +# <- { "return": {} } # # Since: 3.0 ## @@ -1684,12 +2088,10 @@ # # Pause a migration. Currently it only supports postcopy. # -# Returns: nothing. -# # Example: # -# -> { "execute": "migrate-pause" } -# <- { "return": {} } +# -> { "execute": "migrate-pause" } +# <- { "return": {} } # # Since: 3.0 ## @@ -1699,85 +2101,330 @@ # @UNPLUG_PRIMARY: # # Emitted from source side of a migration when migration state is -# WAIT_UNPLUG. Device was unplugged by guest operating system. -# Device resources in QEMU are kept on standby to be able to re-plug it in case -# of migration failure. +# WAIT_UNPLUG. Device was unplugged by guest operating system. Device +# resources in QEMU are kept on standby to be able to re-plug it in +# case of migration failure. # # @device-id: QEMU device id of the unplugged device # # Since: 4.2 # # Example: -# {"event": "UNPLUG_PRIMARY", "data": {"device-id": "hostdev0"} } # +# <- { "event": "UNPLUG_PRIMARY", +# "data": { "device-id": "hostdev0" }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } ## { 'event': 'UNPLUG_PRIMARY', 'data': { 'device-id': 'str' } } ## +# @DirtyRateVcpu: +# +# Dirty rate of vcpu. +# +# @id: vcpu index. +# +# @dirty-rate: dirty rate. +# +# Since: 6.2 +## +{ 'struct': 'DirtyRateVcpu', + 'data': { 'id': 'int', 'dirty-rate': 'int64' } } + +## # @DirtyRateStatus: # -# An enumeration of dirtyrate status. +# Dirty page rate measurement status. # -# @unstarted: the dirtyrate thread has not been started. +# @unstarted: measuring thread has not been started yet # -# @measuring: the dirtyrate thread is measuring. +# @measuring: measuring thread is running # -# @measured: the dirtyrate thread has measured and results are available. +# @measured: dirty page rate is measured and the results are available # # Since: 5.2 -# ## { 'enum': 'DirtyRateStatus', 'data': [ 'unstarted', 'measuring', 'measured'] } ## +# @DirtyRateMeasureMode: +# +# Method used to measure dirty page rate. Differences between +# available methods are explained in @calc-dirty-rate. +# +# @page-sampling: use page sampling +# +# @dirty-ring: use dirty ring +# +# @dirty-bitmap: use dirty bitmap +# +# Since: 6.2 +## +{ 'enum': 'DirtyRateMeasureMode', + 'data': ['page-sampling', 'dirty-ring', 'dirty-bitmap'] } + +## +# @TimeUnit: +# +# Specifies unit in which time-related value is specified. +# +# @second: value is in seconds +# +# @millisecond: value is in milliseconds +# +# Since: 8.2 +## +{ 'enum': 'TimeUnit', + 'data': ['second', 'millisecond'] } + +## # @DirtyRateInfo: # -# Information about current dirty page rate of vm. +# Information about measured dirty page rate. # -# @dirty-rate: an estimate of the dirty page rate of the VM in units of -# MB/s, present only when estimating the rate has completed. +# @dirty-rate: an estimate of the dirty page rate of the VM in units +# of MiB/s. Value is present only when @status is 'measured'. # -# @status: status containing dirtyrate query status includes -# 'unstarted' or 'measuring' or 'measured' +# @status: current status of dirty page rate measurements # # @start-time: start time in units of second for calculation # -# @calc-time: time in units of second for sample dirty pages +# @calc-time: time period for which dirty page rate was measured, +# expressed and rounded down to @calc-time-unit. # -# Since: 5.2 +# @calc-time-unit: time unit of @calc-time (Since 8.2) +# +# @sample-pages: number of sampled pages per GiB of guest memory. +# Valid only in page-sampling mode (Since 6.1) # +# @mode: mode that was used to measure dirty page rate (Since 6.2) +# +# @vcpu-dirty-rate: dirty rate for each vCPU if dirty-ring mode was +# specified (Since 6.2) +# +# Since: 5.2 ## { 'struct': 'DirtyRateInfo', 'data': {'*dirty-rate': 'int64', 'status': 'DirtyRateStatus', 'start-time': 'int64', - 'calc-time': 'int64'} } + 'calc-time': 'int64', + 'calc-time-unit': 'TimeUnit', + 'sample-pages': 'uint64', + 'mode': 'DirtyRateMeasureMode', + '*vcpu-dirty-rate': [ 'DirtyRateVcpu' ] } } ## # @calc-dirty-rate: # -# start calculating dirty page rate for vm -# -# @calc-time: time in units of second for sample dirty pages +# Start measuring dirty page rate of the VM. Results can be retrieved +# with @query-dirty-rate after measurements are completed. +# +# Dirty page rate is the number of pages changed in a given time +# period expressed in MiB/s. The following methods of calculation are +# available: +# +# 1. In page sampling mode, a random subset of pages are selected and +# hashed twice: once at the beginning of measurement time period, +# and once again at the end. If two hashes for some page are +# different, the page is counted as changed. Since this method +# relies on sampling and hashing, calculated dirty page rate is +# only an estimate of its true value. Increasing @sample-pages +# improves estimation quality at the cost of higher computational +# overhead. +# +# 2. Dirty bitmap mode captures writes to memory (for example by +# temporarily revoking write access to all pages) and counting page +# faults. Information about modified pages is collected into a +# bitmap, where each bit corresponds to one guest page. This mode +# requires that KVM accelerator property "dirty-ring-size" is *not* +# set. +# +# 3. Dirty ring mode is similar to dirty bitmap mode, but the +# information about modified pages is collected into ring buffer. +# This mode tracks page modification per each vCPU separately. It +# requires that KVM accelerator property "dirty-ring-size" is set. +# +# @calc-time: time period for which dirty page rate is calculated. +# By default it is specified in seconds, but the unit can be set +# explicitly with @calc-time-unit. Note that larger @calc-time +# values will typically result in smaller dirty page rates because +# page dirtying is a one-time event. Once some page is counted +# as dirty during @calc-time period, further writes to this page +# will not increase dirty page rate anymore. +# +# @calc-time-unit: time unit in which @calc-time is specified. +# By default it is seconds. (Since 8.2) +# +# @sample-pages: number of sampled pages per each GiB of guest memory. +# Default value is 512. For 4KiB guest pages this corresponds to +# sampling ratio of 0.2%. This argument is used only in page +# sampling mode. (Since 6.1) +# +# @mode: mechanism for tracking dirty pages. Default value is +# 'page-sampling'. Others are 'dirty-bitmap' and 'dirty-ring'. +# (Since 6.1) # # Since: 5.2 # # Example: -# {"command": "calc-dirty-rate", "data": {"calc-time": 1} } # +# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, +# 'sample-pages': 512} } +# <- { "return": {} } +# +# Measure dirty rate using dirty bitmap for 500 milliseconds: +# +# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 500, +# "calc-time-unit": "millisecond", "mode": "dirty-bitmap"} } +# +# <- { "return": {} } ## -{ 'command': 'calc-dirty-rate', 'data': {'calc-time': 'int64'} } +{ 'command': 'calc-dirty-rate', 'data': {'calc-time': 'int64', + '*calc-time-unit': 'TimeUnit', + '*sample-pages': 'int', + '*mode': 'DirtyRateMeasureMode'} } ## # @query-dirty-rate: # -# query dirty page rate in units of MB/s for vm +# Query results of the most recent invocation of @calc-dirty-rate. +# +# @calc-time-unit: time unit in which to report calculation time. +# By default it is reported in seconds. (Since 8.2) # # Since: 5.2 +# +# Examples: +# +# 1. Measurement is in progress: +# +# <- {"status": "measuring", "sample-pages": 512, +# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, +# "calc-time-unit": "second"} +# +# 2. Measurement has been completed: +# +# <- {"status": "measured", "sample-pages": 512, "dirty-rate": 108, +# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, +# "calc-time-unit": "second"} +## +{ 'command': 'query-dirty-rate', 'data': {'*calc-time-unit': 'TimeUnit' }, + 'returns': 'DirtyRateInfo' } + +## +# @DirtyLimitInfo: +# +# Dirty page rate limit information of a virtual CPU. +# +# @cpu-index: index of a virtual CPU. +# +# @limit-rate: upper limit of dirty page rate (MB/s) for a virtual +# CPU, 0 means unlimited. +# +# @current-rate: current dirty page rate (MB/s) for a virtual CPU. +# +# Since: 7.1 ## -{ 'command': 'query-dirty-rate', 'returns': 'DirtyRateInfo' } +{ 'struct': 'DirtyLimitInfo', + 'data': { 'cpu-index': 'int', + 'limit-rate': 'uint64', + 'current-rate': 'uint64' } } + +## +# @set-vcpu-dirty-limit: +# +# Set the upper limit of dirty page rate for virtual CPUs. +# +# Requires KVM with accelerator property "dirty-ring-size" set. A +# virtual CPU's dirty page rate is a measure of its memory load. To +# observe dirty page rates, use @calc-dirty-rate. +# +# @cpu-index: index of a virtual CPU, default is all. +# +# @dirty-rate: upper limit of dirty page rate (MB/s) for virtual CPUs. +# +# Since: 7.1 +# +# Example: +# +# -> {"execute": "set-vcpu-dirty-limit"} +# "arguments": { "dirty-rate": 200, +# "cpu-index": 1 } } +# <- { "return": {} } +## +{ 'command': 'set-vcpu-dirty-limit', + 'data': { '*cpu-index': 'int', + 'dirty-rate': 'uint64' } } + +## +# @cancel-vcpu-dirty-limit: +# +# Cancel the upper limit of dirty page rate for virtual CPUs. +# +# Cancel the dirty page limit for the vCPU which has been set with +# set-vcpu-dirty-limit command. Note that this command requires +# support from dirty ring, same as the "set-vcpu-dirty-limit". +# +# @cpu-index: index of a virtual CPU, default is all. +# +# Since: 7.1 +# +# Example: +# +# -> {"execute": "cancel-vcpu-dirty-limit"}, +# "arguments": { "cpu-index": 1 } } +# <- { "return": {} } +## +{ 'command': 'cancel-vcpu-dirty-limit', + 'data': { '*cpu-index': 'int'} } + +## +# @query-vcpu-dirty-limit: +# +# Returns information about virtual CPU dirty page rate limits, if +# any. +# +# Since: 7.1 +# +# Example: +# +# -> {"execute": "query-vcpu-dirty-limit"} +# <- {"return": [ +# { "limit-rate": 60, "current-rate": 3, "cpu-index": 0}, +# { "limit-rate": 60, "current-rate": 3, "cpu-index": 1}]} +## +{ 'command': 'query-vcpu-dirty-limit', + 'returns': [ 'DirtyLimitInfo' ] } + +## +# @MigrationThreadInfo: +# +# Information about migrationthreads +# +# @name: the name of migration thread +# +# @thread-id: ID of the underlying host thread +# +# Since: 7.2 +## +{ 'struct': 'MigrationThreadInfo', + 'data': {'name': 'str', + 'thread-id': 'int'} } + +## +# @query-migrationthreads: +# +# Returns information of migration threads +# +# Returns: @MigrationThreadInfo +# +# Since: 7.2 +## +{ 'command': 'query-migrationthreads', + 'returns': ['MigrationThreadInfo'] } ## # @snapshot-save: @@ -1785,54 +2432,63 @@ # Save a VM snapshot # # @job-id: identifier for the newly created job +# # @tag: name of the snapshot to create +# # @vmstate: block device node name to save vmstate to +# # @devices: list of block device node names to save a snapshot to # # Applications should not assume that the snapshot save is complete -# when this command returns. The job commands / events must be used -# to determine completion and to fetch details of any errors that arise. +# when this command returns. The job commands / events must be used +# to determine completion and to fetch details of any errors that +# arise. # -# Note that execution of the guest CPUs may be stopped during the -# time it takes to save the snapshot. A future version of QEMU -# may ensure CPUs are executing continuously. +# Note that execution of the guest CPUs may be stopped during the time +# it takes to save the snapshot. A future version of QEMU may ensure +# CPUs are executing continuously. # -# It is strongly recommended that @devices contain all writable -# block device nodes if a consistent snapshot is required. +# It is strongly recommended that @devices contain all writable block +# device nodes if a consistent snapshot is required. # # If @tag already exists, an error will be reported # -# Returns: nothing -# # Example: # -# -> { "execute": "snapshot-save", -# "data": { -# "job-id": "snapsave0", -# "tag": "my-snap", -# "vmstate": "disk0", -# "devices": ["disk0", "disk1"] -# } -# } -# <- { "return": { } } -# <- {"event": "JOB_STATUS_CHANGE", -# "data": {"status": "created", "id": "snapsave0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "data": {"status": "running", "id": "snapsave0"}} -# <- {"event": "STOP"} -# <- {"event": "RESUME"} -# <- {"event": "JOB_STATUS_CHANGE", -# "data": {"status": "waiting", "id": "snapsave0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "data": {"status": "pending", "id": "snapsave0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "data": {"status": "concluded", "id": "snapsave0"}} -# -> {"execute": "query-jobs"} -# <- {"return": [{"current-progress": 1, -# "status": "concluded", -# "total-progress": 1, -# "type": "snapshot-save", -# "id": "snapsave0"}]} +# -> { "execute": "snapshot-save", +# "arguments": { +# "job-id": "snapsave0", +# "tag": "my-snap", +# "vmstate": "disk0", +# "devices": ["disk0", "disk1"] +# } +# } +# <- { "return": { } } +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1432121972, "microseconds": 744001}, +# "data": {"status": "created", "id": "snapsave0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1432122172, "microseconds": 744001}, +# "data": {"status": "running", "id": "snapsave0"}} +# <- {"event": "STOP", +# "timestamp": {"seconds": 1432122372, "microseconds": 744001} } +# <- {"event": "RESUME", +# "timestamp": {"seconds": 1432122572, "microseconds": 744001} } +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1432122772, "microseconds": 744001}, +# "data": {"status": "waiting", "id": "snapsave0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1432122972, "microseconds": 744001}, +# "data": {"status": "pending", "id": "snapsave0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1432123172, "microseconds": 744001}, +# "data": {"status": "concluded", "id": "snapsave0"}} +# -> {"execute": "query-jobs"} +# <- {"return": [{"current-progress": 1, +# "status": "concluded", +# "total-progress": 1, +# "type": "snapshot-save", +# "id": "snapsave0"}]} # # Since: 6.0 ## @@ -1848,52 +2504,61 @@ # Load a VM snapshot # # @job-id: identifier for the newly created job +# # @tag: name of the snapshot to load. +# # @vmstate: block device node name to load vmstate from +# # @devices: list of block device node names to load a snapshot from # # Applications should not assume that the snapshot load is complete -# when this command returns. The job commands / events must be used -# to determine completion and to fetch details of any errors that arise. +# when this command returns. The job commands / events must be used +# to determine completion and to fetch details of any errors that +# arise. # # Note that execution of the guest CPUs will be stopped during the # time it takes to load the snapshot. # -# It is strongly recommended that @devices contain all writable -# block device nodes that can have changed since the original -# @snapshot-save command execution. -# -# Returns: nothing +# It is strongly recommended that @devices contain all writable block +# device nodes that can have changed since the original @snapshot-save +# command execution. # # Example: # -# -> { "execute": "snapshot-load", -# "data": { -# "job-id": "snapload0", -# "tag": "my-snap", -# "vmstate": "disk0", -# "devices": ["disk0", "disk1"] -# } -# } -# <- { "return": { } } -# <- {"event": "JOB_STATUS_CHANGE", -# "data": {"status": "created", "id": "snapload0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "data": {"status": "running", "id": "snapload0"}} -# <- {"event": "STOP"} -# <- {"event": "RESUME"} -# <- {"event": "JOB_STATUS_CHANGE", -# "data": {"status": "waiting", "id": "snapload0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "data": {"status": "pending", "id": "snapload0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "data": {"status": "concluded", "id": "snapload0"}} -# -> {"execute": "query-jobs"} -# <- {"return": [{"current-progress": 1, -# "status": "concluded", -# "total-progress": 1, -# "type": "snapshot-load", -# "id": "snapload0"}]} +# -> { "execute": "snapshot-load", +# "arguments": { +# "job-id": "snapload0", +# "tag": "my-snap", +# "vmstate": "disk0", +# "devices": ["disk0", "disk1"] +# } +# } +# <- { "return": { } } +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1472124172, "microseconds": 744001}, +# "data": {"status": "created", "id": "snapload0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1472125172, "microseconds": 744001}, +# "data": {"status": "running", "id": "snapload0"}} +# <- {"event": "STOP", +# "timestamp": {"seconds": 1472125472, "microseconds": 744001} } +# <- {"event": "RESUME", +# "timestamp": {"seconds": 1472125872, "microseconds": 744001} } +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1472126172, "microseconds": 744001}, +# "data": {"status": "waiting", "id": "snapload0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1472127172, "microseconds": 744001}, +# "data": {"status": "pending", "id": "snapload0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1472128172, "microseconds": 744001}, +# "data": {"status": "concluded", "id": "snapload0"}} +# -> {"execute": "query-jobs"} +# <- {"return": [{"current-progress": 1, +# "status": "concluded", +# "total-progress": 1, +# "type": "snapshot-load", +# "id": "snapload0"}]} # # Since: 6.0 ## @@ -1909,41 +2574,47 @@ # Delete a VM snapshot # # @job-id: identifier for the newly created job +# # @tag: name of the snapshot to delete. +# # @devices: list of block device node names to delete a snapshot from # # Applications should not assume that the snapshot delete is complete -# when this command returns. The job commands / events must be used -# to determine completion and to fetch details of any errors that arise. -# -# Returns: nothing +# when this command returns. The job commands / events must be used +# to determine completion and to fetch details of any errors that +# arise. # # Example: # -# -> { "execute": "snapshot-delete", -# "data": { -# "job-id": "snapdelete0", -# "tag": "my-snap", -# "devices": ["disk0", "disk1"] -# } -# } -# <- { "return": { } } -# <- {"event": "JOB_STATUS_CHANGE", -# "data": {"status": "created", "id": "snapdelete0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "data": {"status": "running", "id": "snapdelete0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "data": {"status": "waiting", "id": "snapdelete0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "data": {"status": "pending", "id": "snapdelete0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "data": {"status": "concluded", "id": "snapdelete0"}} -# -> {"execute": "query-jobs"} -# <- {"return": [{"current-progress": 1, -# "status": "concluded", -# "total-progress": 1, -# "type": "snapshot-delete", -# "id": "snapdelete0"}]} +# -> { "execute": "snapshot-delete", +# "arguments": { +# "job-id": "snapdelete0", +# "tag": "my-snap", +# "devices": ["disk0", "disk1"] +# } +# } +# <- { "return": { } } +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1442124172, "microseconds": 744001}, +# "data": {"status": "created", "id": "snapdelete0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1442125172, "microseconds": 744001}, +# "data": {"status": "running", "id": "snapdelete0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1442126172, "microseconds": 744001}, +# "data": {"status": "waiting", "id": "snapdelete0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1442127172, "microseconds": 744001}, +# "data": {"status": "pending", "id": "snapdelete0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1442128172, "microseconds": 744001}, +# "data": {"status": "concluded", "id": "snapdelete0"}} +# -> {"execute": "query-jobs"} +# <- {"return": [{"current-progress": 1, +# "status": "concluded", +# "total-progress": 1, +# "type": "snapshot-delete", +# "id": "snapdelete0"}]} # # Since: 6.0 ## diff --git a/qapi/misc-target.json b/qapi/misc-target.json index 0c7491cd82..4e0a6492a9 100644 --- a/qapi/misc-target.json +++ b/qapi/misc-target.json @@ -3,47 +3,21 @@ # ## -# @RTC_CHANGE: -# -# Emitted when the guest changes the RTC time. -# -# @offset: offset between base RTC clock (as specified by -rtc base), and -# new RTC clock value -# -# Note: This event is rate-limited. -# -# Since: 0.13 -# -# Example: -# -# <- { "event": "RTC_CHANGE", -# "data": { "offset": 78 }, -# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } -# -## -{ 'event': 'RTC_CHANGE', - 'data': { 'offset': 'int' }, - 'if': 'defined(TARGET_ALPHA) || defined(TARGET_ARM) || defined(TARGET_HPPA) || defined(TARGET_I386) || defined(TARGET_MIPS) || defined(TARGET_MIPS64) || defined(TARGET_MOXIE) || defined(TARGET_PPC) || defined(TARGET_PPC64) || defined(TARGET_S390X) || defined(TARGET_SH4) || defined(TARGET_SPARC)' } - -## # @rtc-reset-reinjection: # -# This command will reset the RTC interrupt reinjection backlog. -# Can be used if another mechanism to synchronize guest time -# is in effect, for example QEMU guest agent's guest-set-time -# command. +# This command will reset the RTC interrupt reinjection backlog. Can +# be used if another mechanism to synchronize guest time is in effect, +# for example QEMU guest agent's guest-set-time command. # # Since: 2.1 # # Example: # -# -> { "execute": "rtc-reset-reinjection" } -# <- { "return": {} } -# +# -> { "execute": "rtc-reset-reinjection" } +# <- { "return": {} } ## { 'command': 'rtc-reset-reinjection', - 'if': 'defined(TARGET_I386)' } - + 'if': 'TARGET_I386' } ## # @SevState: @@ -52,24 +26,26 @@ # # @uninit: The guest is uninitialized. # -# @launch-update: The guest is currently being launched; plaintext data and -# register state is being imported. +# @launch-update: The guest is currently being launched; plaintext +# data and register state is being imported. # -# @launch-secret: The guest is currently being launched; ciphertext data -# is being imported. +# @launch-secret: The guest is currently being launched; ciphertext +# data is being imported. # # @running: The guest is fully launched or migrated in. # -# @send-update: The guest is currently being migrated out to another machine. +# @send-update: The guest is currently being migrated out to another +# machine. # -# @receive-update: The guest is currently being migrated from another machine. +# @receive-update: The guest is currently being migrated from another +# machine. # # Since: 2.12 ## { 'enum': 'SevState', 'data': ['uninit', 'launch-update', 'launch-secret', 'running', 'send-update', 'receive-update' ], - 'if': 'defined(TARGET_I386)' } + 'if': 'TARGET_I386' } ## # @SevInfo: @@ -101,7 +77,7 @@ 'state' : 'SevState', 'handle' : 'uint32' }, - 'if': 'defined(TARGET_I386)' + 'if': 'TARGET_I386' } ## @@ -115,15 +91,13 @@ # # Example: # -# -> { "execute": "query-sev" } -# <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0, -# "build-id" : 0, "policy" : 0, "state" : "running", -# "handle" : 1 } } -# +# -> { "execute": "query-sev" } +# <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0, +# "build-id" : 0, "policy" : 0, "state" : "running", +# "handle" : 1 } } ## { 'command': 'query-sev', 'returns': 'SevInfo', - 'if': 'defined(TARGET_I386)' } - + 'if': 'TARGET_I386' } ## # @SevLaunchMeasureInfo: @@ -133,10 +107,9 @@ # @data: the measurement value encoded in base64 # # Since: 2.12 -# ## { 'struct': 'SevLaunchMeasureInfo', 'data': {'data': 'str'}, - 'if': 'defined(TARGET_I386)' } + 'if': 'TARGET_I386' } ## # @query-sev-launch-measure: @@ -149,43 +122,44 @@ # # Example: # -# -> { "execute": "query-sev-launch-measure" } -# <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } } -# +# -> { "execute": "query-sev-launch-measure" } +# <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } } ## { 'command': 'query-sev-launch-measure', 'returns': 'SevLaunchMeasureInfo', - 'if': 'defined(TARGET_I386)' } - + 'if': 'TARGET_I386' } ## # @SevCapability: # -# The struct describes capability for a Secure Encrypted Virtualization -# feature. +# The struct describes capability for a Secure Encrypted +# Virtualization feature. +# +# @pdh: Platform Diffie-Hellman key (base64 encoded) # -# @pdh: Platform Diffie-Hellman key (base64 encoded) +# @cert-chain: PDH certificate chain (base64 encoded) # -# @cert-chain: PDH certificate chain (base64 encoded) +# @cpu0-id: Unique ID of CPU0 (base64 encoded) (since 7.1) # # @cbitpos: C-bit location in page table entry # -# @reduced-phys-bits: Number of physical Address bit reduction when SEV is -# enabled +# @reduced-phys-bits: Number of physical Address bit reduction when +# SEV is enabled # # Since: 2.12 ## { 'struct': 'SevCapability', 'data': { 'pdh': 'str', 'cert-chain': 'str', + 'cpu0-id': 'str', 'cbitpos': 'int', 'reduced-phys-bits': 'int'}, - 'if': 'defined(TARGET_I386)' } + 'if': 'TARGET_I386' } ## # @query-sev-capabilities: # -# This command is used to get the SEV capabilities, and is supported on AMD -# X86 platforms only. +# This command is used to get the SEV capabilities, and is supported +# on AMD X86 platforms only. # # Returns: SevCapability objects. # @@ -193,13 +167,13 @@ # # Example: # -# -> { "execute": "query-sev-capabilities" } -# <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE", -# "cbitpos": 47, "reduced-phys-bits": 5}} -# +# -> { "execute": "query-sev-capabilities" } +# <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE", +# "cpu0-id": "2lvmGwo+...61iEinw==", +# "cbitpos": 47, "reduced-phys-bits": 1}} ## { 'command': 'query-sev-capabilities', 'returns': 'SevCapability', - 'if': 'defined(TARGET_I386)' } + 'if': 'TARGET_I386' } ## # @sev-inject-launch-secret: @@ -213,11 +187,48 @@ # @gpa: the guest physical address where secret will be injected. # # Since: 6.0 -# ## { 'command': 'sev-inject-launch-secret', 'data': { 'packet-header': 'str', 'secret': 'str', '*gpa': 'uint64' }, - 'if': 'defined(TARGET_I386)' } + 'if': 'TARGET_I386' } + +## +# @SevAttestationReport: +# +# The struct describes attestation report for a Secure Encrypted +# Virtualization feature. +# +# @data: guest attestation report (base64 encoded) +# +# Since: 6.1 +## +{ 'struct': 'SevAttestationReport', + 'data': { 'data': 'str'}, + 'if': 'TARGET_I386' } + +## +# @query-sev-attestation-report: +# +# This command is used to get the SEV attestation report, and is +# supported on AMD X86 platforms only. +# +# @mnonce: a random 16 bytes value encoded in base64 (it will be +# included in report) +# +# Returns: SevAttestationReport objects. +# +# Since: 6.1 +# +# Example: +# +# -> { "execute" : "query-sev-attestation-report", +# "arguments": { "mnonce": "aaaaaaa" } } +# <- { "return" : { "data": "aaaaaaaabbbddddd"} } +## +{ 'command': 'query-sev-attestation-report', + 'data': { 'mnonce': 'str' }, + 'returns': 'SevAttestationReport', + 'if': 'TARGET_I386' } ## # @dump-skeys: @@ -226,37 +237,34 @@ # # @filename: the path to the file to dump to # -# This command is only supported on s390 architecture. -# # Since: 2.5 # # Example: # -# -> { "execute": "dump-skeys", -# "arguments": { "filename": "/tmp/skeys" } } -# <- { "return": {} } -# +# -> { "execute": "dump-skeys", +# "arguments": { "filename": "/tmp/skeys" } } +# <- { "return": {} } ## { 'command': 'dump-skeys', 'data': { 'filename': 'str' }, - 'if': 'defined(TARGET_S390X)' } + 'if': 'TARGET_S390X' } ## # @GICCapability: # # The struct describes capability for a specific GIC (Generic -# Interrupt Controller) version. These bits are not only decided by -# QEMU/KVM software version, but also decided by the hardware that -# the program is running upon. +# Interrupt Controller) version. These bits are not only decided by +# QEMU/KVM software version, but also decided by the hardware that the +# program is running upon. # -# @version: version of GIC to be described. Currently, only 2 and 3 -# are supported. +# @version: version of GIC to be described. Currently, only 2 and 3 +# are supported. # # @emulated: whether current QEMU/hardware supports emulated GIC -# device in user space. +# device in user space. # -# @kernel: whether current QEMU/hardware supports hardware -# accelerated GIC device in kernel. +# @kernel: whether current QEMU/hardware supports hardware accelerated +# GIC device in kernel. # # Since: 2.6 ## @@ -264,12 +272,12 @@ 'data': { 'version': 'int', 'emulated': 'bool', 'kernel': 'bool' }, - 'if': 'defined(TARGET_ARM)' } + 'if': 'TARGET_ARM' } ## # @query-gic-capabilities: # -# This command is ARM-only. It will return a list of GICCapability +# This command is ARM-only. It will return a list of GICCapability # objects that describe its capability bits. # # Returns: a list of GICCapability objects. @@ -278,10 +286,199 @@ # # Example: # -# -> { "execute": "query-gic-capabilities" } -# <- { "return": [{ "version": 2, "emulated": true, "kernel": false }, -# { "version": 3, "emulated": false, "kernel": true } ] } -# +# -> { "execute": "query-gic-capabilities" } +# <- { "return": [{ "version": 2, "emulated": true, "kernel": false }, +# { "version": 3, "emulated": false, "kernel": true } ] } ## { 'command': 'query-gic-capabilities', 'returns': ['GICCapability'], - 'if': 'defined(TARGET_ARM)' } + 'if': 'TARGET_ARM' } + +## +# @SGXEPCSection: +# +# Information about intel SGX EPC section info +# +# @node: the numa node +# +# @size: the size of EPC section +# +# Since: 7.0 +## +{ 'struct': 'SGXEPCSection', + 'data': { 'node': 'int', + 'size': 'uint64'}} + +## +# @SGXInfo: +# +# Information about intel Safe Guard eXtension (SGX) support +# +# @sgx: true if SGX is supported +# +# @sgx1: true if SGX1 is supported +# +# @sgx2: true if SGX2 is supported +# +# @flc: true if FLC is supported +# +# @sections: The EPC sections info for guest (Since: 7.0) +# +# Since: 6.2 +## +{ 'struct': 'SGXInfo', + 'data': { 'sgx': 'bool', + 'sgx1': 'bool', + 'sgx2': 'bool', + 'flc': 'bool', + 'sections': ['SGXEPCSection']}, + 'if': 'TARGET_I386' } + +## +# @query-sgx: +# +# Returns information about SGX +# +# Returns: @SGXInfo +# +# Since: 6.2 +# +# Example: +# +# -> { "execute": "query-sgx" } +# <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true, +# "flc": true, +# "sections": [{"node": 0, "size": 67108864}, +# {"node": 1, "size": 29360128}]} } +## +{ 'command': 'query-sgx', 'returns': 'SGXInfo', 'if': 'TARGET_I386' } + +## +# @query-sgx-capabilities: +# +# Returns information from host SGX capabilities +# +# Returns: @SGXInfo +# +# Since: 6.2 +# +# Example: +# +# -> { "execute": "query-sgx-capabilities" } +# <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true, +# "flc": true, +# "section" : [{"node": 0, "size": 67108864}, +# {"node": 1, "size": 29360128}]} } +## +{ 'command': 'query-sgx-capabilities', 'returns': 'SGXInfo', 'if': 'TARGET_I386' } + + +## +# @EvtchnPortType: +# +# An enumeration of Xen event channel port types. +# +# @closed: The port is unused. +# +# @unbound: The port is allocated and ready to be bound. +# +# @interdomain: The port is connected as an interdomain interrupt. +# +# @pirq: The port is bound to a physical IRQ (PIRQ). +# +# @virq: The port is bound to a virtual IRQ (VIRQ). +# +# @ipi: The post is an inter-processor interrupt (IPI). +# +# Since: 8.0 +## +{ 'enum': 'EvtchnPortType', + 'data': ['closed', 'unbound', 'interdomain', 'pirq', 'virq', 'ipi'], + 'if': 'TARGET_I386' } + +## +# @EvtchnInfo: +# +# Information about a Xen event channel port +# +# @port: the port number +# +# @vcpu: target vCPU for this port +# +# @type: the port type +# +# @remote-domain: remote domain for interdomain ports +# +# @target: remote port ID, or virq/pirq number +# +# @pending: port is currently active pending delivery +# +# @masked: port is masked +# +# Since: 8.0 +## +{ 'struct': 'EvtchnInfo', + 'data': {'port': 'uint16', + 'vcpu': 'uint32', + 'type': 'EvtchnPortType', + 'remote-domain': 'str', + 'target': 'uint16', + 'pending': 'bool', + 'masked': 'bool'}, + 'if': 'TARGET_I386' } + + +## +# @xen-event-list: +# +# Query the Xen event channels opened by the guest. +# +# Returns: list of open event channel ports. +# +# Since: 8.0 +# +# Example: +# +# -> { "execute": "xen-event-list" } +# <- { "return": [ +# { +# "pending": false, +# "port": 1, +# "vcpu": 1, +# "remote-domain": "qemu", +# "masked": false, +# "type": "interdomain", +# "target": 1 +# }, +# { +# "pending": false, +# "port": 2, +# "vcpu": 0, +# "remote-domain": "", +# "masked": false, +# "type": "virq", +# "target": 0 +# } +# ] +# } +## +{ 'command': 'xen-event-list', + 'returns': ['EvtchnInfo'], + 'if': 'TARGET_I386' } + +## +# @xen-event-inject: +# +# Inject a Xen event channel port (interrupt) to the guest. +# +# @port: The port number +# +# Since: 8.0 +# +# Example: +# +# -> { "execute": "xen-event-inject", "arguments": { "port": 1 } } +# <- { "return": { } } +## +{ 'command': 'xen-event-inject', + 'data': { 'port': 'uint32' }, + 'if': 'TARGET_I386' } diff --git a/qapi/misc.json b/qapi/misc.json index 156f98203e..ec30e5c570 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -11,30 +11,30 @@ ## # @add_client: # -# Allow client connections for VNC, Spice and socket based -# character devices to be passed in to QEMU via SCM_RIGHTS. +# Allow client connections for VNC, Spice and socket based character +# devices to be passed in to QEMU via SCM_RIGHTS. # -# @protocol: protocol name. Valid names are "vnc", "spice" or the -# name of a character device (eg. from -chardev id=XXXX) +# If the FD associated with @fdname is not a socket, the command will +# fail and the FD will be closed. # -# @fdname: file descriptor name previously passed via 'getfd' command +# @protocol: protocol name. Valid names are "vnc", "spice", +# "@dbus-display" or the name of a character device (e.g. from +# -chardev id=XXXX) # -# @skipauth: whether to skip authentication. Only applies -# to "vnc" and "spice" protocols +# @fdname: file descriptor name previously passed via 'getfd' command # -# @tls: whether to perform TLS. Only applies to the "spice" -# protocol +# @skipauth: whether to skip authentication. Only applies to "vnc" +# and "spice" protocols # -# Returns: nothing on success. +# @tls: whether to perform TLS. Only applies to the "spice" protocol # # Since: 0.14 # # Example: # -# -> { "execute": "add_client", "arguments": { "protocol": "vnc", -# "fdname": "myclient" } } -# <- { "return": {} } -# +# -> { "execute": "add_client", "arguments": { "protocol": "vnc", +# "fdname": "myclient" } } +# <- { "return": {} } ## { 'command': 'add_client', 'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool', @@ -62,9 +62,8 @@ # # Example: # -# -> { "execute": "query-name" } -# <- { "return": { "name": "qemu-name" } } -# +# -> { "execute": "query-name" } +# <- { "return": { "name": "qemu-name" } } ## { 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true } @@ -77,14 +76,17 @@ # # @thread-id: ID of the underlying host thread # -# @poll-max-ns: maximum polling time in ns, 0 means polling is disabled -# (since 2.9) +# @poll-max-ns: maximum polling time in ns, 0 means polling is +# disabled (since 2.9) +# +# @poll-grow: how many ns will be added to polling time, 0 means that +# it's not configured (since 2.9) # -# @poll-grow: how many ns will be added to polling time, 0 means that it's not -# configured (since 2.9) +# @poll-shrink: how many ns will be removed from polling time, 0 means +# that it's not configured (since 2.9) # -# @poll-shrink: how many ns will be removed from polling time, 0 means that -# it's not configured (since 2.9) +# @aio-max-batch: maximum number of requests in a batch for the AIO +# engine, 0 means that the engine will use its default (since 6.1) # # Since: 2.0 ## @@ -93,16 +95,17 @@ 'thread-id': 'int', 'poll-max-ns': 'int', 'poll-grow': 'int', - 'poll-shrink': 'int' } } + 'poll-shrink': 'int', + 'aio-max-batch': 'int' } } ## # @query-iothreads: # # Returns a list of information about each iothread. # -# Note: this list excludes the QEMU main loop thread, which is not declared -# using the -object iothread command-line option. It is always the main thread -# of the process. +# Note: this list excludes the QEMU main loop thread, which is not +# declared using the -object iothread command-line option. It is +# always the main thread of the process. # # Returns: a list of @IOThreadInfo for each iothread # @@ -110,19 +113,18 @@ # # Example: # -# -> { "execute": "query-iothreads" } -# <- { "return": [ -# { -# "id":"iothread0", -# "thread-id":3134 -# }, -# { -# "id":"iothread1", -# "thread-id":3135 -# } -# ] -# } -# +# -> { "execute": "query-iothreads" } +# <- { "return": [ +# { +# "id":"iothread0", +# "thread-id":3134 +# }, +# { +# "id":"iothread1", +# "thread-id":3135 +# } +# ] +# } ## { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'], 'allow-preconfig': true } @@ -130,43 +132,46 @@ ## # @stop: # -# Stop all guest VCPU execution. +# Stop guest VM execution. # -# Since: 0.14 +# Since: 0.14 # -# Notes: This function will succeed even if the guest is already in the stopped -# state. In "inmigrate" state, it will ensure that the guest -# remains paused once migration finishes, as if the -S option was -# passed on the command line. +# Notes: This function will succeed even if the guest is already in +# the stopped state. In "inmigrate" state, it will ensure that +# the guest remains paused once migration finishes, as if the -S +# option was passed on the command line. # -# Example: +# In the "suspended" state, it will completely stop the VM and +# cause a transition to the "paused" state. (Since 9.0) # -# -> { "execute": "stop" } -# <- { "return": {} } +# Example: # +# -> { "execute": "stop" } +# <- { "return": {} } ## { 'command': 'stop' } ## # @cont: # -# Resume guest VCPU execution. +# Resume guest VM execution. # -# Since: 0.14 +# Since: 0.14 # -# Returns: If successful, nothing +# Notes: This command will succeed if the guest is currently running. +# It will also succeed if the guest is in the "inmigrate" state; +# in this case, the effect of the command is to make sure the +# guest starts once migration finishes, removing the effect of the +# -S command line option if it was passed. # -# Notes: This command will succeed if the guest is currently running. It -# will also succeed if the guest is in the "inmigrate" state; in -# this case, the effect of the command is to make sure the guest -# starts once migration finishes, removing the effect of the -S -# command line option if it was passed. +# If the VM was previously suspended, and not been reset or woken, +# this command will transition back to the "suspended" state. +# (Since 9.0) # # Example: # -# -> { "execute": "cont" } -# <- { "return": {} } -# +# -> { "execute": "cont" } +# <- { "return": {} } ## { 'command': 'cont' } @@ -175,23 +180,25 @@ # # Exit from "preconfig" state # -# This command makes QEMU exit the preconfig state and proceed with -# VM initialization using configuration data provided on the command line -# and via the QMP monitor during the preconfig state. The command is only -# available during the preconfig state (i.e. when the --preconfig command -# line option was in use). +# This command makes QEMU exit the preconfig state and proceed with VM +# initialization using configuration data provided on the command line +# and via the QMP monitor during the preconfig state. The command is +# only available during the preconfig state (i.e. when the --preconfig +# command line option was in use). +# +# Features: # -# Since 3.0 +# @unstable: This command is experimental. # -# Returns: nothing +# Since: 3.0 # # Example: # -# -> { "execute": "x-exit-preconfig" } -# <- { "return": {} } -# +# -> { "execute": "x-exit-preconfig" } +# <- { "return": {} } ## -{ 'command': 'x-exit-preconfig', 'allow-preconfig': true } +{ 'command': 'x-exit-preconfig', 'allow-preconfig': true, + 'features': [ 'unstable' ] } ## # @human-monitor-command: @@ -203,35 +210,33 @@ # @cpu-index: The CPU to use for commands that require an implicit CPU # # Features: +# # @savevm-monitor-nodes: If present, HMP command savevm only snapshots -# monitor-owned nodes if they have no parents. -# This allows the use of 'savevm' with -# -blockdev. (since 4.2) +# monitor-owned nodes if they have no parents. This allows the +# use of 'savevm' with -blockdev. (since 4.2) # # Returns: the output of the command as a string # # Since: 0.14 # # Notes: This command only exists as a stop-gap. Its use is highly -# discouraged. The semantics of this command are not -# guaranteed: this means that command names, arguments and -# responses can change or be removed at ANY time. Applications -# that rely on long term stability guarantees should NOT -# use this command. +# discouraged. The semantics of this command are not guaranteed: +# this means that command names, arguments and responses can +# change or be removed at ANY time. Applications that rely on +# long term stability guarantees should NOT use this command. # -# Known limitations: +# Known limitations: # -# * This command is stateless, this means that commands that depend -# on state information (such as getfd) might not work +# * This command is stateless, this means that commands that +# depend on state information (such as getfd) might not work # -# * Commands that prompt the user for data don't currently work +# * Commands that prompt the user for data don't currently work # # Example: # -# -> { "execute": "human-monitor-command", -# "arguments": { "command-line": "info kvm" } } -# <- { "return": "kvm support: enabled\r\n" } -# +# -> { "execute": "human-monitor-command", +# "arguments": { "command-line": "info kvm" } } +# <- { "return": "kvm support: enabled\r\n" } ## { 'command': 'human-monitor-command', 'data': {'command-line': 'str', '*cpu-index': 'int'}, @@ -245,24 +250,47 @@ # # @fdname: file descriptor name # -# Returns: Nothing on success -# # Since: 0.14 # -# Notes: If @fdname already exists, the file descriptor assigned to -# it will be closed and replaced by the received file -# descriptor. +# Notes: If @fdname already exists, the file descriptor assigned to it +# will be closed and replaced by the received file descriptor. # -# The 'closefd' command can be used to explicitly close the -# file descriptor when it is no longer needed. +# The 'closefd' command can be used to explicitly close the file +# descriptor when it is no longer needed. # # Example: # -# -> { "execute": "getfd", "arguments": { "fdname": "fd1" } } -# <- { "return": {} } +# -> { "execute": "getfd", "arguments": { "fdname": "fd1" } } +# <- { "return": {} } +## +{ 'command': 'getfd', 'data': {'fdname': 'str'}, 'if': 'CONFIG_POSIX' } + +## +# @get-win32-socket: +# +# Add a socket that was duplicated to QEMU process with +# WSADuplicateSocketW() via WSASocket() & WSAPROTOCOL_INFOW structure +# and assign it a name (the SOCKET is associated with a CRT file +# descriptor) +# +# @info: the WSAPROTOCOL_INFOW structure (encoded in base64) +# +# @fdname: file descriptor name +# +# Since: 8.0 +# +# Notes: If @fdname already exists, the file descriptor assigned to it +# will be closed and replaced by the received file descriptor. +# +# The 'closefd' command can be used to explicitly close the file +# descriptor when it is no longer needed. +# +# Example: # +# -> { "execute": "get-win32-socket", "arguments": { "info": "abcd123..", fdname": "skclient" } } +# <- { "return": {} } ## -{ 'command': 'getfd', 'data': {'fdname': 'str'} } +{ 'command': 'get-win32-socket', 'data': {'info': 'str', 'fdname': 'str'}, 'if': 'CONFIG_WIN32' } ## # @closefd: @@ -271,15 +299,12 @@ # # @fdname: file descriptor name # -# Returns: Nothing on success -# # Since: 0.14 # # Example: # -# -> { "execute": "closefd", "arguments": { "fdname": "fd1" } } -# <- { "return": {} } -# +# -> { "execute": "closefd", "arguments": { "fdname": "fd1" } } +# <- { "return": {} } ## { 'command': 'closefd', 'data': {'fdname': 'str'} } @@ -290,8 +315,8 @@ # # @fdset-id: The ID of the fd set that @fd was added to. # -# @fd: The file descriptor that was received via SCM rights and -# added to the fd set. +# @fd: The file descriptor that was received via SCM rights and added +# to the fd set. # # Since: 1.2 ## @@ -306,21 +331,24 @@ # # @opaque: A free-form string that can be used to describe the fd. # -# Returns: - @AddfdInfo on success -# - If file descriptor was not received, FdNotSupplied -# - If @fdset-id is a negative value, InvalidParameterValue +# Returns: +# @AddfdInfo +# +# Errors: +# - If file descriptor was not received, GenericError +# - If @fdset-id is a negative value, GenericError # -# Notes: The list of fd sets is shared by all monitor connections. +# Notes: +# The list of fd sets is shared by all monitor connections. # -# If @fdset-id is not specified, a new fd set will be created. +# If @fdset-id is not specified, a new fd set will be created. # # Since: 1.2 # # Example: # -# -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } } -# <- { "return": { "fdset-id": 1, "fd": 3 } } -# +# -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } } +# <- { "return": { "fdset-id": 1, "fd": 3 } } ## { 'command': 'add-fd', 'data': { '*fdset-id': 'int', @@ -336,21 +364,21 @@ # # @fd: The file descriptor that is to be removed. # -# Returns: - Nothing on success -# - If @fdset-id or @fd is not found, FdNotFound +# Errors: +# - If @fdset-id or @fd is not found, GenericError # # Since: 1.2 # -# Notes: The list of fd sets is shared by all monitor connections. +# Notes: +# The list of fd sets is shared by all monitor connections. # -# If @fd is not specified, all file descriptors in @fdset-id -# will be removed. +# If @fd is not specified, all file descriptors in @fdset-id will +# be removed. # # Example: # -# -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } } -# <- { "return": {} } -# +# -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } } +# <- { "return": {} } ## { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} } @@ -395,35 +423,34 @@ # # Example: # -# -> { "execute": "query-fdsets" } -# <- { "return": [ -# { -# "fds": [ +# -> { "execute": "query-fdsets" } +# <- { "return": [ # { -# "fd": 30, -# "opaque": "rdonly:/path/to/file" +# "fds": [ +# { +# "fd": 30, +# "opaque": "rdonly:/path/to/file" +# }, +# { +# "fd": 24, +# "opaque": "rdwr:/path/to/file" +# } +# ], +# "fdset-id": 1 # }, # { -# "fd": 24, -# "opaque": "rdwr:/path/to/file" +# "fds": [ +# { +# "fd": 28 +# }, +# { +# "fd": 29 +# } +# ], +# "fdset-id": 0 # } -# ], -# "fdset-id": 1 -# }, -# { -# "fds": [ -# { -# "fd": 28 -# }, -# { -# "fd": 29 -# } -# ], -# "fdset-id": 0 +# ] # } -# ] -# } -# ## { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] } @@ -439,7 +466,7 @@ # @number: accepts a number # # @size: accepts a number followed by an optional suffix (K)ilo, -# (M)ega, (G)iga, (T)era +# (M)ega, (G)iga, (T)era # # Since: 1.5 ## @@ -470,7 +497,8 @@ ## # @CommandLineOptionInfo: # -# Details about a command line option, including its list of parameter details +# Details about a command line option, including its list of parameter +# details # # @option: option name # @@ -488,34 +516,92 @@ # # @option: option name # -# Returns: list of @CommandLineOptionInfo for all options (or for the given -# @option). Returns an error if the given @option doesn't exist. +# Returns: list of @CommandLineOptionInfo for all options (or for the +# given @option). +# +# Errors: +# - if the given @option doesn't exist # # Since: 1.5 # # Example: # -# -> { "execute": "query-command-line-options", -# "arguments": { "option": "option-rom" } } -# <- { "return": [ -# { -# "parameters": [ -# { -# "name": "romfile", -# "type": "string" -# }, -# { -# "name": "bootindex", -# "type": "number" -# } -# ], -# "option": "option-rom" -# } -# ] -# } -# +# -> { "execute": "query-command-line-options", +# "arguments": { "option": "option-rom" } } +# <- { "return": [ +# { +# "parameters": [ +# { +# "name": "romfile", +# "type": "string" +# }, +# { +# "name": "bootindex", +# "type": "number" +# } +# ], +# "option": "option-rom" +# } +# ] +# } ## {'command': 'query-command-line-options', - 'data': { '*option': 'str' }, + 'data': {'*option': 'str'}, 'returns': ['CommandLineOptionInfo'], - 'allow-preconfig': true } + 'allow-preconfig': true} + +## +# @RTC_CHANGE: +# +# Emitted when the guest changes the RTC time. +# +# @offset: offset in seconds between base RTC clock (as specified by +# -rtc base), and new RTC clock value +# +# @qom-path: path to the RTC object in the QOM tree +# +# Note: This event is rate-limited. It is not guaranteed that the RTC +# in the system implements this event, or even that the system has +# an RTC at all. +# +# Since: 0.13 +# +# Example: +# +# <- { "event": "RTC_CHANGE", +# "data": { "offset": 78 }, +# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } +## +{ 'event': 'RTC_CHANGE', + 'data': { 'offset': 'int', 'qom-path': 'str' } } + +## +# @VFU_CLIENT_HANGUP: +# +# Emitted when the client of a TYPE_VFIO_USER_SERVER closes the +# communication channel +# +# @vfu-id: ID of the TYPE_VFIO_USER_SERVER object. It is the last +# component of @vfu-qom-path referenced below +# +# @vfu-qom-path: path to the TYPE_VFIO_USER_SERVER object in the QOM +# tree +# +# @dev-id: ID of attached PCI device +# +# @dev-qom-path: path to attached PCI device in the QOM tree +# +# Since: 7.1 +# +# Example: +# +# <- { "event": "VFU_CLIENT_HANGUP", +# "data": { "vfu-id": "vfu1", +# "vfu-qom-path": "/objects/vfu1", +# "dev-id": "sas1", +# "dev-qom-path": "/machine/peripheral/sas1" }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } +## +{ 'event': 'VFU_CLIENT_HANGUP', + 'data': { 'vfu-id': 'str', 'vfu-qom-path': 'str', + 'dev-id': 'str', 'dev-qom-path': 'str' } } diff --git a/qapi/net.json b/qapi/net.json index af3f5b0fda..0f5a259475 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -6,7 +6,7 @@ # = Net devices ## -{ 'include': 'common.json' } +{ 'include': 'sockets.json' } ## # @set_link: @@ -17,21 +17,20 @@ # # @up: true to set the link status to be up # -# Returns: Nothing on success -# If @name is not a valid network device, DeviceNotFound +# Errors: +# - If @name is not a valid network device, DeviceNotFound # # Since: 0.14 # -# Notes: Not all network adapters support setting link status. This command -# will succeed even if the network adapter does not support link status -# notification. +# Notes: Not all network adapters support setting link status. This +# command will succeed even if the network adapter does not +# support link status notification. # # Example: # -# -> { "execute": "set_link", -# "arguments": { "name": "e1000.0", "up": false } } -# <- { "return": {} } -# +# -> { "execute": "set_link", +# "arguments": { "name": "e1000.0", "up": false } } +# <- { "return": {} } ## { 'command': 'set_link', 'data': {'name': 'str', 'up': 'bool'} } @@ -44,18 +43,18 @@ # # Since: 0.14 # -# Returns: Nothing on success -# If @type is not a valid network backend, DeviceNotFound +# Errors: +# - If @type is not a valid network backend, DeviceNotFound # # Example: # -# -> { "execute": "netdev_add", -# "arguments": { "type": "user", "id": "netdev1", -# "dnssearch": "example.org" } } -# <- { "return": {} } -# +# -> { "execute": "netdev_add", +# "arguments": { "type": "user", "id": "netdev1", +# "dnssearch": [ { "str": "example.org" } ] } } +# <- { "return": {} } ## -{ 'command': 'netdev_add', 'data': 'Netdev', 'boxed': true } +{ 'command': 'netdev_add', 'data': 'Netdev', 'boxed': true, + 'allow-preconfig': true } ## # @netdev_del: @@ -64,18 +63,18 @@ # # @id: the name of the network backend to remove # -# Returns: Nothing on success -# If @id is not a valid network backend, DeviceNotFound +# Errors: +# - If @id is not a valid network backend, DeviceNotFound # # Since: 0.14 # # Example: # -# -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } } -# <- { "return": {} } -# +# -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } } +# <- { "return": {} } ## -{ 'command': 'netdev_del', 'data': {'id': 'str'} } +{ 'command': 'netdev_del', 'data': {'id': 'str'}, + 'allow-preconfig': true } ## # @NetLegacyNicOptions: @@ -103,27 +102,36 @@ '*vectors': 'uint32' } } ## +# @String: +# +# A fat type wrapping 'str', to be embedded in lists. +# +# Since: 1.2 +## +{ 'struct': 'String', + 'data': { + 'str': 'str' } } + +## # @NetdevUserOptions: # -# Use the user mode network stack which requires no administrator privilege to -# run. +# Use the user mode network stack which requires no administrator +# privilege to run. # # @hostname: client hostname reported by the builtin DHCP server # # @restrict: isolate the guest from the host # -# @ipv4: whether to support IPv4, default true for enabled -# (since 2.6) +# @ipv4: whether to support IPv4, default true for enabled (since 2.6) # -# @ipv6: whether to support IPv6, default true for enabled -# (since 2.6) +# @ipv6: whether to support IPv6, default true for enabled (since 2.6) # # @ip: legacy parameter, use net= instead # -# @net: IP network address that the guest will see, in the -# form addr[/netmask] The netmask is optional, and can be -# either in the form a.b.c.d or as a number of valid top-most -# bits. Default is 10.0.2.0/24. +# @net: IP network address that the guest will see, in the form +# addr[/netmask] The netmask is optional, and can be either in the +# form a.b.c.d or as a number of valid top-most bits. Default is +# 10.0.2.0/24. # # @host: guest-visible address of the host # @@ -132,34 +140,34 @@ # @bootfile: BOOTP filename, for use with tftp= # # @dhcpstart: the first of the 16 IPs the built-in DHCP server can -# assign +# assign # # @dns: guest-visible address of the virtual nameserver # -# @dnssearch: list of DNS suffixes to search, passed as DHCP option -# to the guest +# @dnssearch: list of DNS suffixes to search, passed as DHCP option to +# the guest # # @domainname: guest-visible domain name of the virtual nameserver -# (since 3.0) +# (since 3.0) # -# @ipv6-prefix: IPv6 network prefix (default is fec0::) (since -# 2.6). The network prefix is given in the usual -# hexadecimal IPv6 address notation. +# @ipv6-prefix: IPv6 network prefix (default is fec0::) (since 2.6). +# The network prefix is given in the usual hexadecimal IPv6 +# address notation. # -# @ipv6-prefixlen: IPv6 network prefix length (default is 64) -# (since 2.6) +# @ipv6-prefixlen: IPv6 network prefix length (default is 64) (since +# 2.6) # # @ipv6-host: guest-visible IPv6 address of the host (since 2.6) # -# @ipv6-dns: guest-visible IPv6 address of the virtual -# nameserver (since 2.6) +# @ipv6-dns: guest-visible IPv6 address of the virtual nameserver +# (since 2.6) # # @smb: root directory of the built-in SMB server # # @smbserver: IP address of the built-in SMB server # # @hostfwd: redirect incoming TCP or UDP host connections to guest -# endpoints +# endpoints # # @guestfwd: forward guest TCP connections # @@ -202,7 +210,7 @@ # @fd: file descriptor of an already opened tap # # @fds: multiple file descriptors of already opened multiqueue capable -# tap +# tap # # @script: script to initialize the interface # @@ -212,7 +220,7 @@ # # @helper: command to execute to configure bridge # -# @sndbuf: send buffer limit. Understands [TGMKkb] suffixes. +# @sndbuf: send buffer limit. Understands [TGMKkb] suffixes. # # @vnet_hdr: enable the IFF_VNET_HDR flag on the tap interface # @@ -221,14 +229,14 @@ # @vhostfd: file descriptor of an already opened vhost net device # # @vhostfds: file descriptors of multiple already opened vhost net -# devices +# devices # # @vhostforce: vhost on for non-MSIX virtio guests # # @queues: number of queues to be created for multiqueue capable tap # -# @poll-us: maximum number of microseconds that could -# be spent on busy polling for tap (since 2.7) +# @poll-us: maximum number of microseconds that could be spent on busy +# polling for tap (since 2.7) # # Since: 1.2 ## @@ -296,13 +304,12 @@ # # @udp: use the udp version of l2tpv3 encapsulation # -# @cookie64: use 64 bit coookies +# @cookie64: use 64 bit cookies # # @counter: have sequence counter # -# @pincounter: pin sequence counter to zero - -# workaround for buggy implementations or -# networks with packet reorder +# @pincounter: pin sequence counter to zero - workaround for buggy +# implementations or networks with packet reorder # # @txcookie: 32 or 64 bit transmit cookie # @@ -310,11 +317,11 @@ # # @txsession: 32 bit transmit session # -# @rxsession: 32 bit receive session - if not specified -# set to the same value as transmit +# @rxsession: 32 bit receive session - if not specified set to the +# same value as transmit # -# @offset: additional offset - allows the insertion of -# additional application-specific data before the packet payload +# @offset: additional offset - allows the insertion of additional +# application-specific data before the packet payload # # Since: 2.1 ## @@ -379,7 +386,9 @@ # Connect two or more net clients through a software hub. # # @hubid: hub identifier number -# @netdev: used to connect hub to a netdev instead of a device (since 2.12) +# +# @netdev: used to connect hub to a netdev instead of a device (since +# 2.12) # # Since: 1.2 ## @@ -393,12 +402,12 @@ # # Connect a client to a netmap-enabled NIC or to a VALE switch port # -# @ifname: Either the name of an existing network interface supported by -# netmap, or the name of a VALE port (created on the fly). -# A VALE port name is in the form 'valeXXX:YYY', where XXX and -# YYY are non-negative integers. XXX identifies a switch and -# YYY identifies a port of the switch. VALE ports having the -# same XXX are therefore connected to the same switch. +# @ifname: Either the name of an existing network interface supported +# by netmap, or the name of a VALE port (created on the fly). A +# VALE port name is in the form 'valeXXX:YYY', where XXX and YYY +# are non-negative integers. XXX identifies a switch and YYY +# identifies a port of the switch. VALE ports having the same XXX +# are therefore connected to the same switch. # # @devname: path of the netmap device (default: '/dev/netmap'). # @@ -410,6 +419,63 @@ '*devname': 'str' } } ## +# @AFXDPMode: +# +# Attach mode for a default XDP program +# +# @skb: generic mode, no driver support necessary +# +# @native: DRV mode, program is attached to a driver, packets are +# passed to the socket without allocation of skb. +# +# Since: 8.2 +## +{ 'enum': 'AFXDPMode', + 'data': [ 'native', 'skb' ], + 'if': 'CONFIG_AF_XDP' } + +## +# @NetdevAFXDPOptions: +# +# AF_XDP network backend +# +# @ifname: The name of an existing network interface. +# +# @mode: Attach mode for a default XDP program. If not specified, +# then 'native' will be tried first, then 'skb'. +# +# @force-copy: Force XDP copy mode even if device supports zero-copy. +# (default: false) +# +# @queues: number of queues to be used for multiqueue interfaces +# (default: 1). +# +# @start-queue: Use @queues starting from this queue number +# (default: 0). +# +# @inhibit: Don't load a default XDP program, use one already loaded +# to the interface (default: false). Requires @sock-fds. +# +# @sock-fds: A colon (:) separated list of file descriptors for +# already open but not bound AF_XDP sockets in the queue order. +# One fd per queue. These descriptors should already be added +# into XDP socket map for corresponding queues. Requires +# @inhibit. +# +# Since: 8.2 +## +{ 'struct': 'NetdevAFXDPOptions', + 'data': { + 'ifname': 'str', + '*mode': 'AFXDPMode', + '*force-copy': 'bool', + '*queues': 'int', + '*start-queue': 'int', + '*inhibit': 'bool', + '*sock-fds': 'str' }, + 'if': 'CONFIG_AF_XDP' } + +## # @NetdevVhostUserOptions: # # Vhost-user network backend @@ -419,7 +485,7 @@ # @vhostforce: vhost on for non-MSIX virtio guests (default: false). # # @queues: number of queues to be created for multiqueue vhost-user -# (default: 1) (Since 2.5) +# (default: 1) (Since 2.5) # # Since: 2.1 ## @@ -434,34 +500,227 @@ # # Vhost-vdpa network backend # -# vDPA device is a device that uses a datapath which complies with the virtio -# specifications with a vendor specific control path. +# vDPA device is a device that uses a datapath which complies with the +# virtio specifications with a vendor specific control path. +# +# @vhostdev: path of vhost-vdpa device (default:'/dev/vhost-vdpa-0') # -# @vhostdev: path of vhost-vdpa device -# (default:'/dev/vhost-vdpa-0') +# @vhostfd: file descriptor of an already opened vhost vdpa device # # @queues: number of queues to be created for multiqueue vhost-vdpa -# (default: 1) +# (default: 1) +# +# @x-svq: Start device with (experimental) shadow virtqueue. (Since +# 7.1) (default: false) +# +# Features: +# +# @unstable: Member @x-svq is experimental. # # Since: 5.1 ## { 'struct': 'NetdevVhostVDPAOptions', 'data': { '*vhostdev': 'str', - '*queues': 'int' } } + '*vhostfd': 'str', + '*queues': 'int', + '*x-svq': {'type': 'bool', 'features' : [ 'unstable'] } } } + +## +# @NetdevVmnetHostOptions: +# +# vmnet (host mode) network backend. +# +# Allows the vmnet interface to communicate with other vmnet +# interfaces that are in host mode and also with the host. +# +# @start-address: The starting IPv4 address to use for the interface. +# Must be in the private IP range (RFC 1918). Must be specified +# along with @end-address and @subnet-mask. This address is used +# as the gateway address. The subsequent address up to and +# including end-address are placed in the DHCP pool. +# +# @end-address: The DHCP IPv4 range end address to use for the +# interface. Must be in the private IP range (RFC 1918). Must be +# specified along with @start-address and @subnet-mask. +# +# @subnet-mask: The IPv4 subnet mask to use on the interface. Must be +# specified along with @start-address and @subnet-mask. +# +# @isolated: Enable isolation for this interface. Interface isolation +# ensures that vmnet interface is not able to communicate with any +# other vmnet interfaces. Only communication with host is +# allowed. Requires at least macOS Big Sur 11.0. +# +# @net-uuid: The identifier (UUID) to uniquely identify the isolated +# network vmnet interface should be added to. If set, no DHCP +# service is provided for this interface and network communication +# is allowed only with other interfaces added to this network +# identified by the UUID. Requires at least macOS Big Sur 11.0. +# +# Since: 7.1 +## +{ 'struct': 'NetdevVmnetHostOptions', + 'data': { + '*start-address': 'str', + '*end-address': 'str', + '*subnet-mask': 'str', + '*isolated': 'bool', + '*net-uuid': 'str' }, + 'if': 'CONFIG_VMNET' } + +## +# @NetdevVmnetSharedOptions: +# +# vmnet (shared mode) network backend. +# +# Allows traffic originating from the vmnet interface to reach the +# Internet through a network address translator (NAT). The vmnet +# interface can communicate with the host and with other shared mode +# interfaces on the same subnet. If no DHCP settings, subnet mask and +# IPv6 prefix specified, the interface can communicate with any of +# other interfaces in shared mode. +# +# @start-address: The starting IPv4 address to use for the interface. +# Must be in the private IP range (RFC 1918). Must be specified +# along with @end-address and @subnet-mask. This address is used +# as the gateway address. The subsequent address up to and +# including end-address are placed in the DHCP pool. +# +# @end-address: The DHCP IPv4 range end address to use for the +# interface. Must be in the private IP range (RFC 1918). Must be +# specified along with @start-address and @subnet-mask. +# +# @subnet-mask: The IPv4 subnet mask to use on the interface. Must be +# specified along with @start-address and @subnet-mask. +# +# @isolated: Enable isolation for this interface. Interface isolation +# ensures that vmnet interface is not able to communicate with any +# other vmnet interfaces. Only communication with host is +# allowed. Requires at least macOS Big Sur 11.0. +# +# @nat66-prefix: The IPv6 prefix to use into guest network. Must be a +# unique local address i.e. start with fd00::/8 and have length of +# 64. +# +# Since: 7.1 +## +{ 'struct': 'NetdevVmnetSharedOptions', + 'data': { + '*start-address': 'str', + '*end-address': 'str', + '*subnet-mask': 'str', + '*isolated': 'bool', + '*nat66-prefix': 'str' }, + 'if': 'CONFIG_VMNET' } + +## +# @NetdevVmnetBridgedOptions: +# +# vmnet (bridged mode) network backend. +# +# Bridges the vmnet interface with a physical network interface. +# +# @ifname: The name of the physical interface to be bridged. +# +# @isolated: Enable isolation for this interface. Interface isolation +# ensures that vmnet interface is not able to communicate with any +# other vmnet interfaces. Only communication with host is +# allowed. Requires at least macOS Big Sur 11.0. +# +# Since: 7.1 +## +{ 'struct': 'NetdevVmnetBridgedOptions', + 'data': { + 'ifname': 'str', + '*isolated': 'bool' }, + 'if': 'CONFIG_VMNET' } + +## +# @NetdevStreamOptions: +# +# Configuration info for stream socket netdev +# +# @addr: socket address to listen on (server=true) or connect to +# (server=false) +# +# @server: create server socket (default: false) +# +# @reconnect: For a client socket, if a socket is disconnected, then +# attempt a reconnect after the given number of seconds. Setting +# this to zero disables this function. (default: 0) (since 8.0) +# +# Only SocketAddress types 'unix', 'inet' and 'fd' are supported. +# +# Since: 7.2 +## +{ 'struct': 'NetdevStreamOptions', + 'data': { + 'addr': 'SocketAddress', + '*server': 'bool', + '*reconnect': 'uint32' } } + +## +# @NetdevDgramOptions: +# +# Configuration info for datagram socket netdev. +# +# @remote: remote address +# +# @local: local address +# +# Only SocketAddress types 'unix', 'inet' and 'fd' are supported. +# +# If remote address is present and it's a multicast address, local +# address is optional. Otherwise local address is required and remote +# address is optional. +# +# .. table:: Valid parameters combination table +# :widths: auto +# +# ============= ======== ===== +# remote local okay? +# ============= ======== ===== +# absent absent no +# absent not fd no +# absent fd yes +# multicast absent yes +# multicast present yes +# not multicast absent no +# not multicast present yes +# ============= ======== ===== +# +# Since: 7.2 +## +{ 'struct': 'NetdevDgramOptions', + 'data': { + '*local': 'SocketAddress', + '*remote': 'SocketAddress' } } ## # @NetClientDriver: # # Available netdev drivers. # -# Since: 2.7 +# @l2tpv3: since 2.1 +# @vhost-vdpa: since 5.1 +# @vmnet-host: since 7.1 +# @vmnet-shared: since 7.1 +# @vmnet-bridged: since 7.1 +# @stream: since 7.2 +# @dgram: since 7.2 +# @af-xdp: since 8.2 # -# @vhost-vdpa since 5.1 +# Since: 2.7 ## { 'enum': 'NetClientDriver', - 'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde', - 'bridge', 'hubport', 'netmap', 'vhost-user', 'vhost-vdpa' ] } + 'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'stream', + 'dgram', 'vde', 'bridge', 'hubport', 'netmap', 'vhost-user', + 'vhost-vdpa', + { 'name': 'af-xdp', 'if': 'CONFIG_AF_XDP' }, + { 'name': 'vmnet-host', 'if': 'CONFIG_VMNET' }, + { 'name': 'vmnet-shared', 'if': 'CONFIG_VMNET' }, + { 'name': 'vmnet-bridged', 'if': 'CONFIG_VMNET' }] } ## # @Netdev: @@ -473,8 +732,6 @@ # @type: Specify the driver used for interpreting remaining arguments. # # Since: 1.2 -# -# 'l2tpv3' - since 2.1 ## { 'union': 'Netdev', 'base': { 'id': 'str', 'type': 'NetClientDriver' }, @@ -485,12 +742,22 @@ 'tap': 'NetdevTapOptions', 'l2tpv3': 'NetdevL2TPv3Options', 'socket': 'NetdevSocketOptions', + 'stream': 'NetdevStreamOptions', + 'dgram': 'NetdevDgramOptions', 'vde': 'NetdevVdeOptions', 'bridge': 'NetdevBridgeOptions', 'hubport': 'NetdevHubPortOptions', 'netmap': 'NetdevNetmapOptions', + 'af-xdp': { 'type': 'NetdevAFXDPOptions', + 'if': 'CONFIG_AF_XDP' }, 'vhost-user': 'NetdevVhostUserOptions', - 'vhost-vdpa': 'NetdevVhostVDPAOptions' } } + 'vhost-vdpa': 'NetdevVhostVDPAOptions', + 'vmnet-host': { 'type': 'NetdevVmnetHostOptions', + 'if': 'CONFIG_VMNET' }, + 'vmnet-shared': { 'type': 'NetdevVmnetSharedOptions', + 'if': 'CONFIG_VMNET' }, + 'vmnet-bridged': { 'type': 'NetdevVmnetBridgedOptions', + 'if': 'CONFIG_VMNET' } } } ## # @RxState: @@ -561,41 +828,42 @@ # @name: net client name # # Returns: list of @RxFilterInfo for all NICs (or for the given NIC). -# Returns an error if the given @name doesn't exist, or given -# NIC doesn't support rx-filter querying, or given net client -# isn't a NIC. +# +# Errors: +# - if the given @name doesn't exist +# - if the given NIC doesn't support rx-filter querying +# - if the given net client isn't a NIC # # Since: 1.6 # # Example: # -# -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } } -# <- { "return": [ -# { -# "promiscuous": true, -# "name": "vnet0", -# "main-mac": "52:54:00:12:34:56", -# "unicast": "normal", -# "vlan": "normal", -# "vlan-table": [ -# 4, -# 0 -# ], -# "unicast-table": [ -# ], -# "multicast": "normal", -# "multicast-overflow": false, -# "unicast-overflow": false, -# "multicast-table": [ -# "01:00:5e:00:00:01", -# "33:33:00:00:00:01", -# "33:33:ff:12:34:56" -# ], -# "broadcast-allowed": false -# } -# ] -# } -# +# -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } } +# <- { "return": [ +# { +# "promiscuous": true, +# "name": "vnet0", +# "main-mac": "52:54:00:12:34:56", +# "unicast": "normal", +# "vlan": "normal", +# "vlan-table": [ +# 4, +# 0 +# ], +# "unicast-table": [ +# ], +# "multicast": "normal", +# "multicast-overflow": false, +# "unicast-overflow": false, +# "multicast-table": [ +# "01:00:5e:00:00:01", +# "33:33:00:00:00:01", +# "33:33:ff:12:34:56" +# ], +# "broadcast-allowed": false +# } +# ] +# } ## { 'command': 'query-rx-filter', 'data': { '*name': 'str' }, @@ -604,8 +872,8 @@ ## # @NIC_RX_FILTER_CHANGED: # -# Emitted once until the 'query-rx-filter' command is executed, the first event -# will always be emitted +# Emitted once until the 'query-rx-filter' command is executed, the +# first event will always be emitted # # @name: net client name # @@ -615,12 +883,10 @@ # # Example: # -# <- { "event": "NIC_RX_FILTER_CHANGED", -# "data": { "name": "vnet0", -# "path": "/machine/peripheral/vnet0/virtio-backend" }, -# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } } -# } -# +# <- { "event": "NIC_RX_FILTER_CHANGED", +# "data": { "name": "vnet0", +# "path": "/machine/peripheral/vnet0/virtio-backend" }, +# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } } ## { 'event': 'NIC_RX_FILTER_CHANGED', 'data': { '*name': 'str', 'path': 'str' } } @@ -631,7 +897,7 @@ # Parameters for self-announce timers # # @initial: Initial delay (in ms) before sending the first GARP/RARP -# announcement +# announcement # # @max: Maximum delay (in ms) between GARP/RARP announcement packets # @@ -639,12 +905,12 @@ # # @step: Delay increase (in ms) after each self-announcement attempt # -# @interfaces: An optional list of interface names, which restricts the -# announcement to the listed interfaces. (Since 4.1) +# @interfaces: An optional list of interface names, which restricts +# the announcement to the listed interfaces. (Since 4.1) # # @id: A name to be used to identify an instance of announce-timers -# and to allow it to modified later. Not for use as -# part of the migration parameters. (Since 4.1) +# and to allow it to modified later. Not for use as part of the +# migration parameters. (Since 4.1) # # Since: 4.0 ## @@ -660,16 +926,17 @@ ## # @announce-self: # -# Trigger generation of broadcast RARP frames to update network switches. -# This can be useful when network bonds fail-over the active slave. +# Trigger generation of broadcast RARP frames to update network +# switches. This can be useful when network bonds fail-over the +# active slave. # # Example: # -# -> { "execute": "announce-self", -# "arguments": { -# "initial": 50, "max": 550, "rounds": 10, "step": 50, -# "interfaces": ["vn2", "vn3"], "id": "bob" } } -# <- { "return": {} } +# -> { "execute": "announce-self", +# "arguments": { +# "initial": 50, "max": 550, "rounds": 10, "step": 50, +# "interfaces": ["vn2", "vn3"], "id": "bob" } } +# <- { "return": {} } # # Since: 4.0 ## @@ -679,18 +946,66 @@ ## # @FAILOVER_NEGOTIATED: # -# Emitted when VIRTIO_NET_F_STANDBY was enabled during feature negotiation. -# Failover primary devices which were hidden (not hotplugged when requested) -# before will now be hotplugged by the virtio-net standby device. +# Emitted when VIRTIO_NET_F_STANDBY was enabled during feature +# negotiation. Failover primary devices which were hidden (not +# hotplugged when requested) before will now be hotplugged by the +# virtio-net standby device. +# +# @device-id: QEMU device id of the unplugged device # -# device-id: QEMU device id of the unplugged device # Since: 4.2 # # Example: # -# <- { "event": "FAILOVER_NEGOTIATED", -# "data": "net1" } -# +# <- { "event": "FAILOVER_NEGOTIATED", +# "data": { "device-id": "net1" }, +# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } } ## { 'event': 'FAILOVER_NEGOTIATED', 'data': {'device-id': 'str'} } + +## +# @NETDEV_STREAM_CONNECTED: +# +# Emitted when the netdev stream backend is connected +# +# @netdev-id: QEMU netdev id that is connected +# +# @addr: The destination address +# +# Since: 7.2 +# +# Examples: +# +# <- { "event": "NETDEV_STREAM_CONNECTED", +# "data": { "netdev-id": "netdev0", +# "addr": { "port": "47666", "ipv6": true, +# "host": "::1", "type": "inet" } }, +# "timestamp": { "seconds": 1666269863, "microseconds": 311222 } } +# +# <- { "event": "NETDEV_STREAM_CONNECTED", +# "data": { "netdev-id": "netdev0", +# "addr": { "path": "/tmp/qemu0", "type": "unix" } }, +# "timestamp": { "seconds": 1666269706, "microseconds": 413651 } } +## +{ 'event': 'NETDEV_STREAM_CONNECTED', + 'data': { 'netdev-id': 'str', + 'addr': 'SocketAddress' } } + +## +# @NETDEV_STREAM_DISCONNECTED: +# +# Emitted when the netdev stream backend is disconnected +# +# @netdev-id: QEMU netdev id that is disconnected +# +# Since: 7.2 +# +# Example: +# +# <- { 'event': 'NETDEV_STREAM_DISCONNECTED', +# 'data': {'netdev-id': 'netdev0'}, +# 'timestamp': {'seconds': 1663330937, 'microseconds': 526695} } +## +{ 'event': 'NETDEV_STREAM_DISCONNECTED', + 'data': { 'netdev-id': 'str' } } diff --git a/qapi/opts-visitor.c b/qapi/opts-visitor.c index 587f31baf6..8f1efab8b9 100644 --- a/qapi/opts-visitor.c +++ b/qapi/opts-visitor.c @@ -454,8 +454,8 @@ opts_type_uint64(Visitor *v, const char *name, uint64_t *obj, Error **errp) OptsVisitor *ov = to_ov(v); const QemuOpt *opt; const char *str; - unsigned long long val; - char *endptr; + uint64_t val; + const char *endptr; if (ov->list_mode == LM_UNSIGNED_INTERVAL) { *obj = ov->range_next.u; @@ -471,18 +471,18 @@ opts_type_uint64(Visitor *v, const char *name, uint64_t *obj, Error **errp) /* we've gotten past lookup_scalar() */ assert(ov->list_mode == LM_NONE || ov->list_mode == LM_IN_PROGRESS); - if (parse_uint(str, &val, &endptr, 0) == 0 && val <= UINT64_MAX) { + if (parse_uint(str, &endptr, 0, &val) == 0) { if (*endptr == '\0') { *obj = val; processed(ov, name); return true; } if (*endptr == '-' && ov->list_mode == LM_IN_PROGRESS) { - unsigned long long val2; + uint64_t val2; str = endptr + 1; - if (parse_uint_full(str, &val2, 0) == 0 && - val2 <= UINT64_MAX && val <= val2 && + if (parse_uint_full(str, 0, &val2) == 0 && + val <= val2 && val2 - val < OPTS_VISITOR_RANGE_MAX) { ov->range_next.u = val; ov->range_limit.u = val2; diff --git a/qapi/pci.json b/qapi/pci.json index ee7c659fec..08bf695863 100644 --- a/qapi/pci.json +++ b/qapi/pci.json @@ -29,8 +29,9 @@ # # @bar: the index of the Base Address Register for this region # -# @type: - 'io' if the region is a PIO region -# - 'memory' if the region is a MMIO region +# @type: +# - 'io' if the region is a PIO region +# - 'memory' if the region is a MMIO region # # @size: memory size # @@ -49,21 +50,21 @@ # # Information about a bus of a PCI Bridge device # -# @number: primary bus interface number. This should be the number of the -# bus the device resides on. +# @number: primary bus interface number. This should be the number of +# the bus the device resides on. # -# @secondary: secondary bus interface number. This is the number of the -# main bus for the bridge +# @secondary: secondary bus interface number. This is the number of +# the main bus for the bridge # # @subordinate: This is the highest number bus that resides below the -# bridge. +# bridge. # # @io_range: The PIO range for all devices on this bridge # # @memory_range: The MMIO range for all devices on this bridge # -# @prefetchable_range: The range of prefetchable MMIO for all devices on -# this bridge +# @prefetchable_range: The range of prefetchable MMIO for all devices +# on this bridge # # Since: 2.4 ## @@ -145,8 +146,8 @@ # # @regions: a list of the PCI I/O regions associated with the device # -# Notes: the contents of @class_info.desc are not stable and should only be -# treated as informational. +# Notes: the contents of @class_info.desc are not stable and should +# only be treated as informational. # # Since: 0.14 ## @@ -174,143 +175,143 @@ # # Return information about the PCI bus topology of the guest. # -# Returns: a list of @PciInfo for each PCI bus. Each bus is -# represented by a json-object, which has a key with a json-array of -# all PCI devices attached to it. Each device is represented by a -# json-object. +# Returns: a list of @PciInfo for each PCI bus. Each bus is +# represented by a json-object, which has a key with a json-array +# of all PCI devices attached to it. Each device is represented +# by a json-object. # # Since: 0.14 # # Example: # -# -> { "execute": "query-pci" } -# <- { "return": [ -# { -# "bus": 0, -# "devices": [ -# { -# "bus": 0, -# "qdev_id": "", -# "slot": 0, -# "class_info": { -# "class": 1536, -# "desc": "Host bridge" -# }, -# "id": { -# "device": 32902, -# "vendor": 4663 -# }, -# "function": 0, -# "regions": [ -# ] -# }, -# { -# "bus": 0, -# "qdev_id": "", -# "slot": 1, -# "class_info": { -# "class": 1537, -# "desc": "ISA bridge" -# }, -# "id": { -# "device": 32902, -# "vendor": 28672 -# }, -# "function": 0, -# "regions": [ -# ] -# }, -# { -# "bus": 0, -# "qdev_id": "", -# "slot": 1, -# "class_info": { -# "class": 257, -# "desc": "IDE controller" -# }, -# "id": { -# "device": 32902, -# "vendor": 28688 -# }, -# "function": 1, -# "regions": [ -# { -# "bar": 4, -# "size": 16, -# "address": 49152, -# "type": "io" -# } -# ] -# }, -# { -# "bus": 0, -# "qdev_id": "", -# "slot": 2, -# "class_info": { -# "class": 768, -# "desc": "VGA controller" -# }, -# "id": { -# "device": 4115, -# "vendor": 184 -# }, -# "function": 0, -# "regions": [ -# { -# "prefetch": true, -# "mem_type_64": false, -# "bar": 0, -# "size": 33554432, -# "address": 4026531840, -# "type": "memory" -# }, -# { -# "prefetch": false, -# "mem_type_64": false, -# "bar": 1, -# "size": 4096, -# "address": 4060086272, -# "type": "memory" -# }, -# { -# "prefetch": false, -# "mem_type_64": false, -# "bar": 6, -# "size": 65536, -# "address": -1, -# "type": "memory" -# } -# ] -# }, -# { -# "bus": 0, -# "qdev_id": "", -# "irq": 11, -# "slot": 4, -# "class_info": { -# "class": 1280, -# "desc": "RAM controller" -# }, -# "id": { -# "device": 6900, -# "vendor": 4098 -# }, -# "function": 0, -# "regions": [ -# { -# "bar": 0, -# "size": 32, -# "address": 49280, -# "type": "io" -# } -# ] -# } -# ] -# } -# ] -# } -# -# Note: This example has been shortened as the real response is too long. -# +# -> { "execute": "query-pci" } +# <- { "return": [ +# { +# "bus": 0, +# "devices": [ +# { +# "bus": 0, +# "qdev_id": "", +# "slot": 0, +# "class_info": { +# "class": 1536, +# "desc": "Host bridge" +# }, +# "id": { +# "device": 32902, +# "vendor": 4663 +# }, +# "function": 0, +# "regions": [ +# ] +# }, +# { +# "bus": 0, +# "qdev_id": "", +# "slot": 1, +# "class_info": { +# "class": 1537, +# "desc": "ISA bridge" +# }, +# "id": { +# "device": 32902, +# "vendor": 28672 +# }, +# "function": 0, +# "regions": [ +# ] +# }, +# { +# "bus": 0, +# "qdev_id": "", +# "slot": 1, +# "class_info": { +# "class": 257, +# "desc": "IDE controller" +# }, +# "id": { +# "device": 32902, +# "vendor": 28688 +# }, +# "function": 1, +# "regions": [ +# { +# "bar": 4, +# "size": 16, +# "address": 49152, +# "type": "io" +# } +# ] +# }, +# { +# "bus": 0, +# "qdev_id": "", +# "slot": 2, +# "class_info": { +# "class": 768, +# "desc": "VGA controller" +# }, +# "id": { +# "device": 4115, +# "vendor": 184 +# }, +# "function": 0, +# "regions": [ +# { +# "prefetch": true, +# "mem_type_64": false, +# "bar": 0, +# "size": 33554432, +# "address": 4026531840, +# "type": "memory" +# }, +# { +# "prefetch": false, +# "mem_type_64": false, +# "bar": 1, +# "size": 4096, +# "address": 4060086272, +# "type": "memory" +# }, +# { +# "prefetch": false, +# "mem_type_64": false, +# "bar": 6, +# "size": 65536, +# "address": -1, +# "type": "memory" +# } +# ] +# }, +# { +# "bus": 0, +# "qdev_id": "", +# "irq": 11, +# "slot": 4, +# "class_info": { +# "class": 1280, +# "desc": "RAM controller" +# }, +# "id": { +# "device": 6900, +# "vendor": 4098 +# }, +# "function": 0, +# "regions": [ +# { +# "bar": 0, +# "size": 32, +# "address": 49280, +# "type": "io" +# } +# ] +# } +# ] +# } +# ] +# } +# +# Note: This example has been shortened as the real response is too +# long. ## { 'command': 'query-pci', 'returns': ['PciInfo'] } diff --git a/qapi/pragma.json b/qapi/pragma.json index 3bc0335d1f..59fbe74b8c 100644 --- a/qapi/pragma.json +++ b/qapi/pragma.json @@ -1,9 +1,12 @@ +# -*- Mode: Python -*- +# vim: filetype=python + { 'pragma': { 'doc-required': true } } -# Whitelists to permit QAPI rule violations; think twice before you -# add to them! +# Entries in these lists are allowed to violate the QAPI rules (for +# historical reasons); think twice before you add to them! { 'pragma': { - # Commands allowed to return a non-dictionary: + # Command names containing '_' 'command-name-exceptions': [ 'add_client', 'block_resize', @@ -21,12 +24,68 @@ 'system_powerdown', 'system_reset', 'system_wakeup' ], + # Commands allowed to return a non-dictionary 'command-returns-exceptions': [ 'human-monitor-command', 'qom-get', 'query-tpm-models', 'query-tpm-types', 'ringbuf-read' ], + # Types, commands, and events with undocumented members / arguments: + 'documentation-exceptions': [ + 'AbortWrapper', + 'AudiodevDriver', + 'BlkdebugEvent', + 'BlockDirtyBitmapAddWrapper', + 'BlockDirtyBitmapMergeWrapper', + 'BlockDirtyBitmapWrapper', + 'BlockdevBackupWrapper', + 'BlockdevDriver', + 'BlockdevQcow2EncryptionFormat', + 'BlockdevSnapshotInternalWrapper', + 'BlockdevSnapshotSyncWrapper', + 'BlockdevSnapshotWrapper', + 'BlockdevVmdkAdapterType', + 'ChardevBackendKind', + 'CpuS390Entitlement', + 'CpuS390Polarization', + 'CpuS390State', + 'CxlCorErrorType', + 'DisplayProtocol', + 'DriveBackupWrapper', + 'DummyBlockCoreForceArrays', + 'DummyForceArrays', + 'DummyVirtioForceArrays', + 'GrabToggleKeys', + 'HotKeyMod', + 'ImageInfoSpecificKind', + 'InputAxis', + 'InputButton', + 'IscsiHeaderDigest', + 'IscsiTransport', + 'JSONType', + 'KeyValueKind', + 'MemoryDeviceInfoKind', + 'NetClientDriver', + 'ObjectType', + 'PciMemoryRegion', + 'QCryptoAkCipherKeyType', + 'QCryptodevBackendServiceType', + 'QKeyCode', + 'RbdAuthMode', + 'RbdImageEncryptionFormat', + 'String', + 'StringWrapper', + 'SysEmuTarget', + 'ThrottleGroupProperties', + 'VncPrimaryAuth', + 'VncVencryptSubAuth', + 'X86CPURegister32', + 'XDbgBlockGraph', + 'YankInstanceType', + 'blockdev-reopen', + 'query-rocker', + 'query-rocker-ports' ], # Externally visible types whose member names may use uppercase 'member-name-exceptions': [ # visible in: 'ACPISlotType', # query-acpi-ospm-status diff --git a/qapi/qapi-forward-visitor.c b/qapi/qapi-forward-visitor.c new file mode 100644 index 0000000000..e36d9bc9ba --- /dev/null +++ b/qapi/qapi-forward-visitor.c @@ -0,0 +1,327 @@ +/* + * Forward Visitor + * + * Copyright (C) 2021 Red Hat, Inc. + * + * This work is licensed under the terms of the GNU LGPL, version 2.1 or later. + * See the COPYING.LIB file in the top-level directory. + * + */ + +#include "qemu/osdep.h" +#include "qapi/compat-policy.h" +#include "qapi/error.h" +#include "qapi/forward-visitor.h" +#include "qapi/visitor-impl.h" +#include "qemu/queue.h" +#include "qapi/qmp/qjson.h" +#include "qapi/qmp/qbool.h" +#include "qapi/qmp/qdict.h" +#include "qapi/qmp/qerror.h" +#include "qapi/qmp/qlist.h" +#include "qapi/qmp/qnull.h" +#include "qapi/qmp/qnum.h" +#include "qapi/qmp/qstring.h" +#include "qemu/cutils.h" + +struct ForwardFieldVisitor { + Visitor visitor; + + Visitor *target; + char *from; + char *to; + + int depth; +}; + +static ForwardFieldVisitor *to_ffv(Visitor *v) +{ + return container_of(v, ForwardFieldVisitor, visitor); +} + +static bool forward_field_translate_name(ForwardFieldVisitor *v, const char **name, + Error **errp) +{ + if (v->depth) { + return true; + } + if (g_str_equal(*name, v->from)) { + *name = v->to; + return true; + } + error_setg(errp, QERR_MISSING_PARAMETER, *name); + return false; +} + +static bool forward_field_check_struct(Visitor *v, Error **errp) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + return visit_check_struct(ffv->target, errp); +} + +static bool forward_field_start_struct(Visitor *v, const char *name, void **obj, + size_t size, Error **errp) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + if (!forward_field_translate_name(ffv, &name, errp)) { + return false; + } + if (!visit_start_struct(ffv->target, name, obj, size, errp)) { + return false; + } + ffv->depth++; + return true; +} + +static void forward_field_end_struct(Visitor *v, void **obj) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + assert(ffv->depth); + ffv->depth--; + visit_end_struct(ffv->target, obj); +} + +static bool forward_field_start_list(Visitor *v, const char *name, + GenericList **list, size_t size, + Error **errp) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + if (!forward_field_translate_name(ffv, &name, errp)) { + return false; + } + ffv->depth++; + return visit_start_list(ffv->target, name, list, size, errp); +} + +static GenericList *forward_field_next_list(Visitor *v, GenericList *tail, + size_t size) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + assert(ffv->depth); + return visit_next_list(ffv->target, tail, size); +} + +static bool forward_field_check_list(Visitor *v, Error **errp) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + assert(ffv->depth); + return visit_check_list(ffv->target, errp); +} + +static void forward_field_end_list(Visitor *v, void **obj) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + assert(ffv->depth); + ffv->depth--; + visit_end_list(ffv->target, obj); +} + +static bool forward_field_start_alternate(Visitor *v, const char *name, + GenericAlternate **obj, size_t size, + Error **errp) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + if (!forward_field_translate_name(ffv, &name, errp)) { + return false; + } + /* + * The name passed to start_alternate is used also in the visit_type_* calls + * that retrieve the alternate's content; so, do not increase depth here. + */ + return visit_start_alternate(ffv->target, name, obj, size, errp); +} + +static void forward_field_end_alternate(Visitor *v, void **obj) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + visit_end_alternate(ffv->target, obj); +} + +static bool forward_field_type_int64(Visitor *v, const char *name, int64_t *obj, + Error **errp) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + if (!forward_field_translate_name(ffv, &name, errp)) { + return false; + } + return visit_type_int64(ffv->target, name, obj, errp); +} + +static bool forward_field_type_uint64(Visitor *v, const char *name, + uint64_t *obj, Error **errp) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + if (!forward_field_translate_name(ffv, &name, errp)) { + return false; + } + return visit_type_uint64(ffv->target, name, obj, errp); +} + +static bool forward_field_type_bool(Visitor *v, const char *name, bool *obj, + Error **errp) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + if (!forward_field_translate_name(ffv, &name, errp)) { + return false; + } + return visit_type_bool(ffv->target, name, obj, errp); +} + +static bool forward_field_type_str(Visitor *v, const char *name, char **obj, + Error **errp) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + if (!forward_field_translate_name(ffv, &name, errp)) { + return false; + } + return visit_type_str(ffv->target, name, obj, errp); +} + +static bool forward_field_type_size(Visitor *v, const char *name, uint64_t *obj, + Error **errp) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + if (!forward_field_translate_name(ffv, &name, errp)) { + return false; + } + return visit_type_size(ffv->target, name, obj, errp); +} + +static bool forward_field_type_number(Visitor *v, const char *name, double *obj, + Error **errp) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + if (!forward_field_translate_name(ffv, &name, errp)) { + return false; + } + return visit_type_number(ffv->target, name, obj, errp); +} + +static bool forward_field_type_any(Visitor *v, const char *name, QObject **obj, + Error **errp) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + if (!forward_field_translate_name(ffv, &name, errp)) { + return false; + } + return visit_type_any(ffv->target, name, obj, errp); +} + +static bool forward_field_type_null(Visitor *v, const char *name, + QNull **obj, Error **errp) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + if (!forward_field_translate_name(ffv, &name, errp)) { + return false; + } + return visit_type_null(ffv->target, name, obj, errp); +} + +static void forward_field_optional(Visitor *v, const char *name, bool *present) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + if (!forward_field_translate_name(ffv, &name, NULL)) { + *present = false; + return; + } + visit_optional(ffv->target, name, present); +} + +static bool forward_field_policy_reject(Visitor *v, const char *name, + unsigned special_features, + Error **errp) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + if (!forward_field_translate_name(ffv, &name, errp)) { + return true; + } + return visit_policy_reject(ffv->target, name, special_features, errp); +} + +static bool forward_field_policy_skip(Visitor *v, const char *name, + unsigned special_features) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + if (!forward_field_translate_name(ffv, &name, NULL)) { + return true; + } + return visit_policy_skip(ffv->target, name, special_features); +} + +static void forward_field_complete(Visitor *v, void *opaque) +{ + /* + * Do nothing, the complete method will be called in due time + * on the target visitor. + */ +} + +static void forward_field_free(Visitor *v) +{ + ForwardFieldVisitor *ffv = to_ffv(v); + + g_free(ffv->from); + g_free(ffv->to); + g_free(ffv); +} + +Visitor *visitor_forward_field(Visitor *target, const char *from, const char *to) +{ + ForwardFieldVisitor *v = g_new0(ForwardFieldVisitor, 1); + + /* + * Clone and dealloc visitors don't use a name for the toplevel + * visit, so they make no sense here. + */ + assert(target->type == VISITOR_OUTPUT || target->type == VISITOR_INPUT); + + v->visitor.type = target->type; + v->visitor.start_struct = forward_field_start_struct; + v->visitor.check_struct = forward_field_check_struct; + v->visitor.end_struct = forward_field_end_struct; + v->visitor.start_list = forward_field_start_list; + v->visitor.next_list = forward_field_next_list; + v->visitor.check_list = forward_field_check_list; + v->visitor.end_list = forward_field_end_list; + v->visitor.start_alternate = forward_field_start_alternate; + v->visitor.end_alternate = forward_field_end_alternate; + v->visitor.type_int64 = forward_field_type_int64; + v->visitor.type_uint64 = forward_field_type_uint64; + v->visitor.type_size = forward_field_type_size; + v->visitor.type_bool = forward_field_type_bool; + v->visitor.type_str = forward_field_type_str; + v->visitor.type_number = forward_field_type_number; + v->visitor.type_any = forward_field_type_any; + v->visitor.type_null = forward_field_type_null; + v->visitor.optional = forward_field_optional; + v->visitor.policy_reject = forward_field_policy_reject; + v->visitor.policy_skip = forward_field_policy_skip; + v->visitor.complete = forward_field_complete; + v->visitor.free = forward_field_free; + + v->target = target; + v->from = g_strdup(from); + v->to = g_strdup(to); + + return &v->visitor; +} diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index 4912b9744e..8304d45625 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -5,17 +5,20 @@ # # This document describes all commands currently supported by QMP. # -# Most of the time their usage is exactly the same as in the user Monitor, this -# means that any other document which also describe commands (the manpage, -# QEMU's manual, etc) can and should be consulted. +# Most of the time their usage is exactly the same as in the user +# Monitor, this means that any other document which also describe +# commands (the manpage, QEMU's manual, etc) can and should be +# consulted. # -# QMP has two types of commands: regular and query commands. Regular commands -# usually change the Virtual Machine's state someway, while query commands just -# return information. The sections below are divided accordingly. +# QMP has two types of commands: regular and query commands. Regular +# commands usually change the Virtual Machine's state someway, while +# query commands just return information. The sections below are +# divided accordingly. # -# It's important to observe that all communication examples are formatted in -# a reader-friendly way, so that they're easier to understand. However, in real -# protocol usage, they're emitted as a single line. +# It's important to observe that all communication examples are +# formatted in a reader-friendly way, so that they're easier to +# understand. However, in real protocol usage, they're emitted as a +# single line. # # Also, the following notation is used to denote data flow: # @@ -26,30 +29,9 @@ # -> data issued by the Client # <- Server data response # -# Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for -# detailed information on the Server command and response formats. -# -# = Stability Considerations -# -# The current QMP command set (described in this file) may be useful for a -# number of use cases, however it's limited and several commands have bad -# defined semantics, specially with regard to command completion. -# -# These problems are going to be solved incrementally in the next QEMU releases -# and we're going to establish a deprecation policy for badly defined commands. -# -# If you're planning to adopt QMP, please observe the following: -# -# 1. The deprecation policy will take effect and be documented soon, please -# check the documentation of each used command as soon as a new release of -# QEMU is available -# -# 2. DO NOT rely on anything which is not explicit documented -# -# 3. Errors, in special, are not documented. Applications should NOT check -# for specific errors classes or data (it's strongly recommended to only -# check for the "error" key) -# +# Please refer to the +# :doc:`QEMU Machine Protocol Specification </interop/qmp-spec>` +# for detailed information on the Server command and response formats. ## { 'include': 'pragma.json' } @@ -65,12 +47,13 @@ { 'include': 'sockets.json' } { 'include': 'run-state.json' } { 'include': 'crypto.json' } +{ 'include': 'job.json' } { 'include': 'block.json' } { 'include': 'block-export.json' } { 'include': 'char.json' } { 'include': 'dump.json' } -{ 'include': 'job.json' } { 'include': 'net.json' } +{ 'include': 'ebpf.json' } { 'include': 'rdma.json' } { 'include': 'rocker.json' } { 'include': 'tpm.json' } @@ -84,6 +67,7 @@ { 'include': 'introspect.json' } { 'include': 'qom.json' } { 'include': 'qdev.json' } +{ 'include': 'machine-common.json' } { 'include': 'machine.json' } { 'include': 'machine-target.json' } { 'include': 'replay.json' } @@ -93,3 +77,7 @@ { 'include': 'audio.json' } { 'include': 'acpi.json' } { 'include': 'pci.json' } +{ 'include': 'stats.json' } +{ 'include': 'virtio.json' } +{ 'include': 'cryptodev.json' } +{ 'include': 'cxl.json' } diff --git a/qapi/qapi-type-helpers.c b/qapi/qapi-type-helpers.c new file mode 100644 index 0000000000..266da013ad --- /dev/null +++ b/qapi/qapi-type-helpers.c @@ -0,0 +1,37 @@ +/* + * QAPI common helper functions + * + * This file provides helper functions related to types defined + * in the QAPI schema. + * + * This work is licensed under the terms of the GNU LGPL, version 2.1 or later. + * See the COPYING.LIB file in the top-level directory. + * + */ + +#include "qemu/osdep.h" +#include "qapi/error.h" +#include "qapi/type-helpers.h" + +HumanReadableText *human_readable_text_from_str(GString *str) +{ + HumanReadableText *ret = g_new0(HumanReadableText, 1); + + ret->human_readable_text = g_steal_pointer(&str->str); + + return ret; +} + +char **strv_from_str_list(const strList *list) +{ + const strList *tail; + int i = 0; + char **strv = g_new(char *, QAPI_LIST_LENGTH(list) + 1); + + for (tail = list; tail != NULL; tail = tail->next) { + strv[i++] = g_strdup(tail->value); + } + strv[i] = NULL; + + return strv; +} diff --git a/qapi/qapi-util.c b/qapi/qapi-util.c index 3c24bb3d45..65a7d18437 100644 --- a/qapi/qapi-util.c +++ b/qapi/qapi-util.c @@ -11,10 +11,53 @@ */ #include "qemu/osdep.h" +#include "qapi/compat-policy.h" #include "qapi/error.h" #include "qemu/ctype.h" #include "qapi/qmp/qerror.h" +CompatPolicy compat_policy; + +static bool compat_policy_input_ok1(const char *adjective, + CompatPolicyInput policy, + ErrorClass error_class, + const char *kind, const char *name, + Error **errp) +{ + switch (policy) { + case COMPAT_POLICY_INPUT_ACCEPT: + return true; + case COMPAT_POLICY_INPUT_REJECT: + error_set(errp, error_class, "%s %s %s disabled by policy", + adjective, kind, name); + return false; + case COMPAT_POLICY_INPUT_CRASH: + default: + abort(); + } +} + +bool compat_policy_input_ok(unsigned special_features, + const CompatPolicy *policy, + ErrorClass error_class, + const char *kind, const char *name, + Error **errp) +{ + if ((special_features & 1u << QAPI_DEPRECATED) + && !compat_policy_input_ok1("Deprecated", + policy->deprecated_input, + error_class, kind, name, errp)) { + return false; + } + if ((special_features & (1u << QAPI_UNSTABLE)) + && !compat_policy_input_ok1("Unstable", + policy->unstable_input, + error_class, kind, name, errp)) { + return false; + } + return true; +} + const char *qapi_enum_lookup(const QEnumLookup *lookup, int val) { assert(val >= 0 && val < lookup->size); @@ -69,8 +112,8 @@ bool qapi_bool_parse(const char *name, const char *value, bool *obj, Error **err * It may be prefixed by __RFQDN_ (downstream extension), where RFQDN * may contain only letters, digits, hyphen and period. * The special exception for enumeration names is not implemented. - * See docs/devel/qapi-code-gen.txt for more on QAPI naming rules. - * Keep this consistent with scripts/qapi.py! + * See docs/devel/qapi-code-gen.rst for more on QAPI naming rules. + * Keep this consistent with scripts/qapi-gen.py! * If @complete, the parse fails unless it consumes @str completely. * Return its length on success, -1 on failure. */ diff --git a/qapi/qapi-visit-core.c b/qapi/qapi-visit-core.c index a641adec51..6c13510a2b 100644 --- a/qapi/qapi-visit-core.c +++ b/qapi/qapi-visit-core.c @@ -13,12 +13,17 @@ */ #include "qemu/osdep.h" +#include "qapi/compat-policy.h" #include "qapi/error.h" #include "qapi/qmp/qerror.h" #include "qapi/visitor.h" #include "qapi/visitor-impl.h" #include "trace.h" +/* Zero-initialization must result in default policy */ +QEMU_BUILD_BUG_ON(COMPAT_POLICY_INPUT_ACCEPT || COMPAT_POLICY_OUTPUT_ACCEPT); + + void visit_complete(Visitor *v, void *opaque) { assert(v->type != VISITOR_OUTPUT || v->complete); @@ -135,22 +140,29 @@ bool visit_optional(Visitor *v, const char *name, bool *present) return *present; } -bool visit_deprecated_accept(Visitor *v, const char *name, Error **errp) +bool visit_policy_reject(Visitor *v, const char *name, + unsigned special_features, Error **errp) { - trace_visit_deprecated_accept(v, name); - if (v->deprecated_accept) { - return v->deprecated_accept(v, name, errp); + trace_visit_policy_reject(v, name); + if (v->policy_reject) { + return v->policy_reject(v, name, special_features, errp); } - return true; + return false; } -bool visit_deprecated(Visitor *v, const char *name) +bool visit_policy_skip(Visitor *v, const char *name, + unsigned special_features) { - trace_visit_deprecated(v, name); - if (v->deprecated) { - return v->deprecated(v, name); + trace_visit_policy_skip(v, name); + if (v->policy_skip) { + return v->policy_skip(v, name, special_features); } - return true; + return false; +} + +void visit_set_policy(Visitor *v, CompatPolicy *policy) +{ + v->compat_policy = *policy; } bool visit_is_input(Visitor *v) @@ -384,7 +396,7 @@ static bool input_type_enum(Visitor *v, const char *name, int *obj, const QEnumLookup *lookup, Error **errp) { int64_t value; - char *enum_str; + g_autofree char *enum_str = NULL; if (!visit_type_str(v, name, &enum_str, errp)) { return false; @@ -392,12 +404,19 @@ static bool input_type_enum(Visitor *v, const char *name, int *obj, value = qapi_enum_parse(lookup, enum_str, -1, NULL); if (value < 0) { - error_setg(errp, QERR_INVALID_PARAMETER, enum_str); - g_free(enum_str); + error_setg(errp, "Parameter '%s' does not accept value '%s'", + name ? name : "null", enum_str); + return false; + } + + if (lookup->special_features + && !compat_policy_input_ok(lookup->special_features[value], + &v->compat_policy, + ERROR_CLASS_GENERIC_ERROR, + "value", enum_str, errp)) { return false; } - g_free(enum_str); *obj = value; return true; } diff --git a/qapi/qdev.json b/qapi/qdev.json index b83178220b..facaa0bc6a 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -17,11 +17,12 @@ # # @typename: the type name of a device # -# Returns: a list of ObjectPropertyInfo describing a devices properties +# Returns: a list of ObjectPropertyInfo describing a devices +# properties # -# Note: objects can create properties at runtime, for example to describe -# links between different devices and/or objects. These properties -# are not included in the output of this command. +# Note: objects can create properties at runtime, for example to +# describe links between different devices and/or objects. These +# properties are not included in the output of this command. # # Since: 1.2 ## @@ -32,42 +33,54 @@ ## # @device_add: # +# Add a device. +# # @driver: the name of the new device's driver # # @bus: the device's parent bus (device tree path) # # @id: the device's ID, must be unique # -# Additional arguments depend on the type. +# Features: # -# Add a device. +# @json-cli: If present, the "-device" command line option supports +# JSON syntax with a structure identical to the arguments of this +# command. +# +# @json-cli-hotplug: If present, the "-device" command line option +# supports JSON syntax without the reference counting leak that +# broke hot-unplug # # Notes: -# 1. For detailed information about this command, please refer to the -# 'docs/qdev-device-use.txt' file. # -# 2. It's possible to list device properties by running QEMU with the -# "-device DEVICE,help" command-line argument, where DEVICE is the -# device's name +# 1. Additional arguments depend on the type. +# +# 2. For detailed information about this command, please refer to +# the 'docs/qdev-device-use.txt' file. +# +# 3. It's possible to list device properties by running QEMU with +# the "-device DEVICE,help" command-line argument, where DEVICE +# is the device's name # # Example: # -# -> { "execute": "device_add", -# "arguments": { "driver": "e1000", "id": "net1", -# "bus": "pci.0", -# "mac": "52:54:00:12:34:56" } } -# <- { "return": {} } +# -> { "execute": "device_add", +# "arguments": { "driver": "e1000", "id": "net1", +# "bus": "pci.0", +# "mac": "52:54:00:12:34:56" } } +# <- { "return": {} } # # TODO: This command effectively bypasses QAPI completely due to its -# "additional arguments" business. It shouldn't have been added to -# the schema in this form. It should be qapified properly, or -# replaced by a properly qapified command. +# "additional arguments" business. It shouldn't have been added +# to the schema in this form. It should be qapified properly, or +# replaced by a properly qapified command. # # Since: 0.13 ## { 'command': 'device_add', 'data': {'driver': 'str', '*bus': 'str', '*id': 'str'}, - 'gen': false } # so we can get the additional arguments + 'gen': false, # so we can get the additional arguments + 'features': ['json-cli', 'json-cli-hotplug'] } ## # @device_del: @@ -76,51 +89,75 @@ # # @id: the device's ID or QOM path # -# Returns: Nothing on success -# If @id is not a valid device, DeviceNotFound +# Errors: +# - If @id is not a valid device, DeviceNotFound # -# Notes: When this command completes, the device may not be removed from the -# guest. Hot removal is an operation that requires guest cooperation. -# This command merely requests that the guest begin the hot removal -# process. Completion of the device removal process is signaled with a -# DEVICE_DELETED event. Guest reset will automatically complete removal -# for all devices. +# Notes: When this command completes, the device may not be removed +# from the guest. Hot removal is an operation that requires guest +# cooperation. This command merely requests that the guest begin +# the hot removal process. Completion of the device removal +# process is signaled with a DEVICE_DELETED event. Guest reset +# will automatically complete removal for all devices. If a +# guest-side error in the hot removal process is detected, the +# device will not be removed and a DEVICE_UNPLUG_GUEST_ERROR event +# is sent. Some errors cannot be detected. # # Since: 0.14 # -# Example: -# -# -> { "execute": "device_del", -# "arguments": { "id": "net1" } } -# <- { "return": {} } +# Examples: # -# -> { "execute": "device_del", -# "arguments": { "id": "/machine/peripheral-anon/device[0]" } } -# <- { "return": {} } +# -> { "execute": "device_del", +# "arguments": { "id": "net1" } } +# <- { "return": {} } # +# -> { "execute": "device_del", +# "arguments": { "id": "/machine/peripheral-anon/device[0]" } } +# <- { "return": {} } ## { 'command': 'device_del', 'data': {'id': 'str'} } ## # @DEVICE_DELETED: # -# Emitted whenever the device removal completion is acknowledged by the guest. -# At this point, it's safe to reuse the specified device ID. Device removal can -# be initiated by the guest or by HMP/QMP commands. +# Emitted whenever the device removal completion is acknowledged by +# the guest. At this point, it's safe to reuse the specified device +# ID. Device removal can be initiated by the guest or by HMP/QMP +# commands. # -# @device: device name +# @device: the device's ID if it has one # -# @path: device path +# @path: the device's QOM path # # Since: 1.5 # # Example: # -# <- { "event": "DEVICE_DELETED", -# "data": { "device": "virtio-net-pci-0", -# "path": "/machine/peripheral/virtio-net-pci-0" }, -# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } -# +# <- { "event": "DEVICE_DELETED", +# "data": { "device": "virtio-net-pci-0", +# "path": "/machine/peripheral/virtio-net-pci-0" }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } ## { 'event': 'DEVICE_DELETED', 'data': { '*device': 'str', 'path': 'str' } } + +## +# @DEVICE_UNPLUG_GUEST_ERROR: +# +# Emitted when a device hot unplug fails due to a guest reported +# error. +# +# @device: the device's ID if it has one +# +# @path: the device's QOM path +# +# Since: 6.2 +# +# Example: +# +# <- { "event": "DEVICE_UNPLUG_GUEST_ERROR", +# "data": { "device": "core1", +# "path": "/machine/peripheral/core1" }, +# "timestamp": { "seconds": 1615570772, "microseconds": 202844 } } +## +{ 'event': 'DEVICE_UNPLUG_GUEST_ERROR', + 'data': { '*device': 'str', 'path': 'str' } } diff --git a/qapi/qmp-dispatch.c b/qapi/qmp-dispatch.c index 59600210ce..f3488afeef 100644 --- a/qapi/qmp-dispatch.c +++ b/qapi/qmp-dispatch.c @@ -21,18 +21,15 @@ #include "qapi/qmp/qjson.h" #include "qapi/qobject-input-visitor.h" #include "qapi/qobject-output-visitor.h" -#include "sysemu/runstate.h" #include "qapi/qmp/qbool.h" #include "qemu/coroutine.h" #include "qemu/main-loop.h" -CompatPolicy compat_policy; - Visitor *qobject_input_visitor_new_qmp(QObject *obj) { Visitor *v = qobject_input_visitor_new(obj); - qobject_input_visitor_set_policy(v, compat_policy.deprecated_input); + visit_set_policy(v, &compat_policy); return v; } @@ -40,7 +37,7 @@ Visitor *qobject_output_visitor_new_qmp(QObject **result) { Visitor *v = qobject_output_visitor_new(result); - qobject_output_visitor_set_policy(v, compat_policy.deprecated_output); + visit_set_policy(v, &compat_policy); return v; } @@ -137,8 +134,8 @@ static void do_qmp_dispatch_bh(void *opaque) * Runs outside of coroutine context for OOB commands, but in coroutine * context for everything else. */ -QDict *qmp_dispatch(const QmpCommandList *cmds, QObject *request, - bool allow_oob, Monitor *cur_mon) +QDict *coroutine_mixed_fn qmp_dispatch(const QmpCommandList *cmds, QObject *request, + bool allow_oob, Monitor *cur_mon) { Error *err = NULL; bool oob; @@ -176,19 +173,10 @@ QDict *qmp_dispatch(const QmpCommandList *cmds, QObject *request, "The command %s has not been found", command); goto out; } - if (cmd->options & QCO_DEPRECATED) { - switch (compat_policy.deprecated_input) { - case COMPAT_POLICY_INPUT_ACCEPT: - break; - case COMPAT_POLICY_INPUT_REJECT: - error_set(&err, ERROR_CLASS_COMMAND_NOT_FOUND, - "Deprecated command %s disabled by policy", - command); - goto out; - case COMPAT_POLICY_INPUT_CRASH: - default: - abort(); - } + if (!compat_policy_input_ok(cmd->special_features, &compat_policy, + ERROR_CLASS_COMMAND_NOT_FOUND, + "command", command, &err)) { + goto out; } if (!cmd->enabled) { error_set(&err, ERROR_CLASS_COMMAND_NOT_FOUND, @@ -218,9 +206,28 @@ QDict *qmp_dispatch(const QmpCommandList *cmds, QObject *request, assert(!(oob && qemu_in_coroutine())); assert(monitor_cur() == NULL); if (!!(cmd->options & QCO_COROUTINE) == qemu_in_coroutine()) { + if (qemu_in_coroutine()) { + /* + * Move the coroutine from iohandler_ctx to qemu_aio_context for + * executing the command handler so that it can make progress if it + * involves an AIO_WAIT_WHILE(). + */ + aio_co_reschedule_self(qemu_get_aio_context()); + } + monitor_set_cur(qemu_coroutine_self(), cur_mon); cmd->fn(args, &ret, &err); monitor_set_cur(qemu_coroutine_self(), NULL); + + if (qemu_in_coroutine()) { + /* + * Yield and reschedule so the main loop stays responsive. + * + * Move back to iohandler_ctx so that nested event loops for + * qemu_aio_context don't start new monitor commands. + */ + aio_co_reschedule_self(iohandler_get_aio_context()); + } } else { /* * Actual context doesn't match the one the command needs. @@ -244,7 +251,7 @@ QDict *qmp_dispatch(const QmpCommandList *cmds, QObject *request, .errp = &err, .co = qemu_coroutine_self(), }; - aio_bh_schedule_oneshot(qemu_get_aio_context(), do_qmp_dispatch_bh, + aio_bh_schedule_oneshot(iohandler_get_aio_context(), do_qmp_dispatch_bh, &data); qemu_coroutine_yield(); } diff --git a/qapi/qmp-event.c b/qapi/qmp-event.c index 19d3cd0038..0fe0d0a5a6 100644 --- a/qapi/qmp-event.c +++ b/qapi/qmp-event.c @@ -20,15 +20,12 @@ static void timestamp_put(QDict *qdict) { - int err; QDict *ts; - qemu_timeval tv; + int64_t rt = g_get_real_time(); - err = qemu_gettimeofday(&tv); - /* Put -1 to indicate failure of getting host time */ ts = qdict_from_jsonf_nofail("{ 'seconds': %lld, 'microseconds': %lld }", - err < 0 ? -1LL : (long long)tv.tv_sec, - err < 0 ? -1LL : (long long)tv.tv_usec); + (long long)rt / G_USEC_PER_SEC, + (long long)rt % G_USEC_PER_SEC); qdict_put(qdict, "timestamp", ts); } diff --git a/qapi/qmp-registry.c b/qapi/qmp-registry.c index f78c064aae..485bc5e6fc 100644 --- a/qapi/qmp-registry.c +++ b/qapi/qmp-registry.c @@ -16,7 +16,8 @@ #include "qapi/qmp/dispatch.h" void qmp_register_command(QmpCommandList *cmds, const char *name, - QmpCommandFunc *fn, QmpCommandOptions options) + QmpCommandFunc *fn, QmpCommandOptions options, + unsigned special_features) { QmpCommand *cmd = g_malloc0(sizeof(*cmd)); @@ -27,6 +28,7 @@ void qmp_register_command(QmpCommandList *cmds, const char *name, cmd->fn = fn; cmd->enabled = true; cmd->options = options; + cmd->special_features = special_features; QTAILQ_INSERT_TAIL(cmds, cmd, node); } diff --git a/qapi/qobject-input-visitor.c b/qapi/qobject-input-visitor.c index 04b790412e..3e8aca6b15 100644 --- a/qapi/qobject-input-visitor.c +++ b/qapi/qobject-input-visitor.c @@ -28,7 +28,7 @@ #include "qapi/qmp/qnum.h" #include "qapi/qmp/qstring.h" #include "qemu/cutils.h" -#include "qemu/option.h" +#include "qemu/keyval.h" typedef struct StackObject { const char *name; /* Name of @obj in its parent, if any */ @@ -44,7 +44,6 @@ typedef struct StackObject { struct QObjectInputVisitor { Visitor visitor; - CompatPolicyInput deprecated_policy; /* Root of visit at visitor creation. */ QObject *root; @@ -664,22 +663,13 @@ static void qobject_input_optional(Visitor *v, const char *name, bool *present) *present = true; } -static bool qobject_input_deprecated_accept(Visitor *v, const char *name, - Error **errp) +static bool qobject_input_policy_reject(Visitor *v, const char *name, + unsigned special_features, + Error **errp) { - QObjectInputVisitor *qiv = to_qiv(v); - - switch (qiv->deprecated_policy) { - case COMPAT_POLICY_INPUT_ACCEPT: - return true; - case COMPAT_POLICY_INPUT_REJECT: - error_setg(errp, "Deprecated parameter '%s' disabled by policy", - name); - return false; - case COMPAT_POLICY_INPUT_CRASH: - default: - abort(); - } + return !compat_policy_input_ok(special_features, &v->compat_policy, + ERROR_CLASS_GENERIC_ERROR, + "parameter", name, errp); } static void qobject_input_free(Visitor *v) @@ -716,7 +706,7 @@ static QObjectInputVisitor *qobject_input_visitor_base_new(QObject *obj) v->visitor.end_list = qobject_input_end_list; v->visitor.start_alternate = qobject_input_start_alternate; v->visitor.optional = qobject_input_optional; - v->visitor.deprecated_accept = qobject_input_deprecated_accept; + v->visitor.policy_reject = qobject_input_policy_reject; v->visitor.free = qobject_input_free; v->root = qobject_ref(obj); @@ -739,14 +729,6 @@ Visitor *qobject_input_visitor_new(QObject *obj) return &v->visitor; } -void qobject_input_visitor_set_policy(Visitor *v, - CompatPolicyInput deprecated) -{ - QObjectInputVisitor *qiv = to_qiv(v); - - qiv->deprecated_policy = deprecated; -} - Visitor *qobject_input_visitor_new_keyval(QObject *obj) { QObjectInputVisitor *v = qobject_input_visitor_base_new(obj); diff --git a/qapi/qobject-output-visitor.c b/qapi/qobject-output-visitor.c index e4873308d4..74770edd73 100644 --- a/qapi/qobject-output-visitor.c +++ b/qapi/qobject-output-visitor.c @@ -32,7 +32,6 @@ typedef struct QStackEntry { struct QObjectOutputVisitor { Visitor visitor; - CompatPolicyOutput deprecated_policy; QSLIST_HEAD(, QStackEntry) stack; /* Stack of unfinished containers */ QObject *root; /* Root of the output visit */ @@ -210,11 +209,15 @@ static bool qobject_output_type_null(Visitor *v, const char *name, return true; } -static bool qobject_output_deprecated(Visitor *v, const char *name) +static bool qobject_output_policy_skip(Visitor *v, const char *name, + unsigned special_features) { - QObjectOutputVisitor *qov = to_qov(v); + CompatPolicy *pol = &v->compat_policy; - return qov->deprecated_policy != COMPAT_POLICY_OUTPUT_HIDE; + return ((special_features & 1u << QAPI_DEPRECATED) + && pol->deprecated_output == COMPAT_POLICY_OUTPUT_HIDE) + || ((special_features & 1u << QAPI_UNSTABLE) + && pol->unstable_output == COMPAT_POLICY_OUTPUT_HIDE); } /* Finish building, and return the root object. @@ -266,7 +269,7 @@ Visitor *qobject_output_visitor_new(QObject **result) v->visitor.type_number = qobject_output_type_number; v->visitor.type_any = qobject_output_type_any; v->visitor.type_null = qobject_output_type_null; - v->visitor.deprecated = qobject_output_deprecated; + v->visitor.policy_skip = qobject_output_policy_skip; v->visitor.complete = qobject_output_complete; v->visitor.free = qobject_output_free; @@ -275,11 +278,3 @@ Visitor *qobject_output_visitor_new(QObject **result) return &v->visitor; } - -void qobject_output_visitor_set_policy(Visitor *v, - CompatPolicyOutput deprecated) -{ - QObjectOutputVisitor *qov = to_qov(v); - - qov->deprecated_policy = deprecated; -} diff --git a/qapi/qom.json b/qapi/qom.json index cd0e76d564..85e6b4f84a 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -18,17 +18,20 @@ # # @name: the name of the property # -# @type: the type of the property. This will typically come in one of four -# forms: +# @type: the type of the property. This will typically come in one of +# four forms: # -# 1) A primitive type such as 'u8', 'u16', 'bool', 'str', or 'double'. -# These types are mapped to the appropriate JSON type. +# 1) A primitive type such as 'u8', 'u16', 'bool', 'str', or +# 'double'. These types are mapped to the appropriate JSON +# type. # -# 2) A child type in the form 'child<subtype>' where subtype is a qdev -# device type name. Child properties create the composition tree. +# 2) A child type in the form 'child<subtype>' where subtype is a +# qdev device type name. Child properties create the +# composition tree. # -# 3) A link type in the form 'link<subtype>' where subtype is a qdev -# device type name. Link properties form the device model graph. +# 3) A link type in the form 'link<subtype>' where subtype is a +# qdev device type name. Link properties form the device model +# graph. # # @description: if specified, the description of the property. # @@ -45,26 +48,25 @@ ## # @qom-list: # -# This command will list any properties of a object given a path in the object -# model. +# This command will list any properties of a object given a path in +# the object model. # -# @path: the path within the object model. See @qom-get for a description of -# this parameter. +# @path: the path within the object model. See @qom-get for a +# description of this parameter. # -# Returns: a list of @ObjectPropertyInfo that describe the properties of the -# object. +# Returns: a list of @ObjectPropertyInfo that describe the properties +# of the object. # # Since: 1.2 # # Example: # -# -> { "execute": "qom-list", -# "arguments": { "path": "/chardevs" } } -# <- { "return": [ { "name": "type", "type": "string" }, -# { "name": "parallel0", "type": "child<chardev-vc>" }, -# { "name": "serial0", "type": "child<chardev-vc>" }, -# { "name": "mon0", "type": "child<chardev-stdio>" } ] } -# +# -> { "execute": "qom-list", +# "arguments": { "path": "/chardevs" } } +# <- { "return": [ { "name": "type", "type": "string" }, +# { "name": "parallel0", "type": "child<chardev-vc>" }, +# { "name": "serial0", "type": "child<chardev-vc>" }, +# { "name": "mon0", "type": "child<chardev-stdio>" } ] } ## { 'command': 'qom-list', 'data': { 'path': 'str' }, @@ -74,51 +76,49 @@ ## # @qom-get: # -# This command will get a property from a object model path and return the -# value. +# This command will get a property from a object model path and return +# the value. # -# @path: The path within the object model. There are two forms of supported -# paths--absolute and partial paths. +# @path: The path within the object model. There are two forms of +# supported paths--absolute and partial paths. # -# Absolute paths are derived from the root object and can follow child<> -# or link<> properties. Since they can follow link<> properties, they -# can be arbitrarily long. Absolute paths look like absolute filenames -# and are prefixed with a leading slash. +# Absolute paths are derived from the root object and can follow +# child<> or link<> properties. Since they can follow link<> +# properties, they can be arbitrarily long. Absolute paths look +# like absolute filenames and are prefixed with a leading slash. # -# Partial paths look like relative filenames. They do not begin -# with a prefix. The matching rules for partial paths are subtle but -# designed to make specifying objects easy. At each level of the -# composition tree, the partial path is matched as an absolute path. -# The first match is not returned. At least two matches are searched -# for. A successful result is only returned if only one match is -# found. If more than one match is found, a flag is return to -# indicate that the match was ambiguous. +# Partial paths look like relative filenames. They do not begin +# with a prefix. The matching rules for partial paths are subtle +# but designed to make specifying objects easy. At each level of +# the composition tree, the partial path is matched as an absolute +# path. The first match is not returned. At least two matches +# are searched for. A successful result is only returned if only +# one match is found. If more than one match is found, a flag is +# return to indicate that the match was ambiguous. # # @property: The property name to read # -# Returns: The property value. The type depends on the property -# type. child<> and link<> properties are returned as #str -# pathnames. All integer property types (u8, u16, etc) are -# returned as #int. +# Returns: The property value. The type depends on the property type. +# child<> and link<> properties are returned as #str pathnames. +# All integer property types (u8, u16, etc) are returned as #int. # # Since: 1.2 # -# Example: -# -# 1. Use absolute path +# Examples: # -# -> { "execute": "qom-get", -# "arguments": { "path": "/machine/unattached/device[0]", -# "property": "hotplugged" } } -# <- { "return": false } +# 1. Use absolute path # -# 2. Use partial path +# -> { "execute": "qom-get", +# "arguments": { "path": "/machine/unattached/device[0]", +# "property": "hotplugged" } } +# <- { "return": false } # -# -> { "execute": "qom-get", -# "arguments": { "path": "unattached/sysbus", -# "property": "type" } } -# <- { "return": "System" } +# 2. Use partial path # +# -> { "execute": "qom-get", +# "arguments": { "path": "unattached/sysbus", +# "property": "type" } } +# <- { "return": "System" } ## { 'command': 'qom-get', 'data': { 'path': 'str', 'property': 'str' }, @@ -134,19 +134,18 @@ # # @property: the property name to set # -# @value: a value who's type is appropriate for the property type. See @qom-get -# for a description of type mapping. +# @value: a value who's type is appropriate for the property type. +# See @qom-get for a description of type mapping. # # Since: 1.2 # # Example: # -# -> { "execute": "qom-set", -# "arguments": { "path": "/machine", -# "property": "graphics", -# "value": false } } -# <- { "return": {} } -# +# -> { "execute": "qom-set", +# "arguments": { "path": "/machine", +# "property": "graphics", +# "value": false } } +# <- { "return": {} } ## { 'command': 'qom-set', 'data': { 'path': 'str', 'property': 'str', 'value': 'any' }, @@ -160,7 +159,7 @@ # @name: the type name found in the search # # @abstract: the type is abstract and can't be directly instantiated. -# Omitted if false. (since 2.10) +# Omitted if false. (since 2.10) # # @parent: Name of parent type, if any (since 2.10) # @@ -174,11 +173,13 @@ # # This command will return a list of types given search parameters # -# @implements: if specified, only return types that implement this type name +# @implements: if specified, only return types that implement this +# type name # # @abstract: if true, include abstract types in the results # -# Returns: a list of @ObjectTypeInfo or an empty list if no results are found +# Returns: a list of @ObjectTypeInfo or an empty list if no results +# are found # # Since: 1.1 ## @@ -194,9 +195,9 @@ # # @typename: the type name of an object # -# Note: objects can create properties at runtime, for example to describe -# links between different devices and/or objects. These properties -# are not included in the output of this command. +# Note: objects can create properties at runtime, for example to +# describe links between different devices and/or objects. These +# properties are not included in the output of this command. # # Returns: a list of ObjectPropertyInfo describing object properties # @@ -214,7 +215,8 @@ # # @if: interface name of the host system CAN bus to connect to # -# @canbus: object ID of the can-bus object to connect to the host interface +# @canbus: object ID of the can-bus object to connect to the host +# interface # # Since: 2.12 ## @@ -227,34 +229,35 @@ # # Properties for colo-compare objects. # -# @primary_in: name of the character device backend to use for the primary -# input (incoming packets are redirected to @outdev) +# @primary_in: name of the character device backend to use for the +# primary input (incoming packets are redirected to @outdev) # -# @secondary_in: name of the character device backend to use for secondary -# input (incoming packets are only compared to the input on -# @primary_in and then dropped) +# @secondary_in: name of the character device backend to use for +# secondary input (incoming packets are only compared to the input +# on @primary_in and then dropped) # # @outdev: name of the character device backend to use for output # # @iothread: name of the iothread to run in # -# @notify_dev: name of the character device backend to be used to communicate -# with the remote colo-frame (only for Xen COLO) +# @notify_dev: name of the character device backend to be used to +# communicate with the remote colo-frame (only for Xen COLO) # -# @compare_timeout: the maximum time to hold a packet from @primary_in for -# comparison with an incoming packet on @secondary_in in -# milliseconds (default: 3000) +# @compare_timeout: the maximum time to hold a packet from @primary_in +# for comparison with an incoming packet on @secondary_in in +# milliseconds (default: 3000) # -# @expired_scan_cycle: the interval at which colo-compare checks whether -# packets from @primary have timed out, in milliseconds -# (default: 3000) +# @expired_scan_cycle: the interval at which colo-compare checks +# whether packets from @primary have timed out, in milliseconds +# (default: 3000) # -# @max_queue_size: the maximum number of packets to keep in the queue for -# comparing with incoming packets from @secondary_in. If the -# queue is full and addtional packets are received, the -# addtional packets are dropped. (default: 1024) +# @max_queue_size: the maximum number of packets to keep in the queue +# for comparing with incoming packets from @secondary_in. If the +# queue is full and additional packets are received, the +# additional packets are dropped. (default: 1024) # -# @vnet_hdr_support: if true, vnet header support is enabled (default: false) +# @vnet_hdr_support: if true, vnet header support is enabled +# (default: false) # # Since: 2.8 ## @@ -272,24 +275,31 @@ ## # @CryptodevBackendProperties: # -# Properties for cryptodev-backend and cryptodev-backend-builtin objects. +# Properties for cryptodev-backend and cryptodev-backend-builtin +# objects. +# +# @queues: the number of queues for the cryptodev backend. Ignored +# for cryptodev-backend and must be 1 for +# cryptodev-backend-builtin. (default: 1) +# +# @throttle-bps: limit total bytes per second (Since 8.0) # -# @queues: the number of queues for the cryptodev backend. Ignored for -# cryptodev-backend and must be 1 for cryptodev-backend-builtin. -# (default: 1) +# @throttle-ops: limit total operations per second (Since 8.0) # # Since: 2.8 ## { 'struct': 'CryptodevBackendProperties', - 'data': { '*queues': 'uint32' } } + 'data': { '*queues': 'uint32', + '*throttle-bps': 'uint64', + '*throttle-ops': 'uint64' } } ## # @CryptodevVhostUserProperties: # # Properties for cryptodev-vhost-user objects. # -# @chardev: the name of a Unix domain socket character device that connects to -# the vhost-user server +# @chardev: the name of a Unix domain socket character device that +# connects to the vhost-user server # # Since: 2.12 ## @@ -304,8 +314,8 @@ # # @addr: the name of the DBus bus to connect to # -# @id-list: a comma separated list of DBus IDs of helpers whose data should be -# included in the VM state on migration +# @id-list: a comma separated list of DBus IDs of helpers whose data +# should be included in the VM state on migration # # Since: 5.0 ## @@ -316,7 +326,8 @@ ## # @NetfilterInsert: # -# Indicates where to insert a netfilter relative to a given other filter. +# Indicates where to insert a netfilter relative to a given other +# filter. # # @before: insert before the specified filter # @@ -336,20 +347,20 @@ # # @queue: indicates which queue(s) to filter (default: all) # -# @status: indicates whether the filter is enabled ("on") or disabled ("off") -# (default: "on") +# @status: indicates whether the filter is enabled ("on") or disabled +# ("off") (default: "on") # -# @position: specifies where the filter should be inserted in the filter list. -# "head" means the filter is inserted at the head of the filter list, -# before any existing filters. -# "tail" means the filter is inserted at the tail of the filter list, -# behind any existing filters (default). -# "id=<id>" means the filter is inserted before or behind the filter -# specified by <id>, depending on the @insert property. -# (default: "tail") +# @position: specifies where the filter should be inserted in the +# filter list. "head" means the filter is inserted at the head of +# the filter list, before any existing filters. "tail" means the +# filter is inserted at the tail of the filter list, behind any +# existing filters (default). "id=<id>" means the filter is +# inserted before or behind the filter specified by <id>, +# depending on the @insert property. (default: "tail") # -# @insert: where to insert the filter relative to the filter given in @position. -# Ignored if @position is "head" or "tail". (default: behind) +# @insert: where to insert the filter relative to the filter given in +# @position. Ignored if @position is "head" or "tail". +# (default: behind) # # Since: 2.5 ## @@ -365,8 +376,9 @@ # # Properties for filter-buffer objects. # -# @interval: a non-zero interval in microseconds. All packets arriving in the -# given interval are delayed until the end of the interval. +# @interval: a non-zero interval in microseconds. All packets +# arriving in the given interval are delayed until the end of the +# interval. # # Since: 2.5 ## @@ -381,7 +393,8 @@ # # @file: the filename where the dumped packets should be stored # -# @maxlen: maximum number of bytes in a packet that are stored (default: 65536) +# @maxlen: maximum number of bytes in a packet that are stored +# (default: 65536) # # Since: 2.5 ## @@ -395,10 +408,11 @@ # # Properties for filter-mirror objects. # -# @outdev: the name of a character device backend to which all incoming packets -# are mirrored +# @outdev: the name of a character device backend to which all +# incoming packets are mirrored # -# @vnet_hdr_support: if true, vnet header support is enabled (default: false) +# @vnet_hdr_support: if true, vnet header support is enabled +# (default: false) # # Since: 2.6 ## @@ -412,16 +426,17 @@ # # Properties for filter-redirector objects. # -# At least one of @indev or @outdev must be present. If both are present, they -# must not refer to the same character device backend. +# At least one of @indev or @outdev must be present. If both are +# present, they must not refer to the same character device backend. # -# @indev: the name of a character device backend from which packets are -# received and redirected to the filtered network device +# @indev: the name of a character device backend from which packets +# are received and redirected to the filtered network device # -# @outdev: the name of a character device backend to which all incoming packets -# are redirected +# @outdev: the name of a character device backend to which all +# incoming packets are redirected # -# @vnet_hdr_support: if true, vnet header support is enabled (default: false) +# @vnet_hdr_support: if true, vnet header support is enabled +# (default: false) # # Since: 2.6 ## @@ -436,7 +451,8 @@ # # Properties for filter-rewriter objects. # -# @vnet_hdr_support: if true, vnet header support is enabled (default: false) +# @vnet_hdr_support: if true, vnet header support is enabled +# (default: false) # # Since: 2.8 ## @@ -449,17 +465,18 @@ # # Properties for input-barrier objects. # -# @name: the screen name as declared in the screens section of barrier.conf +# @name: the screen name as declared in the screens section of +# barrier.conf # # @server: hostname of the Barrier server (default: "localhost") # # @port: TCP port of the Barrier server (default: "24800") # # @x-origin: x coordinate of the leftmost pixel on the guest screen -# (default: "0") +# (default: "0") # # @y-origin: y coordinate of the topmost pixel on the guest screen -# (default: "0") +# (default: "0") # # @width: the width of secondary screen in pixels (default: "1920") # @@ -483,13 +500,13 @@ # # @evdev: the path of the host evdev device to use # -# @grab_all: if true, grab is toggled for all devices (e.g. both keyboard and -# mouse) instead of just one device (default: false) +# @grab_all: if true, grab is toggled for all devices (e.g. both +# keyboard and mouse) instead of just one device (default: false) # # @repeat: enables auto-repeat events (default: false) # # @grab-toggle: the key or key combination that toggles device grab -# (default: ctrl-ctrl) +# (default: ctrl-ctrl) # # Since: 2.6 ## @@ -500,39 +517,75 @@ '*grab-toggle': 'GrabToggleKeys' } } ## +# @EventLoopBaseProperties: +# +# Common properties for event loops +# +# @aio-max-batch: maximum number of requests in a batch for the AIO +# engine, 0 means that the engine will use its default. +# (default: 0) +# +# @thread-pool-min: minimum number of threads reserved in the thread +# pool (default:0) +# +# @thread-pool-max: maximum number of threads the thread pool can +# contain (default:64) +# +# Since: 7.1 +## +{ 'struct': 'EventLoopBaseProperties', + 'data': { '*aio-max-batch': 'int', + '*thread-pool-min': 'int', + '*thread-pool-max': 'int' } } + +## # @IothreadProperties: # # Properties for iothread objects. # -# @poll-max-ns: the maximum number of nanoseconds to busy wait for events. -# 0 means polling is disabled (default: 32768 on POSIX hosts, -# 0 otherwise) +# @poll-max-ns: the maximum number of nanoseconds to busy wait for +# events. 0 means polling is disabled (default: 32768 on POSIX +# hosts, 0 otherwise) # -# @poll-grow: the multiplier used to increase the polling time when the -# algorithm detects it is missing events due to not polling long -# enough. 0 selects a default behaviour (default: 0) +# @poll-grow: the multiplier used to increase the polling time when +# the algorithm detects it is missing events due to not polling +# long enough. 0 selects a default behaviour (default: 0) # # @poll-shrink: the divisor used to decrease the polling time when the -# algorithm detects it is spending too long polling without -# encountering events. 0 selects a default behaviour (default: 0) +# algorithm detects it is spending too long polling without +# encountering events. 0 selects a default behaviour (default: 0) +# +# The @aio-max-batch option is available since 6.1. # # Since: 2.0 ## { 'struct': 'IothreadProperties', + 'base': 'EventLoopBaseProperties', 'data': { '*poll-max-ns': 'int', '*poll-grow': 'int', '*poll-shrink': 'int' } } ## +# @MainLoopProperties: +# +# Properties for the main-loop object. +# +# Since: 7.1 +## +{ 'struct': 'MainLoopProperties', + 'base': 'EventLoopBaseProperties', + 'data': {} } + +## # @MemoryBackendProperties: # # Properties for objects of classes derived from memory-backend. # -# @merge: if true, mark the memory as mergeable (default depends on the machine -# type) +# @merge: if true, mark the memory as mergeable (default depends on +# the machine type) # -# @dump: if true, include the memory in core dumps (default depends on the -# machine type) +# @dump: if true, include the memory in core dumps (default depends on +# the machine type) # # @host-nodes: the list of NUMA host nodes to bind the memory to # @@ -540,21 +593,31 @@ # # @prealloc: if true, preallocate memory (default: false) # -# @prealloc-threads: number of CPU threads to use for prealloc (default: 1) +# @prealloc-threads: number of CPU threads to use for prealloc +# (default: 1) +# +# @prealloc-context: thread context to use for creation of +# preallocation threads (default: none) (since 7.2) # -# @share: if false, the memory is private to QEMU; if true, it is shared -# (default: false) +# @share: if false, the memory is private to QEMU; if true, it is +# shared (default: false) +# +# @reserve: if true, reserve swap space (or huge pages) if applicable +# (default: true) (since 6.1) # # @size: size of the memory region in bytes # -# @x-use-canonical-path-for-ramblock-id: if true, the canoncial path is used -# for ramblock-id. Disable this for 4.0 -# machine types or older to allow -# migration with newer QEMU versions. -# This option is considered stable -# despite the x- prefix. (default: -# false generally, but true for machine -# types <= 4.0) +# @x-use-canonical-path-for-ramblock-id: if true, the canonical path +# is used for ramblock-id. Disable this for 4.0 machine types or +# older to allow migration with newer QEMU versions. +# (default: false generally, but true for machine types <= 4.0) +# +# Note: prealloc=true and reserve=false cannot be set at the same +# time. With reserve=true, the behavior depends on the operating +# system: for example, Linux will not reserve swap space for +# shared file mappings -- "not applicable". In contrast, +# reserve=false will bail out if it cannot be configured +# accordingly. # # Since: 2.1 ## @@ -565,7 +628,9 @@ '*policy': 'HostMemPolicy', '*prealloc': 'bool', '*prealloc-threads': 'uint32', + '*prealloc-context': 'str', '*share': 'bool', + '*reserve': 'bool', 'size': 'size', '*x-use-canonical-path-for-ramblock-id': 'bool' } } @@ -574,37 +639,61 @@ # # Properties for memory-backend-file objects. # -# @align: the base address alignment when QEMU mmap(2)s @mem-path. Some -# backend stores specified by @mem-path require an alignment different -# than the default one used by QEMU, e.g. the device DAX /dev/dax0.0 -# requires 2M alignment rather than 4K. In such cases, users can -# specify the required alignment via this option. -# 0 selects a default alignment (currently the page size). (default: 0) -# -# @discard-data: if true, the file contents can be destroyed when QEMU exits, -# to avoid unnecessarily flushing data to the backing file. Note -# that ``discard-data`` is only an optimization, and QEMU might -# not discard file contents if it aborts unexpectedly or is -# terminated using SIGKILL. (default: false) -# -# @mem-path: the path to either a shared memory or huge page filesystem mount -# -# @pmem: specifies whether the backing file specified by @mem-path is in -# host persistent memory that can be accessed using the SNIA NVM -# programming model (e.g. Intel NVDIMM). -# -# @readonly: if true, the backing file is opened read-only; if false, it is -# opened read-write. (default: false) +# @align: the base address alignment when QEMU mmap(2)s @mem-path. +# Some backend stores specified by @mem-path require an alignment +# different than the default one used by QEMU, e.g. the device DAX +# /dev/dax0.0 requires 2M alignment rather than 4K. In such cases, +# users can specify the required alignment via this option. 0 +# selects a default alignment (currently the page size). +# (default: 0) +# +# @offset: the offset into the target file that the region starts at. +# You can use this option to back multiple regions with a single +# file. Must be a multiple of the page size. +# (default: 0) (since 8.1) +# +# @discard-data: if true, the file contents can be destroyed when QEMU +# exits, to avoid unnecessarily flushing data to the backing file. +# Note that @discard-data is only an optimization, and QEMU might +# not discard file contents if it aborts unexpectedly or is +# terminated using SIGKILL. (default: false) +# +# @mem-path: the path to either a shared memory or huge page +# filesystem mount +# +# @pmem: specifies whether the backing file specified by @mem-path is +# in host persistent memory that can be accessed using the SNIA +# NVM programming model (e.g. Intel NVDIMM). +# +# @readonly: if true, the backing file is opened read-only; if false, +# it is opened read-write. (default: false) +# +# @rom: whether to create Read Only Memory (ROM) that cannot be +# modified by the VM. Any write attempts to such ROM will be +# denied. Most use cases want writable RAM instead of ROM. +# However, selected use cases, like R/O NVDIMMs, can benefit from +# ROM. If set to 'on', create ROM; if set to 'off', create +# writable RAM; if set to 'auto', the value of the @readonly +# property is used. This property is primarily helpful when we +# want to have proper RAM in configurations that would +# traditionally create ROM before this property was introduced: VM +# templating, where we want to open a file readonly (@readonly set +# to true) and mark the memory to be private for QEMU (@share set +# to false). For this use case, we need writable RAM instead of +# ROM, and want to set this property to 'off'. (default: auto, +# since 8.2) # # Since: 2.1 ## { 'struct': 'MemoryBackendFileProperties', 'base': 'MemoryBackendProperties', 'data': { '*align': 'size', + '*offset': 'size', '*discard-data': 'bool', 'mem-path': 'str', - '*pmem': { 'type': 'bool', 'if': 'defined(CONFIG_LIBPMEM)' }, - '*readonly': 'bool' } } + '*pmem': { 'type': 'bool', 'if': 'CONFIG_LIBPMEM' }, + '*readonly': 'bool', + '*rom': 'OnOffAuto' } } ## # @MemoryBackendMemfdProperties: @@ -613,16 +702,16 @@ # # The @share boolean option is true by default with memfd. # -# @hugetlb: if true, the file to be created resides in the hugetlbfs filesystem -# (default: false) +# @hugetlb: if true, the file to be created resides in the hugetlbfs +# filesystem (default: false) # -# @hugetlbsize: the hugetlb page size on systems that support multiple hugetlb -# page sizes (it must be a power of 2 value supported by the -# system). 0 selects a default page size. This option is ignored -# if @hugetlb is false. (default: 0) +# @hugetlbsize: the hugetlb page size on systems that support multiple +# hugetlb page sizes (it must be a power of 2 value supported by +# the system). 0 selects a default page size. This option is +# ignored if @hugetlb is false. (default: 0) # -# @seal: if true, create a sealed-file, which will block further resizing of -# the memory (default: true) +# @seal: if true, create a sealed-file, which will block further +# resizing of the memory (default: true) # # Since: 2.12 ## @@ -633,11 +722,29 @@ '*seal': 'bool' } } ## +# @MemoryBackendEpcProperties: +# +# Properties for memory-backend-epc objects. +# +# The @share boolean option is true by default with epc +# +# The @merge boolean option is false by default with epc +# +# The @dump boolean option is false by default with epc +# +# Since: 6.2 +## +{ 'struct': 'MemoryBackendEpcProperties', + 'base': 'MemoryBackendProperties', + 'data': {} } + +## # @PrManagerHelperProperties: # # Properties for pr-manager-helper objects. # -# @path: the path to a Unix domain socket for connecting to the external helper +# @path: the path to a Unix domain socket for connecting to the +# external helper # # Since: 2.11 ## @@ -645,13 +752,29 @@ 'data': { 'path': 'str' } } ## +# @QtestProperties: +# +# Properties for qtest objects. +# +# @chardev: the chardev to be used to receive qtest commands on. +# +# @log: the path to a log file +# +# Since: 6.0 +## +{ 'struct': 'QtestProperties', + 'data': { 'chardev': 'str', + '*log': 'str' } } + +## # @RemoteObjectProperties: # # Properties for x-remote-object objects. # # @fd: file descriptor name previously passed via 'getfd' command # -# @devid: the id of the device to be associated with the file descriptor +# @devid: the id of the device to be associated with the file +# descriptor # # Since: 6.0 ## @@ -659,17 +782,64 @@ 'data': { 'fd': 'str', 'devid': 'str' } } ## +# @VfioUserServerProperties: +# +# Properties for x-vfio-user-server objects. +# +# @socket: socket to be used by the libvfio-user library +# +# @device: the ID of the device to be emulated at the server +# +# Since: 7.1 +## +{ 'struct': 'VfioUserServerProperties', + 'data': { 'socket': 'SocketAddress', 'device': 'str' } } + +## +# @IOMMUFDProperties: +# +# Properties for iommufd objects. +# +# @fd: file descriptor name previously passed via 'getfd' command, +# which represents a pre-opened /dev/iommu. This allows the +# iommufd object to be shared across several subsystems (VFIO, +# VDPA, ...), and the file descriptor to be shared with other +# process, e.g. DPDK. (default: QEMU opens /dev/iommu by itself) +# +# Since: 9.0 +## +{ 'struct': 'IOMMUFDProperties', + 'data': { '*fd': 'str' } } + +## +# @AcpiGenericInitiatorProperties: +# +# Properties for acpi-generic-initiator objects. +# +# @pci-dev: PCI device ID to be associated with the node +# +# @node: NUMA node associated with the PCI device +# +# Since: 9.0 +## +{ 'struct': 'AcpiGenericInitiatorProperties', + 'data': { 'pci-dev': 'str', + 'node': 'uint32' } } + +## # @RngProperties: # # Properties for objects of classes derived from rng. # -# @opened: if true, the device is opened immediately when applying this option -# and will probably fail when processing the next option. Don't use; -# only provided for compatibility. (default: false) +# @opened: if true, the device is opened immediately when applying +# this option and will probably fail when processing the next +# option. Don't use; only provided for compatibility. +# (default: false) # # Features: -# @deprecated: Member @opened is deprecated. Setting true doesn't make sense, -# and false is already the default. +# +# @deprecated: Member @opened is deprecated. Setting true doesn't +# make sense, and false is already the default. # # Since: 1.3 ## @@ -681,8 +851,8 @@ # # Properties for rng-egd objects. # -# @chardev: the name of a character device backend that provides the connection -# to the RNG daemon +# @chardev: the name of a character device backend that provides the +# connection to the RNG daemon # # Since: 1.3 ## @@ -695,8 +865,8 @@ # # Properties for rng-random objects. # -# @filename: the filename of the device on the host to obtain entropy from -# (default: "/dev/urandom") +# @filename: the filename of the device on the host to obtain entropy +# from (default: "/dev/urandom") # # Since: 1.3 ## @@ -722,7 +892,11 @@ # @cbitpos: C-bit location in page table entry (default: 0) # # @reduced-phys-bits: number of bits in physical addresses that become -# unavailable when SEV is enabled +# unavailable when SEV is enabled +# +# @kernel-hashes: if true, add hashes of kernel/initrd/cmdline to a +# designated guest firmware page for measured boot with -kernel +# (default: false) (since 6.2) # # Since: 2.12 ## @@ -733,26 +907,56 @@ '*policy': 'uint32', '*handle': 'uint32', '*cbitpos': 'uint32', - 'reduced-phys-bits': 'uint32' } } + 'reduced-phys-bits': 'uint32', + '*kernel-hashes': 'bool' } } + +## +# @ThreadContextProperties: +# +# Properties for thread context objects. +# +# @cpu-affinity: the list of host CPU numbers used as CPU affinity for +# all threads created in the thread context (default: QEMU main +# thread CPU affinity) +# +# @node-affinity: the list of host node numbers that will be resolved +# to a list of host CPU numbers used as CPU affinity. This is a +# shortcut for specifying the list of host CPU numbers belonging +# to the host nodes manually by setting @cpu-affinity. +# (default: QEMU main thread affinity) +# +# Since: 7.2 +## +{ 'struct': 'ThreadContextProperties', + 'data': { '*cpu-affinity': ['uint16'], + '*node-affinity': ['uint16'] } } + ## # @ObjectType: # +# Features: +# +# @unstable: Member @x-remote-object is experimental. +# # Since: 6.0 ## { 'enum': 'ObjectType', 'data': [ + 'acpi-generic-initiator', 'authz-list', 'authz-listfile', 'authz-pam', 'authz-simple', 'can-bus', - 'can-host-socketcan', + { 'name': 'can-host-socketcan', + 'if': 'CONFIG_LINUX' }, 'colo-compare', 'cryptodev-backend', 'cryptodev-backend-builtin', + 'cryptodev-backend-lkcf', { 'name': 'cryptodev-vhost-user', - 'if': 'defined(CONFIG_VHOST_CRYPTO)' }, + 'if': 'CONFIG_VHOST_CRYPTO' }, 'dbus-vmstate', 'filter-buffer', 'filter-dump', @@ -761,27 +965,38 @@ 'filter-replay', 'filter-rewriter', 'input-barrier', - 'input-linux', + { 'name': 'input-linux', + 'if': 'CONFIG_LINUX' }, + 'iommufd', 'iothread', + 'main-loop', + { 'name': 'memory-backend-epc', + 'if': 'CONFIG_LINUX' }, 'memory-backend-file', { 'name': 'memory-backend-memfd', - 'if': 'defined(CONFIG_LINUX)' }, + 'if': 'CONFIG_LINUX' }, 'memory-backend-ram', 'pef-guest', - 'pr-manager-helper', + { 'name': 'pr-manager-helper', + 'if': 'CONFIG_LINUX' }, + 'qtest', 'rng-builtin', 'rng-egd', - 'rng-random', + { 'name': 'rng-random', + 'if': 'CONFIG_POSIX' }, 'secret', - 'secret_keyring', + { 'name': 'secret_keyring', + 'if': 'CONFIG_SECRET_KEYRING' }, 'sev-guest', + 'thread-context', 's390-pv-guest', 'throttle-group', 'tls-creds-anon', 'tls-creds-psk', 'tls-creds-x509', 'tls-cipher-suites', - 'x-remote-object' + { 'name': 'x-remote-object', 'features': [ 'unstable' ] }, + { 'name': 'x-vfio-user-server', 'features': [ 'unstable' ] } ] } ## @@ -800,16 +1015,19 @@ 'id': 'str' }, 'discriminator': 'qom-type', 'data': { + 'acpi-generic-initiator': 'AcpiGenericInitiatorProperties', 'authz-list': 'AuthZListProperties', 'authz-listfile': 'AuthZListFileProperties', 'authz-pam': 'AuthZPAMProperties', 'authz-simple': 'AuthZSimpleProperties', - 'can-host-socketcan': 'CanHostSocketcanProperties', + 'can-host-socketcan': { 'type': 'CanHostSocketcanProperties', + 'if': 'CONFIG_LINUX' }, 'colo-compare': 'ColoCompareProperties', 'cryptodev-backend': 'CryptodevBackendProperties', 'cryptodev-backend-builtin': 'CryptodevBackendProperties', + 'cryptodev-backend-lkcf': 'CryptodevBackendProperties', 'cryptodev-vhost-user': { 'type': 'CryptodevVhostUserProperties', - 'if': 'defined(CONFIG_VHOST_CRYPTO)' }, + 'if': 'CONFIG_VHOST_CRYPTO' }, 'dbus-vmstate': 'DBusVMStateProperties', 'filter-buffer': 'FilterBufferProperties', 'filter-dump': 'FilterDumpProperties', @@ -818,25 +1036,36 @@ 'filter-replay': 'NetfilterProperties', 'filter-rewriter': 'FilterRewriterProperties', 'input-barrier': 'InputBarrierProperties', - 'input-linux': 'InputLinuxProperties', + 'input-linux': { 'type': 'InputLinuxProperties', + 'if': 'CONFIG_LINUX' }, + 'iommufd': 'IOMMUFDProperties', 'iothread': 'IothreadProperties', + 'main-loop': 'MainLoopProperties', + 'memory-backend-epc': { 'type': 'MemoryBackendEpcProperties', + 'if': 'CONFIG_LINUX' }, 'memory-backend-file': 'MemoryBackendFileProperties', 'memory-backend-memfd': { 'type': 'MemoryBackendMemfdProperties', - 'if': 'defined(CONFIG_LINUX)' }, + 'if': 'CONFIG_LINUX' }, 'memory-backend-ram': 'MemoryBackendProperties', - 'pr-manager-helper': 'PrManagerHelperProperties', + 'pr-manager-helper': { 'type': 'PrManagerHelperProperties', + 'if': 'CONFIG_LINUX' }, + 'qtest': 'QtestProperties', 'rng-builtin': 'RngProperties', 'rng-egd': 'RngEgdProperties', - 'rng-random': 'RngRandomProperties', + 'rng-random': { 'type': 'RngRandomProperties', + 'if': 'CONFIG_POSIX' }, 'secret': 'SecretProperties', - 'secret_keyring': 'SecretKeyringProperties', + 'secret_keyring': { 'type': 'SecretKeyringProperties', + 'if': 'CONFIG_SECRET_KEYRING' }, 'sev-guest': 'SevGuestProperties', + 'thread-context': 'ThreadContextProperties', 'throttle-group': 'ThrottleGroupProperties', 'tls-creds-anon': 'TlsCredsAnonProperties', 'tls-creds-psk': 'TlsCredsPskProperties', 'tls-creds-x509': 'TlsCredsX509Properties', 'tls-cipher-suites': 'TlsCredsProperties', - 'x-remote-object': 'RemoteObjectProperties' + 'x-remote-object': 'RemoteObjectProperties', + 'x-vfio-user-server': 'VfioUserServerProperties' } } ## @@ -844,20 +1073,20 @@ # # Create a QOM object. # -# Returns: Nothing on success -# Error if @qom-type is not a valid class name +# Errors: +# - Error if @qom-type is not a valid class name # # Since: 2.0 # # Example: # -# -> { "execute": "object-add", -# "arguments": { "qom-type": "rng-random", "id": "rng1", -# "filename": "/dev/hwrng" } } -# <- { "return": {} } -# +# -> { "execute": "object-add", +# "arguments": { "qom-type": "rng-random", "id": "rng1", +# "filename": "/dev/hwrng" } } +# <- { "return": {} } ## -{ 'command': 'object-add', 'data': 'ObjectOptions', 'boxed': true } +{ 'command': 'object-add', 'data': 'ObjectOptions', 'boxed': true, + 'allow-preconfig': true } ## # @object-del: @@ -866,15 +1095,15 @@ # # @id: the name of the QOM object to remove # -# Returns: Nothing on success -# Error if @id is not a valid id for a QOM object +# Errors: +# - Error if @id is not a valid id for a QOM object # # Since: 2.0 # # Example: # -# -> { "execute": "object-del", "arguments": { "id": "rng1" } } -# <- { "return": {} } -# +# -> { "execute": "object-del", "arguments": { "id": "rng1" } } +# <- { "return": {} } ## -{ 'command': 'object-del', 'data': {'id': 'str'} } +{ 'command': 'object-del', 'data': {'id': 'str'}, + 'allow-preconfig': true } diff --git a/qapi/rdma.json b/qapi/rdma.json index a1d2175a8b..195c001850 100644 --- a/qapi/rdma.json +++ b/qapi/rdma.json @@ -17,20 +17,19 @@ # # @subnet-prefix: Subnet Prefix # -# @interface-id : Interface ID +# @interface-id: Interface ID # # Since: 4.0 # # Example: # -# <- {"timestamp": {"seconds": 1541579657, "microseconds": 986760}, -# "event": "RDMA_GID_STATUS_CHANGED", -# "data": -# {"netdev": "bridge0", -# "interface-id": 15880512517475447892, -# "gid-status": true, -# "subnet-prefix": 33022}} -# +# <- {"timestamp": {"seconds": 1541579657, "microseconds": 986760}, +# "event": "RDMA_GID_STATUS_CHANGED", +# "data": +# {"netdev": "bridge0", +# "interface-id": 15880512517475447892, +# "gid-status": true, +# "subnet-prefix": 33022}} ## { 'event': 'RDMA_GID_STATUS_CHANGED', 'data': { 'netdev' : 'str', diff --git a/qapi/replay.json b/qapi/replay.json index bfd83d7591..d3559f9c8f 100644 --- a/qapi/replay.json +++ b/qapi/replay.json @@ -1,4 +1,5 @@ # -*- Mode: Python -*- +# vim: filetype=python # ## @@ -12,13 +13,13 @@ # # Mode of the replay subsystem. # -# @none: normal execution mode. Replay or record are not enabled. +# @none: normal execution mode. Replay or record are not enabled. # -# @record: record mode. All non-deterministic data is written into the -# replay log. +# @record: record mode. All non-deterministic data is written into +# the replay log. # -# @play: replay mode. Non-deterministic data required for system execution -# is read from the log. +# @play: replay mode. Non-deterministic data required for system +# execution is read from the log. # # Since: 2.5 ## @@ -32,14 +33,12 @@ # # @mode: current mode. # -# @filename: name of the record/replay log file. -# It is present only in record or replay modes, when the log -# is recorded or replayed. +# @filename: name of the record/replay log file. It is present only +# in record or replay modes, when the log is recorded or replayed. # # @icount: current number of executed instructions. # # Since: 5.2 -# ## { 'struct': 'ReplayInfo', 'data': { 'mode': 'ReplayMode', '*filename': 'str', 'icount': 'int' } } @@ -47,9 +46,9 @@ ## # @query-replay: # -# Retrieve the record/replay information. -# It includes current instruction count which may be used for -# @replay-break and @replay-seek commands. +# Retrieve the record/replay information. It includes current +# instruction count which may be used for @replay-break and +# @replay-seek commands. # # Returns: record/replay information. # @@ -57,9 +56,8 @@ # # Example: # -# -> { "execute": "query-replay" } -# <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } } -# +# -> { "execute": "query-replay" } +# <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } } ## { 'command': 'query-replay', 'returns': 'ReplayInfo' } @@ -67,12 +65,12 @@ ## # @replay-break: # -# Set replay breakpoint at instruction count @icount. -# Execution stops when the specified instruction is reached. -# There can be at most one breakpoint. When breakpoint is set, any prior -# one is removed. The breakpoint may be set only in replay mode and only -# "in the future", i.e. at instruction counts greater than the current one. -# The current instruction count can be observed with @query-replay. +# Set replay breakpoint at instruction count @icount. Execution stops +# when the specified instruction is reached. There can be at most one +# breakpoint. When breakpoint is set, any prior one is removed. The +# breakpoint may be set only in replay mode and only "in the future", +# i.e. at instruction counts greater than the current one. The +# current instruction count can be observed with @query-replay. # # @icount: instruction count to stop at # @@ -80,23 +78,23 @@ # # Example: # -# -> { "execute": "replay-break", "data": { "icount": 220414 } } -# +# -> { "execute": "replay-break", "arguments": { "icount": 220414 } } +# <- { "return": {} } ## { 'command': 'replay-break', 'data': { 'icount': 'int' } } ## # @replay-delete-break: # -# Remove replay breakpoint which was set with @replay-break. -# The command is ignored when there are no replay breakpoints. +# Remove replay breakpoint which was set with @replay-break. The +# command is ignored when there are no replay breakpoints. # # Since: 5.2 # # Example: # -# -> { "execute": "replay-delete-break" } -# +# -> { "execute": "replay-delete-break" } +# <- { "return": {} } ## { 'command': 'replay-delete-break' } @@ -104,11 +102,11 @@ # @replay-seek: # # Automatically proceed to the instruction count @icount, when -# replaying the execution. The command automatically loads nearest +# replaying the execution. The command automatically loads nearest # snapshot and replays the execution to find the desired instruction. -# When there is no preceding snapshot or the execution is not replayed, -# then the command fails. -# icount for the reference may be obtained with @query-replay command. +# When there is no preceding snapshot or the execution is not +# replayed, then the command fails. Instruction count can be obtained +# with the @query-replay command. # # @icount: target instruction count # @@ -116,6 +114,7 @@ # # Example: # -# -> { "execute": "replay-seek", "data": { "icount": 220414 } } +# -> { "execute": "replay-seek", "arguments": { "icount": 220414 } } +# <- { "return": {} } ## { 'command': 'replay-seek', 'data': { 'icount': 'int' } } diff --git a/qapi/rocker.json b/qapi/rocker.json index b48e49a89b..5635cf174f 100644 --- a/qapi/rocker.json +++ b/qapi/rocker.json @@ -32,9 +32,8 @@ # # Example: # -# -> { "execute": "query-rocker", "arguments": { "name": "sw1" } } -# <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}} -# +# -> { "execute": "query-rocker", "arguments": { "name": "sw1" } } +# <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}} ## { 'command': 'query-rocker', 'data': { 'name': 'str' }, @@ -101,13 +100,12 @@ # # Example: # -# -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } } -# <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1", -# "autoneg": "off", "link-up": true, "speed": 10000}, -# {"duplex": "full", "enabled": true, "name": "sw1.2", -# "autoneg": "off", "link-up": true, "speed": 10000} -# ]} -# +# -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } } +# <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1", +# "autoneg": "off", "link-up": true, "speed": 10000}, +# {"duplex": "full", "enabled": true, "name": "sw1.2", +# "autoneg": "off", "link-up": true, "speed": 10000} +# ]} ## { 'command': 'query-rocker-ports', 'data': { 'name': 'str' }, @@ -141,7 +139,7 @@ # @ip-dst: IP header destination address # # Note: optional members may or may not appear in the flow key -# depending if they're relevant to the flow key. +# depending if they're relevant to the flow key. # # Since: 2.4 ## @@ -171,7 +169,7 @@ # @ip-tos: IP header TOS field # # Note: optional members may or may not appear in the flow mask -# depending if they're relevant to the flow mask. +# depending if they're relevant to the flow mask. # # Since: 2.4 ## @@ -198,7 +196,7 @@ # @out-pport: physical output port # # Note: optional members may or may not appear in the flow action -# depending if they're relevant to the flow action. +# depending if they're relevant to the flow action. # # Since: 2.4 ## @@ -235,8 +233,8 @@ # # @name: switch name # -# @tbl-id: flow table ID. If tbl-id is not specified, returns -# flow information for all tables. +# @tbl-id: flow table ID. If tbl-id is not specified, returns flow +# information for all tables. # # Returns: rocker OF-DPA flow information # @@ -244,17 +242,16 @@ # # Example: # -# -> { "execute": "query-rocker-of-dpa-flows", -# "arguments": { "name": "sw1" } } -# <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0}, -# "hits": 138, -# "cookie": 0, -# "action": {"goto-tbl": 10}, -# "mask": {"in-pport": 4294901760} -# }, -# {...more...}, -# ]} -# +# -> { "execute": "query-rocker-of-dpa-flows", +# "arguments": { "name": "sw1" } } +# <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0}, +# "hits": 138, +# "cookie": 0, +# "action": {"goto-tbl": 10}, +# "mask": {"in-pport": 4294901760} +# }, +# {...more...}, +# ]} ## { 'command': 'query-rocker-of-dpa-flows', 'data': { 'name': 'str', '*tbl-id': 'uint32' }, @@ -292,7 +289,7 @@ # @ttl-check: perform TTL check # # Note: optional members may or may not appear in the group depending -# if they're relevant to the group type. +# if they're relevant to the group type. # # Since: 2.4 ## @@ -311,8 +308,8 @@ # # @name: switch name # -# @type: group type. If type is not specified, returns -# group information for all group types. +# @type: group type. If type is not specified, returns group +# information for all group types. # # Returns: rocker OF-DPA group information # @@ -320,22 +317,21 @@ # # Example: # -# -> { "execute": "query-rocker-of-dpa-groups", -# "arguments": { "name": "sw1" } } -# <- { "return": [ {"type": 0, "out-pport": 2, -# "pport": 2, "vlan-id": 3841, -# "pop-vlan": 1, "id": 251723778}, -# {"type": 0, "out-pport": 0, -# "pport": 0, "vlan-id": 3841, -# "pop-vlan": 1, "id": 251723776}, -# {"type": 0, "out-pport": 1, -# "pport": 1, "vlan-id": 3840, -# "pop-vlan": 1, "id": 251658241}, -# {"type": 0, "out-pport": 0, -# "pport": 0, "vlan-id": 3840, -# "pop-vlan": 1, "id": 251658240} -# ]} -# +# -> { "execute": "query-rocker-of-dpa-groups", +# "arguments": { "name": "sw1" } } +# <- { "return": [ {"type": 0, "out-pport": 2, +# "pport": 2, "vlan-id": 3841, +# "pop-vlan": 1, "id": 251723778}, +# {"type": 0, "out-pport": 0, +# "pport": 0, "vlan-id": 3841, +# "pop-vlan": 1, "id": 251723776}, +# {"type": 0, "out-pport": 1, +# "pport": 1, "vlan-id": 3840, +# "pop-vlan": 1, "id": 251658241}, +# {"type": 0, "out-pport": 0, +# "pport": 0, "vlan-id": 3840, +# "pop-vlan": 1, "id": 251658240} +# ]} ## { 'command': 'query-rocker-of-dpa-groups', 'data': { 'name': 'str', '*type': 'uint8' }, diff --git a/qapi/run-state.json b/qapi/run-state.json index 43d66d700f..f8773f23b2 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -16,16 +16,16 @@ # @finish-migrate: guest is paused to finish the migration process # # @inmigrate: guest is paused waiting for an incoming migration. Note -# that this state does not tell whether the machine will start at the -# end of the migration. This depends on the command-line -S option and -# any invocation of 'stop' or 'cont' that has happened since QEMU was -# started. +# that this state does not tell whether the machine will start at +# the end of the migration. This depends on the command-line -S +# option and any invocation of 'stop' or 'cont' that has happened +# since QEMU was started. # -# @internal-error: An internal error that prevents further guest execution -# has occurred +# @internal-error: An internal error that prevents further guest +# execution has occurred # -# @io-error: the last IOP has failed and the device is configured to pause -# on I/O errors +# @io-error: the last IOP has failed and the device is configured to +# pause on I/O errors # # @paused: guest has been paused via the 'stop' command # @@ -43,13 +43,15 @@ # # @suspended: guest is suspended (ACPI S3) # -# @watchdog: the watchdog action is configured to pause and has been triggered +# @watchdog: the watchdog action is configured to pause and has been +# triggered # -# @guest-panicked: guest has been panicked as a result of guest OS panic +# @guest-panicked: guest has been panicked as a result of guest OS +# panic # -# @colo: guest is paused to save/restore VM state under colo checkpoint, -# VM can not get into this state unless colo capability is enabled -# for migration. (since 2.8) +# @colo: guest is paused to save/restore VM state under colo +# checkpoint, VM can not get into this state unless colo +# capability is enabled for migration. (since 2.8) ## { 'enum': 'RunState', 'data': [ 'debug', 'inmigrate', 'internal-error', 'io-error', 'paused', @@ -75,58 +77,57 @@ # @host-ui: Reaction to a UI event, like window close # # @guest-shutdown: Guest shutdown/suspend request, via ACPI or other -# hardware-specific means +# hardware-specific means # # @guest-reset: Guest reset request, and command line turns that into -# a shutdown +# a shutdown # -# @guest-panic: Guest panicked, and command line turns that into a shutdown +# @guest-panic: Guest panicked, and command line turns that into a +# shutdown # -# @subsystem-reset: Partial guest reset that does not trigger QMP events and -# ignores --no-reboot. This is useful for sanitizing -# hypercalls on s390 that are used during kexec/kdump/boot +# @subsystem-reset: Partial guest reset that does not trigger QMP +# events and ignores --no-reboot. This is useful for sanitizing +# hypercalls on s390 that are used during kexec/kdump/boot # +# @snapshot-load: A snapshot is being loaded by the record & replay +# subsystem. This value is used only within QEMU. It doesn't +# occur in QMP. (since 7.2) ## { 'enum': 'ShutdownCause', # Beware, shutdown_caused_by_guest() depends on enumeration order 'data': [ 'none', 'host-error', 'host-qmp-quit', 'host-qmp-system-reset', 'host-signal', 'host-ui', 'guest-shutdown', 'guest-reset', - 'guest-panic', 'subsystem-reset'] } + 'guest-panic', 'subsystem-reset', 'snapshot-load'] } ## # @StatusInfo: # -# Information about VCPU run state +# Information about VM run state # # @running: true if all VCPUs are runnable, false if not runnable # -# @singlestep: true if VCPUs are in single-step mode -# # @status: the virtual machine @RunState # -# Since: 0.14 -# -# Notes: @singlestep is enabled through the GDB stub +# Since: 0.14 ## { 'struct': 'StatusInfo', - 'data': {'running': 'bool', 'singlestep': 'bool', 'status': 'RunState'} } + 'data': {'running': 'bool', + 'status': 'RunState'} } ## # @query-status: # -# Query the run status of all VCPUs +# Query the run status of the VM # -# Returns: @StatusInfo reflecting all VCPUs +# Returns: @StatusInfo reflecting the VM # -# Since: 0.14 +# Since: 0.14 # # Example: # -# -> { "execute": "query-status" } -# <- { "return": { "running": true, -# "singlestep": false, -# "status": "running" } } -# +# -> { "execute": "query-status" } +# <- { "return": { "running": true, +# "status": "running" } } ## { 'command': 'query-status', 'returns': 'StatusInfo', 'allow-preconfig': true } @@ -134,41 +135,43 @@ ## # @SHUTDOWN: # -# Emitted when the virtual machine has shut down, indicating that qemu is -# about to exit. +# Emitted when the virtual machine has shut down, indicating that qemu +# is about to exit. # -# @guest: If true, the shutdown was triggered by a guest request (such as -# a guest-initiated ACPI shutdown request or other hardware-specific action) -# rather than a host request (such as sending qemu a SIGINT). (since 2.10) +# @guest: If true, the shutdown was triggered by a guest request (such +# as a guest-initiated ACPI shutdown request or other +# hardware-specific action) rather than a host request (such as +# sending qemu a SIGINT). (since 2.10) # -# @reason: The @ShutdownCause which resulted in the SHUTDOWN. (since 4.0) +# @reason: The @ShutdownCause which resulted in the SHUTDOWN. +# (since 4.0) # -# Note: If the command-line option "-no-shutdown" has been specified, qemu will -# not exit, and a STOP event will eventually follow the SHUTDOWN event +# Note: If the command-line option "-no-shutdown" has been specified, +# qemu will not exit, and a STOP event will eventually follow the +# SHUTDOWN event # # Since: 0.12 # # Example: # -# <- { "event": "SHUTDOWN", "data": { "guest": true }, -# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } -# +# <- { "event": "SHUTDOWN", +# "data": { "guest": true, "reason": "guest-shutdown" }, +# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } ## { 'event': 'SHUTDOWN', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } } ## # @POWERDOWN: # -# Emitted when the virtual machine is powered down through the power control -# system, such as via ACPI. +# Emitted when the virtual machine is powered down through the power +# control system, such as via ACPI. # # Since: 0.12 # # Example: # -# <- { "event": "POWERDOWN", -# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } -# +# <- { "event": "POWERDOWN", +# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } ## { 'event': 'POWERDOWN' } @@ -178,19 +181,19 @@ # Emitted when the virtual machine is reset # # @guest: If true, the reset was triggered by a guest request (such as -# a guest-initiated ACPI reboot request or other hardware-specific action) -# rather than a host request (such as the QMP command system_reset). -# (since 2.10) +# a guest-initiated ACPI reboot request or other hardware-specific +# action) rather than a host request (such as the QMP command +# system_reset). (since 2.10) # -# @reason: The @ShutdownCause of the RESET. (since 4.0) +# @reason: The @ShutdownCause of the RESET. (since 4.0) # # Since: 0.12 # # Example: # -# <- { "event": "RESET", "data": { "guest": false }, -# "timestamp": { "seconds": 1267041653, "microseconds": 9518 } } -# +# <- { "event": "RESET", +# "data": { "guest": false, "reason": "guest-reset" }, +# "timestamp": { "seconds": 1267041653, "microseconds": 9518 } } ## { 'event': 'RESET', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } } @@ -203,9 +206,8 @@ # # Example: # -# <- { "event": "STOP", -# "timestamp": { "seconds": 1267041730, "microseconds": 281295 } } -# +# <- { "event": "STOP", +# "timestamp": { "seconds": 1267041730, "microseconds": 281295 } } ## { 'event': 'STOP' } @@ -218,58 +220,57 @@ # # Example: # -# <- { "event": "RESUME", -# "timestamp": { "seconds": 1271770767, "microseconds": 582542 } } -# +# <- { "event": "RESUME", +# "timestamp": { "seconds": 1271770767, "microseconds": 582542 } } ## { 'event': 'RESUME' } ## # @SUSPEND: # -# Emitted when guest enters a hardware suspension state, for example, S3 state, -# which is sometimes called standby state +# Emitted when guest enters a hardware suspension state, for example, +# S3 state, which is sometimes called standby state # # Since: 1.1 # # Example: # -# <- { "event": "SUSPEND", -# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } -# +# <- { "event": "SUSPEND", +# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } ## { 'event': 'SUSPEND' } ## # @SUSPEND_DISK: # -# Emitted when guest enters a hardware suspension state with data saved on -# disk, for example, S4 state, which is sometimes called hibernate state +# Emitted when guest enters a hardware suspension state with data +# saved on disk, for example, S4 state, which is sometimes called +# hibernate state # -# Note: QEMU shuts down (similar to event @SHUTDOWN) when entering this state +# Note: QEMU shuts down (similar to event @SHUTDOWN) when entering +# this state # # Since: 1.2 # # Example: # -# <- { "event": "SUSPEND_DISK", -# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } -# +# <- { "event": "SUSPEND_DISK", +# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } ## { 'event': 'SUSPEND_DISK' } ## # @WAKEUP: # -# Emitted when the guest has woken up from suspend state and is running +# Emitted when the guest has woken up from suspend state and is +# running # # Since: 1.1 # # Example: # -# <- { "event": "WAKEUP", -# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } -# +# <- { "event": "WAKEUP", +# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } ## { 'event': 'WAKEUP' } @@ -280,8 +281,9 @@ # # @action: action that has been taken # -# Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is -# followed respectively by the RESET, SHUTDOWN, or STOP events +# Note: If action is "reset", "shutdown", or "pause" the WATCHDOG +# event is followed respectively by the RESET, SHUTDOWN, or STOP +# events # # Note: This event is rate-limited. # @@ -289,10 +291,9 @@ # # Example: # -# <- { "event": "WATCHDOG", -# "data": { "action": "reset" }, -# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } -# +# <- { "event": "WATCHDOG", +# "data": { "action": "reset" }, +# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } ## { 'event': 'WATCHDOG', 'data': { 'action': 'WatchdogAction' } } @@ -300,13 +301,13 @@ ## # @WatchdogAction: # -# An enumeration of the actions taken when the watchdog device's timer is -# expired +# An enumeration of the actions taken when the watchdog device's timer +# is expired # # @reset: system resets # -# @shutdown: system shutdown, note that it is similar to @powerdown, which -# tries to set to system status and notify guest +# @shutdown: system shutdown, note that it is similar to @powerdown, +# which tries to set to system status and notify guest # # @poweroff: system poweroff, the emulator program exits # @@ -316,8 +317,8 @@ # # @none: nothing is done # -# @inject-nmi: a non-maskable interrupt is injected into the first VCPU (all -# VCPUS on x86) (since 2.4) +# @inject-nmi: a non-maskable interrupt is injected into the first +# VCPU (all VCPUS on x86) (since 2.4) # # Since: 2.1 ## @@ -332,7 +333,8 @@ # # @reset: Reset the VM # -# @shutdown: Shutdown the VM and exit, according to the shutdown action +# @shutdown: Shutdown the VM and exit, according to the shutdown +# action # # Since: 6.0 ## @@ -346,7 +348,7 @@ # # @poweroff: Shutdown the VM and exit # -# @pause: pause the VM# +# @pause: pause the VM # # Since: 6.0 ## @@ -360,27 +362,39 @@ # # @pause: Pause the VM # -# @shutdown: Shutdown the VM and exit, according to the shutdown action +# @shutdown: Shutdown the VM and exit, according to the shutdown +# action +# +# @exit-failure: Shutdown the VM and exit with nonzero status (since +# 7.1) # # Since: 6.0 ## { 'enum': 'PanicAction', - 'data': [ 'pause', 'shutdown', 'none' ] } + 'data': [ 'pause', 'shutdown', 'exit-failure', 'none' ] } ## # @watchdog-set-action: # -# Set watchdog action +# Set watchdog action. +# +# @action: @WatchdogAction action taken when watchdog timer expires. # # Since: 2.11 +# +# Example: +# +# -> { "execute": "watchdog-set-action", +# "arguments": { "action": "inject-nmi" } } +# <- { "return": {} } ## { 'command': 'watchdog-set-action', 'data' : {'action': 'WatchdogAction'} } ## # @set-action: # -# Set the actions that will be taken by the emulator in response to guest -# events. +# Set the actions that will be taken by the emulator in response to +# guest events. # # @reboot: @RebootAction action taken on guest reboot. # @@ -388,20 +402,18 @@ # # @panic: @PanicAction action taken on guest panic. # -# @watchdog: @WatchdogAction action taken when watchdog timer expires . -# -# Returns: Nothing on success. +# @watchdog: @WatchdogAction action taken when watchdog timer expires. # # Since: 6.0 # # Example: # -# -> { "execute": "set-action", -# "arguments": { "reboot": "shutdown", -# "shutdown" : "pause", -# "panic": "pause", -# "watchdog": "inject-nmi" } } -# <- { "return": {} } +# -> { "execute": "set-action", +# "arguments": { "reboot": "shutdown", +# "shutdown" : "pause", +# "panic": "pause", +# "watchdog": "inject-nmi" } } +# <- { "return": {} } ## { 'command': 'set-action', 'data': { '*reboot': 'RebootAction', @@ -423,9 +435,9 @@ # # Example: # -# <- { "event": "GUEST_PANICKED", -# "data": { "action": "pause" } } -# +# <- { "event": "GUEST_PANICKED", +# "data": { "action": "pause" }, +# "timestamp": { "seconds": 1648245231, "microseconds": 900001 } } ## { 'event': 'GUEST_PANICKED', 'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } } @@ -443,9 +455,9 @@ # # Example: # -# <- { "event": "GUEST_CRASHLOADED", -# "data": { "action": "run" } } -# +# <- { "event": "GUEST_CRASHLOADED", +# "data": { "action": "run" }, +# "timestamp": { "seconds": 1648245259, "microseconds": 893771 } } ## { 'event': 'GUEST_CRASHLOADED', 'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } } @@ -457,7 +469,11 @@ # # @pause: system pauses # -# Since: 2.1 (poweroff since 2.8, run since 5.0) +# @poweroff: system powers off (since 2.8) +# +# @run: system continues to run (since 5.0) +# +# Since: 2.1 ## { 'enum': 'GuestPanicAction', 'data': [ 'pause', 'poweroff', 'run' ] } @@ -488,22 +504,38 @@ {'union': 'GuestPanicInformation', 'base': {'type': 'GuestPanicInformationType'}, 'discriminator': 'type', - 'data': { 'hyper-v': 'GuestPanicInformationHyperV', - 's390': 'GuestPanicInformationS390' } } + 'data': {'hyper-v': 'GuestPanicInformationHyperV', + 's390': 'GuestPanicInformationS390'}} ## # @GuestPanicInformationHyperV: # # Hyper-V specific guest panic information (HV crash MSRs) # +# @arg1: for Windows, STOP code for the guest crash. For Linux, +# an error code. +# +# @arg2: for Windows, first argument of the STOP. For Linux, the +# guest OS ID, which has the kernel version in bits 16-47 +# and 0x8100 in bits 48-63. +# +# @arg3: for Windows, second argument of the STOP. For Linux, the +# program counter of the guest. +# +# @arg4: for Windows, third argument of the STOP. For Linux, the +# RAX register (x86) or the stack pointer (aarch64) of the guest. +# +# @arg5: for Windows, fourth argument of the STOP. For x86 Linux, the +# stack pointer of the guest. +# # Since: 2.9 ## {'struct': 'GuestPanicInformationHyperV', - 'data': { 'arg1': 'uint64', - 'arg2': 'uint64', - 'arg3': 'uint64', - 'arg4': 'uint64', - 'arg5': 'uint64' } } + 'data': {'arg1': 'uint64', + 'arg2': 'uint64', + 'arg3': 'uint64', + 'arg4': 'uint64', + 'arg5': 'uint64'}} ## # @S390CrashReason: @@ -514,13 +546,13 @@ # # @disabled-wait: the CPU has entered a disabled wait state # -# @extint-loop: clock comparator or cpu timer interrupt with new PSW enabled -# for external interrupts +# @extint-loop: clock comparator or cpu timer interrupt with new PSW +# enabled for external interrupts # # @pgmint-loop: program interrupt with BAD new PSW # -# @opint-loop: operation exception interrupt with invalid code at the program -# interrupt new PSW +# @opint-loop: operation exception interrupt with invalid code at the +# program interrupt new PSW # # Since: 2.12 ## @@ -537,17 +569,20 @@ # S390 specific guest panic information (PSW) # # @core: core id of the CPU that crashed +# # @psw-mask: control fields of guest PSW +# # @psw-addr: guest instruction address +# # @reason: guest crash reason # # Since: 2.12 ## {'struct': 'GuestPanicInformationS390', - 'data': { 'core': 'uint32', - 'psw-mask': 'uint64', - 'psw-addr': 'uint64', - 'reason': 'S390CrashReason' } } + 'data': {'core': 'uint32', + 'psw-mask': 'uint64', + 'psw-addr': 'uint64', + 'reason': 'S390CrashReason'}} ## # @MEMORY_FAILURE: @@ -556,19 +591,20 @@ # # @recipient: recipient is defined as @MemoryFailureRecipient. # -# @action: action that has been taken. action is defined as @MemoryFailureAction. +# @action: action that has been taken. # -# @flags: flags for MemoryFailureAction. action is defined as @MemoryFailureFlags. +# @flags: flags for MemoryFailureAction. # # Since: 5.2 # # Example: # -# <- { "event": "MEMORY_FAILURE", -# "data": { "recipient": "hypervisor", -# "action": "fatal", -# "flags": { 'action-required': false } } -# +# <- { "event": "MEMORY_FAILURE", +# "data": { "recipient": "hypervisor", +# "action": "fatal", +# "flags": { "action-required": false, +# "recursive": false } }, +# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } ## { 'event': 'MEMORY_FAILURE', 'data': { 'recipient': 'MemoryFailureRecipient', @@ -580,40 +616,38 @@ # # Hardware memory failure occurs, handled by recipient. # -# @hypervisor: memory failure at QEMU process address space. -# (none guest memory, but used by QEMU itself). +# @hypervisor: memory failure at QEMU process address space. (none +# guest memory, but used by QEMU itself). # # @guest: memory failure at guest memory, # # Since: 5.2 -# ## { 'enum': 'MemoryFailureRecipient', 'data': [ 'hypervisor', 'guest' ] } - ## # @MemoryFailureAction: # # Actions taken by QEMU in response to a hardware memory failure. # -# @ignore: the memory failure could be ignored. This will only be the case -# for action-optional failures. +# @ignore: the memory failure could be ignored. This will only be the +# case for action-optional failures. # -# @inject: memory failure occurred in guest memory, the guest enabled MCE -# handling mechanism, and QEMU could inject the MCE into the guest -# successfully. +# @inject: memory failure occurred in guest memory, the guest enabled +# MCE handling mechanism, and QEMU could inject the MCE into the +# guest successfully. # -# @fatal: the failure is unrecoverable. This occurs for action-required -# failures if the recipient is the hypervisor; QEMU will exit. +# @fatal: the failure is unrecoverable. This occurs for +# action-required failures if the recipient is the hypervisor; +# QEMU will exit. # -# @reset: the failure is unrecoverable but confined to the guest. This -# occurs if the recipient is a guest guest which is not ready -# to handle memory failures. +# @reset: the failure is unrecoverable but confined to the guest. +# This occurs if the recipient is a guest guest which is not ready +# to handle memory failures. # # Since: 5.2 -# ## { 'enum': 'MemoryFailureAction', 'data': [ 'ignore', @@ -627,14 +661,31 @@ # Additional information on memory failures. # # @action-required: whether a memory failure event is action-required -# or action-optional (e.g. a failure during memory scrub). +# or action-optional (e.g. a failure during memory scrub). # -# @recursive: whether the failure occurred while the previous -# failure was still in progress. +# @recursive: whether the failure occurred while the previous failure +# was still in progress. # # Since: 5.2 -# ## { 'struct': 'MemoryFailureFlags', 'data': { 'action-required': 'bool', 'recursive': 'bool'} } + +## +# @NotifyVmexitOption: +# +# An enumeration of the options specified when enabling notify VM exit +# +# @run: enable the feature, do nothing and continue if the notify VM +# exit happens. +# +# @internal-error: enable the feature, raise a internal error if the +# notify VM exit happens. +# +# @disable: disable the feature. +# +# Since: 7.2 +## +{ 'enum': 'NotifyVmexitOption', + 'data': [ 'run', 'internal-error', 'disable' ] } diff --git a/qapi/sockets.json b/qapi/sockets.json index 2e83452797..aa97c89768 100644 --- a/qapi/sockets.json +++ b/qapi/sockets.json @@ -5,8 +5,6 @@ # = Socket data types ## -{ 'include': 'common.json' } - ## # @NetworkAddressFamily: # @@ -41,21 +39,26 @@ ## # @InetSocketAddress: # -# Captures a socket address or address range in the Internet namespace. +# Captures a socket address or address range in the Internet +# namespace. # -# @numeric: true if the host/port are guaranteed to be numeric, -# false if name resolution should be attempted. Defaults to false. -# (Since 2.9) +# @numeric: true if the host/port are guaranteed to be numeric, false +# if name resolution should be attempted. Defaults to false. +# (Since 2.9) # # @to: If present, this is range of possible addresses, with port -# between @port and @to. +# between @port and @to. +# +# @ipv4: whether to accept IPv4 addresses, default try both IPv4 and +# IPv6 # -# @ipv4: whether to accept IPv4 addresses, default try both IPv4 and IPv6 +# @ipv6: whether to accept IPv6 addresses, default try both IPv4 and +# IPv6 # -# @ipv6: whether to accept IPv6 addresses, default try both IPv4 and IPv6 +# @keep-alive: enable keep-alive when connecting to this socket. Not +# supported for passive sockets. (Since 4.2) # -# @keep-alive: enable keep-alive when connecting to this socket. Not supported -# for passive sockets. (Since 4.2) +# @mptcp: enable multi-path TCP. (Since 6.1) # # Since: 1.3 ## @@ -66,7 +69,8 @@ '*to': 'uint16', '*ipv4': 'bool', '*ipv6': 'bool', - '*keep-alive': 'bool' } } + '*keep-alive': 'bool', + '*mptcp': { 'type': 'bool', 'if': 'HAVE_IPPROTO_MPTCP' } } } ## # @UnixSocketAddress: @@ -74,20 +78,22 @@ # Captures a socket address in the local ("Unix socket") namespace. # # @path: filesystem path to use +# # @abstract: if true, this is a Linux abstract socket address. @path -# will be prefixed by a null byte, and optionally padded -# with null bytes. Defaults to false. (Since 5.1) +# will be prefixed by a null byte, and optionally padded with null +# bytes. Defaults to false. (Since 5.1) +# # @tight: if false, pad an abstract socket address with enough null -# bytes to make it fill struct sockaddr_un member sun_path. -# Defaults to true. (Since 5.1) +# bytes to make it fill struct sockaddr_un member sun_path. +# Defaults to true. (Since 5.1) # # Since: 1.3 ## { 'struct': 'UnixSocketAddress', 'data': { 'path': 'str', - '*abstract': { 'type': 'bool', 'if': 'defined(CONFIG_LINUX)' }, - '*tight': { 'type': 'bool', 'if': 'defined(CONFIG_LINUX)' } } } + '*abstract': { 'type': 'bool', 'if': 'CONFIG_LINUX' }, + '*tight': { 'type': 'bool', 'if': 'CONFIG_LINUX' } } } ## # @VsockSocketAddress: @@ -95,10 +101,11 @@ # Captures a socket address in the vsock namespace. # # @cid: unique host identifier +# # @port: port # # Note: string types are used to allow for possible future hostname or -# service resolution support. +# service resolution support. # # Since: 2.8 ## @@ -108,40 +115,97 @@ 'port': 'str' } } ## +# @FdSocketAddress: +# +# A file descriptor name or number. +# +# @str: decimal is for file descriptor number, otherwise it's a file +# descriptor name. Named file descriptors are permitted in +# monitor commands, in combination with the 'getfd' command. +# Decimal file descriptors are permitted at startup or other +# contexts where no monitor context is active. +# +# Since: 1.2 +## +{ 'struct': 'FdSocketAddress', + 'data': { + 'str': 'str' } } + +## +# @InetSocketAddressWrapper: +# +# @data: internet domain socket address +# +# Since: 1.3 +## +{ 'struct': 'InetSocketAddressWrapper', + 'data': { 'data': 'InetSocketAddress' } } + +## +# @UnixSocketAddressWrapper: +# +# @data: UNIX domain socket address +# +# Since: 1.3 +## +{ 'struct': 'UnixSocketAddressWrapper', + 'data': { 'data': 'UnixSocketAddress' } } + +## +# @VsockSocketAddressWrapper: +# +# @data: VSOCK domain socket address +# +# Since: 2.8 +## +{ 'struct': 'VsockSocketAddressWrapper', + 'data': { 'data': 'VsockSocketAddress' } } + +## +# @FdSocketAddressWrapper: +# +# @data: file descriptor name or number +# +# Since: 1.3 +## +{ 'struct': 'FdSocketAddressWrapper', + 'data': { 'data': 'FdSocketAddress' } } + +## # @SocketAddressLegacy: # -# Captures the address of a socket, which could also be a named file descriptor +# Captures the address of a socket, which could also be a named file +# descriptor +# +# @type: Transport type # # Note: This type is deprecated in favor of SocketAddress. The -# difference between SocketAddressLegacy and SocketAddress is that the -# latter is a flat union rather than a simple union. Flat is nicer -# because it avoids nesting on the wire, i.e. that form has fewer {}. - +# difference between SocketAddressLegacy and SocketAddress is that +# the latter has fewer {} on the wire. # # Since: 1.3 ## { 'union': 'SocketAddressLegacy', + 'base': { 'type': 'SocketAddressType' }, + 'discriminator': 'type', 'data': { - 'inet': 'InetSocketAddress', - 'unix': 'UnixSocketAddress', - 'vsock': 'VsockSocketAddress', - 'fd': 'String' } } + 'inet': 'InetSocketAddressWrapper', + 'unix': 'UnixSocketAddressWrapper', + 'vsock': 'VsockSocketAddressWrapper', + 'fd': 'FdSocketAddressWrapper' } } ## # @SocketAddressType: # # Available SocketAddress types # -# @inet: Internet address +# @inet: Internet address # -# @unix: Unix domain socket +# @unix: Unix domain socket # # @vsock: VMCI address # -# @fd: decimal is for file descriptor number, otherwise a file descriptor name. -# Named file descriptors are permitted in monitor commands, in combination -# with the 'getfd' command. Decimal file descriptors are permitted at -# startup or other contexts where no monitor context is active. +# @fd: Socket file descriptor # # Since: 2.9 ## @@ -151,10 +215,10 @@ ## # @SocketAddress: # -# Captures the address of a socket, which could also be a named file +# Captures the address of a socket, which could also be a socket file # descriptor # -# @type: Transport type +# @type: Transport type # # Since: 2.9 ## @@ -164,4 +228,4 @@ 'data': { 'inet': 'InetSocketAddress', 'unix': 'UnixSocketAddress', 'vsock': 'VsockSocketAddress', - 'fd': 'String' } } + 'fd': 'FdSocketAddress' } } diff --git a/qapi/stats.json b/qapi/stats.json new file mode 100644 index 0000000000..578b52c7ef --- /dev/null +++ b/qapi/stats.json @@ -0,0 +1,277 @@ +# -*- Mode: Python -*- +# vim: filetype=python +# +# Copyright (c) 2022 Oracle and/or its affiliates. +# +# This work is licensed under the terms of the GNU GPL, version 2 or later. +# See the COPYING file in the top-level directory. +# +# SPDX-License-Identifier: GPL-2.0-or-later + +## +# = Statistics +## + +## +# @StatsType: +# +# Enumeration of statistics types +# +# @cumulative: stat is cumulative; value can only increase. +# +# @instant: stat is instantaneous; value can increase or decrease. +# +# @peak: stat is the peak value; value can only increase. +# +# @linear-histogram: stat is a linear histogram. +# +# @log2-histogram: stat is a logarithmic histogram, with one bucket +# for each power of two. +# +# Since: 7.1 +## +{ 'enum' : 'StatsType', + 'data' : [ 'cumulative', 'instant', 'peak', 'linear-histogram', + 'log2-histogram' ] } + +## +# @StatsUnit: +# +# Enumeration of unit of measurement for statistics +# +# @bytes: stat reported in bytes. +# +# @seconds: stat reported in seconds. +# +# @cycles: stat reported in clock cycles. +# +# @boolean: stat is a boolean value. +# +# Since: 7.1 +## +{ 'enum' : 'StatsUnit', + 'data' : [ 'bytes', 'seconds', 'cycles', 'boolean' ] } + +## +# @StatsProvider: +# +# Enumeration of statistics providers. +# +# @kvm: since 7.1 +# +# @cryptodev: since 8.0 +# +# Since: 7.1 +## +{ 'enum': 'StatsProvider', + 'data': [ 'kvm', 'cryptodev' ] } + +## +# @StatsTarget: +# +# The kinds of objects on which one can request statistics. +# +# @vm: statistics that apply to the entire virtual machine or the +# entire QEMU process. +# +# @vcpu: statistics that apply to a single virtual CPU. +# +# @cryptodev: statistics that apply to a crypto device (since 8.0) +# +# Since: 7.1 +## +{ 'enum': 'StatsTarget', + 'data': [ 'vm', 'vcpu', 'cryptodev' ] } + +## +# @StatsRequest: +# +# Indicates a set of statistics that should be returned by +# query-stats. +# +# @provider: provider for which to return statistics. +# +# @names: statistics to be returned (all if omitted). +# +# Since: 7.1 +## +{ 'struct': 'StatsRequest', + 'data': { 'provider': 'StatsProvider', + '*names': [ 'str' ] } } + +## +# @StatsVCPUFilter: +# +# @vcpus: list of QOM paths for the desired vCPU objects. +# +# Since: 7.1 +## +{ 'struct': 'StatsVCPUFilter', + 'data': { '*vcpus': [ 'str' ] } } + +## +# @StatsFilter: +# +# The arguments to the query-stats command; specifies a target for +# which to request statistics and optionally the required subset of +# information for that target. +# +# @target: the kind of objects to query. Note that each possible +# target may enable additional filtering options +# +# @providers: which providers to request statistics from, and optionally +# which named values to return within each provider +# +# Since: 7.1 +## +{ 'union': 'StatsFilter', + 'base': { + 'target': 'StatsTarget', + '*providers': [ 'StatsRequest' ] }, + 'discriminator': 'target', + 'data': { 'vcpu': 'StatsVCPUFilter' } } + +## +# @StatsValue: +# +# @scalar: single unsigned 64-bit integers. +# +# @boolean: single boolean value. +# +# @list: list of unsigned 64-bit integers (used for histograms). +# +# Since: 7.1 +## +{ 'alternate': 'StatsValue', + 'data': { 'scalar': 'uint64', + 'boolean': 'bool', + 'list': [ 'uint64' ] } } + +## +# @Stats: +# +# @name: name of stat. +# +# @value: stat value. +# +# Since: 7.1 +## +{ 'struct': 'Stats', + 'data': { 'name': 'str', + 'value' : 'StatsValue' } } + +## +# @StatsResult: +# +# @provider: provider for this set of statistics. +# +# @qom-path: Path to the object for which the statistics are returned, +# if the object is exposed in the QOM tree +# +# @stats: list of statistics. +# +# Since: 7.1 +## +{ 'struct': 'StatsResult', + 'data': { 'provider': 'StatsProvider', + '*qom-path': 'str', + 'stats': [ 'Stats' ] } } + +## +# @query-stats: +# +# Return runtime-collected statistics for objects such as the VM or +# its vCPUs. +# +# The arguments are a StatsFilter and specify the provider and objects +# to return statistics about. +# +# Returns: a list of StatsResult, one for each provider and object +# (e.g., for each vCPU). +# +# Since: 7.1 +## +{ 'command': 'query-stats', + 'data': 'StatsFilter', + 'boxed': true, + 'returns': [ 'StatsResult' ] } + +## +# @StatsSchemaValue: +# +# Schema for a single statistic. +# +# @name: name of the statistic; each element of the schema is uniquely +# identified by a target, a provider (both available in +# @StatsSchema) and the name. +# +# @type: kind of statistic. +# +# @unit: basic unit of measure for the statistic; if missing, the +# statistic is a simple number or counter. +# +# @base: base for the multiple of @unit in which the statistic is +# measured. Only present if @exponent is non-zero; @base and +# @exponent together form a SI prefix (e.g., _nano-_ for +# ``base=10`` and ``exponent=-9``) or IEC binary prefix (e.g. +# _kibi-_ for ``base=2`` and ``exponent=10``) +# +# @exponent: exponent for the multiple of @unit in which the statistic +# is expressed, or 0 for the basic unit +# +# @bucket-size: Present when @type is "linear-histogram", contains the +# width of each bucket of the histogram. +# +# Since: 7.1 +## +{ 'struct': 'StatsSchemaValue', + 'data': { 'name': 'str', + 'type': 'StatsType', + '*unit': 'StatsUnit', + '*base': 'int8', + 'exponent': 'int16', + '*bucket-size': 'uint32' } } + +## +# @StatsSchema: +# +# Schema for all available statistics for a provider and target. +# +# @provider: provider for this set of statistics. +# +# @target: the kind of object that can be queried through the +# provider. +# +# @stats: list of statistics. +# +# Since: 7.1 +## +{ 'struct': 'StatsSchema', + 'data': { 'provider': 'StatsProvider', + 'target': 'StatsTarget', + 'stats': [ 'StatsSchemaValue' ] } } + +## +# @query-stats-schemas: +# +# Return the schema for all available runtime-collected statistics. +# +# @provider: a provider to restrict the query to. +# +# Note: runtime-collected statistics and their names fall outside +# QEMU's usual deprecation policies. QEMU will try to keep the +# set of available data stable, together with their names, but +# will not guarantee stability at all costs; the same is true of +# providers that source statistics externally, e.g. from Linux. +# For example, if the same value is being tracked with different +# names on different architectures or by different providers, one +# of them might be renamed. A statistic might go away if an +# algorithm is changed or some code is removed; changing a default +# might cause previously useful statistics to always report 0. +# Such changes, however, are expected to be rare. +# +# Since: 7.1 +## +{ 'command': 'query-stats-schemas', + 'data': { '*provider': 'StatsProvider' }, + 'returns': [ 'StatsSchema' ] } diff --git a/qapi/string-output-visitor.c b/qapi/string-output-visitor.c index 5506c933de..5115536b15 100644 --- a/qapi/string-output-visitor.c +++ b/qapi/string-output-visitor.c @@ -14,7 +14,6 @@ #include "qemu/cutils.h" #include "qapi/string-output-visitor.h" #include "qapi/visitor-impl.h" -#include "qemu/host-utils.h" #include <math.h> #include "qemu/range.h" @@ -66,6 +65,7 @@ struct StringOutputVisitor } range_start, range_end; GList *ranges; void *list; /* Only needed for sanity checking the caller */ + unsigned int struct_nesting; }; static StringOutputVisitor *to_sov(Visitor *v) @@ -75,11 +75,27 @@ static StringOutputVisitor *to_sov(Visitor *v) static void string_output_set(StringOutputVisitor *sov, char *string) { - if (sov->string) { - g_string_free(sov->string, true); + switch (sov->list_mode) { + case LM_STARTED: + sov->list_mode = LM_IN_PROGRESS; + /* fall through */ + case LM_NONE: + if (sov->string) { + g_string_free(sov->string, true); + } + sov->string = g_string_new(string); + g_free(string); + break; + + case LM_IN_PROGRESS: + case LM_END: + g_string_append(sov->string, ", "); + g_string_append(sov->string, string); + break; + + default: + abort(); } - sov->string = g_string_new(string); - g_free(string); } static void string_output_append(StringOutputVisitor *sov, int64_t a) @@ -129,6 +145,10 @@ static bool print_type_int64(Visitor *v, const char *name, int64_t *obj, StringOutputVisitor *sov = to_sov(v); GList *l; + if (sov->struct_nesting) { + return true; + } + switch (sov->list_mode) { case LM_NONE: string_output_append(sov, *obj); @@ -216,6 +236,10 @@ static bool print_type_size(Visitor *v, const char *name, uint64_t *obj, uint64_t val; char *out, *psize; + if (sov->struct_nesting) { + return true; + } + if (!sov->human) { out = g_strdup_printf("%"PRIu64, *obj); string_output_set(sov, out); @@ -235,6 +259,11 @@ static bool print_type_bool(Visitor *v, const char *name, bool *obj, Error **errp) { StringOutputVisitor *sov = to_sov(v); + + if (sov->struct_nesting) { + return true; + } + string_output_set(sov, g_strdup(*obj ? "true" : "false")); return true; } @@ -245,6 +274,10 @@ static bool print_type_str(Visitor *v, const char *name, char **obj, StringOutputVisitor *sov = to_sov(v); char *out; + if (sov->struct_nesting) { + return true; + } + if (sov->human) { out = *obj ? g_strdup_printf("\"%s\"", *obj) : g_strdup("<null>"); } else { @@ -258,6 +291,11 @@ static bool print_type_number(Visitor *v, const char *name, double *obj, Error **errp) { StringOutputVisitor *sov = to_sov(v); + + if (sov->struct_nesting) { + return true; + } + string_output_set(sov, g_strdup_printf("%.17g", *obj)); return true; } @@ -268,6 +306,10 @@ static bool print_type_null(Visitor *v, const char *name, QNull **obj, StringOutputVisitor *sov = to_sov(v); char *out; + if (sov->struct_nesting) { + return true; + } + if (sov->human) { out = g_strdup("<null>"); } else { @@ -277,12 +319,37 @@ static bool print_type_null(Visitor *v, const char *name, QNull **obj, return true; } +static bool start_struct(Visitor *v, const char *name, void **obj, + size_t size, Error **errp) +{ + StringOutputVisitor *sov = to_sov(v); + + sov->struct_nesting++; + return true; +} + +static void end_struct(Visitor *v, void **obj) +{ + StringOutputVisitor *sov = to_sov(v); + + if (--sov->struct_nesting) { + return; + } + + /* TODO actually print struct fields */ + string_output_set(sov, g_strdup("<omitted>")); +} + static bool start_list(Visitor *v, const char *name, GenericList **list, size_t size, Error **errp) { StringOutputVisitor *sov = to_sov(v); + if (sov->struct_nesting) { + return true; + } + /* we can't traverse a list in a list */ assert(sov->list_mode == LM_NONE); /* We don't support visits without a list */ @@ -300,6 +367,10 @@ static GenericList *next_list(Visitor *v, GenericList *tail, size_t size) StringOutputVisitor *sov = to_sov(v); GenericList *ret = tail->next; + if (sov->struct_nesting) { + return ret; + } + if (ret && !ret->next) { sov->list_mode = LM_END; } @@ -310,6 +381,10 @@ static void end_list(Visitor *v, void **obj) { StringOutputVisitor *sov = to_sov(v); + if (sov->struct_nesting) { + return; + } + assert(sov->list == obj); assert(sov->list_mode == LM_STARTED || sov->list_mode == LM_END || @@ -364,6 +439,8 @@ Visitor *string_output_visitor_new(bool human, char **result) v->visitor.type_str = print_type_str; v->visitor.type_number = print_type_number; v->visitor.type_null = print_type_null; + v->visitor.start_struct = start_struct; + v->visitor.end_struct = end_struct; v->visitor.start_list = start_list; v->visitor.next_list = next_list; v->visitor.end_list = end_list; diff --git a/qapi/tpm.json b/qapi/tpm.json index 6a10c9ed8d..1577b5c259 100644 --- a/qapi/tpm.json +++ b/qapi/tpm.json @@ -12,12 +12,16 @@ # An enumeration of TPM models # # @tpm-tis: TPM TIS model +# # @tpm-crb: TPM CRB model (since 2.12) +# # @tpm-spapr: TPM SPAPR model (since 5.0) # # Since: 1.5 ## -{ 'enum': 'TpmModel', 'data': [ 'tpm-tis', 'tpm-crb', 'tpm-spapr' ] } +{ 'enum': 'TpmModel', 'data': [ 'tpm-tis', 'tpm-crb', 'tpm-spapr' ], + 'if': 'CONFIG_TPM' } + ## # @query-tpm-models: # @@ -29,11 +33,11 @@ # # Example: # -# -> { "execute": "query-tpm-models" } -# <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] } -# +# -> { "execute": "query-tpm-models" } +# <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] } ## -{ 'command': 'query-tpm-models', 'returns': ['TpmModel'] } +{ 'command': 'query-tpm-models', 'returns': ['TpmModel'], + 'if': 'CONFIG_TPM' } ## # @TpmType: @@ -41,12 +45,13 @@ # An enumeration of TPM types # # @passthrough: TPM passthrough type -# @emulator: Software Emulator TPM type -# Since: 2.11 +# +# @emulator: Software Emulator TPM type (since 2.11) # # Since: 1.5 ## -{ 'enum': 'TpmType', 'data': [ 'passthrough', 'emulator' ] } +{ 'enum': 'TpmType', 'data': [ 'passthrough', 'emulator' ], + 'if': 'CONFIG_TPM' } ## # @query-tpm-types: @@ -59,11 +64,11 @@ # # Example: # -# -> { "execute": "query-tpm-types" } -# <- { "return": [ "passthrough", "emulator" ] } -# +# -> { "execute": "query-tpm-types" } +# <- { "return": [ "passthrough", "emulator" ] } ## -{ 'command': 'query-tpm-types', 'returns': ['TpmType'] } +{ 'command': 'query-tpm-types', 'returns': ['TpmType'], + 'if': 'CONFIG_TPM' } ## # @TPMPassthroughOptions: @@ -72,14 +77,15 @@ # # @path: string describing the path used for accessing the TPM device # -# @cancel-path: string showing the TPM's sysfs cancel file -# for cancellation of TPM commands while they are executing +# @cancel-path: string showing the TPM's sysfs cancel file for +# cancellation of TPM commands while they are executing # # Since: 1.5 ## { 'struct': 'TPMPassthroughOptions', 'data': { '*path': 'str', - '*cancel-path': 'str' } } + '*cancel-path': 'str' }, + 'if': 'CONFIG_TPM' } ## # @TPMEmulatorOptions: @@ -90,21 +96,51 @@ # # Since: 2.11 ## -{ 'struct': 'TPMEmulatorOptions', 'data': { 'chardev' : 'str' } } +{ 'struct': 'TPMEmulatorOptions', 'data': { 'chardev' : 'str' }, + 'if': 'CONFIG_TPM' } + +## +# @TPMPassthroughOptionsWrapper: +# +# @data: Information about the TPM passthrough type +# +# Since: 1.5 +## +{ 'struct': 'TPMPassthroughOptionsWrapper', + 'data': { 'data': 'TPMPassthroughOptions' }, + 'if': 'CONFIG_TPM' } + +## +# @TPMEmulatorOptionsWrapper: +# +# @data: Information about the TPM emulator type +# +# Since: 2.11 +## +{ 'struct': 'TPMEmulatorOptionsWrapper', + 'data': { 'data': 'TPMEmulatorOptions' }, + 'if': 'CONFIG_TPM' } ## # @TpmTypeOptions: # -# A union referencing different TPM backend types' configuration options +# A union referencing different TPM backend types' configuration +# options # -# @type: - 'passthrough' The configuration options for the TPM passthrough type -# - 'emulator' The configuration options for TPM emulator backend type +# @type: +# - 'passthrough' The configuration options for the TPM +# passthrough type +# - 'emulator' The configuration options for TPM emulator backend +# type # # Since: 1.5 ## { 'union': 'TpmTypeOptions', - 'data': { 'passthrough' : 'TPMPassthroughOptions', - 'emulator': 'TPMEmulatorOptions' } } + 'base': { 'type': 'TpmType' }, + 'discriminator': 'type', + 'data': { 'passthrough' : 'TPMPassthroughOptionsWrapper', + 'emulator': 'TPMEmulatorOptionsWrapper' }, + 'if': 'CONFIG_TPM' } ## # @TPMInfo: @@ -122,34 +158,33 @@ { 'struct': 'TPMInfo', 'data': {'id': 'str', 'model': 'TpmModel', - 'options': 'TpmTypeOptions' } } + 'options': 'TpmTypeOptions' }, + 'if': 'CONFIG_TPM' } ## # @query-tpm: # # Return information about the TPM device # -# Returns: @TPMInfo on success -# # Since: 1.5 # # Example: # -# -> { "execute": "query-tpm" } -# <- { "return": -# [ -# { "model": "tpm-tis", -# "options": -# { "type": "passthrough", -# "data": -# { "cancel-path": "/sys/class/misc/tpm0/device/cancel", -# "path": "/dev/tpm0" -# } -# }, -# "id": "tpm0" +# -> { "execute": "query-tpm" } +# <- { "return": +# [ +# { "model": "tpm-tis", +# "options": +# { "type": "passthrough", +# "data": +# { "cancel-path": "/sys/class/misc/tpm0/device/cancel", +# "path": "/dev/tpm0" +# } +# }, +# "id": "tpm0" +# } +# ] # } -# ] -# } -# ## -{ 'command': 'query-tpm', 'returns': ['TPMInfo'] } +{ 'command': 'query-tpm', 'returns': ['TPMInfo'], + 'if': 'CONFIG_TPM' } diff --git a/qapi/trace-events b/qapi/trace-events index 3cabe912ae..ab108c4f0e 100644 --- a/qapi/trace-events +++ b/qapi/trace-events @@ -1,4 +1,4 @@ -# See docs/devel/tracing.txt for syntax documentation. +# See docs/devel/tracing.rst for syntax documentation. # qapi-visit-core.c visit_free(void *v) "v=%p" @@ -17,8 +17,8 @@ visit_start_alternate(void *v, const char *name, void *obj, size_t size) "v=%p n visit_end_alternate(void *v, void *obj) "v=%p obj=%p" visit_optional(void *v, const char *name, bool *present) "v=%p name=%s present=%p" -visit_deprecated_accept(void *v, const char *name) "v=%p name=%s" -visit_deprecated(void *v, const char *name) "v=%p name=%s" +visit_policy_reject(void *v, const char *name) "v=%p name=%s" +visit_policy_skip(void *v, const char *name) "v=%p name=%s" visit_type_enum(void *v, const char *name, int *obj) "v=%p name=%s obj=%p" visit_type_int(void *v, const char *name, int64_t *obj) "v=%p name=%s obj=%p" diff --git a/qapi/trace.json b/qapi/trace.json index 47c68f04da..043d12f83e 100644 --- a/qapi/trace.json +++ b/qapi/trace.json @@ -1,4 +1,5 @@ # -*- mode: python -*- +# vim: filetype=python # # Copyright (C) 2011-2016 Lluís Vilanova <vilanova@ac.upc.edu> # @@ -31,16 +32,20 @@ # Information of a tracing event. # # @name: Event name. +# # @state: Tracing state. +# # @vcpu: Whether this is a per-vCPU event (since 2.7). # -# An event is per-vCPU if it has the "vcpu" property in the "trace-events" -# files. +# Features: +# +# @deprecated: Member @vcpu is deprecated, and always ignored. # # Since: 2.2 ## { 'struct': 'TraceEventInfo', - 'data': {'name': 'str', 'state': 'TraceEventState', 'vcpu': 'bool'} } + 'data': {'name': 'str', 'state': 'TraceEventState', + 'vcpu': { 'type': 'bool', 'features': ['deprecated'] } } } ## # @trace-event-get-state: @@ -48,31 +53,26 @@ # Query the state of events. # # @name: Event name pattern (case-sensitive glob). -# @vcpu: The vCPU to query (any by default; since 2.7). # -# Returns: a list of @TraceEventInfo for the matching events +# @vcpu: The vCPU to query (since 2.7). # -# An event is returned if: +# Features: # -# - its name matches the @name pattern, and -# - if @vcpu is given, the event has the "vcpu" property. +# @deprecated: Member @vcpu is deprecated, and always ignored. # -# Therefore, if @vcpu is given, the operation will only match per-vCPU events, -# returning their state on the specified vCPU. Special case: if @name is an -# exact match, @vcpu is given and the event does not have the "vcpu" property, -# an error is returned. +# Returns: a list of @TraceEventInfo for the matching events # # Since: 2.2 # # Example: # -# -> { "execute": "trace-event-get-state", -# "arguments": { "name": "qemu_memalign" } } -# <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] } -# +# -> { "execute": "trace-event-get-state", +# "arguments": { "name": "qemu_memalign" } } +# <- { "return": [ { "name": "qemu_memalign", "state": "disabled", "vcpu": false } ] } ## { 'command': 'trace-event-get-state', - 'data': {'name': 'str', '*vcpu': 'int'}, + 'data': {'name': 'str', + '*vcpu': {'type': 'int', 'features': ['deprecated'] } }, 'returns': ['TraceEventInfo'] } ## @@ -81,28 +81,25 @@ # Set the dynamic tracing state of events. # # @name: Event name pattern (case-sensitive glob). +# # @enable: Whether to enable tracing. +# # @ignore-unavailable: Do not match unavailable events with @name. +# # @vcpu: The vCPU to act upon (all by default; since 2.7). # -# An event's state is modified if: -# - its name matches the @name pattern, and -# - if @vcpu is given, the event has the "vcpu" property. +# Features: # -# Therefore, if @vcpu is given, the operation will only match per-vCPU events, -# setting their state on the specified vCPU. Special case: if @name is an exact -# match, @vcpu is given and the event does not have the "vcpu" property, an -# error is returned. +# @deprecated: Member @vcpu is deprecated, and always ignored. # # Since: 2.2 # # Example: # -# -> { "execute": "trace-event-set-state", -# "arguments": { "name": "qemu_memalign", "enable": "true" } } -# <- { "return": {} } -# +# -> { "execute": "trace-event-set-state", +# "arguments": { "name": "qemu_memalign", "enable": true } } +# <- { "return": {} } ## { 'command': 'trace-event-set-state', 'data': {'name': 'str', 'enable': 'bool', '*ignore-unavailable': 'bool', - '*vcpu': 'int'} } + '*vcpu': {'type': 'int', 'features': ['deprecated'] } } } diff --git a/qapi/transaction.json b/qapi/transaction.json index 15ddebdbc3..5749c133d4 100644 --- a/qapi/transaction.json +++ b/qapi/transaction.json @@ -23,15 +23,15 @@ # # An enumeration of Transactional completion modes. # -# @individual: Do not attempt to cancel any other Actions if any Actions fail -# after the Transaction request succeeds. All Actions that -# can complete successfully will do so without waiting on others. -# This is the default. +# @individual: Do not attempt to cancel any other Actions if any +# Actions fail after the Transaction request succeeds. All +# Actions that can complete successfully will do so without +# waiting on others. This is the default. # -# @grouped: If any Action fails after the Transaction succeeds, cancel all -# Actions. Actions do not complete until all Actions are ready to -# complete. May be rejected by Actions that do not support this -# completion mode. +# @grouped: If any Action fails after the Transaction succeeds, cancel +# all Actions. Actions do not complete until all Actions are +# ready to complete. May be rejected by Actions that do not +# support this completion mode. # # Since: 2.5 ## @@ -39,40 +39,145 @@ 'data': [ 'individual', 'grouped' ] } ## +# @TransactionActionKind: +# +# @abort: Since 1.6 +# +# @block-dirty-bitmap-add: Since 2.5 +# +# @block-dirty-bitmap-remove: Since 4.2 +# +# @block-dirty-bitmap-clear: Since 2.5 +# +# @block-dirty-bitmap-enable: Since 4.0 +# +# @block-dirty-bitmap-disable: Since 4.0 +# +# @block-dirty-bitmap-merge: Since 4.0 +# +# @blockdev-backup: Since 2.3 +# +# @blockdev-snapshot: Since 2.5 +# +# @blockdev-snapshot-internal-sync: Since 1.7 +# +# @blockdev-snapshot-sync: since 1.1 +# +# @drive-backup: Since 1.6 +# +# Features: +# +# @deprecated: Member @drive-backup is deprecated. Use member +# @blockdev-backup instead. +# +# Since: 1.1 +## +{ 'enum': 'TransactionActionKind', + 'data': [ 'abort', 'block-dirty-bitmap-add', 'block-dirty-bitmap-remove', + 'block-dirty-bitmap-clear', 'block-dirty-bitmap-enable', + 'block-dirty-bitmap-disable', 'block-dirty-bitmap-merge', + 'blockdev-backup', 'blockdev-snapshot', + 'blockdev-snapshot-internal-sync', 'blockdev-snapshot-sync', + { 'name': 'drive-backup', 'features': [ 'deprecated' ] } ] } + +## +# @AbortWrapper: +# +# Since: 1.6 +## +{ 'struct': 'AbortWrapper', + 'data': { 'data': 'Abort' } } + +## +# @BlockDirtyBitmapAddWrapper: +# +# Since: 2.5 +## +{ 'struct': 'BlockDirtyBitmapAddWrapper', + 'data': { 'data': 'BlockDirtyBitmapAdd' } } + +## +# @BlockDirtyBitmapWrapper: +# +# Since: 2.5 +## +{ 'struct': 'BlockDirtyBitmapWrapper', + 'data': { 'data': 'BlockDirtyBitmap' } } + +## +# @BlockDirtyBitmapMergeWrapper: +# +# Since: 4.0 +## +{ 'struct': 'BlockDirtyBitmapMergeWrapper', + 'data': { 'data': 'BlockDirtyBitmapMerge' } } + +## +# @BlockdevBackupWrapper: +# +# Since: 2.3 +## +{ 'struct': 'BlockdevBackupWrapper', + 'data': { 'data': 'BlockdevBackup' } } + +## +# @BlockdevSnapshotWrapper: +# +# Since: 2.5 +## +{ 'struct': 'BlockdevSnapshotWrapper', + 'data': { 'data': 'BlockdevSnapshot' } } + +## +# @BlockdevSnapshotInternalWrapper: +# +# Since: 1.7 +## +{ 'struct': 'BlockdevSnapshotInternalWrapper', + 'data': { 'data': 'BlockdevSnapshotInternal' } } + +## +# @BlockdevSnapshotSyncWrapper: +# +# Since: 1.1 +## +{ 'struct': 'BlockdevSnapshotSyncWrapper', + 'data': { 'data': 'BlockdevSnapshotSync' } } + +## +# @DriveBackupWrapper: +# +# Since: 1.6 +## +{ 'struct': 'DriveBackupWrapper', + 'data': { 'data': 'DriveBackup' } } + +## # @TransactionAction: # # A discriminated record of operations that can be performed with -# @transaction. Action @type can be: -# -# - @abort: since 1.6 -# - @block-dirty-bitmap-add: since 2.5 -# - @block-dirty-bitmap-remove: since 4.2 -# - @block-dirty-bitmap-clear: since 2.5 -# - @block-dirty-bitmap-enable: since 4.0 -# - @block-dirty-bitmap-disable: since 4.0 -# - @block-dirty-bitmap-merge: since 4.0 -# - @blockdev-backup: since 2.3 -# - @blockdev-snapshot: since 2.5 -# - @blockdev-snapshot-internal-sync: since 1.7 -# - @blockdev-snapshot-sync: since 1.1 -# - @drive-backup: since 1.6 +# @transaction. +# +# @type: the operation to be performed # # Since: 1.1 ## { 'union': 'TransactionAction', + 'base': { 'type': 'TransactionActionKind' }, + 'discriminator': 'type', 'data': { - 'abort': 'Abort', - 'block-dirty-bitmap-add': 'BlockDirtyBitmapAdd', - 'block-dirty-bitmap-remove': 'BlockDirtyBitmap', - 'block-dirty-bitmap-clear': 'BlockDirtyBitmap', - 'block-dirty-bitmap-enable': 'BlockDirtyBitmap', - 'block-dirty-bitmap-disable': 'BlockDirtyBitmap', - 'block-dirty-bitmap-merge': 'BlockDirtyBitmapMerge', - 'blockdev-backup': 'BlockdevBackup', - 'blockdev-snapshot': 'BlockdevSnapshot', - 'blockdev-snapshot-internal-sync': 'BlockdevSnapshotInternal', - 'blockdev-snapshot-sync': 'BlockdevSnapshotSync', - 'drive-backup': 'DriveBackup' + 'abort': 'AbortWrapper', + 'block-dirty-bitmap-add': 'BlockDirtyBitmapAddWrapper', + 'block-dirty-bitmap-remove': 'BlockDirtyBitmapWrapper', + 'block-dirty-bitmap-clear': 'BlockDirtyBitmapWrapper', + 'block-dirty-bitmap-enable': 'BlockDirtyBitmapWrapper', + 'block-dirty-bitmap-disable': 'BlockDirtyBitmapWrapper', + 'block-dirty-bitmap-merge': 'BlockDirtyBitmapMergeWrapper', + 'blockdev-backup': 'BlockdevBackupWrapper', + 'blockdev-snapshot': 'BlockdevSnapshotWrapper', + 'blockdev-snapshot-internal-sync': 'BlockdevSnapshotInternalWrapper', + 'blockdev-snapshot-sync': 'BlockdevSnapshotSyncWrapper', + 'drive-backup': 'DriveBackupWrapper' } } ## @@ -81,8 +186,8 @@ # Optional arguments to modify the behavior of a Transaction. # # @completion-mode: Controls how jobs launched asynchronously by -# Actions will complete or fail as a group. -# See @ActionCompletionMode for details. +# Actions will complete or fail as a group. See +# @ActionCompletionMode for details. # # Since: 2.5 ## @@ -95,70 +200,70 @@ ## # @transaction: # -# Executes a number of transactionable QMP commands atomically. If any -# operation fails, then the entire set of actions will be abandoned and the -# appropriate error returned. +# Executes a number of transactionable QMP commands atomically. If +# any operation fails, then the entire set of actions will be +# abandoned and the appropriate error returned. # -# For external snapshots, the dictionary contains the device, the file to use for -# the new snapshot, and the format. The default format, if not specified, is -# qcow2. +# For external snapshots, the dictionary contains the device, the file +# to use for the new snapshot, and the format. The default format, if +# not specified, is qcow2. # # Each new snapshot defaults to being created by QEMU (wiping any -# contents if the file already exists), but it is also possible to reuse -# an externally-created file. In the latter case, you should ensure that -# the new image file has the same contents as the current one; QEMU cannot -# perform any meaningful check. Typically this is achieved by using the -# current image file as the backing file for the new image. +# contents if the file already exists), but it is also possible to +# reuse an externally-created file. In the latter case, you should +# ensure that the new image file has the same contents as the current +# one; QEMU cannot perform any meaningful check. Typically this is +# achieved by using the current image file as the backing file for the +# new image. # # On failure, the original disks pre-snapshot attempt will be used. # -# For internal snapshots, the dictionary contains the device and the snapshot's -# name. If an internal snapshot matching name already exists, the request will -# be rejected. Only some image formats support it, for example, qcow2, rbd, -# and sheepdog. +# For internal snapshots, the dictionary contains the device and the +# snapshot's name. If an internal snapshot matching name already +# exists, the request will be rejected. Only some image formats +# support it, for example, qcow2, and rbd, # -# On failure, qemu will try delete the newly created internal snapshot in the -# transaction. When an I/O error occurs during deletion, the user needs to fix -# it later with qemu-img or other command. +# On failure, qemu will try delete the newly created internal snapshot +# in the transaction. When an I/O error occurs during deletion, the +# user needs to fix it later with qemu-img or other command. # -# @actions: List of @TransactionAction; -# information needed for the respective operations. +# @actions: List of @TransactionAction; information needed for the +# respective operations. # # @properties: structure of additional options to control the -# execution of the transaction. See @TransactionProperties -# for additional detail. +# execution of the transaction. See @TransactionProperties for +# additional detail. # -# Returns: nothing on success +# Errors: +# Any errors from commands in the transaction # -# Errors depend on the operations of the transaction -# -# Note: The transaction aborts on the first failure. Therefore, there will be -# information on only one failed operation returned in an error condition, and -# subsequent actions will not have been attempted. +# Note: The transaction aborts on the first failure. Therefore, there +# will be information on only one failed operation returned in an +# error condition, and subsequent actions will not have been +# attempted. # # Since: 1.1 # # Example: # -# -> { "execute": "transaction", -# "arguments": { "actions": [ -# { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0", -# "snapshot-file": "/some/place/my-image", -# "format": "qcow2" } }, -# { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile", -# "snapshot-file": "/some/place/my-image2", -# "snapshot-node-name": "node3432", -# "mode": "existing", -# "format": "qcow2" } }, -# { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1", -# "snapshot-file": "/some/place/my-image2", -# "mode": "existing", -# "format": "qcow2" } }, -# { "type": "blockdev-snapshot-internal-sync", "data" : { -# "device": "ide-hd2", -# "name": "snapshot0" } } ] } } -# <- { "return": {} } -# +# -> { "execute": "transaction", +# "arguments": { "actions": [ +# { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0", +# "snapshot-file": "/some/place/my-image", +# "format": "qcow2" } }, +# { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile", +# "snapshot-file": "/some/place/my-image2", +# "snapshot-node-name": "node3432", +# "mode": "existing", +# "format": "qcow2" } }, +# { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1", +# "snapshot-file": "/some/place/my-image2", +# "mode": "existing", +# "format": "qcow2" } }, +# { "type": "blockdev-snapshot-internal-sync", "data" : { +# "device": "ide-hd2", +# "name": "snapshot0" } } ] } } +# <- { "return": {} } ## { 'command': 'transaction', 'data': { 'actions': [ 'TransactionAction' ], diff --git a/qapi/ui.json b/qapi/ui.json index 1052ca9c38..f610bce118 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -10,97 +10,194 @@ { 'include': 'sockets.json' } ## -# @set_password: +# @DisplayProtocol: +# +# Display protocols which support changing password options. +# +# Since: 7.0 +## +{ 'enum': 'DisplayProtocol', + 'data': [ 'vnc', 'spice' ] } + +## +# @SetPasswordAction: +# +# An action to take on changing a password on a connection with active +# clients. +# +# @keep: maintain existing clients # -# Sets the password of a remote display session. +# @fail: fail the command if clients are connected # -# @protocol: - 'vnc' to modify the VNC server password -# - 'spice' to modify the Spice server password +# @disconnect: disconnect existing clients +# +# Since: 7.0 +## +{ 'enum': 'SetPasswordAction', + 'data': [ 'keep', 'fail', 'disconnect' ] } + +## +# @SetPasswordOptions: +# +# Options for set_password. +# +# @protocol: +# - 'vnc' to modify the VNC server password +# - 'spice' to modify the Spice server password # # @password: the new password # -# @connected: how to handle existing clients when changing the -# password. If nothing is specified, defaults to 'keep' -# 'fail' to fail the command if clients are connected -# 'disconnect' to disconnect existing clients -# 'keep' to maintain existing clients +# @connected: How to handle existing clients when changing the +# password. If nothing is specified, defaults to 'keep'. For VNC, +# only 'keep' is currently implemented. +# +# Since: 7.0 +## +{ 'union': 'SetPasswordOptions', + 'base': { 'protocol': 'DisplayProtocol', + 'password': 'str', + '*connected': 'SetPasswordAction' }, + 'discriminator': 'protocol', + 'data': { 'vnc': 'SetPasswordOptionsVnc' } } + +## +# @SetPasswordOptionsVnc: +# +# Options for set_password specific to the VNC protocol. # -# Returns: - Nothing on success -# - If Spice is not enabled, DeviceNotFound +# @display: The id of the display where the password should be +# changed. Defaults to the first. +# +# Since: 7.0 +## +{ 'struct': 'SetPasswordOptionsVnc', + 'data': { '*display': 'str' } } + +## +# @set_password: +# +# Set the password of a remote display server. +# +# Errors: +# - If Spice is not enabled, DeviceNotFound # # Since: 0.14 # # Example: # -# -> { "execute": "set_password", "arguments": { "protocol": "vnc", -# "password": "secret" } } -# <- { "return": {} } -# +# -> { "execute": "set_password", "arguments": { "protocol": "vnc", +# "password": "secret" } } +# <- { "return": {} } ## -{ 'command': 'set_password', - 'data': {'protocol': 'str', 'password': 'str', '*connected': 'str'} } +{ 'command': 'set_password', 'boxed': true, 'data': 'SetPasswordOptions' } ## -# @expire_password: +# @ExpirePasswordOptions: # -# Expire the password of a remote display server. +# General options for expire_password. # -# @protocol: the name of the remote display protocol 'vnc' or 'spice' +# @protocol: +# - 'vnc' to modify the VNC server expiration +# - 'spice' to modify the Spice server expiration # # @time: when to expire the password. # -# - 'now' to expire the password immediately -# - 'never' to cancel password expiration -# - '+INT' where INT is the number of seconds from now (integer) -# - 'INT' where INT is the absolute time in seconds +# - 'now' to expire the password immediately +# - 'never' to cancel password expiration +# - '+INT' where INT is the number of seconds from now (integer) +# - 'INT' where INT is the absolute time in seconds # -# Returns: - Nothing on success -# - If @protocol is 'spice' and Spice is not active, DeviceNotFound +# Notes: Time is relative to the server and currently there is no way +# to coordinate server time with client time. It is not +# recommended to use the absolute time version of the @time +# parameter unless you're sure you are on the same machine as the +# QEMU instance. # -# Since: 0.14 +# Since: 7.0 +## +{ 'union': 'ExpirePasswordOptions', + 'base': { 'protocol': 'DisplayProtocol', + 'time': 'str' }, + 'discriminator': 'protocol', + 'data': { 'vnc': 'ExpirePasswordOptionsVnc' } } + +## +# @ExpirePasswordOptionsVnc: +# +# Options for expire_password specific to the VNC protocol. +# +# @display: The id of the display where the expiration should be +# changed. Defaults to the first. +# +# Since: 7.0 +## +{ 'struct': 'ExpirePasswordOptionsVnc', + 'data': { '*display': 'str' } } + +## +# @expire_password: +# +# Expire the password of a remote display server. +# +# Errors: +# - If @protocol is 'spice' and Spice is not active, +# DeviceNotFound # -# Notes: Time is relative to the server and currently there is no way to -# coordinate server time with client time. It is not recommended to -# use the absolute time version of the @time parameter unless you're -# sure you are on the same machine as the QEMU instance. +# Since: 0.14 # # Example: # -# -> { "execute": "expire_password", "arguments": { "protocol": "vnc", -# "time": "+60" } } -# <- { "return": {} } +# -> { "execute": "expire_password", "arguments": { "protocol": "vnc", +# "time": "+60" } } +# <- { "return": {} } +## +{ 'command': 'expire_password', 'boxed': true, 'data': 'ExpirePasswordOptions' } + +## +# @ImageFormat: +# +# Supported image format types. # +# @png: PNG format +# +# @ppm: PPM format +# +# Since: 7.1 ## -{ 'command': 'expire_password', 'data': {'protocol': 'str', 'time': 'str'} } +{ 'enum': 'ImageFormat', + 'data': ['ppm', 'png'] } ## # @screendump: # -# Write a PPM of the VGA screen to a file. +# Capture the contents of a screen and write it to a file. # -# @filename: the path of a new PPM file to store the image +# @filename: the path of a new file to store the image # -# @device: ID of the display device that should be dumped. If this parameter -# is missing, the primary display will be used. (Since 2.12) +# @device: ID of the display device that should be dumped. If this +# parameter is missing, the primary display will be used. (Since +# 2.12) # -# @head: head to use in case the device supports multiple heads. If this -# parameter is missing, head #0 will be used. Also note that the head -# can only be specified in conjunction with the device ID. (Since 2.12) +# @head: head to use in case the device supports multiple heads. If +# this parameter is missing, head #0 will be used. Also note that +# the head can only be specified in conjunction with the device +# ID. (Since 2.12) # -# Returns: Nothing on success +# @format: image format for screendump. (default: ppm) (Since 7.1) # # Since: 0.14 # # Example: # -# -> { "execute": "screendump", -# "arguments": { "filename": "/tmp/image" } } -# <- { "return": {} } -# +# -> { "execute": "screendump", +# "arguments": { "filename": "/tmp/image" } } +# <- { "return": {} } ## { 'command': 'screendump', - 'data': {'filename': 'str', '*device': 'str', '*head': 'int'}, - 'coroutine': true } + 'data': {'filename': 'str', '*device': 'str', '*head': 'int', + '*format': 'ImageFormat'}, + 'coroutine': true, + 'if': 'CONFIG_PIXMAN' } ## # == Spice @@ -123,7 +220,7 @@ 'data': { 'host': 'str', 'port': 'str', 'family': 'NetworkAddressFamily' }, - 'if': 'defined(CONFIG_SPICE)' } + 'if': 'CONFIG_SPICE' } ## # @SpiceServerInfo: @@ -137,23 +234,23 @@ { 'struct': 'SpiceServerInfo', 'base': 'SpiceBasicInfo', 'data': { '*auth': 'str' }, - 'if': 'defined(CONFIG_SPICE)' } + 'if': 'CONFIG_SPICE' } ## # @SpiceChannel: # # Information about a SPICE client channel. # -# @connection-id: SPICE connection id number. All channels with the same id -# belong to the same SPICE session. +# @connection-id: SPICE connection id number. All channels with the +# same id belong to the same SPICE session. # # @channel-type: SPICE channel type number. "1" is the main control -# channel, filter for this one if you want to track spice -# sessions only +# channel, filter for this one if you want to track spice sessions +# only # -# @channel-id: SPICE channel ID number. Usually "0", might be different when -# multiple channels of the same type exist, such as multiple -# display channels in a multihead setup +# @channel-id: SPICE channel ID number. Usually "0", might be +# different when multiple channels of the same type exist, such as +# multiple display channels in a multihead setup # # @tls: true if the channel is encrypted, false otherwise. # @@ -163,7 +260,7 @@ 'base': 'SpiceBasicInfo', 'data': {'connection-id': 'int', 'channel-type': 'int', 'channel-id': 'int', 'tls': 'bool'}, - 'if': 'defined(CONFIG_SPICE)' } + 'if': 'CONFIG_SPICE' } ## # @SpiceQueryMouseMode: @@ -174,8 +271,8 @@ # # @server: Mouse cursor position is determined by the server. # -# @unknown: No information is available about mouse mode used by -# the spice server. +# @unknown: No information is available about mouse mode used by the +# spice server. # # Note: spice/enums.h has a SpiceMouseMode already, hence the name. # @@ -183,7 +280,7 @@ ## { 'enum': 'SpiceQueryMouseMode', 'data': [ 'client', 'server', 'unknown' ], - 'if': 'defined(CONFIG_SPICE)' } + 'if': 'CONFIG_SPICE' } ## # @SpiceInfo: @@ -193,10 +290,10 @@ # @enabled: true if the SPICE server is enabled, false otherwise # # @migrated: true if the last guest migration completed and spice -# migration had completed as well. false otherwise. (since 1.4) +# migration had completed as well, false otherwise (since 1.4) # # @host: The hostname the SPICE server is bound to. This depends on -# the name resolution on the host and may be an IP address. +# the name resolution on the host and may be an IP address. # # @port: The SPICE server's port number. # @@ -206,13 +303,14 @@ # # @auth: the current authentication type used by the server # -# - 'none' if no authentication is being used -# - 'spice' uses SASL or direct TLS authentication, depending on command -# line options +# - 'none' if no authentication is being used +# - 'spice' uses SASL or direct TLS authentication, depending on +# command line options # -# @mouse-mode: The mode in which the mouse cursor is displayed currently. Can -# be determined by the client or the server, or unknown if spice -# server doesn't provide this information. (since: 1.1) +# @mouse-mode: The mode in which the mouse cursor is displayed +# currently. Can be determined by the client or the server, or +# unknown if spice server doesn't provide this information. +# (since: 1.1) # # @channels: a list of @SpiceChannel for each active spice channel # @@ -222,7 +320,7 @@ 'data': {'enabled': 'bool', 'migrated': 'bool', '*host': 'str', '*port': 'int', '*tls-port': 'int', '*auth': 'str', '*compiled-version': 'str', 'mouse-mode': 'SpiceQueryMouseMode', '*channels': ['SpiceChannel']}, - 'if': 'defined(CONFIG_SPICE)' } + 'if': 'CONFIG_SPICE' } ## # @query-spice: @@ -235,40 +333,41 @@ # # Example: # -# -> { "execute": "query-spice" } -# <- { "return": { -# "enabled": true, -# "auth": "spice", -# "port": 5920, -# "tls-port": 5921, -# "host": "0.0.0.0", -# "channels": [ -# { -# "port": "54924", -# "family": "ipv4", -# "channel-type": 1, -# "connection-id": 1804289383, -# "host": "127.0.0.1", -# "channel-id": 0, -# "tls": true -# }, -# { -# "port": "36710", -# "family": "ipv4", -# "channel-type": 4, -# "connection-id": 1804289383, -# "host": "127.0.0.1", -# "channel-id": 0, -# "tls": false -# }, -# [ ... more channels follow ... ] -# ] -# } -# } -# +# -> { "execute": "query-spice" } +# <- { "return": { +# "enabled": true, +# "auth": "spice", +# "port": 5920, +# "migrated":false, +# "tls-port": 5921, +# "host": "0.0.0.0", +# "mouse-mode":"client", +# "channels": [ +# { +# "port": "54924", +# "family": "ipv4", +# "channel-type": 1, +# "connection-id": 1804289383, +# "host": "127.0.0.1", +# "channel-id": 0, +# "tls": true +# }, +# { +# "port": "36710", +# "family": "ipv4", +# "channel-type": 4, +# "connection-id": 1804289383, +# "host": "127.0.0.1", +# "channel-id": 0, +# "tls": false +# }, +# [ ... more channels follow ... ] +# ] +# } +# } ## { 'command': 'query-spice', 'returns': 'SpiceInfo', - 'if': 'defined(CONFIG_SPICE)' } + 'if': 'CONFIG_SPICE' } ## # @SPICE_CONNECTED: @@ -283,24 +382,23 @@ # # Example: # -# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, -# "event": "SPICE_CONNECTED", -# "data": { -# "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"}, -# "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"} -# }} -# +# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, +# "event": "SPICE_CONNECTED", +# "data": { +# "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"}, +# "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"} +# }} ## { 'event': 'SPICE_CONNECTED', 'data': { 'server': 'SpiceBasicInfo', 'client': 'SpiceBasicInfo' }, - 'if': 'defined(CONFIG_SPICE)' } + 'if': 'CONFIG_SPICE' } ## # @SPICE_INITIALIZED: # -# Emitted after initial handshake and authentication takes place (if any) -# and the SPICE channel is up and running +# Emitted after initial handshake and authentication takes place (if +# any) and the SPICE channel is up and running # # @server: server information # @@ -310,20 +408,19 @@ # # Example: # -# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, -# "event": "SPICE_INITIALIZED", -# "data": {"server": {"auth": "spice", "port": "5921", -# "family": "ipv4", "host": "127.0.0.1"}, -# "client": {"port": "49004", "family": "ipv4", "channel-type": 3, -# "connection-id": 1804289383, "host": "127.0.0.1", -# "channel-id": 0, "tls": true} -# }} -# +# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, +# "event": "SPICE_INITIALIZED", +# "data": {"server": {"auth": "spice", "port": "5921", +# "family": "ipv4", "host": "127.0.0.1"}, +# "client": {"port": "49004", "family": "ipv4", "channel-type": 3, +# "connection-id": 1804289383, "host": "127.0.0.1", +# "channel-id": 0, "tls": true} +# }} ## { 'event': 'SPICE_INITIALIZED', 'data': { 'server': 'SpiceServerInfo', 'client': 'SpiceChannel' }, - 'if': 'defined(CONFIG_SPICE)' } + 'if': 'CONFIG_SPICE' } ## # @SPICE_DISCONNECTED: @@ -338,18 +435,17 @@ # # Example: # -# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, -# "event": "SPICE_DISCONNECTED", -# "data": { -# "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"}, -# "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"} -# }} -# +# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, +# "event": "SPICE_DISCONNECTED", +# "data": { +# "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"}, +# "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"} +# }} ## { 'event': 'SPICE_DISCONNECTED', 'data': { 'server': 'SpiceBasicInfo', 'client': 'SpiceBasicInfo' }, - 'if': 'defined(CONFIG_SPICE)' } + 'if': 'CONFIG_SPICE' } ## # @SPICE_MIGRATE_COMPLETED: @@ -360,12 +456,11 @@ # # Example: # -# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, -# "event": "SPICE_MIGRATE_COMPLETED" } -# +# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, +# "event": "SPICE_MIGRATE_COMPLETED" } ## { 'event': 'SPICE_MIGRATE_COMPLETED', - 'if': 'defined(CONFIG_SPICE)' } + 'if': 'CONFIG_SPICE' } ## # == VNC @@ -378,9 +473,9 @@ # # @host: IP address # -# @service: The service name of the vnc port. This may depend on the host -# system's service database so symbolic names should not be relied -# on. +# @service: The service name of the vnc port. This may depend on the +# host system's service database so symbolic names should not be +# relied on. # # @family: address family # @@ -393,22 +488,22 @@ 'service': 'str', 'family': 'NetworkAddressFamily', 'websocket': 'bool' }, - 'if': 'defined(CONFIG_VNC)' } + 'if': 'CONFIG_VNC' } ## # @VncServerInfo: # # The network connection information for server # -# @auth: authentication method used for -# the plain (non-websocket) VNC server +# @auth: authentication method used for the plain (non-websocket) VNC +# server # # Since: 2.1 ## { 'struct': 'VncServerInfo', 'base': 'VncBasicInfo', 'data': { '*auth': 'str' }, - 'if': 'defined(CONFIG_VNC)' } + 'if': 'CONFIG_VNC' } ## # @VncClientInfo: @@ -416,17 +511,17 @@ # Information about a connected VNC client. # # @x509_dname: If x509 authentication is in use, the Distinguished -# Name of the client. +# Name of the client. # # @sasl_username: If SASL authentication is in use, the SASL username -# used for authentication. +# used for authentication. # # Since: 0.14 ## { 'struct': 'VncClientInfo', 'base': 'VncBasicInfo', 'data': { '*x509_dname': 'str', '*sasl_username': 'str' }, - 'if': 'defined(CONFIG_VNC)' } + 'if': 'CONFIG_VNC' } ## # @VncInfo: @@ -435,33 +530,41 @@ # # @enabled: true if the VNC server is enabled, false otherwise # -# @host: The hostname the VNC server is bound to. This depends on -# the name resolution on the host and may be an IP address. +# @host: The hostname the VNC server is bound to. This depends on the +# name resolution on the host and may be an IP address. # -# @family: - 'ipv6' if the host is listening for IPv6 connections -# - 'ipv4' if the host is listening for IPv4 connections -# - 'unix' if the host is listening on a unix domain socket -# - 'unknown' otherwise +# @family: +# - 'ipv6' if the host is listening for IPv6 connections +# - 'ipv4' if the host is listening for IPv4 connections +# - 'unix' if the host is listening on a unix domain socket +# - 'unknown' otherwise # # @service: The service name of the server's port. This may depends -# on the host system's service database so symbolic names should not -# be relied on. +# on the host system's service database so symbolic names should +# not be relied on. # # @auth: the current authentication type used by the server # -# - 'none' if no authentication is being used -# - 'vnc' if VNC authentication is being used -# - 'vencrypt+plain' if VEncrypt is used with plain text authentication -# - 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication -# - 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication -# - 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth -# - 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth -# - 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth -# - 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth -# - 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth -# - 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth -# -# @clients: a list of @VncClientInfo of all currently connected clients +# - 'none' if no authentication is being used +# - 'vnc' if VNC authentication is being used +# - 'vencrypt+plain' if VEncrypt is used with plain text +# authentication +# - 'vencrypt+tls+none' if VEncrypt is used with TLS and no +# authentication +# - 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC +# authentication +# - 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain +# text auth +# - 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth +# - 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth +# - 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain +# text auth +# - 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth +# - 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL +# auth +# +# @clients: a list of @VncClientInfo of all currently connected +# clients # # Since: 0.14 ## @@ -469,7 +572,7 @@ 'data': {'enabled': 'bool', '*host': 'str', '*family': 'NetworkAddressFamily', '*service': 'str', '*auth': 'str', '*clients': ['VncClientInfo']}, - 'if': 'defined(CONFIG_VNC)' } + 'if': 'CONFIG_VNC' } ## # @VncPrimaryAuth: @@ -481,7 +584,7 @@ { 'enum': 'VncPrimaryAuth', 'data': [ 'none', 'vnc', 'ra2', 'ra2ne', 'tight', 'ultra', 'tls', 'vencrypt', 'sasl' ], - 'if': 'defined(CONFIG_VNC)' } + 'if': 'CONFIG_VNC' } ## # @VncVencryptSubAuth: @@ -496,7 +599,7 @@ 'tls-vnc', 'x509-vnc', 'tls-plain', 'x509-plain', 'tls-sasl', 'x509-sasl' ], - 'if': 'defined(CONFIG_VNC)' } + 'if': 'CONFIG_VNC' } ## # @VncServerInfo2: @@ -505,8 +608,8 @@ # # @auth: The current authentication type used by the servers # -# @vencrypt: The vencrypt sub authentication type used by the -# servers, only specified in case auth == vencrypt. +# @vencrypt: The vencrypt sub authentication type used by the servers, +# only specified in case auth == vencrypt. # # Since: 2.9 ## @@ -514,7 +617,7 @@ 'base': 'VncBasicInfo', 'data': { 'auth' : 'VncPrimaryAuth', '*vencrypt' : 'VncVencryptSubAuth' }, - 'if': 'defined(CONFIG_VNC)' } + 'if': 'CONFIG_VNC' } ## # @VncInfo2: @@ -524,17 +627,18 @@ # @id: vnc server name. # # @server: A list of @VncBasincInfo describing all listening sockets. -# The list can be empty (in case the vnc server is disabled). -# It also may have multiple entries: normal + websocket, -# possibly also ipv4 + ipv6 in the future. +# The list can be empty (in case the vnc server is disabled). It +# also may have multiple entries: normal + websocket, possibly +# also ipv4 + ipv6 in the future. # -# @clients: A list of @VncClientInfo of all currently connected clients. -# The list can be empty, for obvious reasons. +# @clients: A list of @VncClientInfo of all currently connected +# clients. The list can be empty, for obvious reasons. # -# @auth: The current authentication type used by the non-websockets servers +# @auth: The current authentication type used by the non-websockets +# servers # # @vencrypt: The vencrypt authentication type used by the servers, -# only specified in case auth == vencrypt. +# only specified in case auth == vencrypt. # # @display: The display device the vnc server is linked to. # @@ -547,7 +651,7 @@ 'auth' : 'VncPrimaryAuth', '*vencrypt' : 'VncVencryptSubAuth', '*display' : 'str' }, - 'if': 'defined(CONFIG_VNC)' } + 'if': 'CONFIG_VNC' } ## # @query-vnc: @@ -560,26 +664,26 @@ # # Example: # -# -> { "execute": "query-vnc" } -# <- { "return": { -# "enabled":true, -# "host":"0.0.0.0", -# "service":"50402", -# "auth":"vnc", -# "family":"ipv4", -# "clients":[ -# { -# "host":"127.0.0.1", -# "service":"50401", -# "family":"ipv4" -# } -# ] -# } -# } -# +# -> { "execute": "query-vnc" } +# <- { "return": { +# "enabled":true, +# "host":"0.0.0.0", +# "service":"50402", +# "auth":"vnc", +# "family":"ipv4", +# "clients":[ +# { +# "host":"127.0.0.1", +# "service":"50401", +# "family":"ipv4", +# "websocket":false +# } +# ] +# } +# } ## { 'command': 'query-vnc', 'returns': 'VncInfo', - 'if': 'defined(CONFIG_VNC)' } + 'if': 'CONFIG_VNC' } ## # @query-vnc-servers: # @@ -590,7 +694,7 @@ # Since: 2.3 ## { 'command': 'query-vnc-servers', 'returns': ['VncInfo2'], - 'if': 'defined(CONFIG_VNC)' } + 'if': 'CONFIG_VNC' } ## # @change-vnc-password: @@ -601,12 +705,13 @@ # # Since: 1.1 # -# Notes: An empty password in this command will set the password to the empty -# string. Existing clients are unaffected by executing this command. +# Notes: An empty password in this command will set the password to +# the empty string. Existing clients are unaffected by executing +# this command. ## { 'command': 'change-vnc-password', 'data': { 'password': 'str' }, - 'if': 'defined(CONFIG_VNC)' } + 'if': 'CONFIG_VNC' } ## # @VNC_CONNECTED: @@ -617,32 +722,31 @@ # # @client: client information # -# Note: This event is emitted before any authentication takes place, thus -# the authentication ID is not provided +# Note: This event is emitted before any authentication takes place, +# thus the authentication ID is not provided # # Since: 0.13 # # Example: # -# <- { "event": "VNC_CONNECTED", -# "data": { -# "server": { "auth": "sasl", "family": "ipv4", -# "service": "5901", "host": "0.0.0.0" }, -# "client": { "family": "ipv4", "service": "58425", -# "host": "127.0.0.1" } }, -# "timestamp": { "seconds": 1262976601, "microseconds": 975795 } } -# +# <- { "event": "VNC_CONNECTED", +# "data": { +# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, +# "service": "5901", "host": "0.0.0.0" }, +# "client": { "family": "ipv4", "service": "58425", +# "host": "127.0.0.1", "websocket": false } }, +# "timestamp": { "seconds": 1262976601, "microseconds": 975795 } } ## { 'event': 'VNC_CONNECTED', 'data': { 'server': 'VncServerInfo', 'client': 'VncBasicInfo' }, - 'if': 'defined(CONFIG_VNC)' } + 'if': 'CONFIG_VNC' } ## # @VNC_INITIALIZED: # -# Emitted after authentication takes place (if any) and the VNC session is -# made active +# Emitted after authentication takes place (if any) and the VNC +# session is made active # # @server: server information # @@ -652,19 +756,18 @@ # # Example: # -# <- { "event": "VNC_INITIALIZED", -# "data": { -# "server": { "auth": "sasl", "family": "ipv4", -# "service": "5901", "host": "0.0.0.0"}, -# "client": { "family": "ipv4", "service": "46089", -# "host": "127.0.0.1", "sasl_username": "luiz" } }, -# "timestamp": { "seconds": 1263475302, "microseconds": 150772 } } -# +# <- { "event": "VNC_INITIALIZED", +# "data": { +# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, +# "service": "5901", "host": "0.0.0.0"}, +# "client": { "family": "ipv4", "service": "46089", "websocket": false, +# "host": "127.0.0.1", "sasl_username": "luiz" } }, +# "timestamp": { "seconds": 1263475302, "microseconds": 150772 } } ## { 'event': 'VNC_INITIALIZED', 'data': { 'server': 'VncServerInfo', 'client': 'VncClientInfo' }, - 'if': 'defined(CONFIG_VNC)' } + 'if': 'CONFIG_VNC' } ## # @VNC_DISCONNECTED: @@ -679,19 +782,18 @@ # # Example: # -# <- { "event": "VNC_DISCONNECTED", -# "data": { -# "server": { "auth": "sasl", "family": "ipv4", -# "service": "5901", "host": "0.0.0.0" }, -# "client": { "family": "ipv4", "service": "58425", -# "host": "127.0.0.1", "sasl_username": "luiz" } }, -# "timestamp": { "seconds": 1262976601, "microseconds": 975795 } } -# +# <- { "event": "VNC_DISCONNECTED", +# "data": { +# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, +# "service": "5901", "host": "0.0.0.0" }, +# "client": { "family": "ipv4", "service": "58425", "websocket": false, +# "host": "127.0.0.1", "sasl_username": "luiz" } }, +# "timestamp": { "seconds": 1262976601, "microseconds": 975795 } } ## { 'event': 'VNC_DISCONNECTED', 'data': { 'server': 'VncServerInfo', 'client': 'VncClientInfo' }, - 'if': 'defined(CONFIG_VNC)' } + 'if': 'CONFIG_VNC' } ## # = Input @@ -708,7 +810,8 @@ # # @current: true if this device is currently receiving mouse events # -# @absolute: true if this device supports absolute coordinates as input +# @absolute: true if this device supports absolute coordinates as +# input # # Since: 0.14 ## @@ -727,23 +830,22 @@ # # Example: # -# -> { "execute": "query-mice" } -# <- { "return": [ -# { -# "name":"QEMU Microsoft Mouse", -# "index":0, -# "current":false, -# "absolute":false -# }, -# { -# "name":"QEMU PS/2 Mouse", -# "index":1, -# "current":true, -# "absolute":true -# } -# ] -# } -# +# -> { "execute": "query-mice" } +# <- { "return": [ +# { +# "name":"QEMU Microsoft Mouse", +# "index":0, +# "current":false, +# "absolute":false +# }, +# { +# "name":"QEMU PS/2 Mouse", +# "index":1, +# "current":true, +# "absolute":true +# } +# ] +# } ## { 'command': 'query-mice', 'returns': ['MouseInfo'] } @@ -755,46 +857,98 @@ # This is used by the @send-key command. # # @unmapped: since 2.0 +# # @pause: since 2.0 +# # @ro: since 2.4 +# # @kp_comma: since 2.4 +# # @kp_equals: since 2.6 +# # @power: since 2.6 +# # @hiragana: since 2.9 +# # @henkan: since 2.9 +# # @yen: since 2.9 # # @sleep: since 2.10 +# # @wake: since 2.10 +# # @audionext: since 2.10 +# # @audioprev: since 2.10 +# # @audiostop: since 2.10 +# # @audioplay: since 2.10 +# # @audiomute: since 2.10 +# # @volumeup: since 2.10 +# # @volumedown: since 2.10 +# # @mediaselect: since 2.10 +# # @mail: since 2.10 +# # @calculator: since 2.10 +# # @computer: since 2.10 +# # @ac_home: since 2.10 +# # @ac_back: since 2.10 +# # @ac_forward: since 2.10 +# # @ac_refresh: since 2.10 +# # @ac_bookmarks: since 2.10 # # @muhenkan: since 2.12 +# # @katakanahiragana: since 2.12 # -# 'sysrq' was mistakenly added to hack around the fact that -# the ps2 driver was not generating correct scancodes sequences -# when 'alt+print' was pressed. This flaw is now fixed and the -# 'sysrq' key serves no further purpose. Any further use of -# 'sysrq' will be transparently changed to 'print', so they -# are effectively synonyms. +# @lang1: since 6.1 # -# Since: 1.3 +# @lang2: since 6.1 +# +# @f13: since 8.0 +# +# @f14: since 8.0 +# +# @f15: since 8.0 +# +# @f16: since 8.0 +# +# @f17: since 8.0 +# +# @f18: since 8.0 # +# @f19: since 8.0 +# +# @f20: since 8.0 +# +# @f21: since 8.0 +# +# @f22: since 8.0 +# +# @f23: since 8.0 +# +# @f24: since 8.0 +# +# 'sysrq' was mistakenly added to hack around the fact that the ps2 +# driver was not generating correct scancodes sequences when +# 'alt+print' was pressed. This flaw is now fixed and the 'sysrq' key +# serves no further purpose. Any further use of 'sysrq' will be +# transparently changed to 'print', so they are effectively synonyms. +# +# Since: 1.3 ## { 'enum': 'QKeyCode', 'data': [ 'unmapped', @@ -818,46 +972,78 @@ 'audionext', 'audioprev', 'audiostop', 'audioplay', 'audiomute', 'volumeup', 'volumedown', 'mediaselect', 'mail', 'calculator', 'computer', - 'ac_home', 'ac_back', 'ac_forward', 'ac_refresh', 'ac_bookmarks' ] } + 'ac_home', 'ac_back', 'ac_forward', 'ac_refresh', 'ac_bookmarks', + 'lang1', 'lang2','f13','f14','f15','f16','f17','f18','f19','f20','f21','f22','f23','f24' ] } + +## +# @KeyValueKind: +# +# Since: 1.3 +## +{ 'enum': 'KeyValueKind', + 'data': [ 'number', 'qcode' ] } + +## +# @IntWrapper: +# +# @data: a numeric key code +# +# Since: 1.3 +## +{ 'struct': 'IntWrapper', + 'data': { 'data': 'int' } } + +## +# @QKeyCodeWrapper: +# +# @data: An enumeration of key name +# +# Since: 1.3 +## +{ 'struct': 'QKeyCodeWrapper', + 'data': { 'data': 'QKeyCode' } } ## # @KeyValue: # # Represents a keyboard key. # +# @type: key encoding +# # Since: 1.3 ## { 'union': 'KeyValue', + 'base': { 'type': 'KeyValueKind' }, + 'discriminator': 'type', 'data': { - 'number': 'int', - 'qcode': 'QKeyCode' } } + 'number': 'IntWrapper', + 'qcode': 'QKeyCodeWrapper' } } ## # @send-key: # # Send keys to guest. # -# @keys: An array of @KeyValue elements. All @KeyValues in this array are -# simultaneously sent to the guest. A @KeyValue.number value is sent -# directly to the guest, while @KeyValue.qcode must be a valid -# @QKeyCode value +# @keys: An array of @KeyValue elements. All @KeyValues in this array +# are simultaneously sent to the guest. A @KeyValue.number value +# is sent directly to the guest, while @KeyValue.qcode must be a +# valid @QKeyCode value # -# @hold-time: time to delay key up events, milliseconds. Defaults -# to 100 +# @hold-time: time to delay key up events, milliseconds. Defaults to +# 100 # -# Returns: - Nothing on success -# - If key is unknown or redundant, InvalidParameter +# Errors: +# - If key is unknown or redundant, GenericError # # Since: 1.3 # # Example: # -# -> { "execute": "send-key", -# "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" }, -# { "type": "qcode", "data": "alt" }, -# { "type": "qcode", "data": "delete" } ] } } -# <- { "return": {} } -# +# -> { "execute": "send-key", +# "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" }, +# { "type": "qcode", "data": "alt" }, +# { "type": "qcode", "data": "delete" } ] } } +# <- { "return": {} } ## { 'command': 'send-key', 'data': { 'keys': ['KeyValue'], '*hold-time': 'int' } } @@ -871,11 +1057,13 @@ # # @extra: rear side button of a 5-button mouse (since 2.9) # +# @touch: screen contact on a multi-touch device (since 8.1) +# # Since: 2.0 ## { 'enum' : 'InputButton', 'data' : [ 'left', 'middle', 'right', 'wheel-up', 'wheel-down', 'side', - 'extra' ] } + 'extra', 'wheel-left', 'wheel-right', 'touch' ] } ## # @InputAxis: @@ -888,12 +1076,34 @@ 'data' : [ 'x', 'y' ] } ## +# @InputMultiTouchType: +# +# Type of a multi-touch event. +# +# @begin: A new touch event sequence has just started. +# +# @update: A touch event sequence has been updated. +# +# @end: A touch event sequence has finished. +# +# @cancel: A touch event sequence has been canceled. +# +# @data: Absolute position data. +# +# Since: 8.1 +## +{ 'enum' : 'InputMultiTouchType', + 'data' : [ 'begin', 'update', 'end', 'cancel', 'data' ] } + + +## # @InputKeyEvent: # # Keyboard input event. # -# @key: Which key this event is for. -# @down: True for key-down and false for key-up events. +# @key: Which key this event is for. +# +# @down: True for key-down and false for key-up events. # # Since: 2.0 ## @@ -907,7 +1117,8 @@ # Pointer button input event. # # @button: Which button this event is for. -# @down: True for key-down and false for key-up events. +# +# @down: True for key-down and false for key-up events. # # Since: 2.0 ## @@ -921,8 +1132,9 @@ # Pointer motion input event. # # @axis: Which axis is referenced by @value. -# @value: Pointer position. For absolute coordinates the -# valid range is 0 -> 0x7ffff +# +# @value: Pointer position. For absolute coordinates the valid range +# is 0 -> 0x7ffff # # Since: 2.0 ## @@ -931,24 +1143,105 @@ 'value' : 'int' } } ## +# @InputMultiTouchEvent: +# +# MultiTouch input event. +# +# @type: The type of multi-touch event. +# +# @slot: Which slot has generated the event. +# +# @tracking-id: ID to correlate this event with previously generated +# events. +# +# @axis: Which axis is referenced by @value. +# +# @value: Contact position. +# +# Since: 8.1 +## +{ 'struct' : 'InputMultiTouchEvent', + 'data' : { 'type' : 'InputMultiTouchType', + 'slot' : 'int', + 'tracking-id': 'int', + 'axis' : 'InputAxis', + 'value' : 'int' } } + +## +# @InputEventKind: +# +# @key: a keyboard input event +# +# @btn: a pointer button input event +# +# @rel: a relative pointer motion input event +# +# @abs: an absolute pointer motion input event +# +# @mtt: a multi-touch input event +# +# Since: 2.0 +## +{ 'enum': 'InputEventKind', + 'data': [ 'key', 'btn', 'rel', 'abs', 'mtt' ] } + +## +# @InputKeyEventWrapper: +# +# @data: Keyboard input event +# +# Since: 2.0 +## +{ 'struct': 'InputKeyEventWrapper', + 'data': { 'data': 'InputKeyEvent' } } + +## +# @InputBtnEventWrapper: +# +# @data: Pointer button input event +# +# Since: 2.0 +## +{ 'struct': 'InputBtnEventWrapper', + 'data': { 'data': 'InputBtnEvent' } } + +## +# @InputMoveEventWrapper: +# +# @data: Pointer motion input event +# +# Since: 2.0 +## +{ 'struct': 'InputMoveEventWrapper', + 'data': { 'data': 'InputMoveEvent' } } + +## +# @InputMultiTouchEventWrapper: +# +# @data: MultiTouch input event +# +# Since: 8.1 +## +{ 'struct': 'InputMultiTouchEventWrapper', + 'data': { 'data': 'InputMultiTouchEvent' } } + +## # @InputEvent: # # Input event union. # -# @type: the input type, one of: -# -# - 'key': Input event of Keyboard -# - 'btn': Input event of pointer buttons -# - 'rel': Input event of relative pointer motion -# - 'abs': Input event of absolute pointer motion +# @type: the type of input event # # Since: 2.0 ## { 'union' : 'InputEvent', - 'data' : { 'key' : 'InputKeyEvent', - 'btn' : 'InputBtnEvent', - 'rel' : 'InputMoveEvent', - 'abs' : 'InputMoveEvent' } } + 'base': { 'type': 'InputEventKind' }, + 'discriminator': 'type', + 'data' : { 'key' : 'InputKeyEventWrapper', + 'btn' : 'InputBtnEventWrapper', + 'rel' : 'InputMoveEventWrapper', + 'abs' : 'InputMoveEventWrapper', + 'mtt' : 'InputMultiTouchEventWrapper' } } ## # @input-send-event: @@ -967,55 +1260,54 @@ # precedence. # # @device: display device to send event(s) to. -# @head: head to send event(s) to, in case the -# display device supports multiple scanouts. -# @events: List of InputEvent union. # -# Returns: Nothing on success. +# @head: head to send event(s) to, in case the display device supports +# multiple scanouts. +# +# @events: List of InputEvent union. # # Since: 2.6 # # Note: The consoles are visible in the qom tree, under -# /backend/console[$index]. They have a device link and head property, -# so it is possible to map which console belongs to which device and -# display. -# -# Example: -# -# 1. Press left mouse button. -# -# -> { "execute": "input-send-event", -# "arguments": { "device": "video0", -# "events": [ { "type": "btn", -# "data" : { "down": true, "button": "left" } } ] } } -# <- { "return": {} } -# -# -> { "execute": "input-send-event", -# "arguments": { "device": "video0", -# "events": [ { "type": "btn", -# "data" : { "down": false, "button": "left" } } ] } } -# <- { "return": {} } -# -# 2. Press ctrl-alt-del. -# -# -> { "execute": "input-send-event", -# "arguments": { "events": [ -# { "type": "key", "data" : { "down": true, -# "key": {"type": "qcode", "data": "ctrl" } } }, -# { "type": "key", "data" : { "down": true, -# "key": {"type": "qcode", "data": "alt" } } }, -# { "type": "key", "data" : { "down": true, -# "key": {"type": "qcode", "data": "delete" } } } ] } } -# <- { "return": {} } -# -# 3. Move mouse pointer to absolute coordinates (20000, 400). -# -# -> { "execute": "input-send-event" , -# "arguments": { "events": [ -# { "type": "abs", "data" : { "axis": "x", "value" : 20000 } }, -# { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } } -# <- { "return": {} } -# +# /backend/console[$index]. They have a device link and head +# property, so it is possible to map which console belongs to +# which device and display. +# +# Examples: +# +# 1. Press left mouse button. +# +# -> { "execute": "input-send-event", +# "arguments": { "device": "video0", +# "events": [ { "type": "btn", +# "data" : { "down": true, "button": "left" } } ] } } +# <- { "return": {} } +# +# -> { "execute": "input-send-event", +# "arguments": { "device": "video0", +# "events": [ { "type": "btn", +# "data" : { "down": false, "button": "left" } } ] } } +# <- { "return": {} } +# +# 2. Press ctrl-alt-del. +# +# -> { "execute": "input-send-event", +# "arguments": { "events": [ +# { "type": "key", "data" : { "down": true, +# "key": {"type": "qcode", "data": "ctrl" } } }, +# { "type": "key", "data" : { "down": true, +# "key": {"type": "qcode", "data": "alt" } } }, +# { "type": "key", "data" : { "down": true, +# "key": {"type": "qcode", "data": "delete" } } } ] } } +# <- { "return": {} } +# +# 3. Move mouse pointer to absolute coordinates (20000, 400). +# +# -> { "execute": "input-send-event" , +# "arguments": { "events": [ +# { "type": "abs", "data" : { "axis": "x", "value" : 20000 } }, +# { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } } +# <- { "return": {} } ## { 'command': 'input-send-event', 'data': { '*device': 'str', @@ -1028,50 +1320,82 @@ # GTK display options. # # @grab-on-hover: Grab keyboard input on mouse hover. +# # @zoom-to-fit: Zoom guest display to fit into the host window. When -# turned off the host window will be resized instead. -# In case the display device can notify the guest on -# window resizes (virtio-gpu) this will default to "on", -# assuming the guest will resize the display to match -# the window size then. Otherwise it defaults to "off". -# Since 3.1 +# turned off the host window will be resized instead. In case the +# display device can notify the guest on window resizes +# (virtio-gpu) this will default to "on", assuming the guest will +# resize the display to match the window size then. Otherwise it +# defaults to "off". (Since 3.1) # -# Since: 2.12 +# @show-tabs: Display the tab bar for switching between the various +# graphical interfaces (e.g. VGA and virtual console character +# devices) by default. (Since 7.1) +# +# @show-menubar: Display the main window menubar. Defaults to "on". +# (Since 8.0) # +# Since: 2.12 ## { 'struct' : 'DisplayGTK', 'data' : { '*grab-on-hover' : 'bool', - '*zoom-to-fit' : 'bool' } } + '*zoom-to-fit' : 'bool', + '*show-tabs' : 'bool', + '*show-menubar' : 'bool' } } ## # @DisplayEGLHeadless: # # EGL headless display options. # -# @rendernode: Which DRM render node should be used. Default is the first -# available node on the host. +# @rendernode: Which DRM render node should be used. Default is the +# first available node on the host. # # Since: 3.1 -# ## { 'struct' : 'DisplayEGLHeadless', 'data' : { '*rendernode' : 'str' } } - ## - # @DisplayGLMode: - # - # Display OpenGL mode. - # - # @off: Disable OpenGL (default). - # @on: Use OpenGL, pick context type automatically. - # Would better be named 'auto' but is called 'on' for backward - # compatibility with bool type. - # @core: Use OpenGL with Core (desktop) Context. - # @es: Use OpenGL with ES (embedded systems) Context. - # - # Since: 3.0 - # - ## +## +# @DisplayDBus: +# +# DBus display options. +# +# @addr: The D-Bus bus address (default to the session bus). +# +# @rendernode: Which DRM render node should be used. Default is the +# first available node on the host. +# +# @p2p: Whether to use peer-to-peer connections (accepted through +# @add_client). +# +# @audiodev: Use the specified DBus audiodev to export audio. +# +# Since: 7.0 +## +{ 'struct' : 'DisplayDBus', + 'data' : { '*rendernode' : 'str', + '*addr': 'str', + '*p2p': 'bool', + '*audiodev': 'str' } } + +## +# @DisplayGLMode: +# +# Display OpenGL mode. +# +# @off: Disable OpenGL (default). +# +# @on: Use OpenGL, pick context type automatically. Would better be +# named 'auto' but is called 'on' for backward compatibility with +# bool type. +# +# @core: Use OpenGL with Core (desktop) Context. +# +# @es: Use OpenGL with ES (embedded systems) Context. +# +# Since: 3.0 +## { 'enum' : 'DisplayGLMode', 'data' : [ 'off', 'on', 'core', 'es' ] } @@ -1080,70 +1404,142 @@ # # Curses display options. # -# @charset: Font charset used by guest (default: CP437). +# @charset: Font charset used by guest (default: CP437). # # Since: 4.0 -# ## { 'struct' : 'DisplayCurses', 'data' : { '*charset' : 'str' } } ## +# @DisplayCocoa: +# +# Cocoa display options. +# +# @left-command-key: Enable/disable forwarding of left command key to +# guest. Allows command-tab window switching on the host without +# sending this key to the guest when "off". Defaults to "on" +# +# @full-grab: Capture all key presses, including system combos. This +# requires accessibility permissions, since it performs a global +# grab on key events. (default: off) See +# https://support.apple.com/en-in/guide/mac-help/mh32356/mac +# +# @swap-opt-cmd: Swap the Option and Command keys so that their key +# codes match their position on non-Mac keyboards and you can use +# Meta/Super and Alt where you expect them. (default: off) +# +# @zoom-to-fit: Zoom guest display to fit into the host window. When +# turned off the host window will be resized instead. Defaults to +# "off". (Since 8.2) +# +# @zoom-interpolation: Apply interpolation to smooth output when +# zoom-to-fit is enabled. Defaults to "off". (Since 9.0) +# +# Since: 7.0 +## +{ 'struct': 'DisplayCocoa', + 'data': { + '*left-command-key': 'bool', + '*full-grab': 'bool', + '*swap-opt-cmd': 'bool', + '*zoom-to-fit': 'bool', + '*zoom-interpolation': 'bool' + } } + +## +# @HotKeyMod: +# +# Set of modifier keys that need to be held for shortcut key actions. +# +# Since: 7.1 +## +{ 'enum' : 'HotKeyMod', + 'data' : [ 'lctrl-lalt', 'lshift-lctrl-lalt', 'rctrl' ] } + +## +# @DisplaySDL: +# +# SDL2 display options. +# +# @grab-mod: Modifier keys that should be pressed together with the +# "G" key to release the mouse grab. +# +# Since: 7.1 +## +{ 'struct' : 'DisplaySDL', + 'data' : { '*grab-mod' : 'HotKeyMod' } } + +## # @DisplayType: # # Display (user interface) type. # -# @default: The default user interface, selecting from the first available -# of gtk, sdl, cocoa, and vnc. +# @default: The default user interface, selecting from the first +# available of gtk, sdl, cocoa, and vnc. # -# @none: No user interface or video output display. The guest will -# still see an emulated graphics card, but its output will not -# be displayed to the QEMU user. +# @none: No user interface or video output display. The guest will +# still see an emulated graphics card, but its output will not be +# displayed to the QEMU user. # # @gtk: The GTK user interface. # # @sdl: The SDL user interface. # # @egl-headless: No user interface, offload GL operations to a local -# DRI device. Graphical display need to be paired with -# VNC or Spice. (Since 3.1) +# DRI device. Graphical display need to be paired with VNC or +# Spice. (Since 3.1) # # @curses: Display video output via curses. For graphics device -# models which support a text mode, QEMU can display this -# output using a curses/ncurses interface. Nothing is -# displayed when the graphics device is in graphical mode or -# if the graphics device does not support a text -# mode. Generally only the VGA device models support text -# mode. +# models which support a text mode, QEMU can display this output +# using a curses/ncurses interface. Nothing is displayed when the +# graphics device is in graphical mode or if the graphics device +# does not support a text mode. Generally only the VGA device +# models support text mode. # # @cocoa: The Cocoa user interface. # # @spice-app: Set up a Spice server and run the default associated -# application to connect to it. The server will redirect -# the serial console and QEMU monitors. (Since 4.0) +# application to connect to it. The server will redirect the +# serial console and QEMU monitors. (Since 4.0) # -# Since: 2.12 +# @dbus: Start a D-Bus service for the display. (Since 7.0) # +# Since: 2.12 ## { 'enum' : 'DisplayType', - 'data' : [ 'default', 'none', 'gtk', 'sdl', - 'egl-headless', 'curses', 'cocoa', - 'spice-app'] } + 'data' : [ + { 'name': 'default' }, + { 'name': 'none' }, + { 'name': 'gtk', 'if': 'CONFIG_GTK' }, + { 'name': 'sdl', 'if': 'CONFIG_SDL' }, + { 'name': 'egl-headless', 'if': 'CONFIG_OPENGL' }, + { 'name': 'curses', 'if': 'CONFIG_CURSES' }, + { 'name': 'cocoa', 'if': 'CONFIG_COCOA' }, + { 'name': 'spice-app', 'if': 'CONFIG_SPICE' }, + { 'name': 'dbus', 'if': 'CONFIG_DBUS_DISPLAY' } + ] +} ## # @DisplayOptions: # # Display (user interface) options. # -# @type: Which DisplayType qemu should use. -# @full-screen: Start user interface in fullscreen mode (default: off). -# @window-close: Allow to quit qemu with window close button (default: on). -# @show-cursor: Force showing the mouse cursor (default: off). -# (since: 5.0) -# @gl: Enable OpenGL support (default: off). +# @type: Which DisplayType qemu should use. # -# Since: 2.12 +# @full-screen: Start user interface in fullscreen mode +# (default: off). +# +# @window-close: Allow to quit qemu with window close button +# (default: on). # +# @show-cursor: Force showing the mouse cursor (default: off). +# (since: 5.0) +# +# @gl: Enable OpenGL support (default: off). +# +# Since: 2.12 ## { 'union' : 'DisplayOptions', 'base' : { 'type' : 'DisplayType', @@ -1152,9 +1548,16 @@ '*show-cursor' : 'bool', '*gl' : 'DisplayGLMode' }, 'discriminator' : 'type', - 'data' : { 'gtk' : 'DisplayGTK', - 'curses' : 'DisplayCurses', - 'egl-headless' : 'DisplayEGLHeadless'} } + 'data' : { + 'gtk': { 'type': 'DisplayGTK', 'if': 'CONFIG_GTK' }, + 'cocoa': { 'type': 'DisplayCocoa', 'if': 'CONFIG_COCOA' }, + 'curses': { 'type': 'DisplayCurses', 'if': 'CONFIG_CURSES' }, + 'egl-headless': { 'type': 'DisplayEGLHeadless', + 'if': 'CONFIG_OPENGL' }, + 'dbus': { 'type': 'DisplayDBus', 'if': 'CONFIG_DBUS_DISPLAY' }, + 'sdl': { 'type': 'DisplaySDL', 'if': 'CONFIG_SDL' } + } +} ## # @query-display-options: @@ -1164,7 +1567,6 @@ # Returns: @DisplayOptions # # Since: 3.1 -# ## { 'command': 'query-display-options', 'returns': 'DisplayOptions' } @@ -1177,7 +1579,6 @@ # @vnc: VNC display # # Since: 6.0 -# ## { 'enum': 'DisplayReloadType', 'data': ['vnc'] } @@ -1190,7 +1591,6 @@ # @tls-certs: reload tls certs or not. # # Since: 6.0 -# ## { 'struct': 'DisplayReloadOptionsVNC', 'data': { '*tls-certs': 'bool' } } @@ -1203,7 +1603,6 @@ # @type: Specify the display type. # # Since: 6.0 -# ## { 'union': 'DisplayReloadOptions', 'base': {'type': 'DisplayReloadType'}, @@ -1215,17 +1614,104 @@ # # Reload display configuration. # -# Returns: Nothing on success. -# # Since: 6.0 # # Example: # -# -> { "execute": "display-reload", -# "arguments": { "type": "vnc", "tls-certs": true } } -# <- { "return": {} } -# +# -> { "execute": "display-reload", +# "arguments": { "type": "vnc", "tls-certs": true } } +# <- { "return": {} } ## { 'command': 'display-reload', 'data': 'DisplayReloadOptions', 'boxed' : true } + +## +# @DisplayUpdateType: +# +# Available DisplayUpdate types. +# +# @vnc: VNC display +# +# Since: 7.1 +## +{ 'enum': 'DisplayUpdateType', + 'data': ['vnc'] } + +## +# @DisplayUpdateOptionsVNC: +# +# Specify the VNC reload options. +# +# @addresses: If specified, change set of addresses to listen for +# connections. Addresses configured for websockets are not +# touched. +# +# Since: 7.1 +## +{ 'struct': 'DisplayUpdateOptionsVNC', + 'data': { '*addresses': ['SocketAddress'] } } + +## +# @DisplayUpdateOptions: +# +# Options of the display configuration reload. +# +# @type: Specify the display type. +# +# Since: 7.1 +## +{ 'union': 'DisplayUpdateOptions', + 'base': {'type': 'DisplayUpdateType'}, + 'discriminator': 'type', + 'data': { 'vnc': 'DisplayUpdateOptionsVNC' } } + +## +# @display-update: +# +# Update display configuration. +# +# Since: 7.1 +# +# Example: +# +# -> { "execute": "display-update", +# "arguments": { "type": "vnc", "addresses": +# [ { "type": "inet", "host": "0.0.0.0", +# "port": "5901" } ] } } +# <- { "return": {} } +## +{ 'command': 'display-update', + 'data': 'DisplayUpdateOptions', + 'boxed' : true } + +## +# @client_migrate_info: +# +# Set migration information for remote display. This makes the server +# ask the client to automatically reconnect using the new parameters +# once migration finished successfully. Only implemented for SPICE. +# +# @protocol: must be "spice" +# +# @hostname: migration target hostname +# +# @port: spice tcp port for plaintext channels +# +# @tls-port: spice tcp port for tls-secured channels +# +# @cert-subject: server certificate subject +# +# Since: 0.14 +# +# Example: +# +# -> { "execute": "client_migrate_info", +# "arguments": { "protocol": "spice", +# "hostname": "virt42.lab.kraxel.org", +# "port": 1234 } } +# <- { "return": {} } +## +{ 'command': 'client_migrate_info', + 'data': { 'protocol': 'str', 'hostname': 'str', '*port': 'int', + '*tls-port': 'int', '*cert-subject': 'str' } } diff --git a/qapi/virtio.json b/qapi/virtio.json new file mode 100644 index 0000000000..74fc27c702 --- /dev/null +++ b/qapi/virtio.json @@ -0,0 +1,981 @@ +# -*- Mode: Python -*- +# vim: filetype=python +# + +## +# = Virtio devices +## + +## +# @VirtioInfo: +# +# Basic information about a given VirtIODevice +# +# @path: The VirtIODevice's canonical QOM path +# +# @name: Name of the VirtIODevice +# +# Since: 7.2 +## +{ 'struct': 'VirtioInfo', + 'data': { 'path': 'str', + 'name': 'str' } } + +## +# @x-query-virtio: +# +# Returns a list of all realized VirtIODevices +# +# Features: +# +# @unstable: This command is meant for debugging. +# +# Returns: List of gathered VirtIODevices +# +# Since: 7.2 +# +# Example: +# +# -> { "execute": "x-query-virtio" } +# <- { "return": [ +# { +# "name": "virtio-input", +# "path": "/machine/peripheral-anon/device[4]/virtio-backend" +# }, +# { +# "name": "virtio-crypto", +# "path": "/machine/peripheral/crypto0/virtio-backend" +# }, +# { +# "name": "virtio-scsi", +# "path": "/machine/peripheral-anon/device[2]/virtio-backend" +# }, +# { +# "name": "virtio-net", +# "path": "/machine/peripheral-anon/device[1]/virtio-backend" +# }, +# { +# "name": "virtio-serial", +# "path": "/machine/peripheral-anon/device[0]/virtio-backend" +# } +# ] +# } +## +{ 'command': 'x-query-virtio', + 'returns': [ 'VirtioInfo' ], + 'features': [ 'unstable' ] } + +## +# @VhostStatus: +# +# Information about a vhost device. This information will only be +# displayed if the vhost device is active. +# +# @n-mem-sections: vhost_dev n_mem_sections +# +# @n-tmp-sections: vhost_dev n_tmp_sections +# +# @nvqs: vhost_dev nvqs (number of virtqueues being used) +# +# @vq-index: vhost_dev vq_index +# +# @features: vhost_dev features +# +# @acked-features: vhost_dev acked_features +# +# @backend-features: vhost_dev backend_features +# +# @protocol-features: vhost_dev protocol_features +# +# @max-queues: vhost_dev max_queues +# +# @backend-cap: vhost_dev backend_cap +# +# @log-enabled: vhost_dev log_enabled flag +# +# @log-size: vhost_dev log_size +# +# Since: 7.2 +## +{ 'struct': 'VhostStatus', + 'data': { 'n-mem-sections': 'int', + 'n-tmp-sections': 'int', + 'nvqs': 'uint32', + 'vq-index': 'int', + 'features': 'VirtioDeviceFeatures', + 'acked-features': 'VirtioDeviceFeatures', + 'backend-features': 'VirtioDeviceFeatures', + 'protocol-features': 'VhostDeviceProtocols', + 'max-queues': 'uint64', + 'backend-cap': 'uint64', + 'log-enabled': 'bool', + 'log-size': 'uint64' } } + +## +# @VirtioStatus: +# +# Full status of the virtio device with most VirtIODevice members. +# Also includes the full status of the corresponding vhost device if +# the vhost device is active. +# +# @name: VirtIODevice name +# +# @device-id: VirtIODevice ID +# +# @vhost-started: VirtIODevice vhost_started flag +# +# @guest-features: VirtIODevice guest_features +# +# @host-features: VirtIODevice host_features +# +# @backend-features: VirtIODevice backend_features +# +# @device-endian: VirtIODevice device_endian +# +# @num-vqs: VirtIODevice virtqueue count. This is the number of +# active virtqueues being used by the VirtIODevice. +# +# @status: VirtIODevice configuration status (VirtioDeviceStatus) +# +# @isr: VirtIODevice ISR +# +# @queue-sel: VirtIODevice queue_sel +# +# @vm-running: VirtIODevice vm_running flag +# +# @broken: VirtIODevice broken flag +# +# @disabled: VirtIODevice disabled flag +# +# @use-started: VirtIODevice use_started flag +# +# @started: VirtIODevice started flag +# +# @start-on-kick: VirtIODevice start_on_kick flag +# +# @disable-legacy-check: VirtIODevice disabled_legacy_check flag +# +# @bus-name: VirtIODevice bus_name +# +# @use-guest-notifier-mask: VirtIODevice use_guest_notifier_mask flag +# +# @vhost-dev: Corresponding vhost device info for a given +# VirtIODevice. Present if the given VirtIODevice has an active +# vhost device. +# +# Since: 7.2 +## +{ 'struct': 'VirtioStatus', + 'data': { 'name': 'str', + 'device-id': 'uint16', + 'vhost-started': 'bool', + 'device-endian': 'str', + 'guest-features': 'VirtioDeviceFeatures', + 'host-features': 'VirtioDeviceFeatures', + 'backend-features': 'VirtioDeviceFeatures', + 'num-vqs': 'int', + 'status': 'VirtioDeviceStatus', + 'isr': 'uint8', + 'queue-sel': 'uint16', + 'vm-running': 'bool', + 'broken': 'bool', + 'disabled': 'bool', + 'use-started': 'bool', + 'started': 'bool', + 'start-on-kick': 'bool', + 'disable-legacy-check': 'bool', + 'bus-name': 'str', + 'use-guest-notifier-mask': 'bool', + '*vhost-dev': 'VhostStatus' } } + +## +# @x-query-virtio-status: +# +# Poll for a comprehensive status of a given virtio device +# +# @path: Canonical QOM path of the VirtIODevice +# +# Features: +# +# @unstable: This command is meant for debugging. +# +# Returns: VirtioStatus of the virtio device +# +# Since: 7.2 +# +# Examples: +# +# 1. Poll for the status of virtio-crypto (no vhost-crypto active) +# +# -> { "execute": "x-query-virtio-status", +# "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend" } +# } +# <- { "return": { +# "device-endian": "little", +# "bus-name": "", +# "disable-legacy-check": false, +# "name": "virtio-crypto", +# "started": true, +# "device-id": 20, +# "backend-features": { +# "transports": [], +# "dev-features": [] +# }, +# "start-on-kick": false, +# "isr": 1, +# "broken": false, +# "status": { +# "statuses": [ +# "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found", +# "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device", +# "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete", +# "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready" +# ] +# }, +# "num-vqs": 2, +# "guest-features": { +# "dev-features": [], +# "transports": [ +# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", +# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", +# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)" +# ] +# }, +# "host-features": { +# "unknown-dev-features": 1073741824, +# "dev-features": [], +# "transports": [ +# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", +# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", +# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)", +# "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts", +# "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ" +# ] +# }, +# "use-guest-notifier-mask": true, +# "vm-running": true, +# "queue-sel": 1, +# "disabled": false, +# "vhost-started": false, +# "use-started": true +# } +# } +# +# 2. Poll for the status of virtio-net (vhost-net is active) +# +# -> { "execute": "x-query-virtio-status", +# "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend" } +# } +# <- { "return": { +# "device-endian": "little", +# "bus-name": "", +# "disabled-legacy-check": false, +# "name": "virtio-net", +# "started": true, +# "device-id": 1, +# "vhost-dev": { +# "n-tmp-sections": 4, +# "n-mem-sections": 4, +# "max-queues": 1, +# "backend-cap": 2, +# "log-size": 0, +# "backend-features": { +# "dev-features": [], +# "transports": [] +# }, +# "nvqs": 2, +# "protocol-features": { +# "protocols": [] +# }, +# "vq-index": 0, +# "log-enabled": false, +# "acked-features": { +# "dev-features": [ +# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers" +# ], +# "transports": [ +# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", +# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", +# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)" +# ] +# }, +# "features": { +# "dev-features": [ +# "VHOST_F_LOG_ALL: Logging write descriptors supported", +# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers" +# ], +# "transports": [ +# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", +# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", +# "VIRTIO_F_IOMMU_PLATFORM: Device can be used on IOMMU platform", +# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)", +# "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts", +# "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ" +# ] +# } +# }, +# "backend-features": { +# "dev-features": [ +# "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported", +# "VIRTIO_NET_F_GSO: Handling GSO-type packets supported", +# "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel", +# "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported", +# "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported", +# "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported", +# "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported", +# "VIRTIO_NET_F_CTRL_VQ: Control channel available", +# "VIRTIO_NET_F_STATUS: Configuration status field available", +# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers", +# "VIRTIO_NET_F_HOST_UFO: Device can receive UFO", +# "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN", +# "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6", +# "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4", +# "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO", +# "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN", +# "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6", +# "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4", +# "VIRTIO_NET_F_MAC: Device has given MAC address", +# "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported", +# "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported", +# "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported" +# ], +# "transports": [ +# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", +# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", +# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)", +# "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts", +# "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ" +# ] +# }, +# "start-on-kick": false, +# "isr": 1, +# "broken": false, +# "status": { +# "statuses": [ +# "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found", +# "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device", +# "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete", +# "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready" +# ] +# }, +# "num-vqs": 3, +# "guest-features": { +# "dev-features": [ +# "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel", +# "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported", +# "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported", +# "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported", +# "VIRTIO_NET_F_CTRL_VQ: Control channel available", +# "VIRTIO_NET_F_STATUS: Configuration status field available", +# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers", +# "VIRTIO_NET_F_HOST_UFO: Device can receive UFO", +# "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN", +# "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6", +# "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4", +# "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO", +# "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN", +# "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6", +# "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4", +# "VIRTIO_NET_F_MAC: Device has given MAC address", +# "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported", +# "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported", +# "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported" +# ], +# "transports": [ +# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", +# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", +# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)" +# ] +# }, +# "host-features": { +# "dev-features": [ +# "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported", +# "VIRTIO_NET_F_GSO: Handling GSO-type packets supported", +# "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel", +# "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported", +# "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported", +# "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported", +# "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported", +# "VIRTIO_NET_F_CTRL_VQ: Control channel available", +# "VIRTIO_NET_F_STATUS: Configuration status field available", +# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers", +# "VIRTIO_NET_F_HOST_UFO: Device can receive UFO", +# "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN", +# "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6", +# "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4", +# "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO", +# "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN", +# "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6", +# "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4", +# "VIRTIO_NET_F_MAC: Device has given MAC address", +# "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported", +# "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported", +# "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported" +# ], +# "transports": [ +# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", +# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", +# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)", +# "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts", +# "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ" +# ] +# }, +# "use-guest-notifier-mask": true, +# "vm-running": true, +# "queue-sel": 2, +# "disabled": false, +# "vhost-started": true, +# "use-started": true +# } +# } +## +{ 'command': 'x-query-virtio-status', + 'data': { 'path': 'str' }, + 'returns': 'VirtioStatus', + 'features': [ 'unstable' ] } + +## +# @VirtioDeviceStatus: +# +# A structure defined to list the configuration statuses of a virtio +# device +# +# @statuses: List of decoded configuration statuses of the virtio +# device +# +# @unknown-statuses: Virtio device statuses bitmap that have not been +# decoded +# +# Since: 7.2 +## +{ 'struct': 'VirtioDeviceStatus', + 'data': { 'statuses': [ 'str' ], + '*unknown-statuses': 'uint8' } } + +## +# @VhostDeviceProtocols: +# +# A structure defined to list the vhost user protocol features of a +# Vhost User device +# +# @protocols: List of decoded vhost user protocol features of a vhost +# user device +# +# @unknown-protocols: Vhost user device protocol features bitmap that +# have not been decoded +# +# Since: 7.2 +## +{ 'struct': 'VhostDeviceProtocols', + 'data': { 'protocols': [ 'str' ], + '*unknown-protocols': 'uint64' } } + +## +# @VirtioDeviceFeatures: +# +# The common fields that apply to most Virtio devices. Some devices +# may not have their own device-specific features (e.g. virtio-rng). +# +# @transports: List of transport features of the virtio device +# +# @dev-features: List of device-specific features (if the device has +# unique features) +# +# @unknown-dev-features: Virtio device features bitmap that have not +# been decoded +# +# Since: 7.2 +## +{ 'struct': 'VirtioDeviceFeatures', + 'data': { 'transports': [ 'str' ], + '*dev-features': [ 'str' ], + '*unknown-dev-features': 'uint64' } } + +## +# @VirtQueueStatus: +# +# Information of a VirtIODevice VirtQueue, including most members of +# the VirtQueue data structure. +# +# @name: Name of the VirtIODevice that uses this VirtQueue +# +# @queue-index: VirtQueue queue_index +# +# @inuse: VirtQueue inuse +# +# @vring-num: VirtQueue vring.num +# +# @vring-num-default: VirtQueue vring.num_default +# +# @vring-align: VirtQueue vring.align +# +# @vring-desc: VirtQueue vring.desc (descriptor area) +# +# @vring-avail: VirtQueue vring.avail (driver area) +# +# @vring-used: VirtQueue vring.used (device area) +# +# @last-avail-idx: VirtQueue last_avail_idx or return of vhost_dev +# vhost_get_vring_base (if vhost active) +# +# @shadow-avail-idx: VirtQueue shadow_avail_idx +# +# @used-idx: VirtQueue used_idx +# +# @signalled-used: VirtQueue signalled_used +# +# @signalled-used-valid: VirtQueue signalled_used_valid flag +# +# Since: 7.2 +## +{ 'struct': 'VirtQueueStatus', + 'data': { 'name': 'str', + 'queue-index': 'uint16', + 'inuse': 'uint32', + 'vring-num': 'uint32', + 'vring-num-default': 'uint32', + 'vring-align': 'uint32', + 'vring-desc': 'uint64', + 'vring-avail': 'uint64', + 'vring-used': 'uint64', + '*last-avail-idx': 'uint16', + '*shadow-avail-idx': 'uint16', + 'used-idx': 'uint16', + 'signalled-used': 'uint16', + 'signalled-used-valid': 'bool' } } + +## +# @x-query-virtio-queue-status: +# +# Return the status of a given VirtIODevice's VirtQueue +# +# @path: VirtIODevice canonical QOM path +# +# @queue: VirtQueue index to examine +# +# Features: +# +# @unstable: This command is meant for debugging. +# +# Returns: VirtQueueStatus of the VirtQueue +# +# Notes: last_avail_idx will not be displayed in the case where the +# selected VirtIODevice has a running vhost device and the +# VirtIODevice VirtQueue index (queue) does not exist for the +# corresponding vhost device vhost_virtqueue. Also, +# shadow_avail_idx will not be displayed in the case where the +# selected VirtIODevice has a running vhost device. +# +# Since: 7.2 +# +# Examples: +# +# 1. Get VirtQueueStatus for virtio-vsock (vhost-vsock running) +# +# -> { "execute": "x-query-virtio-queue-status", +# "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend", +# "queue": 1 } +# } +# <- { "return": { +# "signalled-used": 0, +# "inuse": 0, +# "name": "vhost-vsock", +# "vring-align": 4096, +# "vring-desc": 5217370112, +# "signalled-used-valid": false, +# "vring-num-default": 128, +# "vring-avail": 5217372160, +# "queue-index": 1, +# "last-avail-idx": 0, +# "vring-used": 5217372480, +# "used-idx": 0, +# "vring-num": 128 +# } +# } +# +# 2. Get VirtQueueStatus for virtio-serial (no vhost) +# +# -> { "execute": "x-query-virtio-queue-status", +# "arguments": { "path": "/machine/peripheral-anon/device[0]/virtio-backend", +# "queue": 20 } +# } +# <- { "return": { +# "signalled-used": 0, +# "inuse": 0, +# "name": "virtio-serial", +# "vring-align": 4096, +# "vring-desc": 5182074880, +# "signalled-used-valid": false, +# "vring-num-default": 128, +# "vring-avail": 5182076928, +# "queue-index": 20, +# "last-avail-idx": 0, +# "vring-used": 5182077248, +# "used-idx": 0, +# "shadow-avail-idx": 0, +# "vring-num": 128 +# } +# } +## +{ 'command': 'x-query-virtio-queue-status', + 'data': { 'path': 'str', 'queue': 'uint16' }, + 'returns': 'VirtQueueStatus', + 'features': [ 'unstable' ] } + +## +# @VirtVhostQueueStatus: +# +# Information of a vhost device's vhost_virtqueue, including most +# members of the vhost_dev vhost_virtqueue data structure. +# +# @name: Name of the VirtIODevice that uses this vhost_virtqueue +# +# @kick: vhost_virtqueue kick +# +# @call: vhost_virtqueue call +# +# @desc: vhost_virtqueue desc +# +# @avail: vhost_virtqueue avail +# +# @used: vhost_virtqueue used +# +# @num: vhost_virtqueue num +# +# @desc-phys: vhost_virtqueue desc_phys (descriptor area physical +# address) +# +# @desc-size: vhost_virtqueue desc_size +# +# @avail-phys: vhost_virtqueue avail_phys (driver area physical +# address) +# +# @avail-size: vhost_virtqueue avail_size +# +# @used-phys: vhost_virtqueue used_phys (device area physical address) +# +# @used-size: vhost_virtqueue used_size +# +# Since: 7.2 +## +{ 'struct': 'VirtVhostQueueStatus', + 'data': { 'name': 'str', + 'kick': 'int', + 'call': 'int', + 'desc': 'uint64', + 'avail': 'uint64', + 'used': 'uint64', + 'num': 'int', + 'desc-phys': 'uint64', + 'desc-size': 'uint32', + 'avail-phys': 'uint64', + 'avail-size': 'uint32', + 'used-phys': 'uint64', + 'used-size': 'uint32' } } + +## +# @x-query-virtio-vhost-queue-status: +# +# Return information of a given vhost device's vhost_virtqueue +# +# @path: VirtIODevice canonical QOM path +# +# @queue: vhost_virtqueue index to examine +# +# Features: +# +# @unstable: This command is meant for debugging. +# +# Returns: VirtVhostQueueStatus of the vhost_virtqueue +# +# Since: 7.2 +# +# Examples: +# +# 1. Get vhost_virtqueue status for vhost-crypto +# +# -> { "execute": "x-query-virtio-vhost-queue-status", +# "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend", +# "queue": 0 } +# } +# <- { "return": { +# "avail-phys": 5216124928, +# "name": "virtio-crypto", +# "used-phys": 5216127040, +# "avail-size": 2054, +# "desc-size": 16384, +# "used-size": 8198, +# "desc": 140141447430144, +# "num": 1024, +# "call": 0, +# "avail": 140141447446528, +# "desc-phys": 5216108544, +# "used": 140141447448640, +# "kick": 0 +# } +# } +# +# 2. Get vhost_virtqueue status for vhost-vsock +# +# -> { "execute": "x-query-virtio-vhost-queue-status", +# "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend", +# "queue": 0 } +# } +# <- { "return": { +# "avail-phys": 5182261248, +# "name": "vhost-vsock", +# "used-phys": 5182261568, +# "avail-size": 262, +# "desc-size": 2048, +# "used-size": 1030, +# "desc": 140141413580800, +# "num": 128, +# "call": 0, +# "avail": 140141413582848, +# "desc-phys": 5182259200, +# "used": 140141413583168, +# "kick": 0 +# } +# } +## +{ 'command': 'x-query-virtio-vhost-queue-status', + 'data': { 'path': 'str', 'queue': 'uint16' }, + 'returns': 'VirtVhostQueueStatus', + 'features': [ 'unstable' ] } + +## +# @VirtioRingDesc: +# +# Information regarding the vring descriptor area +# +# @addr: Guest physical address of the descriptor area +# +# @len: Length of the descriptor area +# +# @flags: List of descriptor flags +# +# Since: 7.2 +## +{ 'struct': 'VirtioRingDesc', + 'data': { 'addr': 'uint64', + 'len': 'uint32', + 'flags': [ 'str' ] } } + +## +# @VirtioRingAvail: +# +# Information regarding the avail vring (a.k.a. driver area) +# +# @flags: VRingAvail flags +# +# @idx: VRingAvail index +# +# @ring: VRingAvail ring[] entry at provided index +# +# Since: 7.2 +## +{ 'struct': 'VirtioRingAvail', + 'data': { 'flags': 'uint16', + 'idx': 'uint16', + 'ring': 'uint16' } } + +## +# @VirtioRingUsed: +# +# Information regarding the used vring (a.k.a. device area) +# +# @flags: VRingUsed flags +# +# @idx: VRingUsed index +# +# Since: 7.2 +## +{ 'struct': 'VirtioRingUsed', + 'data': { 'flags': 'uint16', + 'idx': 'uint16' } } + +## +# @VirtioQueueElement: +# +# Information regarding a VirtQueue's VirtQueueElement including +# descriptor, driver, and device areas +# +# @name: Name of the VirtIODevice that uses this VirtQueue +# +# @index: Index of the element in the queue +# +# @descs: List of descriptors (VirtioRingDesc) +# +# @avail: VRingAvail info +# +# @used: VRingUsed info +# +# Since: 7.2 +## +{ 'struct': 'VirtioQueueElement', + 'data': { 'name': 'str', + 'index': 'uint32', + 'descs': [ 'VirtioRingDesc' ], + 'avail': 'VirtioRingAvail', + 'used': 'VirtioRingUsed' } } + +## +# @x-query-virtio-queue-element: +# +# Return the information about a VirtQueue's VirtQueueElement +# +# @path: VirtIODevice canonical QOM path +# +# @queue: VirtQueue index to examine +# +# @index: Index of the element in the queue (default: head of the +# queue) +# +# Features: +# +# @unstable: This command is meant for debugging. +# +# Returns: VirtioQueueElement information +# +# Since: 7.2 +# +# Examples: +# +# 1. Introspect on virtio-net's VirtQueue 0 at index 5 +# +# -> { "execute": "x-query-virtio-queue-element", +# "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend", +# "queue": 0, +# "index": 5 } +# } +# <- { "return": { +# "index": 5, +# "name": "virtio-net", +# "descs": [ +# { +# "flags": ["write"], +# "len": 1536, +# "addr": 5257305600 +# } +# ], +# "avail": { +# "idx": 256, +# "flags": 0, +# "ring": 5 +# }, +# "used": { +# "idx": 13, +# "flags": 0 +# } +# } +# } +# +# 2. Introspect on virtio-crypto's VirtQueue 1 at head +# +# -> { "execute": "x-query-virtio-queue-element", +# "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend", +# "queue": 1 } +# } +# <- { "return": { +# "index": 0, +# "name": "virtio-crypto", +# "descs": [ +# { +# "flags": [], +# "len": 0, +# "addr": 8080268923184214134 +# } +# ], +# "avail": { +# "idx": 280, +# "flags": 0, +# "ring": 0 +# }, +# "used": { +# "idx": 280, +# "flags": 0 +# } +# } +# } +# +# 3. Introspect on virtio-scsi's VirtQueue 2 at head +# +# -> { "execute": "x-query-virtio-queue-element", +# "arguments": { "path": "/machine/peripheral-anon/device[2]/virtio-backend", +# "queue": 2 } +# } +# <- { "return": { +# "index": 19, +# "name": "virtio-scsi", +# "descs": [ +# { +# "flags": ["used", "indirect", "write"], +# "len": 4099327944, +# "addr": 12055409292258155293 +# } +# ], +# "avail": { +# "idx": 1147, +# "flags": 0, +# "ring": 19 +# }, +# "used": { +# "idx": 280, +# "flags": 0 +# } +# } +# } +## +{ 'command': 'x-query-virtio-queue-element', + 'data': { 'path': 'str', 'queue': 'uint16', '*index': 'uint16' }, + 'returns': 'VirtioQueueElement', + 'features': [ 'unstable' ] } + +## +# @IOThreadVirtQueueMapping: +# +# Describes the subset of virtqueues assigned to an IOThread. +# +# @iothread: the id of IOThread object +# +# @vqs: an optional array of virtqueue indices that will be handled by +# this IOThread. When absent, virtqueues are assigned round-robin +# across all IOThreadVirtQueueMappings provided. Either all +# IOThreadVirtQueueMappings must have @vqs or none of them must +# have it. +# +# Since: 9.0 +## + +{ 'struct': 'IOThreadVirtQueueMapping', + 'data': { 'iothread': 'str', '*vqs': ['uint16'] } } + +## +# @DummyVirtioForceArrays: +# +# Not used by QMP; hack to let us use IOThreadVirtQueueMappingList +# internally +# +# Since: 9.0 +## + +{ 'struct': 'DummyVirtioForceArrays', + 'data': { 'unused-iothread-vq-mapping': ['IOThreadVirtQueueMapping'] } } + +## +# @GranuleMode: +# +# @4k: granule page size of 4KiB +# +# @8k: granule page size of 8KiB +# +# @16k: granule page size of 16KiB +# +# @64k: granule page size of 64KiB +# +# @host: granule matches the host page size +# +# Since: 9.0 +## +{ 'enum': 'GranuleMode', + 'data': [ '4k', '8k', '16k', '64k', 'host' ] } diff --git a/qapi/yank.json b/qapi/yank.json index 167a775594..89f2f4d199 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -9,7 +9,7 @@ ## # @YankInstanceType: # -# An enumeration of yank instance types. See @YankInstance for more +# An enumeration of yank instance types. See @YankInstance for more # information. # # Since: 6.0 @@ -20,8 +20,8 @@ ## # @YankInstanceBlockNode: # -# Specifies which block graph node to yank. See @YankInstance for more -# information. +# Specifies which block graph node to yank. See @YankInstance for +# more information. # # @node-name: the name of the block graph node # @@ -33,8 +33,8 @@ ## # @YankInstanceChardev: # -# Specifies which character device to yank. See @YankInstance for more -# information. +# Specifies which character device to yank. See @YankInstance for +# more information. # # @id: the chardev's ID # @@ -46,20 +46,20 @@ ## # @YankInstance: # -# A yank instance can be yanked with the @yank qmp command to recover from a -# hanging QEMU. +# A yank instance can be yanked with the @yank qmp command to recover +# from a hanging QEMU. +# +# @type: yank instance type # # Currently implemented yank instances: -# - nbd block device: -# Yanking it will shut down the connection to the nbd server without -# attempting to reconnect. -# - socket chardev: -# Yanking it will shut down the connected socket. -# - migration: -# Yanking it will shut down all migration connections. Unlike -# @migrate_cancel, it will not notify the migration process, so migration -# will go into @failed state, instead of @cancelled state. @yank should be -# used to recover from hangs. +# +# - nbd block device: Yanking it will shut down the connection to the +# nbd server without attempting to reconnect. +# - socket chardev: Yanking it will shut down the connected socket. +# - migration: Yanking it will shut down all migration connections. +# Unlike @migrate_cancel, it will not notify the migration process, +# so migration will go into @failed state, instead of @cancelled +# state. @yank should be used to recover from hangs. # # Since: 6.0 ## @@ -73,23 +73,23 @@ ## # @yank: # -# Try to recover from hanging QEMU by yanking the specified instances. See -# @YankInstance for more information. +# Try to recover from hanging QEMU by yanking the specified instances. +# See @YankInstance for more information. # -# Takes a list of @YankInstance as argument. +# @instances: the instances to be yanked # -# Returns: - Nothing on success -# - @DeviceNotFound error, if any of the YankInstances doesn't exist +# Errors: +# - If any of the YankInstances doesn't exist, DeviceNotFound # # Example: # -# -> { "execute": "yank", -# "arguments": { -# "instances": [ -# { "type": "block-node", -# "node-name": "nbd0" } -# ] } } -# <- { "return": {} } +# -> { "execute": "yank", +# "arguments": { +# "instances": [ +# { "type": "block-node", +# "node-name": "nbd0" } +# ] } } +# <- { "return": {} } # # Since: 6.0 ## @@ -100,17 +100,17 @@ ## # @query-yank: # -# Query yank instances. See @YankInstance for more information. +# Query yank instances. See @YankInstance for more information. # # Returns: list of @YankInstance # # Example: # -# -> { "execute": "query-yank" } -# <- { "return": [ -# { "type": "block-node", -# "node-name": "nbd0" } -# ] } +# -> { "execute": "query-yank" } +# <- { "return": [ +# { "type": "block-node", +# "node-name": "nbd0" } +# ] } # # Since: 6.0 ## |