[libvirt] [PATCH 2/8] docs: Document support for obeying <backingStore> of <disk> on input

[Peter Krempa]

Until now we've only supported <backingStore> in an output mode. The
documentation for the element states that hypervisor drivers may start
to obey it in the future.

Update the documentation so that it mentions the recently added
'backingStoreInput' domain capability and explain what happens if it is
supported and <backingStore> is present on input.

Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 docs/formatdomain.html.in | 29 ++++++++++++++++++++---------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index a1042a314c..6df4a8b26e 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -3340,15 +3340,26 @@
       <dt><code>backingStore</code></dt>
       <dd>
         This element describes the backing store used by the disk
-        specified by sibling <code>source</code> element. It is
-        currently ignored on input and only used for output to
-        describe the detected backing chains of running
-        domains <span class="since">since 1.2.4</span> (although a
-        future version of libvirt may start accepting chains on input,
-        or output information for offline domains). An
-        empty <code>backingStore</code> element means the sibling
-        source is self-contained and is not based on any backing
-        store. For backing chain information to be accurate, the
+        specified by sibling <code>source</code> element.
+        <span class="since">Since 1.2.4.</span>
+
+        If the hypervisor driver does not support the
+        <a href='formatdomaincaps.html#featureBackingStoreInput'>
+        <code>backingStoreInput</code></a>
+        (<span class='since'>Since 5.10.0</span>)
+        domain feature the <code>backingStore</code> is ignored on
+        input and only used for output to describe the detected
+        backing chains of running domains.
+
+        If <code>backingStoreInput</code> is supported
+        the <code>backingStore</code> is used as the backing image of
+        <code>source</code> or other <code>backingStore</code> overriding
+        any backing image information recorded in the image metadata.
+
+        An empty <code>backingStore</code> element means the sibling
+        source is self-contained and is not based on any backing store.
+
+        For the detected backing chain information to be accurate, the
         backing format must be correctly specified in the metadata of
         each file of the chain (files created by libvirt satisfy this
         property, but using existing external files for snapshot or
-- 
2.23.0