[libvirt] [PATCH v4 14/14] docs: Document the new hostdev and address type 'mdev'

[Erik Skultety]

Signed-off-by: Erik Skultety <eskultet at redhat.com>
---
 docs/formatdomain.html.in | 46 ++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 40 insertions(+), 6 deletions(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 4a3123e989..1eb6c44b6f 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -3886,6 +3886,19 @@
   </devices>
   ...</pre>
 
+    <p>or:</p>
+
+<pre>
+  ...
+  <devices>
+    <hostdev mode='subsystem' type='mdev' model='vfio-pci'>
+    <source>
+      <address uuid='c2177883-f1bb-47f0-914d-32a22e3a8804'>
+    </source>
+    </hostdev>
+  </devices>
+  ...</pre>
+
     <dl>
       <dt><code>hostdev</code></dt>
       <dd>The <code>hostdev</code> element is the main container for describing
@@ -3930,12 +3943,22 @@
             <code>type</code> passes all LUNs presented by a single HBA to
             the guest.
           </dd>
+          <dt><code>mdev</code></dt>
+          <dd>For mediated devices (<span class="since">Since 3.2.0</span>)
+          the <code>model</code> attribute specifies the device API which
+          determines how the host's vfio driver will expose the device to the
+          guest. Currently, only <code>vfio-pci</code> model is supported.
+          There are also some implications on the usage of guest's address type
+          depending on the <code>model</code> attribute, see the
+          <code>address</code> element below.</dd>
         </dl>
         <p>
-          Note: The <code>managed</code> attribute is only used with PCI devices
-          and is ignored by all the other device types, thus setting
-          <code>managed</code> explicitly with other than PCI device has the same
-          effect as omitting it.
+          Note: The <code>managed</code> attribute is only used with PCI and is
+          ignored by all the other device types, thus setting
+          <code>managed</code> explicitly with other than a PCI device has the
+          same effect as omitting it. Similarly, <code>model</code> attribute is
+          only supported by mediated devices and ignored by all other device
+          types.
         </p>
       </dd>
       <dt><code>source</code></dt>
@@ -4000,6 +4023,12 @@
             is the vhost_scsi wwpn (16 hexadecimal digits with a prefix of
             "naa.") established in the host configfs.
           </dd>
+          <dt><code>mdev</code></dt>
+          <dd>Mediated devices (<span class="since">Since 3.2.0</span>) are
+            described by the <code>address</code> element. The
+            <code>address</code> element contains so far a single mandatory
+            attribute <code>uuid</code>.
+          </dd>
         </dl>
       </dd>
       <dt><code>vendor</code>, <code>product</code></dt>
@@ -4043,8 +4072,13 @@
       For PCI devices the element carries 4 attributes allowing to designate
       the device as can be found with the <code>lspci</code> or
       with <code>virsh nodedev-list</code>. For SCSI devices a 'drive'
-      address type must be used. <a href="#elementsAddress">See above</a> for
-      more details on the address element.</dd>
+      address type must be used. For mediated devices, which are only software
+      devices defining an allocation of resources on the physical parent device,
+      the address type used must conform to the <code>model</code> attribute
+      of element <code>hostdev</code>, e.g. any address type other than PCI for
+      <code>vfio-pci</code> device API will result in an error.
+      <a href="#elementsAddress">See above</a> for more details on the address
+      element.</dd>
       <dt><code>driver</code></dt>
       <dd>
         PCI devices can have an optional <code>driver</code>
-- 
2.12.1