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/>
+ 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/>
+ 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/>
+ 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/>
+ 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
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
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/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/>
>+ 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/>
^
Extra parenthesis ------------------------------------------------------------------'
Jan
>+ <br/>
>+ 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/>
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
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 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
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. -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
> > 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. I did so and pushed the documentation stub. Thanks, Erik -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
© 2016 - 2026 Red Hat, Inc.