docs/interop/bitmaps.rst

31 that is tracked is the granularity of the bitmap. If the granularity of a
32 bitmap is 64K, each '1' bit means that a 64K region as a whole may have
36 requires more computational overhead and larger bitmap sizes. Larger
37 granularities mean smaller bitmap sizes, but less targeted backups.
39 The size of a bitmap (in bytes) can be computed as such:
42 e.g. the size of a 64KiB granularity bitmap on a 2TiB image is:
56 attaching the bitmap elsewhere in the storage graph. This is beyond the scope
72 writes bitmap data to disk upon close. If persistence is not required for a
73 specific use case, all bitmap features excepting persistence are available for
77 any changes to the bitmap will be discarded upon exit.
89 - A bitmap's name is unique to the node, but bitmaps attached to different
93 - The name of a user-created bitmap cannot be empty ("").
98 - Persistent storage formats may impose their own requirements on bitmap names
102    - qcow2 bitmap names are limited to between 1 and 1023 bytes long.
117 This struct shows the name, granularity, and dirty byte count for each bitmap.
120 - ``recording``: This bitmap is recording writes.
121 - ``busy``: This bitmap is in-use by an operation.
122 - ``persistent``: This bitmap is a persistent type.
123 - ``inconsistent``: This bitmap is corrupted and cannot be used.
126 modifying a bitmap, and happens when the bitmap is being used for a backup
131 notably allowing only the ``block-dirty-bitmap-remove`` operation.
134 <qemu-qmp-ref.html#index-DirtyBitmapStatus>`_. A bitmap historically had
137    #. ``Frozen``: This bitmap is currently in-use by an operation and is
142    #. ``Disabled``: This bitmap is not recording new writes.
146    #. ``Active``: This bitmap is recording new writes.
150    #. ``Locked``: This bitmap is in-use by an operation, and is immutable.
155    #. ``Inconsistent``: This persistent bitmap was not saved to disk
168 The primary interface to manipulating bitmap objects is via the QMP
176 There are six primary bitmap-management API commands:
178 - ``block-dirty-bitmap-add``
179 - ``block-dirty-bitmap-remove``
180 - ``block-dirty-bitmap-clear``
181 - ``block-dirty-bitmap-disable``
182 - ``block-dirty-bitmap-enable``
183 - ``block-dirty-bitmap-merge``
189 Creation: block-dirty-bitmap-add
192 `block-dirty-bitmap-add
195 Creates a new bitmap that tracks writes to the specified node. granularity,
200  to create a new, actively recording persistent bitmap:
204   -> { "execute": "block-dirty-bitmap-add",
214 - This bitmap will have a default granularity that matches the cluster size of
220  To create a new, disabled (``-recording``), transient bitmap that tracks
225   -> { "execute": "block-dirty-bitmap-add",
236 Deletion: block-dirty-bitmap-remove
239 `block-dirty-bitmap-remove
242 Deletes a bitmap. Bitmaps that are ``+busy`` cannot be removed.
244 - Deleting a bitmap does not impact any other bitmaps attached to the same
245   node, nor does it affect any backups already created from this bitmap or
251 - Deleting a persistent bitmap will remove it from the qcow2 file.
255  Remove a bitmap named ``bitmap0`` from node ``drive0``:
259   -> { "execute": "block-dirty-bitmap-remove",
268 Resetting: block-dirty-bitmap-clear
271 `block-dirty-bitmap-clear
274 Clears all dirty bits from a bitmap. ``+busy`` bitmaps cannot be cleared.
276 - An incremental backup created from an empty bitmap will copy no data, as if
281  Clear all dirty bits from bitmap ``bitmap0`` on node ``drive0``:
285   -> { "execute": "block-dirty-bitmap-clear",
294 Enabling: block-dirty-bitmap-enable
297 `block-dirty-bitmap-enable
300 "Enables" a bitmap, setting the ``recording`` bit to true, causing writes to
310  To set ``+recording`` on bitmap ``bitmap0`` on node ``drive0``:
314   -> { "execute": "block-dirty-bitmap-enable",
323 Enabling: block-dirty-bitmap-disable
326 `block-dirty-bitmap-disable
329 "Disables" a bitmap, setting the ``recording`` bit to false, causing further
339 - Disabling a bitmap may be useful for examining which sectors of a disk
348  To set ``-recording`` on bitmap ``bitmap0`` on node ``drive0``:
352   -> { "execute": "block-dirty-bitmap-disable",
361 Merging, Copying: block-dirty-bitmap-merge
364 `block-dirty-bitmap-merge
367 Merges one or more bitmaps into a target bitmap. For any segment that is dirty
368 in any one source bitmap, the target bitmap will mark that segment dirty.
372   bitmap(s) will be marked dirty in the destination bitmap.
374 - Merge does not create the destination bitmap if it does not exist. A blank
375   bitmap can be created beforehand to achieve the same effect.
380 - If the merge operation should fail, the destination bitmap is guaranteed to
392  Merge the data from ``bitmap0`` into the bitmap ``new_bitmap`` on node
398   -> { "execute": "block-dirty-bitmap-merge",
423  keys from the response to highlight only the bitmap-relevant portions of the
424  API. This result highlights a bitmap ``bitmap0`` attached to the root node of
453 files. Demonstrated in `Creation: block-dirty-bitmap-add`_, passing
454 ``persistent: true`` to ``block-dirty-bitmap-add`` will persist that bitmap to
461 However, if QEMU does not get a chance to close the file cleanly, the bitmap
464 ``block-dirty-bitmap-remove``.
466 Losing a bitmap in this way does not invalidate any existing backups that have
467 been made from this bitmap, but no further backups will be able to be issued
494 #. Create a new bitmap attached to drive0, confident that nothing has been
499 At this point, the bitmap and drive backup would be correctly in sync, and
517           bitmap, but they will copy extra segments reflecting writes that
525 -  ``block-dirty-bitmap-add``
526 -  ``block-dirty-bitmap-clear``
527 -  ``block-dirty-bitmap-enable``
528 -  ``block-dirty-bitmap-disable``
529 -  ``block-dirty-bitmap-merge``
557 new, empty bitmap that records writes from this point in time forward.
565           destination. These writes will be recorded in the bitmap
575              "type": "block-dirty-bitmap-add",
652 If we want to start a new backup chain with an existing bitmap, we can also
653 use a transaction to reset the bitmap while making a new full backup:
662            "type": "block-dirty-bitmap-clear",
699 bitmap instead of adding a new one.
709 #. Create a full backup and sync it to a dirty bitmap using any method:
715      state, careful to add a new bitmap before the VM begins execution.
720    - The bitmap we created is named ``bitmap0``, attached to ``drive0``.
758            "bitmap": "bitmap0",
791           special bitmap that gets re-added to bitmap0 when the backup ends so
832            "bitmap": "bitmap0",
869 Each new incremental backup re-synchronizes the bitmap to the latest backup
929            "bitmap": "bitmap0",
1023                "type": "block-dirty-bitmap-add",
1030                "type": "block-dirty-bitmap-add",
1142                  "bitmap": "bitmap0",
1151                  "bitmap": "bitmap0",
1204 In either failure case, the bitmap used for the failed operation is not
1208 Effectively, the "point in time" that a bitmap is recording differences
1214 same bitmap.
1255            "bitmap": "bitmap0",
1338            "bitmap": "bitmap0",
1379 default. The job(s) that succeeded will clear the dirty bitmap associated with
1399                "bitmap": "bitmap0",
1408                "bitmap": "bitmap0",
1530                "bitmap": "bitmap0",
1539                "bitmap": "bitmap0",