[RFC PATCH 10/11] docs: Provide a nodedev driver stub documentation

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



There's lot more to document about the nodedev driver, besides PCI and
SR-IOV (even this might need to be extended), but let's start small-ish
and at least have a page for it linked from the drivers.html.

Signed-off-by: Erik Skultety <eskultet@xxxxxxxxxx>
---
 docs/drivers.html.in    |   6 +-
 docs/drvnodedev.html.in | 184 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 189 insertions(+), 1 deletion(-)
 create mode 100644 docs/drvnodedev.html.in

diff --git a/docs/drivers.html.in b/docs/drivers.html.in
index be7483b9bc..61993861ee 100644
--- a/docs/drivers.html.in
+++ b/docs/drivers.html.in
@@ -4,7 +4,11 @@
   <body>
     <h1>Internal drivers</h1>
 
-    <ul id="toc"></ul>
+    <ul>
+      <li><a href="#hypervisor">Hypervisor drivers</a></li>
+      <li><a href="#storage">Storage drivers</a></li>
+      <li><a href="drvnodedev.html">Node device driver</a></li>
+    </ul>
 
     <p>
       The libvirt public API delegates its implementation to one or
diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in
new file mode 100644
index 0000000000..ed185c3df3
--- /dev/null
+++ b/docs/drvnodedev.html.in
@@ -0,0 +1,184 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd";>
+<html xmlns="http://www.w3.org/1999/xhtml";>
+  <body>
+    <h1>Host device management</h1>
+
+    <p>
+      Libvirt provides management of both physical and virtual host devices
+      (historically also referred to as node devices) like USB, PCI, SCSI, and
+      network devices. This also includes various virtualization capabilities
+      which the aforementioned devices provide for utilization, for example
+      SR-IOV, NPIV, MDEV, DRM, etc. <br/>
+      <br/>
+      The node device driver provides means to list and show details about host
+      devices (<code>virsh nodedev-list</code>,
+      <code>virsh nodedev-dumpxml</code>), which are generic and can be used
+      with all devices. It also provides means to create and destroy devices
+      (<code>virsh nodedev-create</code>, <code>virsh nodedev-destroy</code>)
+      which are meant to be used to create virtual devices, currently only
+      supported by NPIV
+      (<a href="http://wiki.libvirt.org/page/NPIV_in_libvirt";>more info about NPIV)</a>). <br/>
+      <br/>
+      Devices on the host system are arranged in a tree-like hierarchy, with
+      the root node being called <code>computer</code>. The node device driver
+      supports two backends to manage the devices, HAL and udev, with the former
+      being deprecated in favour of the latter.<br/>
+      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:
+    </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.2.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;
+  &lt;name&gt;pci_0000_00_17_0&lt;/name&gt;
+  &lt;path&gt;/sys/devices/pci0000:00/0000:00:17.0&lt;/path&gt;
+  &lt;parent&gt;computer&lt;/parent&gt;
+  &lt;driver&gt;
+    &lt;name&gt;ahci&lt;/name&gt;
+  &lt;/driver&gt;
+  &lt;capability type='pci'&gt;
+...
+  &lt;/capability&gt;
+&lt;/device&gt;</pre>
+
+    <ul id="toc"/>
+
+    <h2><a name="PCI">PCI host devices</a></h2>
+    <dl>
+      <dt><code>capability</code></dt>
+      <dd>
+        When used as top level element, the supported values for the
+        <code>type</code> attribute are <code>pci</code> and
+        <code>phys_function</code> (see <a href="#SRIOVCap">SR-IOV below</a>).
+      </dd>
+    </dl>
+    <pre>
+&lt;device&gt;
+  &lt;name&gt;pci_0000_04_00_1&lt;/name&gt;
+  &lt;path&gt;/sys/devices/pci0000:00/0000:00:06.0/0000:04:00.1&lt;/path&gt;
+  &lt;parent&gt;pci_0000_00_06_0&lt;/parent&gt;
+  &lt;driver&gt;
+    &lt;name&gt;igb&lt;/name&gt;
+  &lt;/driver&gt;
+  &lt;capability type='pci'&gt;
+    &lt;domain&gt;0&lt;/domain&gt;
+    &lt;bus&gt;4&lt;/bus&gt;
+    &lt;slot&gt;0&lt;/slot&gt;
+    &lt;function&gt;1&lt;/function&gt;
+    &lt;product id='0x10c9'&gt;82576 Gigabit Network Connection&lt;/product&gt;
+    &lt;vendor id='0x8086'&gt;Intel Corporation&lt;/vendor&gt;
+    &lt;iommuGroup number='15'&gt;
+      &lt;address domain='0x0000' bus='0x04' slot='0x00' function='0x1'/&gt;
+    &lt;/iommuGroup&gt;
+    &lt;numa node='0'/&gt;
+    &lt;pci-express&gt;
+      &lt;link validity='cap' port='1' speed='2.5' width='2'/&gt;
+      &lt;link validity='sta' speed='2.5' width='2'/&gt;
+    &lt;/pci-express&gt;
+  &lt;/capability&gt;
+&lt;/device&gt;</pre>
+
+    <p>
+      The XML format for a PCI device stays the same for any further
+      capabilities it supports, a single nested <code>&lt;capability&gt;</code>
+      element will be included for each capability the device supports.
+    </p>
+
+    <h3><a name="SRIOVCap">SR-IOV capability</a></h3>
+    <p>
+      Single root input/output virtualization (SR-IOV) allows sharing of the
+      PCIe resources by multiple virtual environments. That is achieved by
+      slicing up a single full-featured physical resource called physical
+      function (PF) into multiple devices called virtual functions (VFs) sharing
+      their configuration with the underlying PF. Despite the SR-IOV
+      specification, the amount of VFs that can be created on a PF varies among
+      manufacturers.<br/>
+      <br/>
+      Suppose the NIC <a href="#PCI">above</a> was also SR-IOV capable, it would
+      also include a nested
+      <code>&lt;capability&gt;</code> element enumerating all virtual
+      functions available on the physical device (physical port) like in the
+      example below.
+    </p>
+
+    <pre>
+&lt;capability type='pci'&gt;
+...
+  &lt;capability type='virt_functions' maxCount='7'&gt;
+    &lt;address domain='0x0000' bus='0x04' slot='0x10' function='0x1'/&gt;
+    &lt;address domain='0x0000' bus='0x04' slot='0x10' function='0x3'/&gt;
+    &lt;address domain='0x0000' bus='0x04' slot='0x10' function='0x5'/&gt;
+    &lt;address domain='0x0000' bus='0x04' slot='0x10' function='0x7'/&gt;
+    &lt;address domain='0x0000' bus='0x04' slot='0x11' function='0x1'/&gt;
+    &lt;address domain='0x0000' bus='0x04' slot='0x11' function='0x3'/&gt;
+    &lt;address domain='0x0000' bus='0x04' slot='0x11' function='0x5'/&gt;
+  &lt;/capability&gt;
+...
+&lt;/capability&gt;</pre>
+    <p>
+      A SR-IOV child device on the other hand, would then report its top level
+      capability type as a physical function instead:
+    </p>
+
+    <pre>
+&lt;device&gt;
+...
+  &lt;capability type='phys_function'&gt;
+    &lt;address domain='0x0000' bus='0x04' slot='0x00' function='0x0'/&gt;
+  &lt;/capability&gt;
+...
+&lt;device&gt;</pre>
+
+  </body>
+</html>
-- 
2.12.2

--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list



[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]
  Powered by Linux