From a94d431dc46070034de7798f572dc1d257542a50 Mon Sep 17 00:00:00 2001 From: Erik Skultety Date: Mon, 27 Mar 2017 09:03:02 +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. Signed-off-by: Erik Skultety --- 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 be7483b9bc..61993861ee 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 0000000000..0a38703434 --- /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>
+ +