From: Jiri Denemark <jdenemar@redhat.com>
Date: Wed, 16 Apr 2014 13:28:10 +0000 (+0200)
Subject: conf: Output disk backing store details in domain XML
X-Git-Url: http://xenbits.xensource.com/gitweb?a=commitdiff_plain;h=a2e369bc000126b6b0048ce1256c8cea00976f16;p=people%2Fliuw%2Flibxenctrl-split%2Flibvirt.git

conf: Output disk backing store details in domain XML

The XML for quite a longish backing chain is shown below:

  <disk type='network' device='disk'>
    <driver name='qemu' type='qcow2'/>
    <source protocol='nbd' name='bar'>
      <host transport='unix' socket='/var/run/nbdsock'/>
    </source>
    <backingStore type='block' index='1'>
      <format type='qcow2'/>
      <source dev='/dev/HostVG/QEMUGuest1'/>
      <backingStore type='file' index='2'>
        <format type='qcow2'/>
        <source file='/tmp/image2.qcow'/>
        <backingStore type='file' index='3'>
          <format type='qcow2'/>
          <source file='/tmp/image3.qcow'/>
          <backingStore type='file' index='4'>
            <format type='qcow2'/>
            <source file='/tmp/image4.qcow'/>
            <backingStore type='file' index='5'>
              <format type='qcow2'/>
              <source file='/tmp/image5.qcow'/>
              <backingStore type='file' index='6'>
                <format type='raw'/>
                <source file='/tmp/Fedora-17-x86_64-Live-KDE.iso'/>
                <backingStore/>
              </backingStore>
            </backingStore>
          </backingStore>
        </backingStore>
      </backingStore>
    </backingStore>
    <target dev='vdb' bus='virtio'/>
  </disk>

Various disk types and formats can be mixed in one chain. The
<backingStore/> empty element marks the end of the backing chain and it
is there mostly for future support of parsing the chain provided by a
user. If it's missing, we are supposed to probe for the rest of the
chain ourselves, otherwise complete chain was provided by the user. The
index attributes of backingStore elements can be used to unambiguously
identify a specific part of the image chain.

Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
---

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index e851f852a..93ee05c94 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -1624,6 +1624,20 @@
       &lt;/auth&gt;
       &lt;target dev='vda' bus='virtio'/&gt;
     &lt;/disk&gt;
+    &lt;disk type='file' device='disk'&gt;
+      &lt;driver name='qemu' type='qcow2'/&gt;
+      &lt;source file='/var/lib/libvirt/images/domain.qcow'/&gt;
+      &lt;backingStore type='file'&gt;
+        &lt;format type='qcow2'/&gt;
+        &lt;source file='/var/lib/libvirt/images/snapshot.qcow'/&gt;
+        &lt;backingStore type='block'&gt;
+          &lt;format type='raw'/&gt;
+          &lt;source dev='/dev/mapper/base'/&gt;
+          &lt;backingStore/&gt;
+        &lt;/backingStore&gt;
+      &lt;/backingStore&gt;
+      &lt;target dev='vda' bus='virtio'/&gt;
+    &lt;/disk&gt;
   &lt;/devices&gt;
   ...</pre>
 
@@ -1814,6 +1828,53 @@
         This feature doesn't support migration currently.
         </p>
         </dd>
