#
# @compat: compatibility level
#
-# @lazy-refcounts: #optional on or off; only valid for compat >= 1.1
+# @lazy-refcounts: on or off; only valid for compat >= 1.1
#
-# @corrupt: #optional true if the image has been marked corrupt; only valid for
+# @corrupt: true if the image has been marked corrupt; only valid for
# compat >= 1.1 (since 2.2)
#
# @refcount-bits: width of a refcount entry in bits (since 2.3)
#
# @virtual-size: maximum capacity in bytes of the image
#
-# @actual-size: #optional actual size on disk in bytes of the image
+# @actual-size: actual size on disk in bytes of the image
#
-# @dirty-flag: #optional true if image is not cleanly closed
+# @dirty-flag: true if image is not cleanly closed
#
-# @cluster-size: #optional size of a cluster in bytes
+# @cluster-size: size of a cluster in bytes
#
-# @encrypted: #optional true if the image is encrypted
+# @encrypted: true if the image is encrypted
#
-# @compressed: #optional true if the image is compressed (Since 1.7)
+# @compressed: true if the image is compressed (Since 1.7)
#
-# @backing-filename: #optional name of the backing file
+# @backing-filename: name of the backing file
#
-# @full-backing-filename: #optional full path of the backing file
+# @full-backing-filename: full path of the backing file
#
-# @backing-filename-format: #optional the format of the backing file
+# @backing-filename-format: the format of the backing file
#
-# @snapshots: #optional list of VM snapshots
+# @snapshots: list of VM snapshots
#
-# @backing-image: #optional info of the backing image (since 1.6)
+# @backing-image: info of the backing image (since 1.6)
#
-# @format-specific: #optional structure supplying additional format-specific
+# @format-specific: structure supplying additional format-specific
# information (since 1.7)
#
# Since: 1.3
#
# @check-errors: number of unexpected errors occurred during check
#
-# @image-end-offset: #optional offset (in bytes) where the image ends, this
+# @image-end-offset: offset (in bytes) where the image ends, this
# field is present if the driver for the image format
# supports it
#
-# @corruptions: #optional number of corruptions found during the check if any
+# @corruptions: number of corruptions found during the check if any
#
-# @leaks: #optional number of leaks found during the check if any
+# @leaks: number of leaks found during the check if any
#
-# @corruptions-fixed: #optional number of corruptions fixed during the check
+# @corruptions-fixed: number of corruptions fixed during the check
# if any
#
-# @leaks-fixed: #optional number of leaks fixed during the check if any
+# @leaks-fixed: number of leaks fixed during the check if any
#
-# @total-clusters: #optional total number of clusters, this field is present
+# @total-clusters: total number of clusters, this field is present
# if the driver for the image format supports it
#
-# @allocated-clusters: #optional total number of allocated clusters, this
+# @allocated-clusters: total number of allocated clusters, this
# field is present if the driver for the image format
# supports it
#
-# @fragmented-clusters: #optional total number of fragmented clusters, this
+# @fragmented-clusters: total number of fragmented clusters, this
# field is present if the driver for the image format
# supports it
#
-# @compressed-clusters: #optional total number of compressed clusters, this
+# @compressed-clusters: total number of compressed clusters, this
# field is present if the driver for the image format
# supports it
#
#
# @depth: the depth of the mapping
#
-# @offset: #optional the offset in file that the virtual sectors are mapped to
+# @offset: the offset in file that the virtual sectors are mapped to
#
-# @filename: #optional filename that is referred to by @offset
+# @filename: filename that is referred to by @offset
#
# Since: 2.6
#
#
# @file: the filename of the backing device
#
-# @node-name: #optional the name of the block driver node (Since 2.0)
+# @node-name: the name of the block driver node (Since 2.0)
#
# @ro: true if the backing device was open read-only
#
# 2.5: 'host_floppy' dropped
# 2.6: 'luks' added
# 2.8: 'replication' added, 'tftp' dropped
+# 2.9: 'archipelago' dropped
#
-# @backing_file: #optional the name of the backing file (for copy-on-write)
+# @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)
#
#
# @image: the info of image used (since: 1.6)
#
-# @bps_max: #optional total throughput limit during bursts,
+# @bps_max: total throughput limit during bursts,
# in bytes (Since 1.7)
#
-# @bps_rd_max: #optional read throughput limit during bursts,
+# @bps_rd_max: read throughput limit during bursts,
# in bytes (Since 1.7)
#
-# @bps_wr_max: #optional write throughput limit during bursts,
+# @bps_wr_max: write throughput limit during bursts,
# in bytes (Since 1.7)
#
-# @iops_max: #optional total I/O operations per second during bursts,
+# @iops_max: total I/O operations per second during bursts,
# in bytes (Since 1.7)
#
-# @iops_rd_max: #optional read I/O operations per second during bursts,
+# @iops_rd_max: read I/O operations per second during bursts,
# in bytes (Since 1.7)
#
-# @iops_wr_max: #optional write I/O operations per second during bursts,
+# @iops_wr_max: write I/O operations per second during bursts,
# in bytes (Since 1.7)
#
-# @bps_max_length: #optional maximum length of the @bps_max burst
+# @bps_max_length: maximum length of the @bps_max burst
# period, in seconds. (Since 2.6)
#
-# @bps_rd_max_length: #optional maximum length of the @bps_rd_max
+# @bps_rd_max_length: maximum length of the @bps_rd_max
# burst period, in seconds. (Since 2.6)
#
-# @bps_wr_max_length: #optional maximum length of the @bps_wr_max
+# @bps_wr_max_length: maximum length of the @bps_wr_max
# burst period, in seconds. (Since 2.6)
#
-# @iops_max_length: #optional maximum length of the @iops burst
+# @iops_max_length: maximum length of the @iops burst
# period, in seconds. (Since 2.6)
#
-# @iops_rd_max_length: #optional maximum length of the @iops_rd_max
+# @iops_rd_max_length: maximum length of the @iops_rd_max
# burst period, in seconds. (Since 2.6)
#
-# @iops_wr_max_length: #optional maximum length of the @iops_wr_max
+# @iops_wr_max_length: maximum length of the @iops_wr_max
# burst period, in seconds. (Since 2.6)
#
-# @iops_size: #optional an I/O size in bytes (Since 1.7)
+# @iops_size: an I/O size in bytes (Since 1.7)
#
-# @group: #optional throttle group name (Since 2.4)
+# @group: throttle group name (Since 2.4)
#
# @cache: the cache mode used for the block device (since: 2.3)
#
#
# Block dirty bitmap information.
#
-# @name: #optional the name of the dirty bitmap (Since 2.4)
+# @name: the name of the dirty bitmap (Since 2.4)
#
# @count: number of dirty bytes according to the dirty bitmap
#
# @locked: True if the guest has locked this device from having its media
# removed
#
-# @tray_open: #optional True if the device's tray is open
+# @tray_open: True if the device's tray is open
# (only present if it has a tray)
#
-# @dirty-bitmaps: #optional dirty bitmaps information (only present if the
+# @dirty-bitmaps: dirty bitmaps information (only present if the
# driver has one or more dirty bitmaps) (Since 2.0)
#
-# @io-status: #optional @BlockDeviceIoStatus. Only present if the device
+# @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-disk)
#
-# @inserted: #optional @BlockDeviceInfo describing the device if media is
+# @inserted: @BlockDeviceInfo describing the device if media is
# present
#
# Since: 0.14.0
#
# 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
#
# @wr_merged: Number of write requests that have been merged into another
# request (Since 2.3).
#
-# @idle_time_ns: #optional Time since the last I/O operation, in
+# @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).
#
#
# Statistics of a virtual block device or a block backing device.
#
-# @device: #optional If the stats are for a virtual block device, the name
+# @device: If the stats are for a virtual block device, the name
# corresponding to the virtual block device.
#
-# @node-name: #optional The node name of the device. (Since 2.3)
+# @node-name: The node name of the device. (Since 2.3)
#
# @stats: A @BlockDeviceStats for the device.
#
-# @parent: #optional This describes the file block device if it has one.
+# @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
#
-# @backing: #optional This describes the backing block device if it has one.
+# @backing: This describes the backing block device if it has one.
# (Since 2.0)
#
# Since: 0.14.0
#
# Query the @BlockStats for all virtual block devices.
#
-# @query-nodes: #optional If true, the command will query all the block nodes
+# @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". (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.
#
#
# Either @device or @node-name must be set but not both.
#
-# @device: #optional the name of the block backend device to set the password on
+# @device: the name of the block backend device to set the password on
#
-# @node-name: #optional graph node name to set the password on (Since 2.0)
+# @node-name: graph node name to set the password on (Since 2.0)
#
# @password: the password to use for the device
#
#
# Either @device or @node-name must be set but not both.
#
-# @device: #optional the name of the device to get the image resized
+# @device: the name of the device to get the image resized
#
-# @node-name: #optional graph node name to get the image resized (Since 2.0)
+# @node-name: graph node name to get the image resized (Since 2.0)
#
# @size: new image size in bytes
#
#
# Either @device or @node-name must be set but not both.
#
-# @device: #optional the name of the device to generate the snapshot from.
+# @device: the name of the device to generate the snapshot from.
#
-# @node-name: #optional 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 image. If the file exists, or
# if it is a device, the snapshot will be created in the existing
# file/device. Otherwise, a new file will be created.
#
-# @snapshot-node-name: #optional 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: #optional the format of the snapshot image, default is 'qcow2'.
+# @format: the format of the snapshot image, default is 'qcow2'.
#
-# @mode: #optional whether and how QEMU should create a new image, default is
+# @mode: whether and how QEMU should create a new image, default is
# 'absolute-paths'.
##
{ 'struct': 'BlockdevSnapshotSync',
##
# @DriveBackup:
#
-# @job-id: #optional identifier for the newly-created block job. If
+# @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.
# 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: #optional the format of the new destination, default is to
+# @format: the format of the new destination, default is to
# probe if @mode is 'existing', else the format of the source
#
# @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).
#
-# @mode: #optional whether and how QEMU should create a new image, default is
+# @mode: whether and how QEMU should create a new image, default is
# 'absolute-paths'.
#
-# @speed: #optional the maximum speed, in bytes per second
+# @speed: the maximum speed, in bytes per second
#
-# @bitmap: #optional the name of dirty bitmap if sync is "incremental".
+# @bitmap: the name of dirty bitmap if sync is "incremental".
# Must be present if sync is "incremental", must NOT be present
# otherwise. (Since 2.4)
#
-# @compress: #optional true to compress data, if the target format supports it.
+# @compress: true to compress data, if the target format supports it.
# (default: false) (since 2.8)
#
-# @on-source-error: #optional the action to take on an error on the source,
+# @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).
#
-# @on-target-error: #optional the action to take on an error on the target,
+# @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).
#
##
# @BlockdevBackup:
#
-# @job-id: #optional identifier for the newly-created block job. If
+# @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.
# (all the disk, only the sectors allocated in the topmost image, or
# only new I/O).
#
-# @speed: #optional the maximum speed, in bytes per second. The default is 0,
+# @speed: the maximum speed, in bytes per second. The default is 0,
# for unlimited.
#
-# @compress: #optional true to compress data, if the target format supports it.
+# @compress: true to compress data, if the target format supports it.
# (default: false) (since 2.8)
#
-# @on-source-error: #optional the action to take on an error on the source,
+# @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).
#
-# @on-target-error: #optional the action to take on an error on the target,
+# @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).
#
# Live commit of data from overlay image nodes into backing nodes - i.e.,
# writes data between 'top' and 'base' into 'base'.
#
-# @job-id: #optional identifier for the newly-created block job. If
+# @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: #optional The file name of the backing image to write data into.
+# @base: The file name of the backing image to write data into.
# If not specified, this is the deepest backing image.
#
-# @top: #optional The file name of the backing image within the image chain,
+# @top: The file 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.
#
-# @backing-file: #optional The backing file string to write into the overlay
+# @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.
# size of the smaller top, you can safely truncate it
# yourself once the commit operation successfully completes.
#
-# @speed: #optional the maximum speed, in bytes per second
+# @speed: the maximum speed, in bytes per second
+#
+# @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)
#
# Returns: Nothing on success
# If commit or stream is already active on this device, DeviceInUse
##
{ 'command': 'block-commit',
'data': { '*job-id': 'str', 'device': 'str', '*base': 'str', '*top': 'str',
- '*backing-file': 'str', '*speed': 'int' } }
+ '*backing-file': 'str', '*speed': 'int',
+ '*filter-node-name': 'str' } }
##
# @drive-backup:
# The operation can be stopped before it has completed using the
# block-job-cancel command.
#
-# For the arguments, see the documentation of DriveBackup.
-#
# Returns: nothing on success
# If @device is not a valid block device, GenericError
#
# The operation can be stopped before it has completed using the
# block-job-cancel command.
#
-# For the arguments, see the documentation of BlockdevBackup.
-#
# Returns: nothing on success
# If @device is not a valid block device, DeviceNotFound
#
# format of the mirror image, default is to probe if mode='existing',
# else the format of the source.
#
-# See DriveMirror for parameter descriptions
-#
# Returns: nothing on success
# If @device is not a valid block device, GenericError
#
#
# A set of parameters describing drive mirror setup.
#
-# @job-id: #optional identifier for the newly-created block job. If
+# @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
# 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: #optional the format of the new destination, default is to
+# @format: the format of the new destination, default is to
# probe if @mode is 'existing', else the format of the source
#
-# @node-name: #optional the new block driver state node name in the graph
+# @node-name: the new block driver state node name in the graph
# (Since 2.1)
#
-# @replaces: #optional with sync=full graph node name to be replaced by the new
+# @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)
#
-# @mode: #optional whether and how QEMU should create a new image, default is
+# @mode: whether and how QEMU should create a new image, default is
# 'absolute-paths'.
#
-# @speed: #optional 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).
#
-# @granularity: #optional granularity of the dirty bitmap, default is 64K
+# @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: #optional maximum amount of data in flight from source to
+# @buf-size: maximum amount of data in flight from source to
# target (since 1.4).
#
-# @on-source-error: #optional the action to take on an error on the source,
+# @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).
#
-# @on-target-error: #optional the action to take on an error on the target,
+# @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: #optional Whether to try to unmap target sectors where source has
+# @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.
#
# @name: name of the dirty bitmap
#
-# @granularity: #optional the bitmap granularity, default is 64k for
+# @granularity: the bitmap granularity, default is 64k for
# block-dirty-bitmap-add
#
# Since: 2.4
#
# Start mirroring a block device's writes to a new destination.
#
-# @job-id: #optional identifier for the newly-created block job. If
+# @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
# @target: the id or node-name of the block device to mirror to. This mustn't be
# attached to guest.
#
-# @replaces: #optional with sync=full graph node name to be replaced by the new
+# @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.
#
-# @speed: #optional 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).
#
-# @granularity: #optional granularity of the dirty bitmap, default is 64K
+# @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: #optional maximum amount of data in flight from source to
+# @buf-size: maximum amount of data in flight from source to
# target
#
-# @on-source-error: #optional the action to take on an error on the source,
+# @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).
#
-# @on-target-error: #optional the action to take on an error on the target,
+# @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).
#
+# @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)
+#
# Returns: nothing on success.
#
# Since: 2.6
+#
+# Example:
+#
+# -> { "execute": "blockdev-mirror",
+# "arguments": { "device": "ide-hd0",
+# "target": "target0",
+# "sync": "full" } }
+# <- { "return": {} }
+#
##
{ 'command': 'blockdev-mirror',
'data': { '*job-id': 'str', 'device': 'str', 'target': 'str',
'sync': 'MirrorSyncMode',
'*speed': 'int', '*granularity': 'uint32',
'*buf-size': 'int', '*on-source-error': 'BlockdevOnError',
- '*on-target-error': 'BlockdevOnError' } }
+ '*on-target-error': 'BlockdevOnError',
+ '*filter-node-name': 'str' } }
##
# @block_set_io_throttle:
# the device will be removed from its group and the rest of its
# members will not be affected. The 'group' parameter is ignored.
#
-# See BlockIOThrottle for parameter descriptions.
-#
# Returns: Nothing on success
# If @device is not a valid block device, DeviceNotFound
#
#
# A set of parameters describing block throttling.
#
-# @device: #optional Block device name (deprecated, use @id instead)
+# @device: Block device name (deprecated, use @id instead)
#
-# @id: #optional 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)
#
# @bps: total throughput limit in bytes per second
#
#
# @iops_wr: write I/O operations per second
#
-# @bps_max: #optional total throughput limit during bursts,
+# @bps_max: total throughput limit during bursts,
# in bytes (Since 1.7)
#
-# @bps_rd_max: #optional read throughput limit during bursts,
+# @bps_rd_max: read throughput limit during bursts,
# in bytes (Since 1.7)
#
-# @bps_wr_max: #optional write throughput limit during bursts,
+# @bps_wr_max: write throughput limit during bursts,
# in bytes (Since 1.7)
#
-# @iops_max: #optional total I/O operations per second during bursts,
+# @iops_max: total I/O operations per second during bursts,
# in bytes (Since 1.7)
#
-# @iops_rd_max: #optional read I/O operations per second during bursts,
+# @iops_rd_max: read I/O operations per second during bursts,
# in bytes (Since 1.7)
#
-# @iops_wr_max: #optional write I/O operations per second during bursts,
+# @iops_wr_max: write I/O operations per second during bursts,
# in bytes (Since 1.7)
#
-# @bps_max_length: #optional maximum length of the @bps_max burst
+# @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: #optional maximum length of the @bps_rd_max
+# @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: #optional maximum length of the @bps_wr_max
+# @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: #optional maximum length of the @iops burst
+# @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: #optional maximum length of the @iops_rd_max
+# @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: #optional maximum length of the @iops_wr_max
+# @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: #optional an I/O size in bytes (Since 1.7)
+# @iops_size: an I/O size in bytes (Since 1.7)
#
-# @group: #optional throttle group name (Since 2.4)
+# @group: throttle group name (Since 2.4)
#
# Since: 1.1
##
# On successful completion the image file is updated to drop the backing file
# and the BLOCK_JOB_COMPLETED event is emitted.
#
-# @job-id: #optional identifier for the newly-created block job. If
+# @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: #optional the common backing file name.
+# @base: the common backing file name.
# It cannot be set if @base-node is also set.
#
-# @base-node: #optional the node name of the backing file.
+# @base-node: the node name of the backing file.
# It cannot be set if @base is also set. (Since 2.8)
#
-# @backing-file: #optional The backing file string to write into the top
+# @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
# protocol.
# (Since 2.1)
#
-# @speed: #optional the maximum speed, in bytes per second
+# @speed: the maximum speed, in bytes per second
#
-# @on-error: #optional the action to take on an error (default report).
+# @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.
#
# the name of the parameter), but since QEMU 2.7 it can have
# other values.
#
-# @force: #optional whether to allow cancellation of a paused job (default
+# @force: whether to allow cancellation of a paused job (default
# false). Since 1.3.
#
# Returns: Nothing on success
# @ignore: Ignore the request
# @unmap: Forward as an unmap request
#
-# Since: 1.7
+# Since: 2.9
##
{ 'enum': 'BlockdevDiscardOptions',
'data': [ 'ignore', 'unmap' ] }
# @threads: Use qemu's thread pool
# @native: Use native AIO backend (only Linux and Windows)
#
-# Since: 1.7
+# Since: 2.9
##
{ 'enum': 'BlockdevAioOptions',
'data': [ 'threads', 'native' ] }
#
# Includes cache-related options for block devices
#
-# @direct: #optional enables use of O_DIRECT (bypass the host page cache;
+# @direct: enables use of O_DIRECT (bypass the host page cache;
# default: false)
-# @no-flush: #optional ignore any flush requests for the device (default:
+# @no-flush: ignore any flush requests for the device (default:
# false)
#
-# Since: 1.7
+# Since: 2.9
##
{ 'struct': 'BlockdevCacheOptions',
'data': { '*direct': 'bool',
#
# Drivers that are supported in block device operations.
#
-# @host_device: Since 2.1
-# @host_cdrom: Since 2.1
-# @gluster: Since 2.7
-# @nbd: Since 2.8
-# @nfs: Since 2.8
-# @replication: Since 2.8
-# @ssh: Since 2.8
-#
-# Since: 2.0
+# Since: 2.9
##
{ 'enum': 'BlockdevDriver',
- 'data': [ 'archipelago', 'blkdebug', 'blkverify', 'bochs', 'cloop',
+ 'data': [ 'blkdebug', 'blkverify', 'bochs', 'cloop',
'dmg', 'file', 'ftp', 'ftps', 'gluster', 'host_cdrom',
- 'host_device', 'http', 'https', 'luks', 'nbd', 'nfs', 'null-aio',
- 'null-co', 'parallels', 'qcow', 'qcow2', 'qed', 'quorum', 'raw',
- 'replication', 'ssh', 'vdi', 'vhdx', 'vmdk', 'vpc',
- 'vvfat' ] }
+ 'host_device', 'http', 'https', 'iscsi', 'luks', 'nbd', 'nfs',
+ 'null-aio', 'null-co', 'parallels', 'qcow', 'qcow2', 'qed',
+ 'quorum', 'raw', 'rbd', 'replication', 'sheepdog', 'ssh',
+ 'vdi', 'vhdx', 'vmdk', 'vpc', 'vvfat' ] }
##
# @BlockdevOptionsFile:
# Driver specific block device options for the file backend.
#
# @filename: path to the image file
-# @aio: #optional AIO backend (default: threads) (since: 2.8)
+# @aio: AIO backend (default: threads) (since: 2.8)
#
-# Since: 1.7
+# Since: 2.9
##
{ 'struct': 'BlockdevOptionsFile',
'data': { 'filename': 'str',
#
# Driver specific block device options for the null backend.
#
-# @size: #optional size of the device in bytes.
-# @latency-ns: #optional emulated latency (in nanoseconds) in processing
+# @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)
#
-# Since: 2.2
+# Since: 2.9
##
{ 'struct': 'BlockdevOptionsNull',
'data': { '*size': 'int', '*latency-ns': 'uint64' } }
# Driver specific block device options for the vvfat protocol.
#
# @dir: directory to be exported as FAT image
-# @fat-type: #optional FAT type: 12, 16 or 32
-# @floppy: #optional whether to export a floppy image (true) or
+# @fat-type: FAT type: 12, 16 or 32
+# @floppy: whether to export a floppy image (true) or
# partitioned hard disk (false; default)
-# @label: #optional set the volume label, limited to 11 bytes. FAT16 and
+# @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: #optional whether to allow write operations (default: false)
+# @rw: whether to allow write operations (default: false)
#
-# Since: 1.7
+# Since: 2.9
##
{ 'struct': 'BlockdevOptionsVVFAT',
'data': { 'dir': 'str', '*fat-type': 'int', '*floppy': 'bool',
#
# @file: reference to or definition of the data source block device
#
-# Since: 1.7
+# Since: 2.9
##
{ 'struct': 'BlockdevOptionsGenericFormat',
'data': { 'file': 'BlockdevRef' } }
#
# Driver specific block device options for LUKS.
#
-# @key-secret: #optional the ID of a QCryptoSecret object providing
+# @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.
#
-# Since: 2.6
+# Since: 2.9
##
{ 'struct': 'BlockdevOptionsLUKS',
'base': 'BlockdevOptionsGenericFormat',
# Driver specific block device options for image format that have no option
# besides their data source and an optional backing file.
#
-# @backing: #optional reference to or definition of the backing file block
+# @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.
#
-# Since: 1.7
+# Since: 2.9
##
{ 'struct': 'BlockdevOptionsGenericCOWFormat',
'base': 'BlockdevOptionsGenericFormat',
#
# @all: Perform all available overlap checks
#
-# Since: 2.2
+# Since: 2.9
##
{ 'enum': 'Qcow2OverlapCheckMode',
'data': [ 'none', 'constant', 'cached', 'all' ] }
# @template: Specifies a template mode which can be adjusted using the other
# flags, defaults to 'cached'
#
-# Since: 2.2
+# Since: 2.9
##
{ 'struct': 'Qcow2OverlapCheckFlags',
'data': { '*template': 'Qcow2OverlapCheckMode',
#
# @mode: named mode which chooses a specific set of flags
#
-# Since: 2.2
+# Since: 2.9
##
{ 'alternate': 'Qcow2OverlapChecks',
'data': { 'flags': 'Qcow2OverlapCheckFlags',
#
# Driver specific block device options for qcow2.
#
-# @lazy-refcounts: #optional whether to enable the lazy refcounts
+# @lazy-refcounts: whether to enable the lazy refcounts
# feature (default is taken from the image file)
#
-# @pass-discard-request: #optional whether discard requests to the qcow2
+# @pass-discard-request: whether discard requests to the qcow2
# device should be forwarded to the data source
#
-# @pass-discard-snapshot: #optional whether discard requests for 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
#
-# @pass-discard-other: #optional whether discard requests for the data source
+# @pass-discard-other: whether discard requests for the data source
# should be issued on other occasions where a cluster
# gets freed
#
-# @overlap-check: #optional which overlap checks to perform for writes
+# @overlap-check: which overlap checks to perform for writes
# to the image, defaults to 'cached' (since 2.2)
#
-# @cache-size: #optional the maximum total size of the L2 table and
+# @cache-size: the maximum total size of the L2 table and
# refcount block caches in bytes (since 2.2)
#
-# @l2-cache-size: #optional the maximum size of the L2 table cache in
+# @l2-cache-size: the maximum size of the L2 table cache in
# bytes (since 2.2)
#
-# @refcount-cache-size: #optional the maximum size of the refcount block cache
+# @refcount-cache-size: the maximum size of the refcount block cache
# in bytes (since 2.2)
#
-# @cache-clean-interval: #optional clean unused entries in the L2 and refcount
+# @cache-clean-interval: clean unused entries in the L2 and refcount
# caches. The interval is in seconds. The default value
# is 0 and it disables this feature (since 2.5)
#
-# Since: 1.7
+# Since: 2.9
##
{ 'struct': 'BlockdevOptionsQcow2',
'base': 'BlockdevOptionsGenericCOWFormat',
'*cache-clean-interval': 'int' } }
-##
-# @BlockdevOptionsArchipelago:
-#
-# Driver specific block device options for Archipelago.
-#
-# @volume: Name of the Archipelago volume image
-#
-# @mport: #optional The port number on which mapperd is
-# listening. This is optional
-# and if not specified, QEMU will make Archipelago
-# use the default port (1001).
-#
-# @vport: #optional The port number on which vlmcd is
-# listening. This is optional
-# and if not specified, QEMU will make Archipelago
-# use the default port (501).
-#
-# @segment: #optional The name of the shared memory segment
-# Archipelago stack is using. This is optional
-# and if not specified, QEMU will make Archipelago
-# use the default value, 'archipelago'.
-# Since: 2.2
-##
-{ 'struct': 'BlockdevOptionsArchipelago',
- 'data': { 'volume': 'str',
- '*mport': 'int',
- '*vport': 'int',
- '*segment': 'str' } }
-
##
# @BlockdevOptionsSsh:
#
#
# @path: path to the image on the host
#
-# @user: #optional user as which to connect, defaults to current
+# @user: user as which to connect, defaults to current
# local user name
#
# TODO: Expose the host_key_check option in QMP
#
-# Since: 2.8
+# Since: 2.9
##
{ 'struct': 'BlockdevOptionsSsh',
'data': { 'server': 'InetSocketAddress',
#
# Trigger events supported by blkdebug.
#
-# Since: 2.0
+# Since: 2.9
##
{ 'enum': 'BlkdebugEvent', 'prefix': 'BLKDBG',
'data': [ 'l1_update', 'l1_grow_alloc_table', 'l1_grow_write_table',
#
# @event: trigger event
#
-# @state: #optional the state identifier blkdebug needs to be in to
+# @state: the state identifier blkdebug needs to be in to
# actually trigger the event; defaults to "any"
#
-# @errno: #optional error identifier (errno) to be returned; defaults to
+# @errno: error identifier (errno) to be returned; defaults to
# EIO
#
-# @sector: #optional specifies the sector index which has to be affected
+# @sector: specifies the sector index which has to be affected
# in order to actually trigger the event; defaults to "any
# sector"
#
-# @once: #optional disables further events after this one has been
+# @once: disables further events after this one has been
# triggered; defaults to false
#
-# @immediately: #optional fail immediately; defaults to false
+# @immediately: fail immediately; defaults to false
#
-# Since: 2.0
+# Since: 2.9
##
{ 'struct': 'BlkdebugInjectErrorOptions',
'data': { 'event': 'BlkdebugEvent',
#
# @event: trigger event
#
-# @state: #optional the current state identifier blkdebug needs to be in;
+# @state: the current state identifier blkdebug needs to be in;
# defaults to "any"
#
# @new_state: the state identifier blkdebug is supposed to assume if
# this event is triggered
#
-# Since: 2.0
+# Since: 2.9
##
{ 'struct': 'BlkdebugSetStateOptions',
'data': { 'event': 'BlkdebugEvent',
#
# @image: underlying raw block device (or image file)
#
-# @config: #optional filename of the configuration file
+# @config: filename of the configuration file
#
-# @align: #optional required alignment for requests in bytes,
-# must be power of 2, or 0 for default
+# @align: required alignment for requests in bytes, must be
+# positive power of 2, or 0 for default
#
-# @inject-error: #optional array of error injection descriptions
+# @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)
#
-# @set-state: #optional array of state-change descriptions
+# @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)
#
-# Since: 2.0
+# @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)
+#
+# @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)
+#
+# @inject-error: array of error injection descriptions
+#
+# @set-state: array of state-change descriptions
+#
+# Since: 2.9
##
{ 'struct': 'BlockdevOptionsBlkdebug',
'data': { 'image': 'BlockdevRef',
'*config': 'str',
- '*align': 'int',
+ '*align': 'int', '*max-transfer': 'int32',
+ '*opt-write-zero': 'int32', '*max-write-zero': 'int32',
+ '*opt-discard': 'int32', '*max-discard': 'int32',
'*inject-error': ['BlkdebugInjectErrorOptions'],
'*set-state': ['BlkdebugSetStateOptions'] } }
#
# @raw: raw image used for verification
#
-# Since: 2.0
+# Since: 2.9
##
{ 'struct': 'BlockdevOptionsBlkverify',
'data': { 'test': 'BlockdevRef',
#
# @fifo: read only from the first child that has not failed
#
-# Since: 2.2
+# Since: 2.9
##
{ 'enum': 'QuorumReadPattern', 'data': [ 'quorum', 'fifo' ] }
#
# Driver specific block device options for Quorum
#
-# @blkverify: #optional true if the driver must print content mismatch
+# @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: #optional rewrite corrupted data when quorum is reached
+# @rewrite-corrupted: rewrite corrupted data when quorum is reached
# (Since 2.1)
#
-# @read-pattern: #optional choose read pattern and set to quorum by default
+# @read-pattern: choose read pattern and set to quorum by default
# (Since 2.2)
#
-# Since: 2.0
+# Since: 2.9
##
{ 'struct': 'BlockdevOptionsQuorum',
'data': { '*blkverify': 'bool',
'*read-pattern': 'QuorumReadPattern' } }
##
-# @GlusterTransport:
+# @BlockdevOptionsGluster:
#
-# An enumeration of Gluster transport types
+# Driver specific block device options for Gluster
#
-# @tcp: TCP - Transmission Control Protocol
+# @volume: name of gluster volume where VM image resides
#
-# @unix: UNIX - Unix domain socket
+# @path: absolute path to image file in gluster volume
#
-# Since: 2.7
+# @server: gluster servers description
+#
+# @debug: libgfapi log level (default '4' which is Error)
+# (Since 2.8)
+#
+# @logfile: libgfapi log file (default /dev/stderr) (Since 2.8)
+#
+# Since: 2.9
##
-{ 'enum': 'GlusterTransport',
- 'data': [ 'unix', 'tcp' ] }
+{ 'struct': 'BlockdevOptionsGluster',
+ 'data': { 'volume': 'str',
+ 'path': 'str',
+ 'server': ['SocketAddressFlat'],
+ '*debug': 'int',
+ '*logfile': 'str' } }
+##
+# @IscsiTransport:
+#
+# An enumeration of libiscsi transport types
+#
+# Since: 2.9
+##
+{ 'enum': 'IscsiTransport',
+ 'data': [ 'tcp', 'iser' ] }
##
-# @GlusterServer:
+# @IscsiHeaderDigest:
#
-# Captures the address of a socket
+# An enumeration of header digests supported by libiscsi
#
-# Details for connecting to a gluster server
+# Since: 2.9
+##
+{ 'enum': 'IscsiHeaderDigest',
+ 'prefix': 'QAPI_ISCSI_HEADER_DIGEST',
+ 'data': [ 'crc32c', 'none', 'crc32c-none', 'none-crc32c' ] }
+
+##
+# @BlockdevOptionsIscsi:
#
-# @type: Transport type used for gluster connection
+# @transport: The iscsi transport type
#
-# This is similar to SocketAddress, only distinction:
+# @portal: The address of the iscsi portal
#
-# 1. GlusterServer is a flat union, SocketAddress is a simple union.
-# A flat union is nicer than simple because it avoids nesting
-# (i.e. more {}) on the wire.
+# @target: The target iqn name
#
-# 2. GlusterServer lacks case 'fd', since gluster doesn't let you
-# pass in a file descriptor.
+# @lun: LUN to connect to. Defaults to 0.
#
-# GlusterServer is actually not Gluster-specific, its a
-# compatibility evolved into an alternate for SocketAddress.
+# @user: User name to log in with. If omitted, no CHAP
+# authentication is performed.
#
-# Since: 2.7
+# @password-secret: The ID of a QCryptoSecret object providing
+# the password for the login. This option is required if
+# @user is specified.
+#
+# @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.
+#
+# @header-digest: The desired header digest. Defaults to
+# none-crc32c.
+#
+# @timeout: Timeout in seconds after which a request will
+# timeout. 0 means no timeout and is the default.
+#
+# Driver specific block device options for iscsi
+#
+# Since: 2.9
##
-{ 'union': 'GlusterServer',
- 'base': { 'type': 'GlusterTransport' },
- 'discriminator': 'type',
- 'data': { 'unix': 'UnixSocketAddress',
- 'tcp': 'InetSocketAddress' } }
+{ 'struct': 'BlockdevOptionsIscsi',
+ 'data': { 'transport': 'IscsiTransport',
+ 'portal': 'str',
+ 'target': 'str',
+ '*lun': 'int',
+ '*user': 'str',
+ '*password-secret': 'str',
+ '*initiator-name': 'str',
+ '*header-digest': 'IscsiHeaderDigest',
+ '*timeout': 'int' } }
+
##
-# @BlockdevOptionsGluster:
+# @BlockdevOptionsRbd:
#
-# Driver specific block device options for Gluster
+# @pool: Ceph pool name.
#
-# @volume: name of gluster volume where VM image resides
+# @image: Image name in the Ceph pool.
#
-# @path: absolute path to image file in gluster volume
+# @conf: path to Ceph configuration file. Values
+# in the configuration file will be overridden by
+# options specified via QAPI.
#
-# @server: gluster servers description
+# @snapshot: Ceph snapshot name.
#
-# @debug: #optional libgfapi log level (default '4' which is Error)
-# (Since 2.8)
+# @user: Ceph id name.
#
-# @logfile: #optional libgfapi log file (default /dev/stderr) (Since 2.8)
+# @server: Monitor host address and port. This maps
+# to the "mon_host" Ceph option.
#
-# Since: 2.7
+# Since: 2.9
##
-{ 'struct': 'BlockdevOptionsGluster',
- 'data': { 'volume': 'str',
- 'path': 'str',
- 'server': ['GlusterServer'],
- '*debug': 'int',
- '*logfile': 'str' } }
+{ 'struct': 'BlockdevOptionsRbd',
+ 'data': { 'pool': 'str',
+ 'image': 'str',
+ '*conf': 'str',
+ '*snapshot': 'str',
+ '*user': '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': 'SocketAddressFlat',
+ 'vdi': 'str',
+ '*snap-id': 'uint32',
+ '*tag': 'str' } }
##
# @ReplicationMode:
#
# @secondary: Secondary mode, receive the vm's state from primary QEMU.
#
-# Since: 2.8
+# Since: 2.9
##
{ 'enum' : 'ReplicationMode', 'data' : [ 'primary', 'secondary' ] }
#
# @mode: the replication mode
#
-# @top-id: #optional In secondary mode, node name or device ID of the root
+# @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.8
+# Since: 2.9
##
{ 'struct': 'BlockdevOptionsReplication',
'base': 'BlockdevOptionsGenericFormat',
#
# @inet: TCP transport
#
-# Since: 2.8
+# Since: 2.9
##
{ 'enum': 'NFSTransport',
'data': [ 'inet' ] }
#
# @host: host address for NFS server
#
-# Since: 2.8
+# Since: 2.9
##
{ 'struct': 'NFSServer',
'data': { 'type': 'NFSTransport',
#
# @path: path of the image on the host
#
-# @user: #optional UID value to use when talking to the
+# @user: UID value to use when talking to the
# server (defaults to 65534 on Windows and getuid()
# on unix)
#
-# @group: #optional GID value to use when talking to the
+# @group: GID value to use when talking to the
# server (defaults to 65534 on Windows and getgid()
# in unix)
#
-# @tcp-syn-count: #optional number of SYNs during the session
+# @tcp-syn-count: number of SYNs during the session
# establishment (defaults to libnfs default)
#
-# @readahead-size: #optional set the readahead size in bytes (defaults
+# @readahead-size: set the readahead size in bytes (defaults
# to libnfs default)
#
-# @page-cache-size: #optional set the pagecache size in bytes (defaults
+# @page-cache-size: set the pagecache size in bytes (defaults
# to libnfs default)
#
-# @debug: #optional set the NFS debug level (max 2) (defaults
+# @debug: set the NFS debug level (max 2) (defaults
# to libnfs default)
#
-# Since: 2.8
+# Since: 2.9
##
{ 'struct': 'BlockdevOptionsNfs',
'data': { 'server': 'NFSServer',
'*debug': 'int' } }
##
-# @BlockdevOptionsCurl:
+# @BlockdevOptionsCurlBase:
#
-# Driver specific block device options for the curl backend.
+# Driver specific block device options shared by all protocols supported by the
+# curl backend.
#
-# @filename: path to the image file
+# @url: URL of the image file
#
-# Since: 1.7
+# @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)
+#
+# @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)
+#
+# Since: 2.9
+##
+{ 'struct': 'BlockdevOptionsCurlBase',
+ 'data': { 'url': 'str',
+ '*readahead': 'int',
+ '*timeout': 'int',
+ '*username': 'str',
+ '*password-secret': 'str',
+ '*proxy-username': 'str',
+ '*proxy-password-secret': 'str' } }
+
+##
+# @BlockdevOptionsCurlHttp:
+#
+# 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.
+#
+# Since: 2.9
+##
+{ 'struct': 'BlockdevOptionsCurlHttp',
+ 'base': 'BlockdevOptionsCurlBase',
+ 'data': { '*cookie': 'str' } }
+
+##
+# @BlockdevOptionsCurlHttps:
+#
+# 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.
+#
+# @sslverify: Whether to verify the SSL certificate's validity (defaults to
+# true)
+#
+# Since: 2.9
##
-{ 'struct': 'BlockdevOptionsCurl',
- 'data': { 'filename': 'str' } }
+{ 'struct': 'BlockdevOptionsCurlHttps',
+ 'base': 'BlockdevOptionsCurlBase',
+ 'data': { '*cookie': 'str',
+ '*sslverify': 'bool' } }
+
+##
+# @BlockdevOptionsCurlFtp:
+#
+# Driver specific block device options for FTP connections over the curl
+# backend. URLs must start with "ftp://".
+#
+# Since: 2.9
+##
+{ 'struct': 'BlockdevOptionsCurlFtp',
+ 'base': 'BlockdevOptionsCurlBase',
+ 'data': { } }
+
+##
+# @BlockdevOptionsCurlFtps:
+#
+# 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)
+#
+# Since: 2.9
+##
+{ 'struct': 'BlockdevOptionsCurlFtps',
+ 'base': 'BlockdevOptionsCurlBase',
+ 'data': { '*sslverify': 'bool' } }
##
# @BlockdevOptionsNbd:
#
# @server: NBD server address
#
-# @export: #optional export name
+# @export: export name
#
-# @tls-creds: #optional TLS credentials ID
+# @tls-creds: TLS credentials ID
#
-# Since: 2.8
+# Since: 2.9
##
{ 'struct': 'BlockdevOptionsNbd',
- 'data': { 'server': 'SocketAddress',
+ 'data': { 'server': 'SocketAddressFlat',
'*export': 'str',
'*tls-creds': 'str' } }
#
# Driver specific block device options for the raw driver.
#
-# @offset: #optional position where the block device starts
-# @size: #optional the assumed size of the device
+# @offset: position where the block device starts
+# @size: the assumed size of the device
#
-# Since: 2.8
+# Since: 2.9
##
{ 'struct': 'BlockdevOptionsRaw',
'base': 'BlockdevOptionsGenericFormat',
# block devices, independent of the block driver:
#
# @driver: block driver name
-# @node-name: #optional the node name of the new node (Since 2.0).
+# @node-name: the node name of the new node (Since 2.0).
# This option is required on the top level of blockdev-add.
-# @discard: #optional discard-related options (default: ignore)
-# @cache: #optional cache-related options
-# @read-only: #optional whether the block device should be read-only
+# @discard: discard-related options (default: ignore)
+# @cache: cache-related options
+# @read-only: whether the block device should be read-only
# (default: false)
-# @detect-zeroes: #optional detect and optimize zero writes (Since 2.1)
+# @detect-zeroes: detect and optimize zero writes (Since 2.1)
# (default: off)
#
# Remaining options are determined by the block driver.
#
-# Since: 1.7
+# Since: 2.9
##
{ 'union': 'BlockdevOptions',
'base': { 'driver': 'BlockdevDriver',
'*detect-zeroes': 'BlockdevDetectZeroesOptions' },
'discriminator': 'driver',
'data': {
- 'archipelago':'BlockdevOptionsArchipelago',
'blkdebug': 'BlockdevOptionsBlkdebug',
'blkverify': 'BlockdevOptionsBlkverify',
'bochs': 'BlockdevOptionsGenericFormat',
'cloop': 'BlockdevOptionsGenericFormat',
'dmg': 'BlockdevOptionsGenericFormat',
'file': 'BlockdevOptionsFile',
- 'ftp': 'BlockdevOptionsCurl',
- 'ftps': 'BlockdevOptionsCurl',
+ 'ftp': 'BlockdevOptionsCurlFtp',
+ 'ftps': 'BlockdevOptionsCurlFtps',
'gluster': 'BlockdevOptionsGluster',
'host_cdrom': 'BlockdevOptionsFile',
'host_device':'BlockdevOptionsFile',
- 'http': 'BlockdevOptionsCurl',
- 'https': 'BlockdevOptionsCurl',
-# TODO iscsi: Wait for structured options
+ 'http': 'BlockdevOptionsCurlHttp',
+ 'https': 'BlockdevOptionsCurlHttps',
+ 'iscsi': 'BlockdevOptionsIscsi',
'luks': 'BlockdevOptionsLUKS',
'nbd': 'BlockdevOptionsNbd',
'nfs': 'BlockdevOptionsNfs',
'qed': 'BlockdevOptionsGenericCOWFormat',
'quorum': 'BlockdevOptionsQuorum',
'raw': 'BlockdevOptionsRaw',
-# TODO rbd: Wait for structured options
+ 'rbd': 'BlockdevOptionsRbd',
'replication':'BlockdevOptionsReplication',
-# TODO sheepdog: Wait for structured options
+ 'sheepdog': 'BlockdevOptionsSheepdog',
'ssh': 'BlockdevOptionsSsh',
'vdi': 'BlockdevOptionsGenericFormat',
'vhdx': 'BlockdevOptionsGenericFormat',
# empty string means that no block device should be
# referenced.
#
-# Since: 1.7
+# Since: 2.9
##
{ 'alternate': 'BlockdevRef',
'data': { 'definition': 'BlockdevOptions',
# BlockBackend will be created; otherwise, @node-name is mandatory at the top
# level and no BlockBackend will be created.
#
-# For the arguments, see the documentation of BlockdevOptions.
-#
-# Note: This command is still a work in progress. It doesn't support all
-# block drivers among other things. Stay away from it unless you want
-# to help with its development.
-#
-# Since: 1.7
+# Since: 2.9
#
# Example:
#
# 1.
# -> { "execute": "blockdev-add",
# "arguments": {
-# "options" : { "driver": "qcow2",
-# "file": { "driver": "file",
-# "filename": "test.qcow2" } } } }
+# "driver": "qcow2",
+# "node-name": "test1",
+# "file": {
+# "driver": "file",
+# "filename": "test.qcow2"
+# }
+# }
+# }
# <- { "return": {} }
#
# 2.
# -> { "execute": "blockdev-add",
# "arguments": {
-# "options": {
-# "driver": "qcow2",
-# "node-name": "node0",
-# "discard": "unmap",
-# "cache": {
-# "direct": true,
-# "writeback": true
+# "driver": "qcow2",
+# "node-name": "node0",
+# "discard": "unmap",
+# "cache": {
+# "direct": true
# },
# "file": {
-# "driver": "file",
-# "filename": "/tmp/test.qcow2"
+# "driver": "file",
+# "filename": "/tmp/test.qcow2"
# },
# "backing": {
-# "driver": "raw",
-# "file": {
-# "driver": "file",
-# "filename": "/dev/fdset/4"
+# "driver": "raw",
+# "file": {
+# "driver": "file",
+# "filename": "/dev/fdset/4"
# }
# }
-# }
# }
# }
#
{ 'command': 'blockdev-add', 'data': 'BlockdevOptions', 'boxed': true }
##
-# @x-blockdev-del:
+# @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
#
# @node-name: Name of the graph node to delete.
#
-# 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.9
#
# Example:
#
# -> { "execute": "blockdev-add",
# "arguments": {
-# "options": {
-# "driver": "qcow2",
-# "node-name": "node0",
-# "file": {
-# "driver": "file",
-# "filename": "test.qcow2"
-# }
-# }
+# "driver": "qcow2",
+# "node-name": "node0",
+# "file": {
+# "driver": "file",
+# "filename": "test.qcow2"
+# }
# }
# }
# <- { "return": {} }
#
-# -> { "execute": "x-blockdev-del",
+# -> { "execute": "blockdev-del",
# "arguments": { "node-name": "node0" }
# }
# <- { "return": {} }
#
##
-{ 'command': 'x-blockdev-del', 'data': { 'node-name': 'str' } }
+{ 'command': 'blockdev-del', 'data': { 'node-name': 'str' } }
##
# @blockdev-open-tray:
# to it
# - if the guest device does not have an actual tray
#
-# @device: #optional Block device name (deprecated, use @id instead)
+# @device: Block device name (deprecated, use @id instead)
#
-# @id: #optional 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)
#
-# @force: #optional if false (the default), an eject request will be sent to
+# @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
#
# If the tray was already closed before, this will be a no-op.
#
-# @device: #optional Block device name (deprecated, use @id instead)
+# @device: Block device name (deprecated, use @id instead)
#
-# @id: #optional 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)
#
# 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 } }
+#
+# <- { "return": {} }
+#
##
{ 'command': 'blockdev-close-tray',
'data': { '*device': 'str',
#
# If the tray is open and there is no medium inserted, this will be a no-op.
#
-# @device: #optional Block device name (deprecated, use @id instead)
+# @device: Block device name (deprecated, use @id instead)
#
-# @id: #optional 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)
#
# 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
+#
+# Example:
+#
+# -> { "execute": "x-blockdev-remove-medium",
+# "arguments": { "id": "ide0-1-0" } }
+#
+# <- { "error": { "class": "GenericError",
+# "desc": "Tray of device 'ide0-1-0' is not open" } }
+#
+# -> { "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 } }
+#
+# <- { "return": {} }
+#
+# -> { "execute": "x-blockdev-remove-medium",
+# "arguments": { "device": "ide0-1-0" } }
+#
+# <- { "return": {} }
+#
##
{ 'command': 'x-blockdev-remove-medium',
'data': { '*device': 'str',
# device's tray must currently be open (unless there is no attached guest
# device) and there must be no medium inserted already.
#
-# @device: #optional Block device name (deprecated, use @id instead)
+# @device: Block device name (deprecated, use @id instead)
#
-# @id: #optional 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)
#
# @node-name: name of a node in the block driver state graph
#
# Stay away from it unless you want to help with its development.
#
# Since: 2.5
+#
+# Example:
+#
+# -> { "execute": "blockdev-add",
+# "arguments": {
+# "options": { "node-name": "node0",
+# "driver": "raw",
+# "file": { "driver": "file",
+# "filename": "fedora.iso" } } } }
+# <- { "return": {} }
+#
+# -> { "execute": "x-blockdev-insert-medium",
+# "arguments": { "id": "ide0-1-0",
+# "node-name": "node0" } }
+#
+# <- { "return": {} }
+#
##
{ 'command': 'x-blockdev-insert-medium',
'data': { '*device': 'str',
# @read-write: Makes the device writable
#
# Since: 2.3
+#
##
{ 'enum': 'BlockdevChangeReadOnlyMode',
'data': ['retain', 'read-only', 'read-write'] }
# combines blockdev-open-tray, x-blockdev-remove-medium,
# x-blockdev-insert-medium and blockdev-close-tray).
#
-# @device: #optional Block device name (deprecated, use @id instead)
+# @device: Block device name (deprecated, use @id instead)
#
-# @id: #optional The name or QOM path of the guest device
+# @id: The name or QOM path of the guest device
# (since: 2.8)
#
# @filename: filename of the new image to be loaded
#
-# @format: #optional, format to open the new image with (defaults to
+# @format: format to open the new image with (defaults to
# the probed format)
#
-# @read-only-mode: #optional, change the read-only mode of the device; defaults
+# @read-only-mode: change the read-only mode of the device; defaults
# to 'retain'
#
# 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": {} }
+#
+# 2. Load a read-only medium into a writable drive
+#
+# -> { "execute": "blockdev-change-medium",
+# "arguments": { "id": "floppyA",
+# "filename": "/srv/images/ro.img",
+# "format": "raw",
+# "read-only-mode": "retain" } }
+#
+# <- { "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": "read-only" } }
+#
+# <- { "return": {} }
+#
##
{ 'command': 'blockdev-change-medium',
'data': { '*device': 'str',
##
# @BLOCK_IMAGE_CORRUPTED:
#
-# Emitted when a corruption has been detected in a disk image
+# 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.
#
-# @node-name: #optional node name (Since: 2.4)
+# @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
#
-# @offset: #optional, if the corruption resulted from an image access, this is
+# @offset: if the corruption resulted from an image access, this is
# the host's access offset into the image
#
-# @size: #optional, if the corruption resulted from an image access, this is
+# @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
+# @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.
+#
+# 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 } }
+#
# Since: 1.7
##
{ 'event': 'BLOCK_IMAGE_CORRUPTED',
#
# @action: action that has been taken
#
-# @nospace: #optional true if I/O error was caused due to a no-space
+# @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)
# BLOCK_IO_ERROR event
#
# Since: 0.13.0
+#
+# 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': 'str', 'node-name': 'str', 'operation': 'IoOperationType',
#
# @speed: rate limit, bytes per second
#
-# @error: #optional, error message. Only present on failure. This field
+# @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' : 'BlockJobType',
# @speed: rate limit, bytes per second
#
# Since: 1.1
+#
+# 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' : 'BlockJobType',
# @action: action that has been taken
#
# Since: 1.3
+#
+# Example:
+#
+# <- { "event": "BLOCK_JOB_ERROR",
+# "data": { "device": "ide0-hd1",
+# "operation": "write",
+# "action": "stop" },
+# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+#
##
{ 'event': 'BLOCK_JOB_ERROR',
'data': { 'device' : 'str',
# 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': { 'type' : 'BlockJobType',
##
# @block-set-write-threshold:
#
-# Change the write threshold for a block drive. An event will be delivered
-# if a write to this block drive crosses the configured threshold.
+# 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.
+#
# This is useful to transparently resize thin-provisioned drives without
# the guest OS noticing.
#
# Use 0 to disable the threshold.
#
# Since: 2.3
+#
+# Example:
+#
+# -> { "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' } }
#
# @parent: the id or name of the parent node.
#
-# @child: #optional the name of a child under the given parent node.
+# @child: the name of a child under the given parent node.
#
-# @node: #optional the name of the node that will be added.
+# @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
# the rest of the array.
#
# Since: 2.7
+#
+# Example:
+#
+# 1. Add a new node to a quorum
+# -> { "execute": "blockdev-add",
+# "arguments": {
+# "options": { "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',
projects / mirror_qemu.git / blobdiff