[PATCH 6/6] 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(a)redhat.com&gt; --- 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