diff options
| author | John Snow <jsnow@redhat.com> | 2019-02-19 17:49:43 -0500 |
|---|---|---|
| committer | John Snow <jsnow@redhat.com> | 2019-02-19 17:49:43 -0500 |
| commit | 73ab5d601c8b4311090a70e525f5970f70b8b2a0 (patch) | |
| tree | 8baf9482d74fc73e98fe8855e60e0d0ffa603186 /qapi | |
| parent | f67cf661f8b88afe8a5ea2f120583924cba9087f (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')
| -rw-r--r-- | qapi/block-core.json | 34 |
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 |