From nobody Sun Feb 8 16:12:29 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zoho.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 1493218549026766.7755600903137; Wed, 26 Apr 2017 07:55:49 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id CC2DE23E6D4; Wed, 26 Apr 2017 14:55:46 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 9BD3888D62; Wed, 26 Apr 2017 14:55:46 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 435D318523D6; Wed, 26 Apr 2017 14:55:46 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id v3QEtYMv017165 for ; Wed, 26 Apr 2017 10:55:34 -0400 Received: by smtp.corp.redhat.com (Postfix) id 88C8384DB3; Wed, 26 Apr 2017 14:55:34 +0000 (UTC) Received: from beluga.usersys.redhat.com.com (dhcp129-94.brq.redhat.com [10.34.129.94]) by smtp.corp.redhat.com (Postfix) with ESMTP id E0FA85C46F; Wed, 26 Apr 2017 14:55:33 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com CC2DE23E6D4 Authentication-Results: ext-mx05.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx05.extmail.prod.ext.phx2.redhat.com; spf=pass smtp.mailfrom=libvir-list-bounces@redhat.com DKIM-Filter: OpenDKIM Filter v2.11.0 mx1.redhat.com CC2DE23E6D4 From: Erik Skultety To: libvir-list@redhat.com Date: Wed, 26 Apr 2017 16:55:33 +0200 Message-Id: <70612ed83253b74c0aaed27f44fa0baedd6948aa.1493218185.git.eskultet@redhat.com> In-Reply-To: References: In-Reply-To: References: X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com Cc: Erik Skultety Subject: [libvirt] [PATCH v3 6/6] docs: Document the mediated devices within the nodedev driver X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.29]); Wed, 26 Apr 2017 14:55:48 +0000 (UTC) X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" Signed-off-by: Erik Skultety --- docs/drvnodedev.html.in | 164 ++++++++++++++++++++++++++++++++++++++++++++= +++- 1 file changed, 163 insertions(+), 1 deletion(-) diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in index 0a3870343..8f820cca1 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 capabilit= ies which the aforementioned devices provide for utilization, for example - SR-IOV, NPIV, DRM, etc. + SR-IOV, NPIV, MDEV, DRM, etc.

=20

@@ -75,6 +75,7 @@ storage (Since 1.0.4), scsi_generic (Since 1.0.7), drm (Since 3.1.0), and + mdev (Since 3.3.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,166 @@ ... <device> =20 +

MDEV capability

+

+ A PCI device capable of creating mediated devices will include a nes= ted + capability mdev_types which enumerates all supported md= ev + types on the physical device, along with the type attributes availab= le + 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 h= olds + an official vendor-supplied identifier for the type. + Since 3.3.0 +
+ +
name
+
+ The name element holds a vendor-supplied code name for + the given mediated device type. This is an optional element. + Since 3.3.0 +
+ +
deviceAPI
+
+ The value of this element describes how an instance of the given t= ype + will be presented to the guest by the VFIO framework. + Since 3.3.0 +
+ +
availableInstances
+
+ This element reports the current state of resource allocation. In = other + words, how many instances of the given type can still be successfu= lly + created on the physical device. + Since 3.3.0 +
+
+ +

+ For a more info about mediated devices, refer to the + paragraph below. +

+ +
+<device>
+...
+  <driver>
+    <name>nvidia</name>
+  </driver>
+  <capability type=3D'pci'>
+...
+    <capability type=3D'mdev_types'>
+      <type id=3D'nvidia-11'>
+        <name>GRID M60-0B</name>
+        <deviceAPI>vfio-pci</deviceAPI>
+        <availableInstances>16</availableInstances>
+      </type>
+      <!-- Here would come the rest of the available mdev types -->
+    </capability>
+...
+  </capability>
+</device>
+ +

Mediated devices (MDEVs)

+

+ Mediated devices (Since 3.3.0) are soft= ware + 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 perform= ance + among multiple guests. Unlike SR-IOV however, where a PCIe device ap= pears + as multiple separate PCIe devices on the host's PCI bus, mediated de= vices + 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 h= olds + an official vendor-supplied identifier for the type. + Since 3.3.0 +
+ +
iommuGroup
+
+ This element supports a single attribute number which= holds + the IOMMU group number the mediated device belongs to. + Since 3.3.0 +
+
+ +

Example of a mediated device

+ 
+<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=3D'mdev'>
+    <type id=3D'nvidia-11'/>
+    <iommuGroup number=3D'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.3.0) +
    • +
  • + display device details + (Since 3.3.0) +
    • +
+ +

+ Because mediated devices are instantiated from vendor specific templ= ates, + simply called 'types', information describing these types is contain= ed + within the parent device's capabilities + (see the example in PCI host devices).

+ + To see the supported mediated device types on a specific physical de= vice + use the following: +

+ + 
+$ ls /sys/class/mdev_bus/<device>/mdev_supported_types
+ +

+ To manually instantiate a mediated device, use one of the following = as a + reference: +

+ + 
+$ uuidgen > /sys/class/mdev_bus/<device>/mdev_supported_types/<=
;type>/create
+...
+$ echo <UUID> > /sys/class/mdev_bus/<device>/mdev_supported=
_types/<type>/create
+ +

+ Manual removal of a mediated device is then performed as follows: +

+ + 
+$ echo 1 > /sys/bus/mdev/devices/<uuid>/remove
+ --=20 2.12.2 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list