[libvirt PATCH 1/2] docs: Expand manpage documentation for nodedev commands
Bring the documentation for nodedev-list up to date with the latest code, especially documenting the --active and -all options. Also add documentation for the nodedev-define, nodedev-undefine, and nodedev-start commands. Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com> --- docs/manpages/virsh.rst | 48 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 44 insertions(+), 4 deletions(-) diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst index ce98283ae3..73daf2735f 100644 --- a/docs/manpages/virsh.rst +++ b/docs/manpages/virsh.rst @@ -5020,6 +5020,44 @@ Note that this makes libvirt quit managing a host device, and may even make that device unusable by the rest of the physical host until a reboot. +nodedev-define +-------------- + +**Syntax:** + +:: + + nodedev-define FILE + +Define an inactive persistent device or modify an existing persistent one from +the XML *FILE*. + + +nodedev-undefine +---------------- + +**Syntax:** + +:: + + nodedev-undefine device + +Undefine the configuration for a persistent device. If the device is active, +make it transient. + + +nodedev-start +------------- + +**Syntax:** + +:: + + nodedev-start network + +Start a (previously defined) inactive device. + + nodedev-detach -------------- @@ -5076,16 +5114,18 @@ nodedev-list :: - nodedev-list cap --tree + nodedev-list [--cap capability] [--tree] [--inactive | --all] List all of the devices available on the node that are known by libvirt. *cap* is used to filter the list by capability types, the types must be separated by comma, e.g. --cap pci,scsi. Valid capability types include 'system', 'pci', 'usb_device', 'usb', 'net', 'scsi_host', 'scsi_target', 'scsi', 'storage', 'fc_host', 'vports', 'scsi_generic', 'drm', 'mdev', -'mdev_types', 'ccw', 'css', 'ap_card', 'ap_queue', 'ap_matrix'. -If *--tree* is used, the output is formatted in a tree representing parents of each -node. *cap* and *--tree* are mutually exclusive. +'mdev_types', 'ccw', 'css', 'ap_card', 'ap_queue', 'ap_matrix'. By default, +only active devices are listed. *--inactive* is used to list only inactive +devices, and *-all* is used to list both active and inactive devices. +If *--tree* is used, the output is formatted in a tree representing parents of +each node. *--tree* is mutually exclusive with all other options. nodedev-reattach -- 2.31.1
Add up-to-date information about creating and defining mediated devices in libvirt. Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com> --- 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..09ab063aab 100644 --- a/docs/drvnodedev.html.in +++ b/docs/drvnodedev.html.in @@ -14,13 +14,26 @@ <p> 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="https://wiki.libvirt.org/page/NPIV_in_libvirt">more info about NPIV)</a>). + 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>). @@ -198,6 +211,7 @@ </driver> <capability type='mdev'> <type id='nvidia-11'/> + <uuid>4b20d080-1b54-4048-85b3-a6a62d165c01</uuid> <iommuGroup number='12'/> </capability> </device></pre> @@ -216,22 +230,31 @@ 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>). + 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> -$ ls /sys/class/mdev_bus/<device>/mdev_supported_types</pre> + <pre>$ virsh nodedev-dumpxml <device></pre> <p> Before creating a mediated device, unbind the device from the respective @@ -252,22 +275,40 @@ echo $subchannel > /sys/bus/css/drivers/vfio_ccw/bind </pre> <p> - 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. </p> - <pre> -$ uuidgen > /sys/class/mdev_bus/<device>/mdev_supported_types/<type>/create -... -$ echo <UUID> > /sys/class/mdev_bus/<device>/mdev_supported_types/<type>/create</pre> + <pre>$ virsh nodedev-create <xml-file> +Node device '<device-name>' created from '<xml-file>'</pre> <p> - 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 <code>virsh nodedev-define</code> + instead of <code>nodedev-craete</code>: </p> - <pre> -$ echo 1 > /sys/bus/mdev/devices/<uuid>/remove</pre> + <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> -- 2.31.1
On 9/15/21 10:16 PM, Jonathon Jongsma wrote:
Add up-to-date information about creating and defining mediated devices in libvirt.
Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com> --- docs/drvnodedev.html.in | 83 ++++++++++++++++++++++++++++++----------- 1 file changed, 62 insertions(+), 21 deletions(-)
for both: Reviewed-by: Michal Privoznik <mprivozn@redhat.com> Michal
participants (2)
-
Jonathon Jongsma -
Michal Prívozník