#
# @compat: compatibility level
#
+# @data-file: the filename of the external data file that is stored in the
+# image and used as a default for opening the image (since: 4.0)
+#
+# @data-file-raw: True if the external data file must stay valid as a
+# standalone (read-only) raw image without looking at qcow2
+# metadata (since: 4.0)
+#
# @lazy-refcounts: on or off; only valid for compat >= 1.1
#
# @corrupt: true if the image has been marked corrupt; only valid for
{ 'struct': 'ImageInfoSpecificQCow2',
'data': {
'compat': 'str',
+ '*data-file': 'str',
+ '*data-file-raw': 'bool',
'*lazy-refcounts': 'bool',
'*corrupt': 'bool',
'refcount-bits': 'int',
#
# An enumeration of possible states that a dirty bitmap can report to the user.
#
-# @frozen: The bitmap is currently in-use by a backup operation or block job,
-# and is immutable.
+# @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 currently in-use by an internal operation and is
-# read-only. It can still be deleted.
+# @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 can not be
-# cleared, deleted, or used for backup operations. (Since 2.12)
+# @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'] }
+ '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)
+# @status: Deprecated in favor of @recording and @locked. (since 2.4)
+#
+# @recording: true if the bitmap is recording new writes from the guest.
+# Replaces `active` and `disabled` statuses. (since 4.0)
+#
+# @busy: true if the bitmap is in-use by some operation (NBD or jobs)
+# and cannot be modified via QMP or used by another operation.
+# Replaces `locked` and `frozen` statuses. (since 4.0)
+#
+# @persistent: true if the bitmap was stored on disk, is scheduled to be stored
+# on disk, or both. (since 4.0)
+#
+# @inconsistent: true if this is a persistent bitmap that was improperly
+# stored. Implies @persistent to be true; @recording and
+# @busy to be false. This bitmap cannot be used. To remove
+# it, use @block-dirty-bitmap-remove. (Since 4.0)
#
# Since: 1.3
##
{ 'struct': 'BlockDirtyInfo',
'data': {'*name': 'str', 'count': 'int', 'granularity': 'uint32',
- 'status': 'DirtyBitmapStatus'} }
+ 'recording': 'bool', 'busy': 'bool', 'status': 'DirtyBitmapStatus',
+ 'persistent': 'bool', '*inconsistent': 'bool' } }
##
# @Qcow2BitmapInfoFlags:
# +------------------
# 10 50 100
#
-# Since: 2.12
+# Since: 4.0
##
{ 'struct': 'BlockLatencyHistogramInfo',
'data': {'boundaries': ['uint64'], 'bins': ['uint64'] } }
##
-# @x-block-latency-histogram-set:
+# @block-latency-histogram-set:
#
# Manage read, write and flush latency histograms for the device.
#
-# If only @device parameter is specified, remove all present latency histograms
+# If only @id parameter is specified, remove all present latency histograms
# for the device. Otherwise, add/reset some of (or all) latency histograms.
#
-# @device: device name to set latency histogram for.
+# @id: The name or QOM path of the guest device.
#
# @boundaries: list of interval boundary values (see description in
# BlockLatencyHistogramInfo definition). If specified, all
#
# Returns: error if device is not found or any boundary arrays are invalid.
#
-# Since: 2.12
+# Since: 4.0
#
# Example: set new histograms for all io types with intervals
# [0, 10), [10, 50), [50, 100), [100, +inf):
#
# -> { "execute": "block-latency-histogram-set",
-# "arguments": { "device": "drive0",
+# "arguments": { "id": "drive0",
# "boundaries": [10, 50, 100] } }
# <- { "return": {} }
#
# not changed (or not created):
#
# -> { "execute": "block-latency-histogram-set",
-# "arguments": { "device": "drive0",
+# "arguments": { "id": "drive0",
# "boundaries-write": [10, 50, 100] } }
# <- { "return": {} }
#
# write: [0, 1000), [1000, 5000), [5000, +inf)
#
# -> { "execute": "block-latency-histogram-set",
-# "arguments": { "device": "drive0",
+# "arguments": { "id": "drive0",
# "boundaries": [10, 50, 100],
# "boundaries-write": [1000, 5000] } }
# <- { "return": {} }
# Example: remove all latency histograms:
#
# -> { "execute": "block-latency-histogram-set",
-# "arguments": { "device": "drive0" } }
+# "arguments": { "id": "drive0" } }
# <- { "return": {} }
##
-{ 'command': 'x-block-latency-histogram-set',
- 'data': {'device': 'str',
+{ 'command': 'block-latency-histogram-set',
+ 'data': {'id': 'str',
'*boundaries': ['uint64'],
'*boundaries-read': ['uint64'],
'*boundaries-write': ['uint64'],
# @timed_stats: Statistics specific to the set of previously defined
# intervals of time (Since 2.5)
#
-# @x_rd_latency_histogram: @BlockLatencyHistogramInfo. (Since 2.12)
+# @rd_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0)
#
-# @x_wr_latency_histogram: @BlockLatencyHistogramInfo. (Since 2.12)
+# @wr_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0)
#
-# @x_flush_latency_histogram: @BlockLatencyHistogramInfo. (Since 2.12)
+# @flush_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0)
#
# Since: 0.14.0
##
'invalid_wr_operations': 'int', 'invalid_flush_operations': 'int',
'account_invalid': 'bool', 'account_failed': 'bool',
'timed_stats': ['BlockDeviceTimedStats'],
- '*x_rd_latency_histogram': 'BlockLatencyHistogramInfo',
- '*x_wr_latency_histogram': 'BlockLatencyHistogramInfo',
- '*x_flush_latency_histogram': 'BlockLatencyHistogramInfo' } }
+ '*rd_latency_histogram': 'BlockLatencyHistogramInfo',
+ '*wr_latency_histogram': 'BlockLatencyHistogramInfo',
+ '*flush_latency_histogram': 'BlockLatencyHistogramInfo' } }
##
# @BlockStats:
# @block-dirty-bitmap-merge:
#
# Merge dirty bitmaps listed in @bitmaps to the @target dirty bitmap.
-# The @bitmaps dirty bitmaps are unchanged.
+# Dirty bitmaps in @bitmaps will be unchanged, except if it also appears
+# as the @target bitmap. Any bits already set in @target will still be
+# set after the merge, i.e., this operation does not clear the target.
# On error, @target is unchanged.
#
+# The resulting bitmap will count as dirty any clusters that were dirty in any
+# of the source bitmaps. This can be used to achieve backup checkpoints, or in
+# simpler usages, to copy bitmaps.
+#
# Returns: nothing on success
# If @node is not a valid block device, DeviceNotFound
# If any bitmap in @bitmaps or @target is not found, GenericError
##
# @x-debug-block-dirty-bitmap-sha256:
#
-# Get bitmap SHA256
+# Get bitmap SHA256.
#
# Returns: BlockDirtyBitmapSha256 on success
# If @node is not a valid block device, DeviceNotFound
# @locking: whether to enable file locking. If set to 'auto', only enable
# when Open File Descriptor (OFD) locking API is available
# (default: auto, since 2.10)
+# @drop-cache: invalidate page cache during live migration. This prevents
+# stale data on the migration destination with cache.direct=off.
+# Currently only supported on Linux hosts.
+# (default: on, since: 4.0)
# @x-check-cache-dropped: whether to check that page cache was dropped on live
# migration. May cause noticeable delays if the image
# file is large, do not use in production.
'*pr-manager': 'str',
'*locking': 'OnOffAuto',
'*aio': 'BlockdevAioOptions',
+ '*drop-cache': {'type': 'bool',
+ 'if': 'defined(CONFIG_LINUX)'},
'*x-check-cache-dropped': 'bool' } }
##
##
# @BlockdevQcow2EncryptionFormat:
-# @aes: AES-CBC with plain64 initialization venctors
+# @aes: AES-CBC with plain64 initialization vectors
#
# Since: 2.10
##
# encrypted images, except when doing a metadata-only
# probe of the image. (since 2.10)
#
+# @data-file: reference to or definition of the external data file.
+# This may only be specified for images that require an
+# external data file. If it is not specified for such
+# an image, the data file name is loaded from the image
+# file. (since 4.0)
+#
# Since: 2.9
##
{ 'struct': 'BlockdevOptionsQcow2',
'*l2-cache-entry-size': 'int',
'*refcount-cache-size': 'int',
'*cache-clean-interval': 'int',
- '*encrypt': 'BlockdevQcow2Encryption' } }
+ '*encrypt': 'BlockdevQcow2Encryption',
+ '*data-file': 'BlockdevRef' } }
##
# @SshHostKeyCheckMode:
##
{ 'command': 'blockdev-add', 'data': 'BlockdevOptions', 'boxed': true }
+##
+# @x-blockdev-reopen:
+#
+# Reopens a block device using the given set of options. Any option
+# not specified will be reset to its default value regardless of its
+# previous status. If an option cannot be changed or a particular
+# driver does not support reopening then the command will return an
+# error.
+#
+# The top-level @node-name option (from BlockdevOptions) must be
+# specified and is used to select the block device to be reopened.
+# Other @node-name options must be either omitted or set to the
+# current name of the appropriate node. This command won't change any
+# node name and any attempt to do it will result in an error.
+#
+# In the case of options that refer to child nodes, the behavior of
+# this command depends on the value:
+#
+# 1) A set of options (BlockdevOptions): the child is reopened with
+# the specified set of options.
+#
+# 2) A reference to the current child: the child is reopened using
+# its existing set of options.
+#
+# 3) A reference to a different node: the current child is replaced
+# with the specified one.
+#
+# 4) NULL: the current child (if any) is detached.
+#
+# Options (1) and (2) are supported in all cases, but at the moment
+# only @backing allows replacing or detaching an existing child.
+#
+# Unlike with blockdev-add, the @backing option must always be present
+# unless the node being reopened does not have a backing file and its
+# image does not have a default backing file name as part of its
+# metadata.
+#
+# Since: 4.0
+##
+{ 'command': 'x-blockdev-reopen',
+ 'data': 'BlockdevOptions', 'boxed': true }
+
##
# @blockdev-del:
#
# Driver specific image creation options for qcow2.
#
# @file Node to create the image format on
+# @data-file Node to use as an external data file in which all guest
+# data is stored so that only metadata remains in the qcow2
+# file (since: 4.0)
+# @data-file-raw True if the external data file must stay valid as a
+# standalone (read-only) raw image without looking at qcow2
+# metadata (default: false; since: 4.0)
# @size Size of the virtual disk in bytes
# @version Compatibility level (default: v3)
# @backing-file File name of the backing file if a backing file
##
{ 'struct': 'BlockdevCreateOptionsQcow2',
'data': { 'file': 'BlockdevRef',
+ '*data-file': 'BlockdevRef',
+ '*data-file-raw': 'bool',
'size': 'size',
'*version': 'BlockdevQcow2Version',
'*backing-file': 'str',
projects / mirror_qemu.git / blobdiff