[libvirt] [RFC PATCH 11/11] docs: Document the mediated devices within the nodedev driver

[Erik Skultety]

Signed-off-by: Erik Skultety <eskultet at redhat.com>
---
 docs/drvnodedev.html.in | 91 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)

diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in
index ed185c3df3..776c88cc87 100644
--- a/docs/drvnodedev.html.in
+++ b/docs/drvnodedev.html.in
@@ -180,5 +180,96 @@
 ...
 <device></pre>
 
+    <h3><a name="MDEVCap">MDEV capability</a></h3>
+    <p>
+      A PCI device capable of creating mediated devices will include a nested
+      capability mdev which enumerates all the supported mdev types on the
+      physical device, along with the type attributes available through sysfs.
+      For a more info about mediated devices, refer to the
+      <a href="#MDEV">paragraph below</a>.
+    </p>
+
+<pre>
+<device>
+...
+  <driver>
+    <name>nvidia</name>
+  </driver>
+  <capability type='pci'>
+...
+    <capability type='mdev'>
+      <type id='nvidia-11'>
+        <name>GRID M60-0B</name>
+        <description>num_heads=2, frl_config=45, framebuffer=512M,
+        max_resolution=2560x1600, max_instance=16</description>
+        <device_api>vfio-pci</device_api>
+        <available_instances>16</available_instances>
+      </type>
+      <!-- Here would come the rest of the available mdev types -->
+    </capability>
+...
+  </capability>
+</device></pre>
+
+    <h2><a name="MDEV">Mediated devices (MDEVs)</a></h2>
+    <p>
+      Mediated devices (<span class="since">Since 3.2.0</span>) are software
+      devices defining resource allocation on the backing physical device which
+      in turn allows the parent physical device's resources to be divided into
+      several mediated devices, thus sharing the physical device's performance
+      among multiple guests. Unlike SR-IOV however, where a PCIe device appears
+      as multiple separate PCIe devices on the host's PCI bus, mediated devices
+      only appear on the mdev virtual bus. Therefore, no detach/reattach
+      procedure from/to the host driver procedure is involved even though
+      mediated devices are used in a direct device assignment manner.<br/>
+      <br/>
+      At the moment, libvirt can only list the available mediated devices on the
+      host and display all information libvirt can gather about them, see the
+      examples below. Because mediated devices are instantiated from vendor
+      specific templates, simply called 'types', information about the resource
+      allocation for a specific type is contained within the backing physical
+      parent device (see <a href="#PCI">PCI host devices</a> for an example).
+    </p>
+
+    <h3>Example of a mediated device</h3>
+    <pre>
+<device>
+  <name>mdev_4b20d080_1b54_4048_85b3_a6a62d165c01</name>
+  <path>/sys/devices/pci0000:00/0000:00:02.0/4b20d080-1b54-4048-85b3-a6a62d165c01</path>
+  <parent>pci_0000_06_00_0</parent>
+  <driver>
+    <name>vfio_mdev</name>
+  </driver>
+  <capability type='mdev'>
+    <type id='nvidia-11'/>
+    <iommuGroup number='12'/>
+  <capability/>
+<device/></pre>
+
+    <p>
+      To see the supported mediated device types on a specific physical device
+      use the following:
+    </p>
+
+    <pre>
+$ ls /sys/class/mdev_bus/<device>/mdev_supported_types</pre>
+
+    <p>
+      To manually instantiate a mediated device, use one of the following as a
+      reference:
+    </p>
+
+    <pre>
+$ uuidgen > /sys/class/mdev_bus/<device>/mdev_supported_types/<type>/create
+...
+$ echo <UUID> > /sys/class/mdev_bus/<device>/mdev_supported_types/<type>/create</pre>
+
+    <p>
+      Manual removal of a mediated device is then performed as follows:
+    </p>
+
+    <pre>
+$ echo 1 > /sys/bus/mdev/devices/<uuid>/remove</pre>
+
   </body>
 </html>
-- 
2.12.2