[libvirt] docs: Document the new hostdev and address type 'mdev'

[Martin Polednik]

On 20/02/17 15:28 +0100, Erik Skultety wrote:
>Signed-off-by: Erik Skultety <eskultet at redhat.com>
>---
> docs/formatdomain.html.in | 48 +++++++++++++++++++++++++++++++++++++++++++----
> 1 file changed, 44 insertions(+), 4 deletions(-)
>
>diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
>index b69bd4c..13cb767 100644
>--- a/docs/formatdomain.html.in
>+++ b/docs/formatdomain.html.in
>@@ -3277,8 +3277,20 @@
>         attributes: <code>iobase</code> and <code>irq</code>.
>         <span class="since">Since 1.2.1</span>
>       </dd>
>+      <dt><code>mdev</code></dt>
>+      <dd>Mediated devices' addresses have so far only one mandatory attribute
>+        <code>uuid</code> (<span class="since">since 3.1.0</span>) which
>+        uniquely identifies a mediated device under the syfs file system.
>+      </dd>
>     </dl>
>
>+    <p>
>+        Note: Due to nature of mediated devices, being only software devices
>+        defining an allocation of resources on the physical parent device, the
>+        address type <code>mdev</code> is supposed to be used to identify a
>+        device on the host only, rather than identifying it in the guest.
>+    </p>
>+
>     <h4><a name="elementsControllers">Controllers</a></h4>
>
>     <p>
>@@ -3774,6 +3786,19 @@
>   </devices>
>   ...</pre>
>
>+    <p>or:</p>
>+
>+<pre>
>+  ...
>+  <devices>
>+    <hostdev mode='subsystem' type='mdev' model='vfio-pci'>
>+    <source>
>+      <address type='mdev' uuid='c2177883-f1bb-47f0-914d-32a22e3a8804'>
>+    </source>
>+    </hostdev>
>+  </devices>
>+  ...</pre>

Can't really test it yet, but from the docs/code seems to be OK for
oVirt.

>+
>     <dl>
>       <dt><code>hostdev</code></dt>
>       <dd>The <code>hostdev</code> element is the main container for describing
>@@ -3818,12 +3843,23 @@
>             <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.1.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.
>+          The model also has implications on the guest's address type, i.e.
>+          for <code>vfio-pci</code> device API any address type other than PCI
>+          will result in an error.
>+          </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>
>@@ -3888,6 +3924,10 @@
>             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.1.0</span>) are
>+          described by the <code>address</code> element.
>+          </dd>
>         </dl>
>       </dd>
>       <dt><code>vendor</code>, <code>product</code></dt>
>-- 
>2.10.2
>
>--
>libvir-list mailing list
>libvir-list at redhat.com
>https://www.redhat.com/mailman/listinfo/libvir-list