[libvirt] [PATCH v2 09/10] docs: Provide a nodedev driver stub documentation

Mon Apr 24 14:04:01 UTC 2017

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 at 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 and instead of double 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 or replace it with a pair of and 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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: Digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20170424/fb45dbec/attachment-0001.sig>