From 8c30b1e683b37d67d7fe827f6ab63174c596494e Mon Sep 17 00:00:00 2001 Message-Id: <8c30b1e683b37d67d7fe827f6ab63174c596494e@dist-git> From: Erik Skultety Date: Thu, 18 May 2017 14:02:49 +0200 Subject: [PATCH] docs: Provide a nodedev driver stub documentation 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. https://bugzilla.redhat.com/show_bug.cgi?id=1452072 Signed-off-by: Erik Skultety (cherry picked from commit a94d431dc46070034de7798f572dc1d257542a50) Signed-off-by: Erik Skultety Signed-off-by: Jiri Denemark --- docs/drivers.html.in | 6 +- docs/drvnodedev.html.in | 189 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 194 insertions(+), 1 deletion(-) create mode 100644 docs/drvnodedev.html.in diff --git a/docs/drivers.html.in b/docs/drivers.html.in index be7483b9b..61993861e 100644 --- a/docs/drivers.html.in +++ b/docs/drivers.html.in @@ -4,7 +4,11 @@

Internal drivers

-
    +

    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 000000000..0a3870343 --- /dev/null +++ b/docs/drvnodedev.html.in @@ -0,0 +1,189 @@ + + + + +

    Host device management

    + +

    + 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, DRM, etc. +

    + +

    + The node device driver provides means to list and show details about host + devices (virsh nodedev-list, + virsh nodedev-dumpxml), which are generic and can be used + with all devices. It also provides means to create and destroy devices + (virsh nodedev-create, virsh nodedev-destroy) + which are meant to be used to create virtual devices, currently only + supported by NPIV + (more info about NPIV)). + Devices on the host system are arranged in a tree-like hierarchy, with + the root node being called computer. The node device driver + supports two backends to manage the devices, HAL and udev, with the former + being deprecated in favour of the latter. +

    + +

    + 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: +

    +
    +
    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 + 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>
+  <name>pci_0000_00_17_0</name>
+  <path>/sys/devices/pci0000:00/0000:00:17.0</path>
+  <parent>computer</parent>
+  <driver>
+    <name>ahci</name>
+  </driver>
+  <capability type='pci'>
+...
+  </capability>
+</device>
    + +
      + +

      PCI host devices

      +
      +
      capability
      +
      + When used as top level element, the supported values for the + type attribute are pci and + phys_function (see SR-IOV below). +
      +
      + 
      +<device>
+  <name>pci_0000_04_00_1</name>
+  <path>/sys/devices/pci0000:00/0000:00:06.0/0000:04:00.1</path>
+  <parent>pci_0000_00_06_0</parent>
+  <driver>
+    <name>igb</name>
+  </driver>
+  <capability type='pci'>
+    <domain>0</domain>
+    <bus>4</bus>
+    <slot>0</slot>
+    <function>1</function>
+    <product id='0x10c9'>82576 Gigabit Network Connection</product>
+    <vendor id='0x8086'>Intel Corporation</vendor>
+    <iommuGroup number='15'>
+      <address domain='0x0000' bus='0x04' slot='0x00' function='0x1'/>
+    </iommuGroup>
+    <numa node='0'/>
+    <pci-express>
+      <link validity='cap' port='1' speed='2.5' width='2'/>
+      <link validity='sta' speed='2.5' width='2'/>
+    </pci-express>
+  </capability>
+</device>
      + +

      + The XML format for a PCI device stays the same for any further + capabilities it supports, a single nested <capability> + element will be included for each capability the device supports. +

      + +

      SR-IOV capability

      +

      + 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. +

      + +

      + Suppose the NIC above was also SR-IOV capable, it would + also include a nested + <capability> element enumerating all virtual + functions available on the physical device (physical port) like in the + example below. +

      + + 
      +<capability type='pci'>
+...
+  <capability type='virt_functions' maxCount='7'>
+    <address domain='0x0000' bus='0x04' slot='0x10' function='0x1'/>
+    <address domain='0x0000' bus='0x04' slot='0x10' function='0x3'/>
+    <address domain='0x0000' bus='0x04' slot='0x10' function='0x5'/>
+    <address domain='0x0000' bus='0x04' slot='0x10' function='0x7'/>
+    <address domain='0x0000' bus='0x04' slot='0x11' function='0x1'/>
+    <address domain='0x0000' bus='0x04' slot='0x11' function='0x3'/>
+    <address domain='0x0000' bus='0x04' slot='0x11' function='0x5'/>
+  </capability>
+...
+</capability>
      +

      + A SR-IOV child device on the other hand, would then report its top level + capability type as a phys_function instead: +

      + + 
      +<device>
+...
+  <capability type='phys_function'>
+    <address domain='0x0000' bus='0x04' slot='0x00' function='0x0'/>
+  </capability>
+...
+<device>
      + + + -- 2.13.0