aboutsummaryrefslogtreecommitdiff
path: root/qapi/block-core.json
diff options
context:
space:
mode:
authorJohn Snow <jsnow@redhat.com>2019-02-19 17:49:43 -0500
committerJohn Snow <jsnow@redhat.com>2019-02-19 17:49:43 -0500
commit73ab5d601c8b4311090a70e525f5970f70b8b2a0 (patch)
tree8baf9482d74fc73e98fe8855e60e0d0ffa603186 /qapi/block-core.json
parentf67cf661f8b88afe8a5ea2f120583924cba9087f (diff)
block/dirty-bitmap: Documentation and Comment fixups
The meaning of the states has changed subtly over time, this should bring the understanding more in-line with the current, actual usages. Reported-by: Eric Blake <eblake@redhat.com> Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Message-id: 20190202011048.12343-1-jsnow@redhat.com Signed-off-by: John Snow <jsnow@redhat.com>
Diffstat (limited to 'qapi/block-core.json')
-rw-r--r--qapi/block-core.json34
1 files changed, 25 insertions, 9 deletions
diff --git a/qapi/block-core.json b/qapi/block-core.json
index b8c8e04d02..2b8afbb924 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -420,17 +420,27 @@
#
# 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.
-#
-# @disabled: The bitmap is currently in-use by an internal operation and is
-# read-only. It can still be deleted.
+# @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 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)
#
# Since: 2.4
##
@@ -2094,9 +2104,15 @@
# @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
@@ -2131,7 +2147,7 @@
##
# @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