From eba98a1db93474678d7358886fcd12a823e158f4 Mon Sep 17 00:00:00 2001 From: Jonathon Jongsma Date: Wed, 2 Jun 2021 15:03:12 -0500 Subject: [PATCH] docs: update nodedev driver docs for new mdev features Add up-to-date information about creating and defining mediated devices in libvirt. Signed-off-by: Jonathon Jongsma Reviewed-by: Michal Privoznik --- docs/drvnodedev.html.in | 83 ++++++++++++++++++++++++++++++----------- 1 file changed, 62 insertions(+), 21 deletions(-) diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in index 84c3bd3ef9..70f7e6717d 100644 --- a/docs/drvnodedev.html.in +++ b/docs/drvnodedev.html.in @@ -14,13 +14,26 @@

The node device driver provides means to list and show details about host - devices (virsh nodedev-list, - virsh nodedev-dumpxml), which are generic and can be used - with all devices. It also provides means to create and destroy devices - (virsh nodedev-create, virsh nodedev-destroy) - which are meant to be used to create virtual devices, currently only - supported by NPIV - (more info about NPIV)). + 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)). +

+

+ 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). @@ -198,6 +211,7 @@ </driver> <capability type='mdev'> <type id='nvidia-11'/> + <uuid>4b20d080-1b54-4048-85b3-a6a62d165c01</uuid> <iommuGroup number='12'/> </capability> </device> @@ -216,22 +230,31 @@ display device details (Since 3.4.0) +

  • + create transient mediated devices + (Since 6.5.0) +
    • +
  • + define persistent mediated devices + (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). + within the parent device's capabilities (see the example in PCI host devices). 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:

    - 
    -$ ls /sys/class/mdev_bus/<device>/mdev_supported_types
    + 
    $ virsh nodedev-dumpxml <device>

    Before creating a mediated device, unbind the device from the respective @@ -252,22 +275,40 @@ echo $subchannel > /sys/bus/css/drivers/vfio_ccw/bind

    - To manually instantiate a mediated device, use one of the following as a - reference. For a CCW device, use the subchannel ID instead of the device - ID. + To instantiate a transient mediated device, create an XML file representing the + device. See above for information about the mediated device xml format.

    - 
    -$ uuidgen > /sys/class/mdev_bus/<device>/mdev_supported_types/<type>/create
-...
-$ echo <UUID> > /sys/class/mdev_bus/<device>/mdev_supported_types/<type>/create
    + 
    $ virsh nodedev-create <xml-file>
+Node device '<device-name>' created from '<xml-file>'

    - Manual removal of a mediated device is then performed as follows: + 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:

    - 
    -$ echo 1 > /sys/bus/mdev/devices/<uuid>/remove
    + 
    $ 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>