On Mon, Apr 24, 2017 at 04:04:01PM +0200, Pavel Hrdina wrote:
On Thu, Apr 20, 2017 at 03:05:59PM +0200, Erik Skultety wrote:
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@redhat.com> --- 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 be7483b9b..61993861e 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 000000000..ed185c3df --- /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/>
You should use </p> and <p> instead of double <br/> if we are using paragraphs.
+ 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/>
Same here.
+ 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/>
Either remove the single <br/> or replace it with a pair of </p> and <p> to end current paragraph and start a new one.
+ 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> +<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></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> +<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></pre> + + <p> + The XML format for a PCI device stays the same for any further + capabilities it supports, a single nested <code><capability></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/>
Replace double <br/> with </p> and <p>.
+ Suppose the NIC <a href="#PCI">above</a> was also SR-IOV capable, it would + also include a nested + <code><capability></code> element enumerating all virtual + functions available on the physical device (physical port) like in the + example below. + </p> + + <pre> +<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></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> +<device> +... + <capability type='phys_function'> + <address domain='0x0000' bus='0x04' slot='0x00' function='0x0'/> + </capability> +... +<device></pre> + + </body> +</html> -- 2.12.2
I'm not a native speaker but the text makes sense and having something is definitely better than having no documentation at all.
ACK
Pavel
If you remove all MDEV references you can push it right away.