From nobody Thu Apr 25 21:18:22 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) client-ip=207.211.31.120; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1590091797; cv=none; d=zohomail.com; s=zohoarc; b=baNIP+gXXr6rDUFWz5GElk5oderjhFyo6yJxinsnISpyp0KMZw9ZoaWtqy4foQUu9wxuHZLkPkDQEPzpWCDdTXABDc5w4LZUfMOIAVmfk0s4CJnxTyqXL1hKqyIYygPZX1XPxMfDp+9FORqmJgUR7mjXHFLbV0ecWRZHCeJzxBw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1590091797; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=r5I5YQllD03dwgexK7ClWr5WQoQt+aolGwjpgeLhEe4=; b=DExVMpc8DcWmGVa+rwoMWQDlB6IB0YzMKFz3xLNdnWVhugpVf51+b6ilVCfypeBNV4zrPd9iIlpgheyte06vO6IjW5xd8H8ry8RrdITFum+fekCitZ0WaodL44tMEJZ9NEmBfB1Spo8p1r/44yL++60MZuCseThcakQMfxu24nc= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [207.211.31.120]) by mx.zohomail.com with SMTPS id 1590091797197591.2886575573082; Thu, 21 May 2020 13:09:57 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-491-j1l75nBvNlqMI5q4wJVDrw-1; Thu, 21 May 2020 16:09:54 -0400 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 4F16E100A61D; Thu, 21 May 2020 20:09:48 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 08AF260C05; Thu, 21 May 2020 20:09:48 +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 BE1D654D06; Thu, 21 May 2020 20:09:47 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 04LK9dRD028369 for ; Thu, 21 May 2020 16:09:39 -0400 Received: by smtp.corp.redhat.com (Postfix) id A2AB25632D; Thu, 21 May 2020 20:09:39 +0000 (UTC) Received: from himantopus.redhat.com (ovpn-112-181.phx2.redhat.com [10.3.112.181]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 75E7F56324 for ; Thu, 21 May 2020 20:09:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1590091796; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=r5I5YQllD03dwgexK7ClWr5WQoQt+aolGwjpgeLhEe4=; b=HBNESI+EBIJgIyztRHuc+0EUdEioJwOHUIud3WWMrsXgwdPttsK3au2V3SDFAJN/5QBvUX AiJVAB1AIuveIjHe19kLWn2BsqDgS2+OMMLDpwJsIuwEmuVu/7W0kdilwv00MOXFHLi/eU /PCKBTaoc1BhxsZXesgZbR7dCQVWyUo= X-MC-Unique: j1l75nBvNlqMI5q4wJVDrw-1 From: Jonathon Jongsma To: libvir-list@redhat.com Subject: [libvirt PATCH 1/2] docs: Fix names for PF and VF PCI device capabilities Date: Thu, 21 May 2020 15:09:34 -0500 Message-Id: <20200521200935.19237-2-jjongsma@redhat.com> In-Reply-To: <20200521200935.19237-1-jjongsma@redhat.com> References: <20200521200935.19237-1-jjongsma@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-loop: libvir-list@redhat.com 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: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" The proper name for physical function capability is 'phys_function', not 'physical_function'. Likewise, a virtual function capability is 'virt_functions' rather than 'virtual_function'. Signed-off-by: Jonathon Jongsma Reviewed-by: Erik Skultety --- docs/formatnode.html.in | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/formatnode.html.in b/docs/formatnode.html.in index c2a8f8fb7a..7dcd3638ff 100644 --- a/docs/formatnode.html.in +++ b/docs/formatnode.html.in @@ -109,7 +109,7 @@ exists, it has a mandatory type attribute which will be set to:
-
physical_function
+
phys_function
That means there will be a single address subelement which contains the PCI address of the SRIOV @@ -117,7 +117,7 @@ (and this device is, by implication, an SRIOV Virtual Function (VF)).
-
virtual_function
+
virt_functions
In this case this device is an SRIOV PF, and the capab= ility element will have a list of address --=20 2.21.3 From nobody Thu Apr 25 21:18:22 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 207.211.31.81 as permitted sender) client-ip=207.211.31.81; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.81 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1590091794; cv=none; d=zohomail.com; s=zohoarc; b=WaScwo53pFNEoPYRNId0K/2mGA0cvyoYRQx2SOkBdhGi9waoRseSw1m2KyhApAlCksiQWxMpFIC8fWr0I7mhTdWLUZVHqKtv8hg73ZVJK1/uS/kraYyZKiETY5w1wchPWhJoy3Mo+uB14aFAc0rrqAfS0YSmxasqpl3NR38Fwnw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1590091794; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=rL8oNXEa4c57bLrbpJlMrhQKcJHeBXUrznT1oeOeU9k=; b=kUtgAFKBPGP2q88RpFl6Md3z0o6s54MiWvlZdkocF+eVyV9LhcH4P0sjiHCbrup7yFAOLOf2nNN11InqLiG8UfQ9ZPRqFlwy8/cvNM+KQGgSaXC8mPFJ/TMTn8/pKrCZ+M0RWxFfO2D04Nfem2Oqsyt7bLKL0pknjHXGU+hGnCo= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.81 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-1.mimecast.com (us-smtp-2.mimecast.com [207.211.31.81]) by mx.zohomail.com with SMTPS id 1590091794427812.2168964892492; Thu, 21 May 2020 13:09:54 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-407-NBSti5ZoMrmI7RTPRORKoQ-1; Thu, 21 May 2020 16:09:51 -0400 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id B2D671800D42; Thu, 21 May 2020 20:09:45 +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 18C6456330; Thu, 21 May 2020 20:09:45 +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 1256118095FF; Thu, 21 May 2020 20:09:42 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 04LK9d9P028375 for ; Thu, 21 May 2020 16:09:39 -0400 Received: by smtp.corp.redhat.com (Postfix) id ED93B56324; Thu, 21 May 2020 20:09:39 +0000 (UTC) Received: from himantopus.redhat.com (ovpn-112-181.phx2.redhat.com [10.3.112.181]) by smtp.corp.redhat.com (Postfix) with ESMTPS id BED6156330 for ; Thu, 21 May 2020 20:09:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1590091793; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=rL8oNXEa4c57bLrbpJlMrhQKcJHeBXUrznT1oeOeU9k=; b=hd28eC0WT6tisaA/eYayRNS1wjr5Vb1M1iHgImtxtEAv9QHKstM1z88BVtdvzFGpX03JbO JEJGvleCaRCWcfmo/lB9G+IaZbmKGQ7n0JxdxpNAdlHSbLz0YT7b8LsFfAwUFwnX08kAvn kjycZt5pDe9rz7S/dp3K6TJjR4sZdH0= X-MC-Unique: NBSti5ZoMrmI7RTPRORKoQ-1 From: Jonathon Jongsma To: libvir-list@redhat.com Subject: [libvirt PATCH 2/2] docs: Document full node device xml in formatnode.html.in Date: Thu, 21 May 2020 15:09:35 -0500 Message-Id: <20200521200935.19237-3-jjongsma@redhat.com> In-Reply-To: <20200521200935.19237-1-jjongsma@redhat.com> References: <20200521200935.19237-1-jjongsma@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-loop: libvir-list@redhat.com 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: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" Some of the node device xml schema was documented in drvnodedev.html.in rather than in formatnode.html.in. Move all of the schema documentation to formatnode.html.in and provide reference links from the drvnodedev.html.in page. Signed-off-by: Jonathon Jongsma Reviewed-by: Erik Skultety --- docs/drvnodedev.html.in | 127 ++++------------------------------------ docs/formatnode.html.in | 70 +++++++++++++++++++++- 2 files changed, 81 insertions(+), 116 deletions(-) diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in index 71a8a57b0c..90af2ea4ff 100644 --- a/docs/drvnodedev.html.in +++ b/docs/drvnodedev.html.in @@ -28,60 +28,12 @@

