kbase: incrementalbackupinternals: Describe 'block commit'

oVirt does merge images out of libvirt in some cases. Add docs outlining
how it's done from a high level.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>

diff --git a/docs/kbase/incrementalbackupinternals.rst b/docs/kbase/incrementalbackupinternals.rst
index 3c400dfd98fee8c67edea28803dfe0ef636af7f4..29e90092e84763300708512bed6cdc5076a37581 100644 (file)
--- a/docs/kbase/incrementalbackupinternals.rst
+++ b/docs/kbase/incrementalbackupinternals.rst
@@ -245,3 +245,40 @@ the snapshot.
             continue
 
         create RECORDING bitmap named BITMAP in OVERLAY with GRANULARITY
+
+Committing external snapshots manually
+--------------------------------------
+
+``block commit`` refers to an operation where data from a subchain of the
+backing chain is merged down into the backing image of the subchain removing all
+images in the subchain.
+
+``COMMIT_TOP`` refers to the top of the subchain to merge into ``COMMIT_BASE``
+(which stays in the new chain).
+
+It's strongly advised to use ``virDomainBlockCommit`` API in libvirt directly if
+possible. Inactive VMs can be started with ``VIR_DOMAIN_START_PAUSED`` flag
+(``virsh start --paused``) to prevent OS from running.
+
+Otherwise the following pseudo-algorithm can be used:
+
+Note: A ``valid`` bitmap chain is a set of images containing bitmaps which
+conform to the rules about valid bitmaps mentioned above.
+
+::
+
+    commit data from COMMIT_TOP to COMMIT_BASE
+
+    let BITMAPS = valid bitmap chains in COMMIT_TOP
+
+    for each BITMAP in BITMAPS
+        let GRANULARITY = granularity of BITMAP in ACTIVE
+
+        if BITMAP is not present in COMMIT_BASE:
+            create RECORDING bitmap named BITMAP in COMMIT_BASE with GRANULARITY
+
+        for each IMAGE between COMMIT_TOP(inclusive) and COMMIT_BASE(exclusive):
+            if BITMAP is not present in IMAGE:
+                break
+
+            merge BITMAP in IMAGE into BITMAP in COMMIT_BASE