Managing mediated devices with libvirt

Edit online

Use libvirt commands to manage the lifecycle of VFIO mediated devices.

nodedev-create
to create a transient VFIO mediated device and start it.
nodedev-define
to define a persistent VFIO mediated device.
nodedev-start
to activate an inactive persistent VFIO mediated device.
nodedev-list
to list mediated devices and other host resources that can be detected by libvirt.
nodedev-dumpxml
to display the properties, in node-device XML format, of a host resource that can be detected by libvirt.
nodedev-destroy
to deactivate a persistent VFIO mediated device or to completely remove a transient VFIO mediated device.
nodedev-undefine
to remove the definition of a persistent VFIO mediated device from libvirt.
Figure 1. Lifecycle of VFIO mediated devices and virsh nodedev commands

This graphic is a visual summary of the text that follows.
As illustrated in Figure 1 the lifecycle of a mediated device begins with a device description in node-device XML format. You can use templates to write a node-device XML file.

If you already have a mediated device, for example a transient device that you have created with general Linux® commands, you can obtain a node-device XML file as the output of the nodedev-dumpxml command.

You can create a persistent or a transient mediated device from the node-device XML file:
Persistent VFIO mediated device
Processing the node-device XML file with the virsh nodedev-define command creates an inactive persistent mediated device within libvirt. Before you can add the device to a virtual server, you must activate it with a virsh nodedev-start command.

Applying the virsh nodedev-destroy command to an active persistent mediated device deactivates it. It can then be activated again, for example after a host reboot.

An inactive persistent device ceases to exist when you apply the virsh nodedev-undefine command to it. If you apply virsh nodedev-undefine to an active persistent device, it continues to exist as an active transient device.

Transient VFIO mediated device
Processing the node-device XML file with the virsh nodedev-create command creates a transient mediated device. Transient mediated devices are always active and can be added to a virtual server.

A transient mediated device ceases to exist when you apply the virsh nodedev-destroy command to it.

You can use mediated devices as hotplug devices or you can define them in a domain configuration-XML file of a virtual server. Mediated devices that are defined in a domain configuration-XML file require a stable UUID and the device must be active before the virtual server is started.