docs: Document support for obeying <backingStore> of <disk> on input

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@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index a1042a314c6b2e19000b6910f9f043f4fe3f22a7..6df4a8b26e854b317ba2a666fe9ae659167a3d07 100644 (file)
--- 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