Re: [libvirt] [PATCH v4 6/6] docs: Document the mediated devices within the nodedev driver

[John Ferlan]

On 05/15/2017 08:10 AM, Erik Skultety wrote:
> Signed-off-by: Erik Skultety 
> ---
>  docs/drvnodedev.html.in | 168 
> +++-
>  tools/virsh.pod |   7 +-
>  2 files changed, 171 insertions(+), 4 deletions(-)
> 

Reviewed-by: John Ferlan 

John

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

[libvirt] [PATCH v4 6/6] docs: Document the mediated devices within the nodedev driver

[Erik Skultety]

Signed-off-by: Erik Skultety 
---
 docs/drvnodedev.html.in | 168 +++-
 tools/virsh.pod |   7 +-
 2 files changed, 171 insertions(+), 4 deletions(-)

diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in
index 0a3870343..26c52dd0d 100644
--- a/docs/drvnodedev.html.in
+++ b/docs/drvnodedev.html.in
@@ -9,7 +9,7 @@
   (historically also referred to as node devices) like USB, PCI, SCSI, and
   network devices. This also includes various virtualization capabilities
   which the aforementioned devices provide for utilization, for example
-  SR-IOV, NPIV, DRM, etc.
+  SR-IOV, NPIV, MDEV, DRM, etc.
 
 
 
@@ -75,6 +75,7 @@
   storage (Since 1.0.4),
   scsi_generic (Since 1.0.7),
   drm (Since 3.1.0), and
+  mdev (Since 3.4.0).
   This element can be nested in which case it further specifies a
   device's capability. Refer to specific device types to see more 
values
   for the type attribute which are exclusive.
@@ -185,5 +186,170 @@
 ...
 device
 
+MDEV capability
+
+  A PCI device capable of creating mediated devices will include a nested
+  capability mdev_types which enumerates all supported mdev
+  types on the physical device, along with the type attributes available
+  through sysfs:
+
+
+
+  type
+  
+This element describes a mediated device type which acts as an
+abstract template defining a resource allocation for instances of this
+device type. The element has one attribute id which holds
+an official vendor-supplied identifier for the type.
+Since 3.4.0
+  
+
+  name
+  
+The name element holds a vendor-supplied code name for
+the given mediated device type. This is an optional element.
+Since 3.4.0
+  
+
+  deviceAPI
+  
+The value of this element describes how an instance of the given type
+will be presented to the guest by the VFIO framework.
+Since 3.4.0
+  
+
+  availableInstances
+  
+This element reports the current state of resource allocation. In other
+words, how many instances of the given type can still be successfully
+created on the physical device.
+Since 3.4.0
+  
+
+
+
+  For a more info about mediated devices, refer to the
+  paragraph below.
+
+
+
+device
+...
+  driver
+namenvidia/name
+  /driver
+  capability type='pci'
+...
+capability type='mdev_types'
+  type id='nvidia-11'
+nameGRID M60-0B/name
+deviceAPIvfio-pci/deviceAPI
+availableInstances16/availableInstances
+  /type
+  !-- Here would come the rest of the available mdev types --
+/capability
+...
+  /capability
+/device
+
+Mediated devices (MDEVs)
+
+  Mediated devices (Since 3.2.0) 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.
+
+
+
+  The following sub-elements and attributes are exposed within the
+  capability element:
+
+
+
+  type
+  
+This element describes a mediated device type which acts as an
+abstract template defining a resource allocation for instances of this
+device type. The element has one attribute id which holds
+an official vendor-supplied identifier for the type.
+Since 3.4.0
+  
+
+  iommuGroup
+  
+This element supports a single attribute number which 
holds
+the IOMMU group number the mediated device belongs to.
+Since 3.4.0
+  
+
+
+Example of a mediated device
+
+device
+  namemdev_4b20d080_1b54_4048_85b3_a6a62d165c01/name
+  
path/sys/devices/pci:00/:00:02.0/4b20d080-1b54-4048-85b3-a6a62d165c01/path
+  parentpci__06_00_0/parent
+  driver
+namevfio_mdev/name
+  /driver
+  capability type='mdev'
+type id='nvidia-11'/
+iommuGroup number='12'/
+  capability/
+device/
+
+
+  The support of mediated device's framework in libvirt's node device 
driver
+  covers the following features:
+
+
+
+  
+list available mediated devices on the host
+(Since 3.4.0)
+  
+  
+display device details
+(Since 3.4.0)
+  
+
+
+
+  Because mediated devices are instantiated from