+      <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.
+        <span class="since">Since 1.2.4</span>. An empty
+        <code>backingStore</code> element means the sibling source is
+        self-contained and is not based on any backing store. The following
+        attributes and sub-elements are supported in
+        <code>backingStore</code>:
+        <dl>
+          <dt><code>type</code> attribute</dt>
+          <dd>
+            The <code>type</code> attribute represents the type of disk used
+            by the backing store, see disk type attribute above for more
+            details and possible values.
+          </dd>
+          <dt><code>index</code> attribute</dt>
+          <dd>
+            This attribute is only valid in output (and ignored on input) and
+            it can be used to refer to a specific part of the disk chain when
+            doing block operations (such as via the
+            <code>virDomainBlockRebase</code> API). For example,
+            <code>vda[2]</code> refers to the backing store with
+            <code>index='2'</code> of the disk with <code>vda</code> target.
+          </dd>
+          <dt><code>format</code> sub-element</dt>
+          <dd>
+            The <code>format</code> element contains <code>type</code>
+            attribute which specifies the internal format of the backing
+            store, such as <code>raw</code> or <code>qcow2</code>.
+          </dd>
+          <dt><code>source</code> sub-element</dt>
+          <dd>
+            This element has the same structure as the <code>source</code>
+            element in <code>disk</code>. It specifies which file, device,
+            or network location contains the data of the described backing
+            store.
+          </dd>
+          <dt><code>backingStore</code> sub-element</dt>
+          <dd>
+            If the backing store is not self-contained, the next element
+            in the chain is described by nested <code>backingStore</code>
+            element.
+          </dd>
+        </dl>
+      </dd>
       <dt><code>mirror</code></dt>
       <dd>
         This element is present if the hypervisor has started a block
diff --git a/docs/schemas/domaincommon.rng b/docs/schemas/domaincommon.rng
index d2235e1f5..4249ed56e 100644
--- a/docs/schemas/domaincommon.rng
+++ b/docs/schemas/domaincommon.rng
@@ -1196,10 +1196,51 @@
       <optional>
         <ref name="snapshot"/>
       </optional>
-      <ref name="diskSource"/>
+      <interleave>
+        <ref name="diskSource"/>
+        <ref name="storageSourceExtra"/>
+        <ref name="diskBackingChain"/>
+      </interleave>
+    </element>
+  </define>
+
+  <define name="diskBackingChain">
+    <choice>
+      <ref name="diskBackingStore"/>
+      <ref name="diskBackingStoreLast"/>
+    </choice>
+  </define>
+
+  <define name="diskBackingStore">
+    <element name="backingStore">
+      <attribute name="index">
+        <ref name="positiveInteger"/>
+      </attribute>
+      <interleave>
+        <ref name="diskSource"/>
+        <ref name="diskBackingChain"/>
+        <ref name="diskFormat"/>
+      </interleave>
+    </element>
+  </define>
+
+  <define name="diskFormat">
+    <element name="format">
+      <attribute name="type">
+        <ref name="storageFormat"/>
+      </attribute>
+      <empty/>
     </element>
   </define>
 
+  <define name="diskBackingStoreLast">
+    <optional>
+      <element name="backingStore">
+        <empty/>
+      </element>
+    </optional>
+  </define>
+
   <define name="diskSource">
     <choice>
       <ref name="diskSourceFile"/>
@@ -1232,7 +1273,6 @@
           </optional>
         </element>
       </optional>
-      <ref name='storageSourceExtra'/>
     </interleave>
   </define>
 
@@ -1256,7 +1296,6 @@
           </optional>
         </element>
       </optional>
-      <ref name='storageSourceExtra'/>
     </interleave>
   </define>
 
@@ -1276,7 +1315,6 @@
           <empty/>
         </element>
       </optional>
-      <ref name='storageSourceExtra'/>
     </interleave>
   </define>
 
@@ -1340,7 +1378,6 @@
         </zeroOrMore>
         <empty/>
       </element>
-      <ref name='storageSourceExtra'/>
     </interleave>
   </define>
 
@@ -1373,7 +1410,6 @@
           </optional>
         </element>
       </optional>
-      <ref name='storageSourceExtra'/>
     </interleave>
   </define>
 
