From nobody Tue Feb 10 01:20:02 2026 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