From nobody Mon Feb 9 02:42:56 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 1492693786642318.8918814515871; Thu, 20 Apr 2017 06:09:46 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id A41F8B0805; Thu, 20 Apr 2017 13:09:44 +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 723D77F6B7; Thu, 20 Apr 2017 13:09:44 +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 0FE7F18523CF; Thu, 20 Apr 2017 13:09:27 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id v3KD6JfW027961 for ; Thu, 20 Apr 2017 09:06:20 -0400 Received: by smtp.corp.redhat.com (Postfix) id EE65617110; Thu, 20 Apr 2017 13:06:19 +0000 (UTC) Received: from beluga.usersys.redhat.com (dhcp129-94.brq.redhat.com [10.34.129.94]) by smtp.corp.redhat.com (Postfix) with ESMTP id 50DE44DA37; Thu, 20 Apr 2017 13:06:19 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com A41F8B0805 Authentication-Results: ext-mx10.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx10.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 A41F8B0805 From: Erik Skultety To: libvir-list@redhat.com Date: Thu, 20 Apr 2017 15:06:00 +0200 Message-Id: In-Reply-To: References: In-Reply-To: References: X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-loop: libvir-list@redhat.com Cc: Erik Skultety Subject: [libvirt] [PATCH v2 10/10] 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.14 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.39]); Thu, 20 Apr 2017 13:09:45 +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, 162 insertions(+), 2 deletions(-) diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in index ed185c3df..6dece3806 100644 --- a/docs/drvnodedev.html.in +++ b/docs/drvnodedev.html.in @@ -71,7 +71,7 @@ storage (Since 1.0.4), scsi_generic (Since 1.0.7), drm (Since 3.1.0), and - mdev (Since 3.2.0). + 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. @@ -168,7 +168,7 @@ </capability>

A SR-IOV child device on the other hand, would then report its top l= evel - capability type as a physical function instead: + capability type as phys_function instead:

=20 
@@ -180,5 +180,165 @@
 ...
 <device>
=20 +

MDEV capability

+

+ A PCI device capable of creating mediated devices will include a nes= ted + capability mdev which enumerates all the supported mdev types on the + physical device, along with the type attributes available through sy= sfs: +

+ +
+
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'>
+      <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