6:11 p.m.
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