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>
---
 docs/kbase/incrementalbackupinternals.rst | 37 +++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/docs/kbase/incrementalbackupinternals.rst b/docs/kbase/incrementalbackupinternals.rst
index 9a96ef6df3..e50bf52e89 100644
--- 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
+
+Commiting 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
-- 
2.26.2

On 6/24/20 9:07 AM, Peter Krempa wrote:
> 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>
> ---
>   docs/kbase/incrementalbackupinternals.rst | 37 +++++++++++++++++++++++
>   1 file changed, 37 insertions(+)
> 
> diff --git a/docs/kbase/incrementalbackupinternals.rst b/docs/kbase/incrementalbackupinternals.rst
> index 9a96ef6df3..e50bf52e89 100644
> --- 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
> +
> +Commiting external snapshots manually

Committing

> +-------------------------------------
> +
> +``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 .

Drop space before .

Does oVirt care about block pull, or only block commit?  But block pull 
can be a separate patch if we need more information; this one is useful 
as-is (well, with typos fixed).

Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org

On Wed, Jun 24, 2020 at 09:35:22 -0500, Eric Blake wrote:
> On 6/24/20 9:07 AM, Peter Krempa wrote:
> > 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>
> > ---
> >   docs/kbase/incrementalbackupinternals.rst | 37 +++++++++++++++++++++++
> >   1 file changed, 37 insertions(+)
> > 
> > diff --git a/docs/kbase/incrementalbackupinternals.rst b/docs/kbase/incrementalbackupinternals.rst
> > index 9a96ef6df3..e50bf52e89 100644
> > --- 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
> > +
> > +Commiting external snapshots manually
> 
> Committing
> 
> > +-------------------------------------
> > +
> > +``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 .
> 
> Drop space before .
> 
> Does oVirt care about block pull, or only block commit?  But block pull can
> be a separate patch if we need more information; this one is useful as-is
> (well, with typos fixed).

oVirt doesn't use block pull for now and even libvirt doesn't implement
bitmap handling for the pull job for now. I'll add information here once
I do the implementation.