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 <jjongsma@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>

diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in
index a9c86f9fc709e42f8c3e4a5fe8cb10b3369f58ee..e28af4e737d621d189f8f0810ca21786eb38c51f 100644 (file)
--- a/docs/drvnodedev.html.in
+++ b/docs/drvnodedev.html.in
@@ -28,60 +28,12 @@
     </p>
 
     <p>
-      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 <a
+      href="formatnode.html">here</a>. Of particular interest is the
+      <code>capability</code> element, which describes features supported by
+      the device. Some specific device types are addressed in more detail
+      below.
     </p>
-      <dl>
-        <dt><code>name</code></dt>
-        <dd>
-          The device's name will be generated by libvirt using the subsystem,
-          like pci and the device's sysfs basename.
-        </dd>
-        <dt><code>path</code></dt>
-        <dd>
-          Fully qualified sysfs path to the device.
-        </dd>
-        <dt><code>parent</code></dt>
-        <dd>
-          This element identifies the parent node in the device hierarchy. The
-          value of the element will correspond with the device parent's
-          <code>name</code> element or <code>computer</code> if the device does
-          not have any parent.
-        </dd>
-        <dt><code>driver</code></dt>
-        <dd>
-          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.
-        </dd>
-        <dt><code>capability</code></dt>
-        <dd>
-          Describes the device in terms of feature support. The element has one
-          mandatory attribute <code>type</code> the value of which determines
-          the type of the device. Currently recognized values for the attribute
-          are:
-          <code>system</code>,
-          <code>pci</code>,
-          <code>usb</code>,
-          <code>usb_device</code>,
-          <code>net</code>,
-          <code>scsi</code>,
-          <code>scsi_host</code> (<span class="since">Since 0.4.7</span>),
-          <code>fc_host</code>,
-          <code>vports</code>,
-          <code>scsi_target</code> (<span class="since">Since 0.7.3</span>),
-          <code>storage</code> (<span class="since">Since 1.0.4</span>),
-          <code>scsi_generic</code> (<span class="since">Since 1.0.7</span>),
-          <code>drm</code> (<span class="since">Since 3.1.0</span>), and
-          <code>mdev</code> (<span class="since">Since 3.4.0</span>).
-          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 <code>type</code> attribute which are exclusive.
-        </dd>
-      </dl>
-
     <h2>Basic structure of a node device</h2>
     <pre>
 &lt;device&gt;
@@ -191,45 +143,14 @@
       A PCI device capable of creating mediated devices will include a nested
       capability <code>mdev_types</code> 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
+      <code>mdev_types</code> capability can be found
+      <a href="formatnode.html#MDEVCap">here</a>.
     </p>
-
-    <dl>
-      <dt><code>type</code></dt>
-      <dd>
-        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 <code>id</code> which holds
-        an official vendor-supplied identifier for the type.
-        <span class="since">Since 3.4.0</span>
-      </dd>
-
-      <dt><code>name</code></dt>
-      <dd>
-        The <code>name</code> element holds a vendor-supplied code name for
-        the given mediated device type. This is an optional element.
-        <span class="since">Since 3.4.0</span>
-      </dd>
-
-      <dt><code>deviceAPI</code></dt>
-      <dd>
-        The value of this element describes how an instance of the given type
-        will be presented to the guest by the VFIO framework.
-        <span class="since">Since 3.4.0</span>
-      </dd>
-
-      <dt><code>availableInstances</code></dt>
-      <dd>
-        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.
-        <span class="since">Since 3.4.0</span>
-      </dd>
-    </dl>
-
     <p>
-      For a more info about mediated devices, refer to the
-      <a href="#MDEV">paragraph below</a>.
+      The following example shows how we might represent an NVIDIA GPU device
+      that supports mediated devices. See below for <a href="#MDEV">more
+      information about mediated devices</a>.
     </p>
 
 <pre>