diff --git a/tests/domainschemadata/backing-chains.xml b/tests/domainschemadata/backing-chains.xml
new file mode 100644
index 000000000..84df1dbd3
--- /dev/null
+++ b/tests/domainschemadata/backing-chains.xml
@@ -0,0 +1,94 @@
+<domain type='qemu'>
+  <name>QEMUGuest1</name>
+  <uuid>c7a5fdbd-edaf-9455-926a-d65c16db1809</uuid>
+  <memory unit='KiB'>219136</memory>
+  <currentMemory unit='KiB'>219136</currentMemory>
+  <vcpu placement='static'>1</vcpu>
+  <os>
+    <type arch='i686' machine='pc'>hvm</type>
+    <boot dev='hd'/>
+  </os>
+  <clock offset='utc'/>
+  <on_poweroff>destroy</on_poweroff>
+  <on_reboot>restart</on_reboot>
+  <on_crash>destroy</on_crash>
+  <devices>
+    <emulator>/usr/bin/qemu</emulator>
+    <disk type='network' device='disk'>
+      <driver name='qemu' type='qcow2'/>
+      <source protocol='gluster' name='Volume2/Image'>
+        <host transport='unix' socket='/path/to/sock'/>
+      </source>
+      <backingStore type='file' index='1'>
+        <format type='qcow2'/>
+        <source file='/tmp/missing-backing-store.qcow'/>
+      </backingStore>
+      <target dev='vda' bus='virtio'/>
+    </disk>
+    <disk type='network' device='disk'>
+      <driver name='qemu' type='qcow2'/>
+      <source protocol='nbd' name='bar'>
+        <host transport='unix' socket='/var/run/nbdsock'/>
+      </source>
+      <backingStore type='block' index='1'>
+        <format type='qcow2'/>
+        <source dev='/dev/HostVG/QEMUGuest1'/>
+        <backingStore type='file' index='2'>
+          <format type='qcow2'/>
+          <source file='/tmp/image2.qcow'/>
+          <backingStore type='file' index='3'>
+            <format type='qcow2'/>
+            <source file='/tmp/image3.qcow'/>
+            <backingStore type='file' index='4'>
+              <format type='qcow2'/>
+              <source file='/tmp/image4.qcow'/>
+              <backingStore type='file' index='5'>
+                <source file='/tmp/image5.qcow'/>
+                <format type='qcow2'/>
+                <backingStore type='file' index='6'>
+                  <format type='raw'/>
+                  <source file='/tmp/Fedora-17-x86_64-Live-KDE.iso'/>
+                  <backingStore/>
+                </backingStore>
+              </backingStore>
+            </backingStore>
+          </backingStore>
+        </backingStore>
+      </backingStore>
+      <target dev='vdb' bus='virtio'/>
+    </disk>
+    <disk type='network' device='disk'>
+      <driver name='qemu' type='raw'/>
+      <backingStore/>
+      <source protocol='gluster' name='Volume1/Image'>
+        <host name='example.org' port='6000'/>
+      </source>
+      <target dev='vdc' bus='virtio'/>
+    </disk>
+    <disk type='network' device='disk'>
+      <driver name='qemu' type='qcow2'/>
+      <auth username='myname'>
+        <secret type='ceph' usage='mycluster_myname'/>
+      </auth>
+      <source protocol='rbd' name='pool/image'>
+        <host name='mon1.example.org' port='6321'/>
+        <host name='mon2.example.org' port='6322'/>
+        <host name='mon3.example.org' port='6322'/>
+      </source>
+      <backingStore type='file' index='1'>
+        <source file='/tmp/image.qcow'/>
+        <backingStore/>
+        <format type='qcow2'/>
+      </backingStore>
+      <target dev='vdd' bus='virtio'/>
+    </disk>
+    <disk type='block' device='disk'>
+      <driver name='qemu' type='qcow2'/>
+      <source dev='/dev/HostVG/QEMUGuest11'/>
+      <target dev='vde' bus='virtio'/>
+    </disk>
+    <controller type='usb' index='0'/>
+    <controller type='pci' index='0' model='pci-root'/>
+    <memballoon model='virtio'/>
+  </devices>
+</domain>