On 6/24/20 9:07 AM, Peter Krempa wrote:
Add a section that outlines usage of tools to handle bitmaps and
introduce terms corresponding to the output of qemu-img to be used in
further sections.
With this we can simplify the section about checking bitmap health as we
don't have to explain the qemu-img output but can refer to the newly
defined terms.
Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
docs/kbase/incrementalbackupinternals.rst | 58 ++++++++++++++++-------
1 file changed, 40 insertions(+), 18 deletions(-)
@@ -186,6 +174,40 @@ following rules:
refcount bits: 16
corrupt: false
+The ``flags`` have following meanings:
+
+``auto`` - **recording**
+
+ The bitmap is automatically activated when the image is opened for wrinting
writing
+ and thus it's actively recording writes.
+
+``in-use`` - **inconsistent**
+
+ The bitmap was not properly saved when the qemu process was shut down last
+ time thus didn't conistently record all the changed sectors.
consistently
+
+It's reccomended to use ``--output=json`` parameter to work with a machine
recommended
+readable output rather than trying to process the human readable output by
+scripts. For processing JSON in shell the ``jq`` tool can be used.
+
+Checking bitmap health
+----------------------
+
+QEMU optimizes disk writes by only updating the bitmaps in certain cases. This
+also can cause problems in cases when e.g. QEMU crashes.
+
+For a chain of corresponding bitmaps in a backing chain images to be considered
+valid and eligible for use for an incremental backup with
+``virDomainBackupBegin`` the bitmaps intended to be used must conform to the
+following rules:
+
+1) active/topmost image must contain the bitmap
+2) if bitmap with the same name is contained in one of the backing images it
s/if/if a/
+ must be a contiguougs subchain starting from the topmost image which contains
contiguous
+ the bitmaps (no gaps)
+3) all of the above bitmaps must be marked as **recording**
+4) all of the above bitmaps must not be **inconsistent**
+
(See also the ``qemuBlockBitmapChainIsValid`` helper method in
``src/qemu/qemu_block.c``)
With fixes,
Reviewed-by: Eric Blake <eblake@xxxxxxxxxx>
--
Eric Blake, Principal Software Engineer
Red Hat, Inc. +1-919-301-3226
Virtualization: qemu.org | libvirt.org