=20

- The generic format of a host device XML can be seen below. - To identify a device both within the host and the device tree hierar= chy, - the following elements are used: + Details of the XML format of a host device can be found here. Of particular interest is the + capability element, which describes features supported = by + the device. Some specific device types are addressed in more detail + below.

-
-
name
-
- The device's name will be generated by libvirt using the subsyst= em, - like pci and the device's sysfs basename. -
-
path
-
- Fully qualified sysfs path to the device. -
-
parent
-
- This element identifies the parent node in the device hierarchy.= The - value of the element will correspond with the device parent's - name element or computer if the device= does - not have any parent. -
-
driver
-
- This elements reports the driver in use for this device. The pre= sence - of this element in the output XML depends on whether the underly= ing - device manager (most likely udev) exposes information about the - driver. -
-
capability
-
- Describes the device in terms of feature support. The element ha= s one - mandatory attribute type the value of which determi= nes - the type of the device. Currently recognized values for the attr= ibute - are: - system, - pci, - usb, - usb_device, - net, - scsi, - scsi_host (Since 0.4.7= ), - fc_host, - vports, - scsi_target (Since 0.7.3), - 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. -
-
-

Basic structure of a node device

 <device>
@@ -191,45 +143,13 @@
       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:
+      through sysfs. A detailed description of the XML format for the mdev
+      capability can be found here.
     

