[PATCH 07/29] docs: Convert 'drvnodedev' page to rST
Peter Krempa
pkrempa at redhat.com
Mon Mar 28 12:10:22 UTC 2022
Fix one cross link anchor along with the conversion.
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
docs/drvnodedev.html.in | 383 ----------------------------------------
docs/drvnodedev.rst | 348 ++++++++++++++++++++++++++++++++++++
docs/formatdomain.rst | 3 +-
docs/meson.build | 2 +-
4 files changed, 351 insertions(+), 385 deletions(-)
delete mode 100644 docs/drvnodedev.html.in
create mode 100644 docs/drvnodedev.rst
diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in
deleted file mode 100644
index ee75eeb25c..0000000000
--- a/docs/drvnodedev.html.in
+++ /dev/null
@@ -1,383 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<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.
- </p>
-
- <p>
- The node device driver provides means to list and show details about host
- devices (<code>virsh nodedev-list</code>, <code>virsh nodedev-info</code>,
- and <code>virsh nodedev-dumpxml</code>), which are generic and can be used
- with all devices. It also provides the means to manage virtual devices.
- Persistently-defined virtual devices are only supported for mediated
- devices, while transient devices are supported by both mediated devices
- and NPIV (<a href="https://wiki.libvirt.org/page/NPIV_in_libvirt">more
- info about NPIV)</a>).
- </p>
- <p>
- Persistent virtual devices are managed with
- <code>virsh nodedev-define</code> and <code>virsh nodedev-undefine</code>.
- Persistent devices can be configured to start manually or automatically
- using <code>virsh nodedev-autostart</code>. Inactive devices can be made
- active with <code>virsh nodedev-start</code>.
- </p>
- <p>
- Transient virtual devices are started and stopped with the commands
- <code>virsh nodedev-create</code> and <code>virsh nodedev-destroy</code>.
- </p>
- <p>
- 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 udev backend (HAL backend was removed in <code>6.8.0</code>).
- </p>
-
- <p>
- Details of the XML format of a host device can be found <a
- href="formatnode.html">here</a>. Of particular interest is the
- <code>capability</code> element, which describes features supported by
- the device. Some specific device types are addressed in more detail
- below.
- </p>
- <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 id="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 id="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.
- </p>
-
- <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 <code>phys_function</code> instead:
- </p>
-
- <pre>
-<device>
-...
- <capability type='phys_function'>
- <address domain='0x0000' bus='0x04' slot='0x00' function='0x0'/>
- </capability>
-...
-</device></pre>
-
- <h3><a id="MDEVCap">MDEV capability</a></h3>
- <p>
- A device capable of creating mediated devices will include a nested
- capability <code>mdev_types</code> which enumerates all supported mdev
- types on the physical device, along with the type attributes available
- through sysfs. A detailed description of the XML format for the
- <code>mdev_types</code> capability can be found
- <a href="formatnode.html#MDEVTypesCap">here</a>.
- </p>
- <p>
- The following example shows how we might represent an NVIDIA GPU device
- that supports mediated devices. See below for <a href="#MDEV">more
- information about mediated devices</a>.
- </p>
-
-<pre>
-<device>
-...
- <driver>
- <name>nvidia</name>
- </driver>
- <capability type='pci'>
-...
- <capability type='mdev_types'>
- <type id='nvidia-11'>
- <name>GRID M60-0B</name>
- <deviceAPI>vfio-pci</deviceAPI>
- <availableInstances>16</availableInstances>
- </type>
- <!-- Here would come the rest of the available mdev types -->
- </capability>
-...
- </capability>
-</device></pre>
-
- <h3><a id="VPDCap">VPD capability</a></h3>
- <p>
- A device that exposes a PCI/PCIe VPD capability will include a nested
- capability <code>vpd</code> which presents data stored in the Vital Product
- Data (VPD). VPD provides a device name and a number of other standard-defined
- read-only fields (change level, manufacture id, part number, serial number) and
- vendor-specific read-only fields. Additionally, if a device supports it,
- read-write fields (asset tag, vendor-specific fields or system fields) may
- also be present. The VPD capability is optional for PCI/PCIe devices and the
- set of exposed fields may vary depending on a device. The XML format follows
- the binary format described in "I.3. VPD Definitions" in PCI Local Bus (2.2+)
- and the identical format in PCIe 4.0+. At the time of writing, the support for
- exposing this capability is only present on Linux-based systems (kernel version
- v2.6.26 is the first one to expose VPD via sysfs which Libvirt relies on).
- Reading the VPD contents requires root privileges, therefore,
- <code>virsh nodedev-dumpxml</code> must be executed accordingly.
- A description of the XML format for the <code>vpd</code> capability can
- be found <a href="formatnode.html#VPDCap">here</a>.
- </p>
- <p>
- The following example shows a VPD representation for a device that exposes the
- VPD capability with read-only and read-write fields. Among other things,
- the VPD of this particular device includes a unique board serial number.
- </p>
-<pre>
-<device>
- <name>pci_0000_42_00_0</name>
- <capability type='pci'>
- <class>0x020000</class>
- <domain>0</domain>
- <bus>66</bus>
- <slot>0</slot>
- <function>0</function>
- <product id='0xa2d6'>MT42822 BlueField-2 integrated ConnectX-6 Dx network controller</product>
- <vendor id='0x15b3'>Mellanox Technologies</vendor>
- <capability type='virt_functions' maxCount='16'/>
- <capability type='vpd'>
- <name>BlueField-2 DPU 25GbE Dual-Port SFP56, Crypto Enabled, 16GB on-board DDR, 1GbE OOB management, Tall Bracket</name>
- <fields access='readonly'>
- <change_level>B1</change_level>
- <manufacture_id>foobar</manufacture_id>
- <part_number>MBF2H332A-AEEOT</part_number>
- <serial_number>MT2113X00000</serial_number>
- <vendor_field index='0'>PCIeGen4 x8</vendor_field>
- <vendor_field index='2'>MBF2H332A-AEEOT</vendor_field>
- <vendor_field index='3'>3c53d07eec484d8aab34dabd24fe575aa</vendor_field>
- <vendor_field index='A'>MLX:MN=MLNX:CSKU=V2:UUID=V3:PCI=V0:MODL=BF2H332A</vendor_field>
- </fields>
- <fields access='readwrite'>
- <asset_tag>fooasset</asset_tag>
- <vendor_field index='0'>vendorfield0</vendor_field>
- <vendor_field index='2'>vendorfield2</vendor_field>
- <vendor_field index='A'>vendorfieldA</vendor_field>
- <system_field index='B'>systemfieldB</system_field>
- <system_field index='0'>systemfield0</system_field>
- </fields>
- </capability>
- <iommuGroup number='65'>
- <address domain='0x0000' bus='0x42' slot='0x00' function='0x0'/>
- </iommuGroup>
- <numa node='0'/>
- <pci-express>
- <link validity='cap' port='0' speed='16' width='8'/>
- <link validity='sta' speed='8' width='8'/>
- </pci-express>
- </capability>
-</device>
-</pre>
-
- <h2><a id="MDEV">Mediated devices (MDEVs)</a></h2>
- <p>
- Mediated devices (<span class="since">Since 3.2.0</span>) are software
- devices defining resource allocation on the backing physical device which
- in turn allows the parent physical device's resources to be divided into
- several mediated devices, thus sharing the physical device's performance
- among multiple guests. Unlike SR-IOV however, where a PCIe device appears
- as multiple separate PCIe devices on the host's PCI bus, mediated devices
- only appear on the mdev virtual bus. Therefore, no detach/reattach
- procedure from/to the host driver procedure is involved even though
- mediated devices are used in a direct device assignment manner. A
- detailed description of the XML format for the <code>mdev</code>
- capability can be found <a href="formatnode.html#mdev">here</a>.
- </p>
-
- <h3>Example of a mediated device</h3>
- <pre>
-<device>
- <name>mdev_4b20d080_1b54_4048_85b3_a6a62d165c01</name>
- <path>/sys/devices/pci0000:00/0000:00:02.0/4b20d080-1b54-4048-85b3-a6a62d165c01</path>
- <parent>pci_0000_06_00_0</parent>
- <driver>
- <name>vfio_mdev</name>
- </driver>
- <capability type='mdev'>
- <type id='nvidia-11'/>
- <uuid>4b20d080-1b54-4048-85b3-a6a62d165c01</uuid>
- <iommuGroup number='12'/>
- </capability>
-</device></pre>
-
- <p>
- The support of mediated device's framework in libvirt's node device driver
- covers the following features:
- </p>
-
- <ul>
- <li>
- list available mediated devices on the host
- (<span class="since">Since 3.4.0</span>)
- </li>
- <li>
- display device details
- (<span class="since">Since 3.4.0</span>)
- </li>
- <li>
- create transient mediated devices
- (<span class="since">Since 6.5.0</span>)
- </li>
- <li>
- define persistent mediated devices
- (<span class="since">Since 7.3.0</span>)
- </li>
- </ul>
-
- <p>
- Because mediated devices are instantiated from vendor specific templates,
- simply called 'types', information describing these types is contained
- within the parent device's capabilities (see the example in <a
- href="#PCI">PCI host devices</a>). To list all devices capable of
- creating mediated devices, the following command can be used.
- </p>
- <pre>$ virsh nodedev-list --cap mdev_types</pre>
-
- <p>
- To see the supported mediated device types on a specific physical device
- use the following:
- </p>
-
- <pre>$ virsh nodedev-dumpxml <device></pre>
-
- <p>
- Before creating a mediated device, unbind the device from the respective
- device driver, eg. subchannel I/O driver for a CCW device. Then bind the
- device to the respective VFIO driver. For a CCW device, also unbind the
- corresponding subchannel of the CCW device from the subchannel I/O driver
- and then bind the subchannel (instead of the CCW device) to the vfio_ccw
- driver. The below example shows the unbinding and binding steps for a CCW
- device.
- </p>
-
- <pre>
-device="0.0.1234"
-subchannel="0.0.0123"
-echo $device > /sys/bus/ccw/devices/$device/driver/unbind
-echo $subchannel > /sys/bus/css/devices/$subchannel/driver/unbind
-echo $subchannel > /sys/bus/css/drivers/vfio_ccw/bind
- </pre>
-
- <p>
- To instantiate a transient mediated device, create an XML file representing the
- device. See above for information about the mediated device xml format.
- </p>
-
- <pre>$ virsh nodedev-create <xml-file>
-Node device '<device-name>' created from '<xml-file>'</pre>
-
- <p>
- If you would like to persistently define the device so that it will be
- maintained across host reboots, use <code>virsh nodedev-define</code>
- instead of <code>nodedev-create</code>:
- </p>
-
- <pre>$ virsh nodedev-define <xml-file>
-Node device '<device-name>' defined from '<xml-file>'</pre>
-
- <p>
- To start an instance of this device definition, use the following command:
- </p>
-
- <pre>$ virsh nodedev-start <device-name></pre>
- <p>
- Active mediated device instances can be stopped using <code>virsh
- nodedev-destroy</code>, and persistent device definitions can be removed
- using <code>virsh nodedev-undefine</code>.
- </p>
-
- <p>
- If a mediated device is defined persistently, it can also be set to be
- automatically started whenever the host reboots or when the parent device
- becomes available. In order to autostart a mediated device, use the
- following command:
- </p>
-
- <pre>$ virsh nodedev-autostart <device-name></pre>
- </body>
-</html>
diff --git a/docs/drvnodedev.rst b/docs/drvnodedev.rst
new file mode 100644
index 0000000000..cddb36c73b
--- /dev/null
+++ b/docs/drvnodedev.rst
@@ -0,0 +1,348 @@
+.. role:: since
+
+======================
+Host device management
+======================
+
+.. contents::
+
+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.
+
+The node device driver provides means to list and show details about host
+devices (``virsh nodedev-list``, ``virsh nodedev-info``, and
+``virsh nodedev-dumpxml``), which are generic and can be used with all devices.
+It also provides the means to manage virtual devices. Persistently-defined
+virtual devices are only supported for mediated devices, while transient devices
+are supported by both mediated devices and NPIV (`more info about
+NPIV) <https://wiki.libvirt.org/page/NPIV_in_libvirt>`__).
+
+Persistent virtual devices are managed with ``virsh nodedev-define`` and
+``virsh nodedev-undefine``. Persistent devices can be configured to start
+manually or automatically using ``virsh nodedev-autostart``. Inactive devices
+can be made active with ``virsh nodedev-start``.
+
+Transient virtual devices are started and stopped with the commands
+``virsh nodedev-create`` and ``virsh nodedev-destroy``.
+
+Devices on the host system are arranged in a tree-like hierarchy, with the root
+node being called ``computer``. The node device driver supports udev backend
+(HAL backend was removed in ``6.8.0``).
+
+Details of the XML format of a host device can be found
+`here <formatnode.html>`__. Of particular interest is the ``capability``
+element, which describes features supported by the device. Some specific device
+types are addressed in more detail below.
+
+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>
+
+PCI host devices
+----------------
+
+``capability``
+ When used as top level element, the supported values for the ``type``
+ attribute are ``pci`` and ``phys_function`` (see `SR-IOV
+ below <#SRIOVCap>`__).
+
+::
+
+ <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>
+
+The XML format for a PCI device stays the same for any further capabilities it
+supports, a single nested ``<capability>`` element will be included for each
+capability the device supports.
+
+SR-IOV capability
+~~~~~~~~~~~~~~~~~
+
+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.
+
+Suppose the NIC `above <#PCI>`__ was also SR-IOV capable, it would also include
+a nested ``<capability>`` element enumerating all virtual functions available on
+the physical device (physical port) like in the example below.
+
+::
+
+ <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>
+
+A SR-IOV child device on the other hand, would then report its top level
+capability type as a ``phys_function`` instead:
+
+::
+
+ <device>
+ ...
+ <capability type='phys_function'>
+ <address domain='0x0000' bus='0x04' slot='0x00' function='0x0'/>
+ </capability>
+ ...
+ </device>
+
+MDEV capability
+~~~~~~~~~~~~~~~
+
+A device capable of creating mediated devices will include a nested capability
+``mdev_types`` which enumerates all supported mdev types on the physical device,
+along with the type attributes available through sysfs. A detailed description
+of the XML format for the ``mdev_types`` capability can be found
+`here <formatnode.html#MDEVTypesCap>`__.
+
+The following example shows how we might represent an NVIDIA GPU device that
+supports mediated devices. See below for `more information about mediated
+devices <#MDEV>`__.
+
+::
+
+ <device>
+ ...
+ <driver>
+ <name>nvidia</name>
+ </driver>
+ <capability type='pci'>
+ ...
+ <capability type='mdev_types'>
+ <type id='nvidia-11'>
+ <name>GRID M60-0B</name>
+ <deviceAPI>vfio-pci</deviceAPI>
+ <availableInstances>16</availableInstances>
+ </type>
+ <!-- Here would come the rest of the available mdev types -->
+ </capability>
+ ...
+ </capability>
+ </device>
+
+VPD capability
+~~~~~~~~~~~~~~
+
+A device that exposes a PCI/PCIe VPD capability will include a nested capability
+``vpd`` which presents data stored in the Vital Product Data (VPD). VPD provides
+a device name and a number of other standard-defined read-only fields (change
+level, manufacture id, part number, serial number) and vendor-specific read-only
+fields. Additionally, if a device supports it, read-write fields (asset tag,
+vendor-specific fields or system fields) may also be present. The VPD capability
+is optional for PCI/PCIe devices and the set of exposed fields may vary
+depending on a device. The XML format follows the binary format described in
+"I.3. VPD Definitions" in PCI Local Bus (2.2+) and the identical format in PCIe
+4.0+. At the time of writing, the support for exposing this capability is only
+present on Linux-based systems (kernel version v2.6.26 is the first one to
+expose VPD via sysfs which Libvirt relies on). Reading the VPD contents requires
+root privileges, therefore, ``virsh nodedev-dumpxml`` must be executed
+accordingly. A description of the XML format for the ``vpd`` capability can be
+found `here <formatnode.html#VPDCap>`__.
+
+The following example shows a VPD representation for a device that exposes the
+VPD capability with read-only and read-write fields. Among other things, the VPD
+of this particular device includes a unique board serial number.
+
+::
+
+ <device>
+ <name>pci_0000_42_00_0</name>
+ <capability type='pci'>
+ <class>0x020000</class>
+ <domain>0</domain>
+ <bus>66</bus>
+ <slot>0</slot>
+ <function>0</function>
+ <product id='0xa2d6'>MT42822 BlueField-2 integrated ConnectX-6 Dx network controller</product>
+ <vendor id='0x15b3'>Mellanox Technologies</vendor>
+ <capability type='virt_functions' maxCount='16'/>
+ <capability type='vpd'>
+ <name>BlueField-2 DPU 25GbE Dual-Port SFP56, Crypto Enabled, 16GB on-board DDR, 1GbE OOB management, Tall Bracket</name>
+ <fields access='readonly'>
+ <change_level>B1</change_level>
+ <manufacture_id>foobar</manufacture_id>
+ <part_number>MBF2H332A-AEEOT</part_number>
+ <serial_number>MT2113X00000</serial_number>
+ <vendor_field index='0'>PCIeGen4 x8</vendor_field>
+ <vendor_field index='2'>MBF2H332A-AEEOT</vendor_field>
+ <vendor_field index='3'>3c53d07eec484d8aab34dabd24fe575aa</vendor_field>
+ <vendor_field index='A'>MLX:MN=MLNX:CSKU=V2:UUID=V3:PCI=V0:MODL=BF2H332A</vendor_field>
+ </fields>
+ <fields access='readwrite'>
+ <asset_tag>fooasset</asset_tag>
+ <vendor_field index='0'>vendorfield0</vendor_field>
+ <vendor_field index='2'>vendorfield2</vendor_field>
+ <vendor_field index='A'>vendorfieldA</vendor_field>
+ <system_field index='B'>systemfieldB</system_field>
+ <system_field index='0'>systemfield0</system_field>
+ </fields>
+ </capability>
+ <iommuGroup number='65'>
+ <address domain='0x0000' bus='0x42' slot='0x00' function='0x0'/>
+ </iommuGroup>
+ <numa node='0'/>
+ <pci-express>
+ <link validity='cap' port='0' speed='16' width='8'/>
+ <link validity='sta' speed='8' width='8'/>
+ </pci-express>
+ </capability>
+ </device>
+
+Mediated devices (MDEVs)
+------------------------
+
+Mediated devices ( :since:`Since 3.2.0` ) are software devices defining resource
+allocation on the backing physical device which in turn allows the parent
+physical device's resources to be divided into several mediated devices, thus
+sharing the physical device's performance among multiple guests. Unlike SR-IOV
+however, where a PCIe device appears as multiple separate PCIe devices on the
+host's PCI bus, mediated devices only appear on the mdev virtual bus. Therefore,
+no detach/reattach procedure from/to the host driver procedure is involved even
+though mediated devices are used in a direct device assignment manner. A
+detailed description of the XML format for the ``mdev`` capability can be found
+`here <formatnode.html#mdev>`__.
+
+Example of a mediated device
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <device>
+ <name>mdev_4b20d080_1b54_4048_85b3_a6a62d165c01</name>
+ <path>/sys/devices/pci0000:00/0000:00:02.0/4b20d080-1b54-4048-85b3-a6a62d165c01</path>
+ <parent>pci_0000_06_00_0</parent>
+ <driver>
+ <name>vfio_mdev</name>
+ </driver>
+ <capability type='mdev'>
+ <type id='nvidia-11'/>
+ <uuid>4b20d080-1b54-4048-85b3-a6a62d165c01</uuid>
+ <iommuGroup number='12'/>
+ </capability>
+ </device>
+
+The support of mediated device's framework in libvirt's node device driver
+covers the following features:
+
+- list available mediated devices on the host ( :since:`Since 3.4.0` )
+- display device details ( :since:`Since 3.4.0` )
+- create transient mediated devices ( :since:`Since 6.5.0` )
+- define persistent mediated devices ( :since:`Since 7.3.0` )
+
+Because mediated devices are instantiated from vendor specific templates, simply
+called 'types', information describing these types is contained within the
+parent device's capabilities (see the example in `PCI host devices <#PCI>`__).
+To list all devices capable of creating mediated devices, the following command
+can be used.
+
+::
+
+ $ virsh nodedev-list --cap mdev_types
+
+To see the supported mediated device types on a specific physical device use the
+following:
+
+::
+
+ $ virsh nodedev-dumpxml <device>
+
+Before creating a mediated device, unbind the device from the respective device
+driver, eg. subchannel I/O driver for a CCW device. Then bind the device to the
+respective VFIO driver. For a CCW device, also unbind the corresponding
+subchannel of the CCW device from the subchannel I/O driver and then bind the
+subchannel (instead of the CCW device) to the vfio_ccw driver. The below example
+shows the unbinding and binding steps for a CCW device.
+
+::
+
+ device="0.0.1234"
+ subchannel="0.0.0123"
+ echo $device > /sys/bus/ccw/devices/$device/driver/unbind
+ echo $subchannel > /sys/bus/css/devices/$subchannel/driver/unbind
+ echo $subchannel > /sys/bus/css/drivers/vfio_ccw/bind
+
+To instantiate a transient mediated device, create an XML file representing the
+device. See above for information about the mediated device xml format.
+
+::
+
+ $ virsh nodedev-create <xml-file>
+ Node device '<device-name>' created from '<xml-file>'
+
+If you would like to persistently define the device so that it will be
+maintained across host reboots, use ``virsh nodedev-define`` instead of
+``nodedev-create``:
+
+::
+
+ $ virsh nodedev-define <xml-file>
+ Node device '<device-name>' defined from '<xml-file>'
+
+To start an instance of this device definition, use the following command:
+
+::
+
+ $ virsh nodedev-start <device-name>
+
+Active mediated device instances can be stopped using
+``virsh nodedev-destroy``, and persistent device definitions can be
+removed using ``virsh nodedev-undefine``.
+
+If a mediated device is defined persistently, it can also be set to be
+automatically started whenever the host reboots or when the parent device
+becomes available. In order to autostart a mediated device, use the following
+command:
+
+::
+
+ $ virsh nodedev-autostart <device-name>
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index e492532004..4fb2e1a9f4 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -4166,7 +4166,8 @@ or:
specifies the device API which determines how the host's vfio driver will
expose the device to the guest. Currently, ``model='vfio-pci'``,
``model='vfio-ccw'`` ( :since:`Since 4.4.0` ) and ``model='vfio-ap'`` (
- :since:`Since 4.9.0` ) is supported. `MDEV <drvnodedev.html#MDEV>`__
+ :since:`Since 4.9.0` ) is supported.
+ `MDEV <drvnodedev.html#mediated-devices-mdevs>`__
section provides more information about mediated devices as well as how to
create mediated devices on the host. :since:`Since 4.6.0 (QEMU 2.12)` an
optional ``display`` attribute may be used to enable or disable support
diff --git a/docs/meson.build b/docs/meson.build
index fdf1714da8..bf5a978b07 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp',
'dbus',
'docs',
- 'drvnodedev',
'drvopenvz',
'drvsecret',
'drvtest',
@@ -80,6 +79,7 @@ docs_rst_files = [
'drvesx',
'drvhyperv',
'drvlxc',
+ 'drvnodedev',
'drvqemu',
'errors',
'formatbackup',
--
2.35.1
More information about the libvir-list
mailing list