From: Jonathon Jongsma Date: Thu, 21 May 2020 20:09:35 +0000 (-0500) Subject: docs: Document full node device xml in formatnode.html.in X-Git-Tag: v6.4.0-rc1~25 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=88cab64fb3088e5c29eb7c7d0bc1d69b8882d720;p=thirdparty%2Flibvirt.git docs: Document full node device xml in formatnode.html.in 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 --- diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in index a9c86f9fc7..e28af4e737 100644 --- a/docs/drvnodedev.html.in +++ b/docs/drvnodedev.html.in @@ -28,60 +28,12 @@

- The generic format of a host device XML can be seen below. - To identify a device both within the host and the device tree hierarchy, - 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 subsystem, - 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 presence - of this element in the output XML depends on whether the underlying - device manager (most likely udev) exposes information about the - driver. -
-
capability
-
- Describes the device in terms of feature support. The element has one - mandatory attribute type the value of which determines - the type of the device. Currently recognized values for the attribute - 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,14 @@
       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:
+      through sysfs. A detailed description of the XML format for the
+      mdev_types 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 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.
+      The following example shows how we might represent an NVIDIA GPU device
+      that supports mediated devices. See below for more
+      information about mediated devices.
     

 
 
@@ -262,32 +183,11 @@
       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.
+      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.
     

 
-    

-      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>
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. 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 presence
+        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, and
+                    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 identifier
+                    for the type. It supports the following sub-elements:
+                      

+                        
name

+                        

+                          The name element holds a vendor-supplied
+                          code name for the given mediated device type. This is
+                          an optional element.
+                      

+                      
deviceAPI

+                      

+                        The value of this element describes how an instance of
+                        the given type will be presented to the guest by the
+                        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 device
@@ -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 belongs
+                  to.
+              

+            

+          

           
ccw

           
Describes a Command Channel Word (CCW) device commonly found on
           the S390 architecture. Sub-elements include: