#
# Mapping information from a virtual block range to a host file range
#
-# @start: the start byte of the mapped virtual range
+# @start: virtual (guest) offset of the first byte described by this
+# entry
#
# @length: the number of bytes of the mapped virtual range
#
-# @data: whether the mapped range has data
+# @data: reading the image will actually read data from a file (in
+# particular, if @offset is present this means that the sectors
+# are not simply preallocated, but contain actual data in raw
+# format)
#
-# @zero: whether the virtual blocks are zeroed
+# @zero: whether the virtual blocks read as zeroes
#
-# @depth: the depth of the mapping
+# @depth: number of layers (0 = top image, 1 = top image's backing
+# file, ..., n - 1 = bottom image (where n is the number of
+# images in the chain)) before reaching one for which the
+# range is allocated
#
-# @offset: the offset in file that the virtual sectors are mapped to
+# @offset: if present, the image file stores the data for this range
+# in raw format at the given (host) offset
#
# @filename: filename that is referred to by @offset
#
# @ro: true if the backing device was open read-only
#
# @drv: the name of the block format used to open the backing device. As of
-# 0.14.0 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
+# 0.14 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
# 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device',
# 'http', 'https', 'luks', 'nbd', 'parallels', 'qcow',
# 'qcow2', 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat'
#
# @encrypted: true if the backing device is encrypted
#
-# @encryption_key_missing: always false
-#
# @detect_zeroes: detect and optimize zero writes (Since 2.1)
#
# @bps: total throughput limit in bytes per second is specified
# @dirty-bitmaps: dirty bitmaps information (only present if node
# has one or more dirty bitmaps) (Since 4.2)
#
-# Features:
-# @deprecated: Member @encryption_key_missing is deprecated. It is
-# always false.
-#
-# Since: 0.14.0
+# Since: 0.14
#
##
{ 'struct': 'BlockDeviceInfo',
'data': { 'file': 'str', '*node-name': 'str', 'ro': 'bool', 'drv': 'str',
'*backing_file': 'str', 'backing_file_depth': 'int',
'encrypted': 'bool',
- 'encryption_key_missing': { 'type': 'bool',
- 'features': [ 'deprecated' ] },
'detect_zeroes': 'BlockdevDetectZeroesOptions',
'bps': 'int', 'bps_rd': 'int', 'bps_wr': 'int',
'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int',
##
{ 'enum': 'BlockDeviceIoStatus', 'data': [ 'ok', 'failed', 'nospace' ] }
-##
-# @BlockDeviceMapEntry:
-#
-# Entry in the metadata map of the device (returned by "qemu-img map")
-#
-# @start: Offset in the image of the first byte described by this entry
-# (in bytes)
-#
-# @length: Length of the range described by this entry (in bytes)
-#
-# @depth: Number of layers (0 = top image, 1 = top image's backing file, etc.)
-# before reaching one for which the range is allocated. The value is
-# in the range 0 to the depth of the image chain - 1.
-#
-# @zero: the sectors in this range read as zeros
-#
-# @data: reading the image will actually read data from a file (in particular,
-# if @offset is present this means that the sectors are not simply
-# preallocated, but contain actual data in raw format)
-#
-# @offset: if present, the image file stores the data for this range in
-# raw format at the given offset.
-#
-# Since: 1.7
-##
-{ 'struct': 'BlockDeviceMapEntry',
- 'data': { 'start': 'int', 'length': 'int', 'depth': 'int', 'zero': 'bool',
- 'data': 'bool', '*offset': 'int' } }
-
-##
-# @DirtyBitmapStatus:
-#
-# An enumeration of possible states that a dirty bitmap can report to the user.
-#
-# @frozen: The bitmap is currently in-use by some operation and is immutable.
-# If the bitmap was @active prior to the operation, new writes by the
-# guest are being recorded in a temporary buffer, and will not be lost.
-# Generally, bitmaps are cleared on successful use in an operation and
-# the temporary buffer is committed into the bitmap. On failure, the
-# temporary buffer is merged back into the bitmap without first
-# clearing it.
-# Please refer to the documentation for each bitmap-using operation,
-# See also @blockdev-backup, @drive-backup.
-#
-# @disabled: The bitmap is not currently recording new writes by the guest.
-# This is requested explicitly via @block-dirty-bitmap-disable.
-# It can still be cleared, deleted, or used for backup operations.
-#
-# @active: The bitmap is actively monitoring for new writes, and can be cleared,
-# deleted, or used for backup operations.
-#
-# @locked: The bitmap is currently in-use by some operation and is immutable.
-# If the bitmap was @active prior to the operation, it is still
-# recording new writes. If the bitmap was @disabled, it is not
-# recording new writes. (Since 2.12)
-#
-# @inconsistent: This is a persistent dirty bitmap that was marked in-use on
-# disk, and is unusable by QEMU. It can only be deleted.
-# Please rely on the inconsistent field in @BlockDirtyInfo
-# instead, as the status field is deprecated. (Since 4.0)
-#
-# Since: 2.4
-##
-{ 'enum': 'DirtyBitmapStatus',
- 'data': ['active', 'disabled', 'frozen', 'locked', 'inconsistent'] }
-
##
# @BlockDirtyInfo:
#
#
# @granularity: granularity of the dirty bitmap in bytes (since 1.4)
#
-# @status: current status of the dirty bitmap (since 2.4)
-#
# @recording: true if the bitmap is recording new writes from the guest.
# Replaces `active` and `disabled` statuses. (since 4.0)
#
# @busy to be false. This bitmap cannot be used. To remove
# it, use @block-dirty-bitmap-remove. (Since 4.0)
#
-# Features:
-# @deprecated: Member @status is deprecated. Use @recording and
-# @locked instead.
-#
# Since: 1.3
##
{ 'struct': 'BlockDirtyInfo',
'data': {'*name': 'str', 'count': 'int', 'granularity': 'uint32',
'recording': 'bool', 'busy': 'bool',
- 'status': { 'type': 'DirtyBitmapStatus',
- 'features': [ 'deprecated' ] },
'persistent': 'bool', '*inconsistent': 'bool' } }
##
# @tray_open: True if the device's tray is open
# (only present if it has a tray)
#
-# @dirty-bitmaps: dirty bitmaps information (only present if the
-# driver has one or more dirty bitmaps) (Since 2.0)
-#
# @io-status: @BlockDeviceIoStatus. Only present if the device
# supports it and the VM is configured to stop on errors
# (supported device models: virtio-blk, IDE, SCSI except
# @inserted: @BlockDeviceInfo describing the device if media is
# present
#
-# Features:
-# @deprecated: Member @dirty-bitmaps is deprecated. Use @inserted
-# member @dirty-bitmaps instead.
-#
-# Since: 0.14.0
+# Since: 0.14
##
{ 'struct': 'BlockInfo',
'data': {'device': 'str', '*qdev': 'str', 'type': 'str', 'removable': 'bool',
'locked': 'bool', '*inserted': 'BlockDeviceInfo',
- '*tray_open': 'bool', '*io-status': 'BlockDeviceIoStatus',
- '*dirty-bitmaps': { 'type': ['BlockDirtyInfo'],
- 'features': [ 'deprecated' ] } } }
+ '*tray_open': 'bool', '*io-status': 'BlockDeviceIoStatus' } }
##
# @BlockMeasureInfo:
# Returns: a list of @BlockInfo describing each virtual block device. Filter
# nodes that were created implicitly are skipped over.
#
-# Since: 0.14.0
+# Since: 0.14
#
# Example:
#
# @wr_operations: The number of write operations performed by the device.
#
# @flush_operations: The number of cache flush operations performed by the
-# device (since 0.15.0)
+# device (since 0.15)
#
# @unmap_operations: The number of unmap operations performed by the device
# (Since 4.2)
#
-# @rd_total_time_ns: Total time spent on reads in nanoseconds (since 0.15.0).
+# @rd_total_time_ns: Total time spent on reads in nanoseconds (since 0.15).
#
-# @wr_total_time_ns: Total time spent on writes in nanoseconds (since 0.15.0).
+# @wr_total_time_ns: Total time spent on writes in nanoseconds (since 0.15).
#
# @flush_total_time_ns: Total time spent on cache flushes in nanoseconds
-# (since 0.15.0).
+# (since 0.15).
#
# @unmap_total_time_ns: Total time spent on unmap operations in nanoseconds
# (Since 4.2)
#
# @flush_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0)
#
-# Since: 0.14.0
+# Since: 0.14
##
{ 'struct': 'BlockDeviceStats',
'data': {'rd_bytes': 'int', 'wr_bytes': 'int', 'unmap_bytes' : 'int',
# @backing: This describes the backing block device if it has one.
# (Since 2.0)
#
-# Since: 0.14.0
+# Since: 0.14
##
{ 'struct': 'BlockStats',
'data': {'*device': 'str', '*qdev': 'str', '*node-name': 'str',
#
# Returns: A list of @BlockStats for each virtual block devices.
#
-# Since: 0.14.0
+# Since: 0.14
#
# Example:
#
# Returns: - nothing on success
# - If @device is not a valid block device, DeviceNotFound
#
-# Since: 0.14.0
+# Since: 0.14
#
# Example:
#
{ 'struct': 'BlockdevSnapshot',
'data': { 'node': 'str', 'overlay': 'str' } }
+##
+# @BackupPerf:
+#
+# Optional parameters for backup. These parameters don't affect
+# functionality, but may significantly affect performance.
+#
+# @use-copy-range: Use copy offloading. Default false.
+#
+# @max-workers: Maximum number of parallel requests for the sustained background
+# copying process. Doesn't influence copy-before-write operations.
+# Default 64.
+#
+# @max-chunk: Maximum request length for the sustained background copying
+# process. Doesn't influence copy-before-write operations.
+# 0 means unlimited. If max-chunk is non-zero then it should not be
+# less than job cluster size which is calculated as maximum of
+# target image cluster size and 64k. Default 0.
+#
+# Since: 6.0
+##
+{ 'struct': 'BackupPerf',
+ 'data': { '*use-copy-range': 'bool',
+ '*max-workers': 'int', '*max-chunk': 'int64' } }
+
##
# @BackupCommon:
#
# above node specified by @drive. If this option is not given,
# a node name is autogenerated. (Since: 4.2)
#
+# @x-perf: Performance options. (Since 6.0)
+#
# Note: @on-source-error and @on-target-error only affect background
# I/O. If an error occurs during a guest write request, the device's
# rerror/werror actions will be used.
'*on-source-error': 'BlockdevOnError',
'*on-target-error': 'BlockdevOnError',
'*auto-finalize': 'bool', '*auto-dismiss': 'bool',
- '*filter-node-name': 'str' } }
+ '*filter-node-name': 'str', '*x-perf': 'BackupPerf' } }
##
# @DriveBackup:
# Returns: - nothing on success
# - If @device is not a valid block device, DeviceNotFound
#
-# Since: 0.14.0
+# Since: 0.14
#
# Example:
#
'*bps-write-max' : 'int', '*bps-write-max-length' : 'int',
'*iops-size' : 'int' } }
+##
+# @ThrottleGroupProperties:
+#
+# Properties for throttle-group objects.
+#
+# The options starting with x- are aliases for the same key without x- in
+# the @limits object. As indicated by the x- prefix, this is not a stable
+# interface and may be removed or changed incompatibly in the future. Use
+# @limits for a supported stable interface.
+#
+# @limits: limits to apply for this throttle group
+#
+# Since: 2.11
+##
+{ 'struct': 'ThrottleGroupProperties',
+ 'data': { '*limits': 'ThrottleLimits',
+ '*x-iops-total' : 'int', '*x-iops-total-max' : 'int',
+ '*x-iops-total-max-length' : 'int', '*x-iops-read' : 'int',
+ '*x-iops-read-max' : 'int', '*x-iops-read-max-length' : 'int',
+ '*x-iops-write' : 'int', '*x-iops-write-max' : 'int',
+ '*x-iops-write-max-length' : 'int', '*x-bps-total' : 'int',
+ '*x-bps-total-max' : 'int', '*x-bps-total-max-length' : 'int',
+ '*x-bps-read' : 'int', '*x-bps-read-max' : 'int',
+ '*x-bps-read-max-length' : 'int', '*x-bps-write' : 'int',
+ '*x-bps-write-max' : 'int', '*x-bps-write-max-length' : 'int',
+ '*x-iops-size' : 'int' } }
+
##
# @block-stream:
#
# @device: the device or node name of the top image
#
# @base: the common backing file name.
-# It cannot be set if @base-node is also set.
+# It cannot be set if @base-node or @bottom is also set.
#
# @base-node: the node name of the backing file.
-# It cannot be set if @base is also set. (Since 2.8)
+# It cannot be set if @base or @bottom is also set. (Since 2.8)
+#
+# @bottom: the last node in the chain that should be streamed into
+# top. It cannot be set if @base or @base-node is also set.
+# It cannot be filter node. (Since 6.0)
#
# @backing-file: The backing file string to write into the top
# image. This filename is not validated.
# 'stop' and 'enospc' can only be used if the block device
# supports io-status (see BlockInfo). Since 1.3.
#
+# @filter-node-name: the node name that should be assigned to the
+# filter driver that the stream job inserts into the graph
+# above @device. If this option is not given, a node name is
+# autogenerated. (Since: 6.0)
+#
# @auto-finalize: When false, this job will wait in a PENDING state after it has
# finished its work, waiting for @block-job-finalize before
# making any block graph changes.
##
{ 'command': 'block-stream',
'data': { '*job-id': 'str', 'device': 'str', '*base': 'str',
- '*base-node': 'str', '*backing-file': 'str', '*speed': 'int',
- '*on-error': 'BlockdevOnError',
+ '*base-node': 'str', '*backing-file': 'str', '*bottom': 'str',
+ '*speed': 'int', '*on-error': 'BlockdevOnError',
+ '*filter-node-name': 'str',
'*auto-finalize': 'bool', '*auto-dismiss': 'bool' } }
##
'cloop', 'compress', 'copy-on-read', 'dmg', 'file', 'ftp', 'ftps',
'gluster', 'host_cdrom', 'host_device', 'http', 'https', 'iscsi',
'luks', 'nbd', 'nfs', 'null-aio', 'null-co', 'nvme', 'parallels',
- 'qcow', 'qcow2', 'qed', 'quorum', 'raw', 'rbd',
+ 'preallocate', 'qcow', 'qcow2', 'qed', 'quorum', 'raw', 'rbd',
{ 'name': 'replication', 'if': 'defined(CONFIG_REPLICATION)' },
'sheepdog',
'ssh', 'throttle', 'vdi', 'vhdx', 'vmdk', 'vpc', 'vvfat' ] }
'data': { 'aes': 'QCryptoBlockOptionsQCow',
'luks': 'QCryptoBlockOptionsLUKS'} }
+##
+# @BlockdevOptionsPreallocate:
+#
+# Filter driver intended to be inserted between format and protocol node
+# and do preallocation in protocol node on write.
+#
+# @prealloc-align: on preallocation, align file length to this number,
+# default 1048576 (1M)
+#
+# @prealloc-size: how much to preallocate, default 134217728 (128M)
+#
+# Since: 6.0
+##
+{ 'struct': 'BlockdevOptionsPreallocate',
+ 'base': 'BlockdevOptionsGenericFormat',
+ 'data': { '*prealloc-align': 'int', '*prealloc-size': 'int' } }
+
##
# @BlockdevOptionsQcow2:
#
#
# @tls-creds: TLS credentials ID
#
-# @x-dirty-bitmap: A "qemu:dirty-bitmap:NAME" string to query in place of
+# @x-dirty-bitmap: A metadata context name such as "qemu:dirty-bitmap:NAME"
+# or "qemu:allocation-depth" to query in place of the
# traditional "base:allocation" block status (see
-# NBD_OPT_LIST_META_CONTEXT in the NBD protocol) (since 3.0)
+# NBD_OPT_LIST_META_CONTEXT in the NBD protocol; and
+# yes, naming this option x-context would have made
+# more sense) (since 3.0)
#
# @reconnect-delay: On an unexpected disconnect, the nbd client tries to
# connect again until succeeding or encountering a serious
'data': { 'throttle-group': 'str',
'file' : 'BlockdevRef'
} }
+
+##
+# @BlockdevOptionsCor:
+#
+# Driver specific block device options for the copy-on-read driver.
+#
+# @bottom: The name of a non-filter node (allocation-bearing layer) that
+# limits the COR operations in the backing chain (inclusive), so
+# that no data below this node will be copied by this filter.
+# If option is absent, the limit is not applied, so that data
+# from all backing layers may be copied.
+#
+# Since: 6.0
+##
+{ 'struct': 'BlockdevOptionsCor',
+ 'base': 'BlockdevOptionsGenericFormat',
+ 'data': { '*bottom': 'str' } }
+
##
# @BlockdevOptions:
#
'bochs': 'BlockdevOptionsGenericFormat',
'cloop': 'BlockdevOptionsGenericFormat',
'compress': 'BlockdevOptionsGenericFormat',
- 'copy-on-read':'BlockdevOptionsGenericFormat',
+ 'copy-on-read':'BlockdevOptionsCor',
'dmg': 'BlockdevOptionsGenericFormat',
'file': 'BlockdevOptionsFile',
'ftp': 'BlockdevOptionsCurlFtp',
'null-co': 'BlockdevOptionsNull',
'nvme': 'BlockdevOptionsNVMe',
'parallels': 'BlockdevOptionsGenericFormat',
+ 'preallocate':'BlockdevOptionsPreallocate',
'qcow2': 'BlockdevOptionsQcow2',
'qcow': 'BlockdevOptionsQcow',
'qed': 'BlockdevOptionsGenericCOWFormat',
# Note: If action is "stop", a STOP event will eventually follow the
# BLOCK_IO_ERROR event
#
-# Since: 0.13.0
+# Since: 0.13
#
# Example:
#
projects / qemu.git / blobdiff