block/dirty-bitmap: Documentation and Comment fixups

#include "block/blockjob.h"

/**

 * A BdrvDirtyBitmap can be in three possible states:

 * (1) successor is NULL and disabled is false: full r/w mode

 * (2) successor is NULL and disabled is true: read only mode ("disabled")

 * (3) successor is set: frozen mode.

 *     A frozen bitmap cannot be renamed, deleted, anonymized, cleared, set,

 *     or enabled. A frozen bitmap can only abdicate() or reclaim().

 * A BdrvDirtyBitmap can be in four possible user-visible states:

 * (1) Active:   successor is NULL, and disabled is false: full r/w mode

 * (2) Disabled: successor is NULL, and disabled is true: qualified r/w mode,

 *               guest writes are dropped, but monitor writes are possible,

 *               through commands like merge and clear.

 * (3) Frozen:   successor is not NULL.

 *               A frozen bitmap cannot be renamed, deleted, cleared, set,

 *               enabled, merged to, etc. A frozen bitmap can only abdicate()

 *               or reclaim().

 *               In this state, the anonymous successor bitmap may be either

 *               Active and recording writes from the guest (e.g. backup jobs),

 *               but it can be Disabled and not recording writes.

 * (4) Locked:   Whether Active or Disabled, the user cannot modify this bitmap

 *               in any way from the monitor.

 */

struct BdrvDirtyBitmap {

    QemuMutex *mutex;

#

# 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

##

# @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