Clarify some of the effects of managed passthrough <hostdev> devices; with today's recent changes, a nodedev-reattach is only needed to pair up to an explicit nodedev-dettach (but beware that virt-manager has a bug where it uses explicit nodedev-dettach under the hood when using the gui to hotplug a hostdev device). * docs/formatdomain.html.in: Mention reattach. * tools/virsh.pod (nodedev): Mention managed mode. --- My earlier commit beeab55 was pessimistic on when nodedev-reattach was needed, especially in light of today's patches. Hopefully this describes the situation with more accuracy. docs/formatdomain.html.in | 5 ++++- tools/virsh.pod | 30 ++++++++++++++++++------------ 2 files changed, 22 insertions(+), 13 deletions(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index c007dff..bc20392 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1410,7 +1410,10 @@ "subsystem" and <code>type</code> is "usb" for a USB device and "pci" for a PCI device. When <code>managed</code> is "yes" for a PCI device, it is detached from the host before being passed on to - the guest.</dd> + the guest, and reattached to the host after the guest exits; + otherwise, the user is responsible to + call <code>virNodeDeviceDettach</code> + and <code>virNodeDeviceReAttach</code> at appropriate points.</dd> <dt><code>source</code></dt> <dd>The source element describes the device as seen from the host. The USB device can either be addressed by vendor / product id using the diff --git a/tools/virsh.pod b/tools/virsh.pod index 74ae647..f9ac6b8 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -1211,7 +1211,8 @@ Attach a device to the domain, using a device definition in an XML file. See the documentation to learn about libvirt XML format for a device. For cdrom and floppy devices, this command only replaces the media within the single existing device; consider using B<update-device> for this usage. -For passthrough host devices, see also B<nodedev-dettach>. +For passthrough host devices, see also B<nodedev-dettach>, needed if +the device does not use managed mode. =item B<attach-disk> I<domain-id> I<source> I<target> [I<--driver driver>] [I<--subdriver subdriver>] [I<--cache cache>] @@ -1257,7 +1258,8 @@ will be created automatically. Detach a device from the domain, takes the same kind of XML descriptions as command B<attach-device>. -For passthrough host devices, see also B<nodedev-reattach>. +For passthrough host devices, see also B<nodedev-reattach>, needed if +the device does not use managed mode. =item B<detach-disk> I<domain-id> I<target> @@ -1299,11 +1301,16 @@ For more information on node device definition see: L<http://libvirt.org/formatnode.html>;. Passthrough devices cannot be simultaneously used by the host and its -guest domains. Attempts to use a passthrough <hostdev> for a guest may -have the ability to behave as if B<nodedev-dettach> had been called, -although making this call explicitly is safe. Once a guest no longer -needs a passthrough device, reversing the process so that the host can -again use the device requires the explicit use of B<nodedev-reattach>. +guest domains. If the <hostdev> description includes the attribute +B<managed='yes'>, and the hypervisor supports it, then the device is +in managed mode, and attempts to use that passthrough device in an +active guest will automatically behave as if B<nodedev-dettach> (guest +start, device hot-plug) and B<nodedev-reattach> (guest stop, device +hot-unplug) were called at the right points. If a device is not +marked as managed, then it must manually be detached and reattached +before a guest can use it. Also, if a device is manually detached, +then the host does not regain control of the device without a matching +reattach, even if the guests use the device in managed mode. =over 4 @@ -1325,7 +1332,7 @@ by the rest of the physical host until a reboot. Detach I<nodedev> from the host, so that it can safely be used by guests via <hostdev> passthrough. This is reversed with -B<nodedev-reattach>. +B<nodedev-reattach>, and is done automatically for managed devices. =item B<nodedev-dumpxml> I<nodedev> @@ -1344,10 +1351,9 @@ formatted in a tree representing parents of each node. =item B<nodedev-reattach> I<nodedev> Declare that I<nodedev> is no longer in use by any guests, and that -the host can resume normal use of the device. While libvirt can -sometimes perform an implicit B<nodedev-dettach> when creating a -guest, it currently requires an explicit B<nodedev-reattach> after -the last guest use of the device before the host regains full control. +the host can resume normal use of the device. This is done +automatically for devices in managed mode, but must be done explicitly +to match any explicit B<nodedev-dettach>. =item B<nodedev-reset> I<nodedev> -- 1.7.4.4