# -*- Mode: Python -*-
##
-# == QAPI block core definitions (vm unrelated)
+# == Block core (VM unrelated)
##
-# QAPI common definitions
{ 'include': 'common.json' }
+{ 'include': 'crypto.json' }
+{ 'include': 'sockets.json' }
##
# @SnapshotInfo:
#
# @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)
+#
# @type: This field is returned only for compatibility reasons, it should
# not be used (always returns 'unknown')
#
# Since: 0.14.0
##
{ 'struct': 'BlockInfo',
- 'data': {'device': 'str', 'type': 'str', 'removable': 'bool',
+ 'data': {'device': 'str', '*qdev': 'str', 'type': 'str', 'removable': 'bool',
'locked': 'bool', '*inserted': 'BlockDeviceInfo',
'*tray_open': 'bool', '*io-status': 'BlockDeviceIoStatus',
'*dirty-bitmaps': ['BlockDirtyInfo'] } }
#
# Get a list of BlockInfo for all virtual block devices.
#
-# Returns: a list of @BlockInfo describing each virtual block device
+# Returns: a list of @BlockInfo describing each virtual block device. Filter
+# nodes that were created implicitly are skipped over.
#
# Since: 0.14.0
#
# }
# }
# },
+# "qdev": "ide_disk",
# "type":"unknown"
# },
# {
# "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"
# },
# {
# information, but not "backing".
# If false or omitted, the behavior is as before - query all the
# device backends, recursively including their "parent" and
-# "backing". (Since 2.3)
+# "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.
#
# Example:
#
# -> { "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,
'*iops_rd_max_length': 'int', '*iops_wr_max_length': 'int',
'*iops_size': 'int', '*group': 'str' } }
+##
+# @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.
+#
+# @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-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-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.
+# @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-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-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.
+# @iops-size: when limiting by iops max size of an I/O in bytes
+#
+# Since: 2.11
+##
+{ 'struct': 'ThrottleLimits',
+ 'data': { '*iops-total' : 'int', '*iops-total-max' : 'int',
+ '*iops-total-max-length' : 'int', '*iops-read' : 'int',
+ '*iops-read-max' : 'int', '*iops-read-max-length' : 'int',
+ '*iops-write' : 'int', '*iops-write-max' : 'int',
+ '*iops-write-max-length' : 'int', '*bps-total' : 'int',
+ '*bps-total-max' : 'int', '*bps-total-max-length' : 'int',
+ '*bps-read' : 'int', '*bps-read-max' : 'int',
+ '*bps-read-max-length' : 'int', '*bps-write' : 'int',
+ '*bps-write-max' : 'int', '*bps-write-max-length' : 'int',
+ '*iops-size' : 'int' } }
+
##
# @block-stream:
#
# 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
# Drivers that are supported in block device operations.
#
# @vxhs: Since 2.10
+# @throttle: Since 2.11
+# @nvme: Since 2.12
#
# Since: 2.9
##
'data': [ 'blkdebug', 'blkverify', 'bochs', 'cloop',
'dmg', 'file', 'ftp', 'ftps', 'gluster', 'host_cdrom',
'host_device', 'http', 'https', 'iscsi', 'luks', 'nbd', 'nfs',
- 'null-aio', 'null-co', 'parallels', 'qcow', 'qcow2', 'qed',
+ 'null-aio', 'null-co', 'nvme', 'parallels', 'qcow', 'qcow2', 'qed',
'quorum', 'raw', 'rbd', 'replication', 'sheepdog', 'ssh',
- 'vdi', 'vhdx', 'vmdk', 'vpc', 'vvfat', 'vxhs' ] }
+ 'throttle', 'vdi', 'vhdx', 'vmdk', 'vpc', 'vvfat', 'vxhs' ] }
##
# @BlockdevOptionsFile:
# 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)
# @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
##
{ 'struct': 'BlockdevOptionsFile',
'data': { 'filename': 'str',
+ '*pr-manager': 'str',
'*locking': 'OnOffAuto',
'*aio': 'BlockdevAioOptions' } }
{ 'struct': 'BlockdevOptionsNull',
'data': { '*size': 'int', '*latency-ns': 'uint64' } }
+##
+# @BlockdevOptionsNVMe:
+#
+# Driver specific block device options for the NVMe backend.
+#
+# @device: controller address of the NVMe device.
+# @namespace: namespace number of the device, starting from 1.
+#
+# Since: 2.12
+##
+{ 'struct': 'BlockdevOptionsNVMe',
+ 'data': { 'device': 'str', 'namespace': 'int' } }
+
##
# @BlockdevOptionsVVFAT:
#
# besides their data source and an optional backing file.
#
# @backing: reference to or definition of the backing file block
-# device (if missing, taken from the image file content). It is
-# allowed to pass an empty string here in order to disable the
-# default backing file.
+# device, null disables the backing file entirely.
+# Defaults to the backing file stored the image file.
#
# Since: 2.9
##
{ 'struct': 'BlockdevOptionsGenericCOWFormat',
'base': 'BlockdevOptionsGenericFormat',
- 'data': { '*backing': 'BlockdevRef' } }
+ 'data': { '*backing': 'BlockdevRefOrNull' } }
##
# @Qcow2OverlapCheckMode:
#
# Trigger events supported by blkdebug.
#
+# @l1_shrink_write_table: write zeros to the l1 table to shrink image.
+# (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)
+#
# Since: 2.9
##
{ 'enum': 'BlkdebugEvent', 'prefix': 'BLKDBG',
'cluster_alloc_bytes', 'cluster_free', 'flush_to_os',
'flush_to_disk', 'pwritev_rmw_head', 'pwritev_rmw_after_head',
'pwritev_rmw_tail', 'pwritev_rmw_after_tail', 'pwritev',
- 'pwritev_zero', 'pwritev_done', 'empty_image_prepare' ] }
+ 'pwritev_zero', 'pwritev_done', 'empty_image_prepare',
+ 'l1_shrink_write_table', 'l1_shrink_free_l2_clusters',
+ 'cor_write'] }
##
# @BlkdebugInjectErrorOptions:
'*tls-creds': 'str' } }
##
+# @BlockdevOptionsThrottle:
+#
+# Driver specific block device options for the throttle driver
+#
+# @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',
+ 'data': { 'throttle-group': 'str',
+ 'file' : 'BlockdevRef'
+ } }
+##
# @BlockdevOptions:
#
# Options for creating a block device. Many options are available for all
# This option is required on the top level of blockdev-add.
# @discard: discard-related options (default: ignore)
# @cache: cache-related options
-# @read-only: whether the block device should be read-only
-# (default: false)
+# @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.
# @detect-zeroes: detect and optimize zero writes (Since 2.1)
# (default: off)
# @force-share: force share all permission on added nodes.
'nfs': 'BlockdevOptionsNfs',
'null-aio': 'BlockdevOptionsNull',
'null-co': 'BlockdevOptionsNull',
+ 'nvme': 'BlockdevOptionsNVMe',
'parallels': 'BlockdevOptionsGenericFormat',
'qcow2': 'BlockdevOptionsQcow2',
'qcow': 'BlockdevOptionsQcow',
'replication':'BlockdevOptionsReplication',
'sheepdog': 'BlockdevOptionsSheepdog',
'ssh': 'BlockdevOptionsSsh',
+ 'throttle': 'BlockdevOptionsThrottle',
'vdi': 'BlockdevOptionsGenericFormat',
'vhdx': 'BlockdevOptionsGenericFormat',
'vmdk': 'BlockdevOptionsGenericCOWFormat',
# 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.
+# @reference: references the ID of an existing block device
#
# Since: 2.9
##
'data': { 'definition': 'BlockdevOptions',
'reference': 'str' } }
+##
+# @BlockdevRefOrNull:
+#
+# 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.
+# @null: No block device should be referenced (since 2.10)
+#
+# Since: 2.9
+##
+{ 'alternate': 'BlockdevRefOrNull',
+ 'data': { 'definition': 'BlockdevOptions',
+ 'reference': 'str',
+ 'null': 'null' } }
+
##
# @blockdev-add:
#
'*id': 'str' } }
##
-# @x-blockdev-remove-medium:
+# @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
#
# If the tray is open and there is no medium inserted, this will be a no-op.
#
-# @device: Block device name (deprecated, use @id instead)
-#
-# @id: The name or QOM path of the guest device (since: 2.8)
-#
-# Note: This command is still a work in progress and is considered experimental.
-# Stay away from it unless you want to help with its development.
+# @id: The name or QOM path of the guest device
#
-# Since: 2.5
+# Since: 2.12
#
# Example:
#
-# -> { "execute": "x-blockdev-remove-medium",
+# -> { "execute": "blockdev-remove-medium",
# "arguments": { "id": "ide0-1-0" } }
#
# <- { "error": { "class": "GenericError",
#
# <- { "return": {} }
#
-# -> { "execute": "x-blockdev-remove-medium",
+# -> { "execute": "blockdev-remove-medium",
# "arguments": { "id": "ide0-1-0" } }
#
# <- { "return": {} }
#
##
-{ 'command': 'x-blockdev-remove-medium',
- 'data': { '*device': 'str',
- '*id': 'str' } }
+{ 'command': 'blockdev-remove-medium',
+ 'data': { 'id': 'str' } }
##
-# @x-blockdev-insert-medium:
+# @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.
#
-# @device: Block device name (deprecated, use @id instead)
-#
-# @id: The name or QOM path of the guest device (since: 2.8)
+# @id: The name or QOM path of the guest device
#
# @node-name: name of a node in the block driver state graph
#
-# Note: This command is still a work in progress and is considered experimental.
-# Stay away from it unless you want to help with its development.
-#
-# Since: 2.5
+# Since: 2.12
#
# Example:
#
# "filename": "fedora.iso" } } }
# <- { "return": {} }
#
-# -> { "execute": "x-blockdev-insert-medium",
+# -> { "execute": "blockdev-insert-medium",
# "arguments": { "id": "ide0-1-0",
# "node-name": "node0" } }
#
# <- { "return": {} }
#
##
-{ 'command': 'x-blockdev-insert-medium',
- 'data': { '*device': 'str',
- '*id': 'str',
+{ 'command': 'blockdev-insert-medium',
+ 'data': { 'id': 'str',
'node-name': 'str'} }
#
# 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, x-blockdev-remove-medium,
-# x-blockdev-insert-medium and blockdev-close-tray).
+# combines blockdev-open-tray, blockdev-remove-medium, blockdev-insert-medium
+# and blockdev-close-tray).
#
# @device: Block device name (deprecated, use @id instead)
#
# 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().
+#
# Warning: The data in a new quorum child MUST be consistent with that of
# the rest of the array.
#
'data' : { 'parent': 'str',
'*child': 'str',
'*node': 'str' } }
+
+##
+# @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.
+#
+# The node must not be attached to a BlockBackend.
+#
+# @node-name: the name of the block driver node
+#
+# @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
+#
+# Note: this command is experimental and intended for test cases that need
+# control over IOThreads only.
+#
+# Since: 2.12
+#
+# Example:
+#
+# 1. Move a node into an IOThread
+# -> { "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": {} }
+#
+##
+{ 'command': 'x-blockdev-set-iothread',
+ 'data' : { 'node-name': 'str',
+ 'iothread': 'StrOrNull',
+ '*force': 'bool' } }