|
 |
3e5111 |
From 8c30b1e683b37d67d7fe827f6ab63174c596494e Mon Sep 17 00:00:00 2001
|
|
|
3e5111 |
Message-Id: <8c30b1e683b37d67d7fe827f6ab63174c596494e@dist-git>
|
|
|
3e5111 |
From: Erik Skultety <eskultet@redhat.com>
|
|
|
3e5111 |
Date: Thu, 18 May 2017 14:02:49 +0200
|
|
|
3e5111 |
Subject: [PATCH] docs: Provide a nodedev driver stub documentation
|
|
|
3e5111 |
|
|
|
3e5111 |
There's lot more to document about the nodedev driver, besides PCI and
|
|
|
3e5111 |
SR-IOV (even this might need to be extended), but let's start small-ish
|
|
|
3e5111 |
and at least have a page for it linked from the drivers.html.
|
|
|
3e5111 |
|
|
|
3e5111 |
https://bugzilla.redhat.com/show_bug.cgi?id=1452072
|
|
|
3e5111 |
|
|
|
3e5111 |
Signed-off-by: Erik Skultety <eskultet@redhat.com>
|
|
|
3e5111 |
(cherry picked from commit a94d431dc46070034de7798f572dc1d257542a50)
|
|
|
3e5111 |
Signed-off-by: Erik Skultety <eskultet@redhat.com>
|
|
|
3e5111 |
Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
|
|
|
3e5111 |
---
|
|
|
3e5111 |
docs/drivers.html.in | 6 +-
|
|
|
3e5111 |
docs/drvnodedev.html.in | 189 ++++++++++++++++++++++++++++++++++++++++++++++++
|
|
|
3e5111 |
2 files changed, 194 insertions(+), 1 deletion(-)
|
|
|
3e5111 |
create mode 100644 docs/drvnodedev.html.in
|
|
|
3e5111 |
|
|
|
3e5111 |
diff --git a/docs/drivers.html.in b/docs/drivers.html.in
|
|
|
3e5111 |
index be7483b9b..61993861e 100644
|
|
|
3e5111 |
--- a/docs/drivers.html.in
|
|
|
3e5111 |
+++ b/docs/drivers.html.in
|
|
|
3e5111 |
@@ -4,7 +4,11 @@
|
|
|
3e5111 |
<body>
|
|
|
3e5111 |
Internal drivers
|
|
|
3e5111 |
|
|
|
3e5111 |
-
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ Hypervisor drivers
|
|
|
3e5111 |
+ Storage drivers
|
|
|
3e5111 |
+ Node device driver
|
|
|
3e5111 |
+
|
|
|
3e5111 |
|
|
|
3e5111 |
|
|
|
3e5111 |
The libvirt public API delegates its implementation to one or
|
|
|
3e5111 |
diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in
|
|
|
3e5111 |
new file mode 100644
|
|
|
3e5111 |
index 000000000..0a3870343
|
|
|
3e5111 |
--- /dev/null
|
|
|
3e5111 |
+++ b/docs/drvnodedev.html.in
|
|
|
3e5111 |
@@ -0,0 +1,189 @@
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+<html xmlns="http://www.w3.org/1999/xhtml">
|
|
|
3e5111 |
+ <body>
|
|
|
3e5111 |
+ Host device management
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ Libvirt provides management of both physical and virtual host devices
|
|
|
3e5111 |
+ (historically also referred to as node devices) like USB, PCI, SCSI, and
|
|
|
3e5111 |
+ network devices. This also includes various virtualization capabilities
|
|
|
3e5111 |
+ which the aforementioned devices provide for utilization, for example
|
|
|
3e5111 |
+ SR-IOV, NPIV, DRM, etc.
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ The node device driver provides means to list and show details about host
|
|
|
3e5111 |
+ devices (virsh nodedev-list,
|
|
|
3e5111 |
+ virsh nodedev-dumpxml), which are generic and can be used
|
|
|
3e5111 |
+ with all devices. It also provides means to create and destroy devices
|
|
|
3e5111 |
+ (virsh nodedev-create, virsh nodedev-destroy)
|
|
|
3e5111 |
+ which are meant to be used to create virtual devices, currently only
|
|
|
3e5111 |
+ supported by NPIV
|
|
|
3e5111 |
+ (more info about NPIV)).
|
|
|
3e5111 |
+ Devices on the host system are arranged in a tree-like hierarchy, with
|
|
|
3e5111 |
+ the root node being called computer. The node device driver
|
|
|
3e5111 |
+ supports two backends to manage the devices, HAL and udev, with the former
|
|
|
3e5111 |
+ being deprecated in favour of the latter.
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ The generic format of a host device XML can be seen below.
|
|
|
3e5111 |
+ To identify a device both within the host and the device tree hierarchy,
|
|
|
3e5111 |
+ the following elements are used:
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ name
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ The device's name will be generated by libvirt using the subsystem,
|
|
|
3e5111 |
+ like pci and the device's sysfs basename.
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ path
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ Fully qualified sysfs path to the device.
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ parent
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ This element identifies the parent node in the device hierarchy. The
|
|
|
3e5111 |
+ value of the element will correspond with the device parent's
|
|
|
3e5111 |
+ name element or computer if the device does
|
|
|
3e5111 |
+ not have any parent.
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ driver
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ This elements reports the driver in use for this device. The presence
|
|
|
3e5111 |
+ of this element in the output XML depends on whether the underlying
|
|
|
3e5111 |
+ device manager (most likely udev) exposes information about the
|
|
|
3e5111 |
+ driver.
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ capability
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ Describes the device in terms of feature support. The element has one
|
|
|
3e5111 |
+ mandatory attribute type the value of which determines
|
|
|
3e5111 |
+ the type of the device. Currently recognized values for the attribute
|
|
|
3e5111 |
+ are:
|
|
|
3e5111 |
+ system,
|
|
|
3e5111 |
+ pci,
|
|
|
3e5111 |
+ usb,
|
|
|
3e5111 |
+ usb_device,
|
|
|
3e5111 |
+ net,
|
|
|
3e5111 |
+ scsi,
|
|
|
3e5111 |
+ scsi_host (Since 0.4.7),
|
|
|
3e5111 |
+ fc_host,
|
|
|
3e5111 |
+ vports,
|
|
|
3e5111 |
+ scsi_target (Since 0.7.3),
|
|
|
3e5111 |
+ storage (Since 1.0.4),
|
|
|
3e5111 |
+ scsi_generic (Since 1.0.7),
|
|
|
3e5111 |
+ drm (Since 3.1.0), and
|
|
|
3e5111 |
+ This element can be nested in which case it further specifies a
|
|
|
3e5111 |
+ device's capability. Refer to specific device types to see more values
|
|
|
3e5111 |
+ for the type attribute which are exclusive.
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ Basic structure of a node device
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+<device>
|
|
|
3e5111 |
+ <name>pci_0000_00_17_0</name>
|
|
|
3e5111 |
+ <path>/sys/devices/pci0000:00/0000:00:17.0</path>
|
|
|
3e5111 |
+ <parent>computer</parent>
|
|
|
3e5111 |
+ <driver>
|
|
|
3e5111 |
+ <name>ahci</name>
|
|
|
3e5111 |
+ </driver>
|
|
|
3e5111 |
+ <capability type='pci'>
|
|
|
3e5111 |
+...
|
|
|
3e5111 |
+ </capability>
|
|
|
3e5111 |
+</device>
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ capability
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ When used as top level element, the supported values for the
|
|
|
3e5111 |
+ type attribute are pci and
|
|
|
3e5111 |
+ phys_function (see SR-IOV below).
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+<device>
|
|
|
3e5111 |
+ <name>pci_0000_04_00_1</name>
|
|
|
3e5111 |
+ <path>/sys/devices/pci0000:00/0000:00:06.0/0000:04:00.1</path>
|
|
|
3e5111 |
+ <parent>pci_0000_00_06_0</parent>
|
|
|
3e5111 |
+ <driver>
|
|
|
3e5111 |
+ <name>igb</name>
|
|
|
3e5111 |
+ </driver>
|
|
|
3e5111 |
+ <capability type='pci'>
|
|
|
3e5111 |
+ <domain>0</domain>
|
|
|
3e5111 |
+ <bus>4</bus>
|
|
|
3e5111 |
+ <slot>0</slot>
|
|
|
3e5111 |
+ <function>1</function>
|
|
|
3e5111 |
+ <product id='0x10c9'>82576 Gigabit Network Connection</product>
|
|
|
3e5111 |
+ <vendor id='0x8086'>Intel Corporation</vendor>
|
|
|
3e5111 |
+ <iommuGroup number='15'>
|
|
|
3e5111 |
+ <address domain='0x0000' bus='0x04' slot='0x00' function='0x1'/>
|
|
|
3e5111 |
+ </iommuGroup>
|
|
|
3e5111 |
+ <numa node='0'/>
|
|
|
3e5111 |
+ <pci-express>
|
|
|
3e5111 |
+ <link validity='cap' port='1' speed='2.5' width='2'/>
|
|
|
3e5111 |
+ <link validity='sta' speed='2.5' width='2'/>
|
|
|
3e5111 |
+ </pci-express>
|
|
|
3e5111 |
+ </capability>
|
|
|
3e5111 |
+</device>
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ The XML format for a PCI device stays the same for any further
|
|
|
3e5111 |
+ capabilities it supports, a single nested <capability>
|
|
|
3e5111 |
+ element will be included for each capability the device supports.
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ Single root input/output virtualization (SR-IOV) allows sharing of the
|
|
|
3e5111 |
+ PCIe resources by multiple virtual environments. That is achieved by
|
|
|
3e5111 |
+ slicing up a single full-featured physical resource called physical
|
|
|
3e5111 |
+ function (PF) into multiple devices called virtual functions (VFs) sharing
|
|
|
3e5111 |
+ their configuration with the underlying PF. Despite the SR-IOV
|
|
|
3e5111 |
+ specification, the amount of VFs that can be created on a PF varies among
|
|
|
3e5111 |
+ manufacturers.
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ Suppose the NIC above was also SR-IOV capable, it would
|
|
|
3e5111 |
+ also include a nested
|
|
|
3e5111 |
+ <capability> element enumerating all virtual
|
|
|
3e5111 |
+ functions available on the physical device (physical port) like in the
|
|
|
3e5111 |
+ example below.
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+<capability type='pci'>
|
|
|
3e5111 |
+...
|
|
|
3e5111 |
+ <capability type='virt_functions' maxCount='7'>
|
|
|
3e5111 |
+ <address domain='0x0000' bus='0x04' slot='0x10' function='0x1'/>
|
|
|
3e5111 |
+ <address domain='0x0000' bus='0x04' slot='0x10' function='0x3'/>
|
|
|
3e5111 |
+ <address domain='0x0000' bus='0x04' slot='0x10' function='0x5'/>
|
|
|
3e5111 |
+ <address domain='0x0000' bus='0x04' slot='0x10' function='0x7'/>
|
|
|
3e5111 |
+ <address domain='0x0000' bus='0x04' slot='0x11' function='0x1'/>
|
|
|
3e5111 |
+ <address domain='0x0000' bus='0x04' slot='0x11' function='0x3'/>
|
|
|
3e5111 |
+ <address domain='0x0000' bus='0x04' slot='0x11' function='0x5'/>
|
|
|
3e5111 |
+ </capability>
|
|
|
3e5111 |
+...
|
|
|
3e5111 |
+</capability>
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ A SR-IOV child device on the other hand, would then report its top level
|
|
|
3e5111 |
+ capability type as a phys_function instead:
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+<device>
|
|
|
3e5111 |
+...
|
|
|
3e5111 |
+ <capability type='phys_function'>
|
|
|
3e5111 |
+ <address domain='0x0000' bus='0x04' slot='0x00' function='0x0'/>
|
|
|
3e5111 |
+ </capability>
|
|
|
3e5111 |
+...
|
|
|
3e5111 |
+<device>
|
|
|
3e5111 |
+
|
|
|
3e5111 |
+ </body>
|
|
|
3e5111 |
+</html>
|
|
|
3e5111 |
--
|
|
|
3e5111 |
2.13.0
|
|
|
3e5111 |
|