[PATCH 07/29] docs: Convert 'drvnodedev' page to rST

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Fix one cross link anchor along with the conversion.

Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
 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>
-&lt;device&gt;
-  &lt;name&gt;pci_0000_00_17_0&lt;/name&gt;
-  &lt;path&gt;/sys/devices/pci0000:00/0000:00:17.0&lt;/path&gt;
-  &lt;parent&gt;computer&lt;/parent&gt;
-  &lt;driver&gt;
-    &lt;name&gt;ahci&lt;/name&gt;
-  &lt;/driver&gt;
-  &lt;capability type='pci'&gt;
-...
-  &lt;/capability&gt;
-&lt;/device&gt;</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>
-&lt;device&gt;
-  &lt;name&gt;pci_0000_04_00_1&lt;/name&gt;
-  &lt;path&gt;/sys/devices/pci0000:00/0000:00:06.0/0000:04:00.1&lt;/path&gt;
-  &lt;parent&gt;pci_0000_00_06_0&lt;/parent&gt;
-  &lt;driver&gt;
-    &lt;name&gt;igb&lt;/name&gt;
-  &lt;/driver&gt;
-  &lt;capability type='pci'&gt;
-    &lt;domain&gt;0&lt;/domain&gt;
-    &lt;bus&gt;4&lt;/bus&gt;
-    &lt;slot&gt;0&lt;/slot&gt;
-    &lt;function&gt;1&lt;/function&gt;
-    &lt;product id='0x10c9'&gt;82576 Gigabit Network Connection&lt;/product&gt;
-    &lt;vendor id='0x8086'&gt;Intel Corporation&lt;/vendor&gt;
-    &lt;iommuGroup number='15'&gt;
-      &lt;address domain='0x0000' bus='0x04' slot='0x00' function='0x1'/&gt;
-    &lt;/iommuGroup&gt;
-    &lt;numa node='0'/&gt;
-    &lt;pci-express&gt;
-      &lt;link validity='cap' port='1' speed='2.5' width='2'/&gt;
-      &lt;link validity='sta' speed='2.5' width='2'/&gt;
-    &lt;/pci-express&gt;
-  &lt;/capability&gt;
-&lt;/device&gt;</pre>
-
-    <p>
-      The XML format for a PCI device stays the same for any further
-      capabilities it supports, a single nested <code>&lt;capability&gt;</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>&lt;capability&gt;</code> element enumerating all virtual
-      functions available on the physical device (physical port) like in the
-      example below.
-    </p>
-
-    <pre>
-&lt;capability type='pci'&gt;
-...
-  &lt;capability type='virt_functions' maxCount='7'&gt;
-    &lt;address domain='0x0000' bus='0x04' slot='0x10' function='0x1'/&gt;
-    &lt;address domain='0x0000' bus='0x04' slot='0x10' function='0x3'/&gt;
-    &lt;address domain='0x0000' bus='0x04' slot='0x10' function='0x5'/&gt;
-    &lt;address domain='0x0000' bus='0x04' slot='0x10' function='0x7'/&gt;
-    &lt;address domain='0x0000' bus='0x04' slot='0x11' function='0x1'/&gt;
-    &lt;address domain='0x0000' bus='0x04' slot='0x11' function='0x3'/&gt;
-    &lt;address domain='0x0000' bus='0x04' slot='0x11' function='0x5'/&gt;
-  &lt;/capability&gt;
-...
-&lt;/capability&gt;</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>
-&lt;device&gt;
-...
-  &lt;capability type='phys_function'&gt;
-    &lt;address domain='0x0000' bus='0x04' slot='0x00' function='0x0'/&gt;
-  &lt;/capability&gt;
-...
-&lt;/device&gt;</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>
-&lt;device&gt;
-...
-  &lt;driver&gt;
-    &lt;name&gt;nvidia&lt;/name&gt;
-  &lt;/driver&gt;
-  &lt;capability type='pci'&gt;
-...
-    &lt;capability type='mdev_types'&gt;
-      &lt;type id='nvidia-11'&gt;
-        &lt;name&gt;GRID M60-0B&lt;/name&gt;
-        &lt;deviceAPI&gt;vfio-pci&lt;/deviceAPI&gt;
-        &lt;availableInstances&gt;16&lt;/availableInstances&gt;
-      &lt;/type&gt;
-      &lt;!-- Here would come the rest of the available mdev types --&gt;
-    &lt;/capability&gt;
-...
-  &lt;/capability&gt;
-&lt;/device&gt;</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>
-&lt;device&gt;
-  &lt;name&gt;pci_0000_42_00_0&lt;/name&gt;
-  &lt;capability type=&apos;pci&apos;&gt;
-    &lt;class&gt;0x020000&lt;/class&gt;
-    &lt;domain&gt;0&lt;/domain&gt;
-    &lt;bus&gt;66&lt;/bus&gt;
-    &lt;slot&gt;0&lt;/slot&gt;
-    &lt;function&gt;0&lt;/function&gt;
-    &lt;product id=&apos;0xa2d6&apos;&gt;MT42822 BlueField-2 integrated ConnectX-6 Dx network controller&lt;/product&gt;
-    &lt;vendor id=&apos;0x15b3&apos;&gt;Mellanox Technologies&lt;/vendor&gt;
-    &lt;capability type=&apos;virt_functions&apos; maxCount=&apos;16&apos;/&gt;
-    &lt;capability type=&apos;vpd&apos;&gt;
-      &lt;name&gt;BlueField-2 DPU 25GbE Dual-Port SFP56, Crypto Enabled, 16GB on-board DDR, 1GbE OOB management, Tall Bracket&lt;/name&gt;
-      &lt;fields access=&apos;readonly&apos;&gt;
-        &lt;change_level&gt;B1&lt;/change_level&gt;
-        &lt;manufacture_id&gt;foobar&lt;/manufacture_id&gt;
-        &lt;part_number&gt;MBF2H332A-AEEOT&lt;/part_number&gt;
-        &lt;serial_number&gt;MT2113X00000&lt;/serial_number&gt;
-        &lt;vendor_field index=&apos;0&apos;&gt;PCIeGen4 x8&lt;/vendor_field&gt;
-        &lt;vendor_field index=&apos;2&apos;&gt;MBF2H332A-AEEOT&lt;/vendor_field&gt;
-        &lt;vendor_field index=&apos;3&apos;&gt;3c53d07eec484d8aab34dabd24fe575aa&lt;/vendor_field&gt;
-        &lt;vendor_field index=&apos;A&apos;&gt;MLX:MN=MLNX:CSKU=V2:UUID=V3:PCI=V0:MODL=BF2H332A&lt;/vendor_field&gt;
-      &lt;/fields&gt;
-      &lt;fields access=&apos;readwrite&apos;&gt;
-        &lt;asset_tag&gt;fooasset&lt;/asset_tag&gt;
-        &lt;vendor_field index=&apos;0&apos;&gt;vendorfield0&lt;/vendor_field&gt;
-        &lt;vendor_field index=&apos;2&apos;&gt;vendorfield2&lt;/vendor_field&gt;
-        &lt;vendor_field index=&apos;A&apos;&gt;vendorfieldA&lt;/vendor_field&gt;
-        &lt;system_field index=&apos;B&apos;&gt;systemfieldB&lt;/system_field&gt;
-        &lt;system_field index=&apos;0&apos;&gt;systemfield0&lt;/system_field&gt;
-      &lt;/fields&gt;
-    &lt;/capability&gt;
-    &lt;iommuGroup number=&apos;65&apos;&gt;
-      &lt;address domain=&apos;0x0000&apos; bus=&apos;0x42&apos; slot=&apos;0x00&apos; function=&apos;0x0&apos;/&gt;
-    &lt;/iommuGroup&gt;
-    &lt;numa node=&apos;0&apos;/&gt;
-    &lt;pci-express&gt;
-      &lt;link validity=&apos;cap&apos; port=&apos;0&apos; speed=&apos;16&apos; width=&apos;8&apos;/&gt;
-      &lt;link validity=&apos;sta&apos; speed=&apos;8&apos; width=&apos;8&apos;/&gt;
-    &lt;/pci-express&gt;
-  &lt;/capability&gt;
-&lt;/device&gt;
-</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>
-&lt;device&gt;
-  &lt;name&gt;mdev_4b20d080_1b54_4048_85b3_a6a62d165c01&lt;/name&gt;
-  &lt;path&gt;/sys/devices/pci0000:00/0000:00:02.0/4b20d080-1b54-4048-85b3-a6a62d165c01&lt;/path&gt;
-  &lt;parent&gt;pci_0000_06_00_0&lt;/parent&gt;
-  &lt;driver&gt;
-    &lt;name&gt;vfio_mdev&lt;/name&gt;
-  &lt;/driver&gt;
-  &lt;capability type='mdev'&gt;
-    &lt;type id='nvidia-11'/&gt;
-    &lt;uuid&gt;4b20d080-1b54-4048-85b3-a6a62d165c01&lt;/uuid&gt;
-    &lt;iommuGroup number='12'/&gt;
-  &lt;/capability&gt;
-&lt;/device&gt;</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 &lt;device&gt;</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 &gt; /sys/bus/ccw/devices/$device/driver/unbind
-echo $subchannel &gt; /sys/bus/css/devices/$subchannel/driver/unbind
-echo $subchannel &gt; /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 &lt;xml-file&gt;
-Node device '&lt;device-name&gt;' created from '&lt;xml-file&gt;'</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 &lt;xml-file&gt;
-Node device '&lt;device-name&gt;' defined from '&lt;xml-file&gt;'</pre>
-
-    <p>
-      To start an instance of this device definition, use the following command:
-    </p>
-
-    <pre>$ virsh nodedev-start &lt;device-name&gt;</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 &lt;device-name&gt;</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




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux