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>.