@@ -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 <code>mdev</code>
+      capability can be found <a href="formatnode.html#mdev">here</a>.
     </p>
 
-    <p>
-      The following sub-elements and attributes are exposed within the
-      <code>capability</code> element:
-    </p>
-
-    <dl>
-      <dt><code>type</code></dt>
-      <dd>
-        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 <code>id</code> which holds
-        an official vendor-supplied identifier for the type.
-        <span class="since">Since 3.4.0</span>
-      </dd>
-
-      <dt><code>iommuGroup</code></dt>
-      <dd>
-        This element supports a single attribute <code>number</code> which holds
-        the IOMMU group number the mediated device belongs to.
-        <span class="since">Since 3.4.0</span>
-      </dd>
-    </dl>
-
     <h3>Example of a mediated device</h3>
     <pre>
 &lt;device&gt;

diff --git a/docs/formatnode.html.in b/docs/formatnode.html.in
index 7dcd3638ffb2d8aa72f309b60a492fa45bbad9b3..76eae928dea597ea2ccbc884239e11fa231fe751 100644 (file)
--- 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".
       </dd>
+      <dt><code>path</code></dt>
+      <dd>
+        Fully qualified sysfs path to the device.
+      </dd>
       <dt><code>parent</code></dt>
-      <dd>If this element is present, it names the parent device (that
-        is, a controller to which this node belongs).
+      <dd>
+        This element identifies the parent node in the device hierarchy. The
+        value of the element will correspond with the device parent's
+        <code>name</code> element or <code>computer</code> if the device does
+        not have any parent.
+      </dd>
+      <dt><code>driver</code></dt>
+      <dd>
+        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.
       </dd>
       <dt><code>devnode</code></dt>
       <dd>This node appears for each associated <code>/dev</code>
@@ -138,8 +152,40 @@
                     means such device cannot be used for PCI passthrough.
                     <span class="since">Since 1.3.3</span>
                   </dd>
+                  <dt><code><a id="MDEVCap">mdev_types</a></code></dt>
+                  <dd>
+                    This device is capable of creating mediated devices, and
+                    the capability will contain a list of <code>type</code>
+                    elements, which list all mdev types supported on the
+                    physical device. <span class="since">Since 3.4.0</span>
+                    Each <code>type</code> element has a single <code>id</code>
+                    attribute that holds an official vendor-supplied identifier
+                    for the type. It supports the following sub-elements:
+                      <dl>
+                        <dt><code>name</code></dt>
+                        <dd>
+                          The <code>name</code> element holds a vendor-supplied
+                          code name for the given mediated device type. This is
+                          an optional element.
+                      </dd>
+                      <dt><code>deviceAPI</code></dt>
+                      <dd>
+                        The value of this element describes how an instance of
+                        the given type will be presented to the guest by the
+                        VFIO framework.
+                      </dd>
+                      <dt><code>availableInstances</code></dt>
+                      <dd>
+                        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.
+                    </dd>
+                  </dl>
+                </dd>
                 </dl>
               </dd>
+
               <dt><code>numa</code></dt>
               <dd>
                 This optional element contains information on the PCI device
@@ -329,6 +375,26 @@
               <code>render</code>.</dd>
             </dl>
           </dd>
+          <dt><a id="mdev"><code>mdev</code></a></dt>
+          <dd>Describes a mediated device.  <span class="since">Since
+            3.4.0</span> Sub-elements include:
+            <dl>
+              <dt><code>type</code></dt>
+              <dd>
+                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
+                <code>id</code> which holds an official vendor-supplied
+                identifier for the type.
+              </dd>
+              <dt><code>iommuGroup</code></dt>
+              <dd>
+                This element supports a single attribute <code>number</code>
+                which holds the IOMMU group number the mediated device belongs
+                  to.
+              </dd>
+            </dl>
+          </dd>
           <dt><code>ccw</code></dt>
           <dd>Describes a Command Channel Word (CCW) device commonly found on
           the S390 architecture. Sub-elements include: