# -*- Mode: Python -*-
+# vim: filetype=python
##
# == Block core (VM unrelated)
#
# @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)
+#
# Since: 1.3
#
##
{ 'struct': 'SnapshotInfo',
'data': { 'id': 'str', 'name': 'str', 'vm-state-size': 'int',
'date-sec': 'int', 'date-nsec': 'int',
- 'vm-clock-sec': 'int', 'vm-clock-nsec': 'int' } }
+ 'vm-clock-sec': 'int', 'vm-clock-nsec': 'int',
+ '*icount': 'int' } }
##
# @ImageInfoSpecificQCow2EncryptionBase:
# 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)
+#
# @lazy-refcounts: on or off; only valid for compat >= 1.1
#
# @corrupt: true if the image has been marked corrupt; only valid for
'compat': 'str',
'*data-file': 'str',
'*data-file-raw': 'bool',
+ '*extended-l2': 'bool',
'*lazy-refcounts': 'bool',
'*corrupt': 'bool',
'refcount-bits': 'int',
#
# Features:
# @deprecated: Member @encryption_key_missing is deprecated. It is
-# always false.
+# always false.
#
# Since: 0.14.0
#
#
# Features:
# @deprecated: Member @status is deprecated. Use @recording and
-# @locked instead.
+# @locked instead.
#
# Since: 1.3
##
# For the example above, @bins may be something like [3, 1, 5, 2],
# and corresponding histogram looks like:
#
-# | 5| *
-# | 4| *
-# | 3| * *
-# | 2| * * *
-# | 1| * * * *
-# | +------------------
-# | 10 50 100
+# ::
+#
+# 5| *
+# 4| *
+# 3| * *
+# 2| * * *
+# 1| * * * *
+# +------------------
+# 10 50 100
#
# Since: 4.0
##
#
# Features:
# @deprecated: Member @dirty-bitmaps is deprecated. Use @inserted
-# member @dirty-bitmaps instead.
+# member @dirty-bitmaps instead.
#
# Since: 0.14.0
##
# 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 bitmap creation, may
-# require additional space and is not covered here.
+# 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.
+# @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.
+# 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)
#
# Since: 2.10
##
{ 'struct': 'BlockMeasureInfo',
- 'data': {'required': 'int', 'fully-allocated': 'int'} }
+ 'data': {'required': 'int', 'fully-allocated': 'int', '*bitmaps': 'int'} }
##
# @query-block:
{ 'command': 'block_resize',
'data': { '*device': 'str',
'*node-name': 'str',
- 'size': 'int' } }
+ 'size': 'int' },
+ 'coroutine': true }
##
# @NewImageMode:
# 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 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
+# image, the base will not be truncated. If you want the base image
+# 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)
#
# accepted
#
# @backing-file: The backing file string to write into the overlay
-# image of 'top'. If 'top' is the active layer,
-# specifying a backing file string is an error. This
-# filename is not validated.
+# 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.
#
-# 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.
+# 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
# filename or protocol.
# (Since 2.1)
#
-# If top == base, that is an error.
-# If top == active, the job will not be completed by itself,
-# 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 image, the base will not be
-# truncated. If you want the base image size to match the
-# size of the smaller top, you can safely truncate it
-# yourself once the commit operation successfully completes.
-#
# @speed: the maximum speed, in bytes per second
#
# @on-error: the action to take on an error. 'ignore' means that the request
#
# 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
#
# @block-backend: corresponds to BlockBackend
#
-# @block-job: corresonds to BlockJob
+# @block-job: corresponds to BlockJob
#
# @block-driver: corresponds to BlockDriverState
#
#
# Since: 4.0
##
- { 'enum': 'BlockPermission',
- 'data': [ 'consistent-read', 'write', 'write-unchanged', 'resize',
- 'graph-mod' ] }
+{ 'enum': 'BlockPermission',
+ 'data': [ 'consistent-read', 'write', 'write-unchanged', 'resize',
+ 'graph-mod' ] }
##
# @XDbgBlockGraphEdge:
#
#
# @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. (Since 2.1)
+# 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'.
# @target: name of the destination dirty bitmap
#
# @bitmaps: name(s) of the source dirty bitmap(s) at @node and/or fully
-# specifed BlockDirtyBitmap elements. The latter are supported
+# specified BlockDirtyBitmap elements. The latter are supported
# since 4.1.
#
# Since: 4.0
# <- { "return": {} }
#
##
- { 'command': 'block-dirty-bitmap-enable',
- 'data': 'BlockDirtyBitmap' }
+{ 'command': 'block-dirty-bitmap-enable',
+ 'data': 'BlockDirtyBitmap' }
##
# @block-dirty-bitmap-disable:
# <- { "return": {} }
#
##
- { 'command': 'block-dirty-bitmap-disable',
- 'data': 'BlockDirtyBitmap' }
+{ 'command': 'block-dirty-bitmap-disable',
+ 'data': 'BlockDirtyBitmap' }
##
# @block-dirty-bitmap-merge:
# <- { "return": {} }
#
##
- { 'command': 'block-dirty-bitmap-merge',
- 'data': 'BlockDirtyBitmapMerge' }
+{ 'command': 'block-dirty-bitmap-merge',
+ 'data': 'BlockDirtyBitmapMerge' }
##
# @BlockDirtyBitmapSha256:
#
# Since: 2.10
##
- { 'struct': 'BlockDirtyBitmapSha256',
- 'data': {'sha256': 'str'} }
+{ 'struct': 'BlockDirtyBitmapSha256',
+ 'data': {'sha256': 'str'} }
##
# @x-debug-block-dirty-bitmap-sha256:
#
# Since: 2.10
##
- { 'command': 'x-debug-block-dirty-bitmap-sha256',
- 'data': 'BlockDirtyBitmap', 'returns': 'BlockDirtyBitmapSha256' }
+{ 'command': 'x-debug-block-dirty-bitmap-sha256',
+ 'data': 'BlockDirtyBitmap', 'returns': 'BlockDirtyBitmapSha256' }
##
# @blockdev-mirror:
#
# @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.
+# broken Quorum files. By default, @device is replaced, although
+# implicitly created filters on it are kept.
#
# @speed: the maximum speed, in bytes per second
#
# of 'device'.
#
# If a base file is specified then sectors are not copied from that base file and
-# its backing chain. When streaming completes the image file will have the base
-# file as its backing file. This can be used to stream a subset of the backing
-# file chain instead of flattening the entire image.
+# 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)
#
#
# Drivers that are supported in block device operations.
#
-# @vxhs: Since 2.10
# @throttle: Since 2.11
# @nvme: Since 2.12
# @copy-on-read: Since 3.0
'qcow', 'qcow2', 'qed', 'quorum', 'raw', 'rbd',
{ 'name': 'replication', 'if': 'defined(CONFIG_REPLICATION)' },
'sheepdog',
- 'ssh', 'throttle', 'vdi', 'vhdx', 'vmdk', 'vpc', 'vvfat', 'vxhs' ] }
+ 'ssh', 'throttle', 'vdi', 'vhdx', 'vmdk', 'vpc', 'vvfat' ] }
##
# @BlockdevOptionsFile:
'base': 'BlockdevOptionsGenericFormat',
'data': { '*offset': 'int', '*size': 'int' } }
-##
-# @BlockdevOptionsVxHS:
-#
-# Driver specific block device options for VxHS
-#
-# @vdisk-id: UUID of VxHS volume
-# @server: vxhs server IP, port
-# @tls-creds: TLS credentials ID
-#
-# Since: 2.10
-##
-{ 'struct': 'BlockdevOptionsVxHS',
- 'data': { 'vdisk-id': 'str',
- 'server': 'InetSocketAddressBase',
- '*tls-creds': 'str' } }
-
##
# @BlockdevOptionsThrottle:
#
'vhdx': 'BlockdevOptionsGenericFormat',
'vmdk': 'BlockdevOptionsGenericCOWFormat',
'vpc': 'BlockdevOptionsGenericFormat',
- 'vvfat': 'BlockdevOptionsVVFAT',
- 'vxhs': 'BlockdevOptionsVxHS'
+ 'vvfat': 'BlockdevOptionsVVFAT'
} }
##
##
# @blockdev-add:
#
-# Creates a new block device. If the @id option is given at the top level, a
-# BlockBackend will be created; otherwise, @node-name is mandatory at the top
-# level and no BlockBackend will be created.
+# Creates a new block device.
#
# Since: 2.9
#
# falloc (if defined CONFIG_POSIX_FALLOCATE),
# full (if defined 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)
#
# Since: 2.12
##
{ 'struct': 'BlockdevCreateOptionsFile',
- 'data': { 'filename': 'str',
- 'size': 'size',
- '*preallocation': 'PreallocMode',
- '*nocow': 'bool' } }
+ 'data': { 'filename': 'str',
+ 'size': 'size',
+ '*preallocation': 'PreallocMode',
+ '*nocow': 'bool',
+ '*extent-size-hint': 'size'} }
##
# @BlockdevCreateOptionsGluster:
# @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)
+# @extended-l2: True to make the image have extended L2 entries
+# (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
'data': { 'file': 'BlockdevRef',
'*data-file': 'BlockdevRef',
'*data-file-raw': 'bool',
+ '*extended-l2': 'bool',
'size': 'size',
'*version': 'BlockdevQcow2Version',
'*backing-file': 'str',
'data': { 'job-id': 'str',
'options': 'BlockdevCreateOptions' } }
+##
+# @BlockdevAmendOptionsLUKS:
+#
+# Driver specific image amend options for LUKS.
+#
+# Since: 5.1
+##
+{ 'struct': 'BlockdevAmendOptionsLUKS',
+ 'base': 'QCryptoBlockAmendOptionsLUKS',
+ 'data': { }
+}
+
+##
+# @BlockdevAmendOptionsQcow2:
+#
+# Driver specific image amend options for qcow2.
+# For now, only encryption options can be amended
+#
+# @encrypt Encryption options to be amended
+#
+# Since: 5.1
+##
+{ 'struct': 'BlockdevAmendOptionsQcow2',
+ 'data': { '*encrypt': 'QCryptoBlockAmendOptions' } }
+
+##
+# @BlockdevAmendOptions:
+#
+# Options for amending an image format
+#
+# @driver: Block driver of the node to amend.
+#
+# Since: 5.1
+##
+{ 'union': 'BlockdevAmendOptions',
+ 'base': {
+ 'driver': 'BlockdevDriver' },
+ 'discriminator': 'driver',
+ 'data': {
+ 'luks': 'BlockdevAmendOptionsLUKS',
+ 'qcow2': 'BlockdevAmendOptionsQcow2' } }
+
+##
+# @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.
+#
+# @job-id: Identifier for the newly created job.
+#
+# @node-name: Name of the block node to work on
+#
+# @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)
+#
+# Since: 5.1
+##
+{ 'command': 'x-blockdev-amend',
+ 'data': { 'job-id': 'str',
+ 'node-name': 'str',
+ 'options': 'BlockdevAmendOptions',
+ '*force': 'bool' } }
+
##
# @BlockErrorAction:
#
'iothread': 'StrOrNull',
'*force': 'bool' } }
-##
-# @NbdServerOptions:
-#
-# @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).
-#
-# Keep this type consistent with the nbd-server-start arguments. The only
-# intended difference is using SocketAddress instead of SocketAddressLegacy.
-#
-# Since: 4.2
-##
-{ 'struct': 'NbdServerOptions',
- 'data': { 'addr': 'SocketAddress',
- '*tls-creds': 'str',
- '*tls-authz': 'str'} }
-
-##
-# @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".
-#
-# @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).
-#
-# Returns: error if the server is already running.
-#
-# Keep this type consistent with the NbdServerOptions type. The only intended
-# difference is using SocketAddressLegacy instead of SocketAddress.
-#
-# Since: 1.3.0
-##
-{ 'command': 'nbd-server-start',
- 'data': { 'addr': 'SocketAddressLegacy',
- '*tls-creds': 'str',
- '*tls-authz': 'str'} }
-
-##
-# @BlockExportNbd:
-#
-# An NBD block export.
-#
-# @device: The device name or node name of the node to be exported
-#
-# @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)
-#
-# @writable: Whether clients should be able to write to the device via the
-# NBD connection (default false).
-#
-# @bitmap: Also export the dirty bitmap reachable from @device, so the
-# NBD client can use NBD_OPT_SET_META_CONTEXT with
-# "qemu:dirty-bitmap:NAME" to inspect the bitmap. (since 4.0)
-#
-# Since: 5.0
-##
-{ 'struct': 'BlockExportNbd',
- 'data': {'device': 'str', '*name': 'str', '*description': 'str',
- '*writable': 'bool', '*bitmap': 'str' } }
-
-##
-# @nbd-server-add:
-#
-# Export a block node to QEMU's embedded NBD server.
-#
-# Returns: error if the server is not running, or export with the same name
-# already exists.
-#
-# Since: 1.3.0
-##
-{ 'command': 'nbd-server-add',
- 'data': 'BlockExportNbd', 'boxed': true }
-
-##
-# @NbdServerRemoveMode:
-#
-# Mode for removing an NBD export.
-#
-# @safe: Remove export if there are no existing connections, fail otherwise.
-#
-# @hard: Drop all connections immediately and remove export.
-#
-# Potential additional modes to be added in the future:
-#
-# hide: Just hide export from new clients, leave existing connections as is.
-# Remove export after all clients are disconnected.
-#
-# soft: Hide export from new clients, answer with ESHUTDOWN for all further
-# requests from existing clients.
-#
-# Since: 2.12
-##
-{'enum': 'NbdServerRemoveMode', 'data': ['safe', 'hard']}
-
-##
-# @nbd-server-remove:
-#
-# Remove NBD export by name.
-#
-# @name: Export name.
-#
-# @mode: Mode of command operation. See @NbdServerRemoveMode description.
-# Default is 'safe'.
-#
-# Returns: error if
-# - the server is not running
-# - export is not found
-# - mode is 'safe' and there are existing connections
-#
-# Since: 2.12
-##
-{ 'command': 'nbd-server-remove',
- 'data': {'name': 'str', '*mode': 'NbdServerRemoveMode'} }
-
-##
-# @nbd-server-stop:
-#
-# Stop QEMU's embedded NBD server, and unregister all devices previously
-# added via @nbd-server-add.
-#
-# Since: 1.3.0
-##
-{ 'command': 'nbd-server-stop' }
-
-##
-# @BlockExportType:
-#
-# An enumeration of block export types
-#
-# @nbd: NBD export
-#
-# Since: 4.2
-##
-{ 'enum': 'BlockExportType',
- 'data': [ 'nbd' ] }
-
-##
-# @BlockExport:
-#
-# Describes a block export, i.e. how single node should be exported on an
-# external interface.
-#
-# Since: 4.2
-##
-{ 'union': 'BlockExport',
- 'base': { 'type': 'BlockExportType' },
- 'discriminator': 'type',
- 'data': {
- 'nbd': 'BlockExportNbd'
- } }
-
##
# @QuorumOpType:
#
# "date-sec": 1000012,
# "date-nsec": 10,
# "vm-clock-sec": 100,
-# "vm-clock-nsec": 20
+# "vm-clock-nsec": 20,
+# "icount": 220414
# }
# }
#