Signed-off-by: Erik Skultety <eskultet@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 da0ae4aeba..3aa3ccc53a 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -3848,6 +3848,19 @@
   &lt;/devices&gt;
   ...</pre>
 
+    <p>or:</p>
+
+<pre>
+  ...
+  &lt;devices&gt;
+    &lt;hostdev mode='subsystem' type='mdev' model='vfio-pci'&gt;
+    &lt;source&gt;
+      &lt;address uuid='c2177883-f1bb-47f0-914d-32a22e3a8804'&gt;
+    &lt;/source&gt;
+    &lt;/hostdev&gt;
+  &lt;/devices&gt;
+  ...</pre>
+
     <dl>
       <dt><code>hostdev</code></dt>
       <dd>The <code>hostdev</code> element is the main container for describing
@@ -3892,12 +3905,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>
@@ -3962,6 +3985,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>
@@ -4005,8 +4034,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.0

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list

On Thu, Mar 16, 2017 at 01:21:18PM +0100, Erik Skultety wrote:
> Signed-off-by: Erik Skultety <eskultet@redhat.com>
> ---
>  docs/formatdomain.html.in | 46 ++++++++++++++++++++++++++++++++++++++++------
>  1 file changed, 40 insertions(+), 6 deletions(-)

We need some docs somewhere decsribing how to use the virNodeDev APIs
or virsh nodedev commands to create/delete mdevs in the host. It seems
we dont really have any docs about our nodedev usage at all, even
for other types it can create like NPIV. We probably want to introduce
a drvnodedev.html.in and link it from drivers.html.in to cover this
aspect


Regards,
Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://entangle-photo.org       -o-    http://search.cpan.org/~danberr/ :|

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list

On Thu, Mar 16, 2017 at 12:28:34PM +0000, Daniel P. Berrange wrote:
> On Thu, Mar 16, 2017 at 01:21:18PM +0100, Erik Skultety wrote:
> > Signed-off-by: Erik Skultety <eskultet@redhat.com>
> > ---
> >  docs/formatdomain.html.in | 46 ++++++++++++++++++++++++++++++++++++++++------
> >  1 file changed, 40 insertions(+), 6 deletions(-)
> 
> We need some docs somewhere decsribing how to use the virNodeDev APIs
> or virsh nodedev commands to create/delete mdevs in the host. It seems
> we dont really have any docs about our nodedev usage at all, even
> for other types it can create like NPIV. We probably want to introduce
> a drvnodedev.html.in and link it from drivers.html.in to cover this
> aspect
> 

Yeah, that one's coming with the node-dev series actually. This one was just
introducing internal stuff to libvirt, the node-dev part is coming as soon as I
rebase onto this series and give it a test :). But thanks for the note.

Erik

> 
> Regards,
> Daniel
> -- 
> |: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
> |: http://libvirt.org              -o-             http://virt-manager.org :|
> |: http://entangle-photo.org       -o-    http://search.cpan.org/~danberr/ :|

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list