-
-    

-      
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.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 t=
ype
-        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 successfu=
lly
-        created on the physical device.
-        Since 3.4.0
-      

-    

-
     

-      For a more info about mediated devices, refer to the
-      paragraph below.
+      The following example shows how we might represent an Nvidia GPU dev=
ice
+      that supports mediated devices. See below for more
+      information about mediated devices.
     

=20
 
@@ -262,32 +182,11 @@
       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.
+      mediated devices are used in a direct device assignment manner.  A
+      detailed description of the XML format for the mdev capability can be
+      found here.
     

=20
-    

-      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.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>
diff --git a/docs/formatnode.html.in b/docs/formatnode.html.in
index 7dcd3638ff..76eae928de 100644
--- a/docs/formatnode.html.in
+++ b/docs/formatnode.html.in
@@ -33,9 +33,23 @@
         to provide more specific names, such as
         "net_eth1_00_27_13_6a_fe_00".
+
path
+
+ Fully qualified sysfs path to the device. +
parent
-
If this element is present, it names the parent device (that - is, a controller to which this node belongs). +
+ This element identifies the parent node in the device hierarchy. T= he + value of the element will correspond with the device parent's + name element or computer if the device d= oes + not have any parent. +
+
driver
+
+ This elements reports the driver in use for this device. The prese= nce + of this element in the output XML depends on whether the underlying + device manager (most likely udev) exposes information about the + driver.
devnode
This node appears for each associated /dev @@ -138,8 +152,40 @@ means such device cannot be used for PCI passthrough. Since 1.3.3
+
mdev_types
+
+ This device is capable of creating mediated devices, a= nd + the capability will contain a list of type + elements, which list all mdev types supported on the + physical device. Since 3.4.0 + Each type element has a single id + attribute that holds an official vendor-supplied ident= ifier + for the type. It supports the following sub-elements: +
+
name
+
+ The name element holds a vendor-sup= plied + code name for the given mediated device type. Th= is is + an optional element. +
+
deviceAPI
+
+ The value of this element describes how an instanc= e of + the given type will be presented to the guest by t= he + VFIO framework. +
+
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. +
+
+
+
numa
This optional element contains information on the PCI devi= ce @@ -329,6 +375,26 @@ render.
+
mdev
+
Describes a mediated device. Since + 3.4.0 Sub-elements include: +
+
type
+
+ 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. +
+
iommuGroup
+
+ This element supports a single attribute number + which holds the IOMMU group number the mediated device bel= ongs + to. +
+
+
ccw
Describes a Command Channel Word (CCW) device commonly found= on the S390 architecture. Sub-elements include: --=20 2.21.3