docs: document managed=yes of hostdev passthrough

Clarify some of the effects of managed passthrough <hostdev> devices;
with recent changes (commit d093547), a nodedev-reattach is only needed
to pair up to an explicit nodedev-dettach (but beware that older
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.

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 12055c2217317d23112fa477831fbba45274873c..95d33c0baa13e18282ec963c5a1cb3c618467352 100644 (file)
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -1411,7 +1411,15 @@
         "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.
+        If <code>managed</code> is omitted or "no", and for USB
+        devices, the user is responsible to
+        call <code>virNodeDeviceDettach</code> (or <code>virsh
+        nodedev-dettach</code>) before starting the guest or
+        hot-plugging the device,
+        and <code>virNodeDeviceReAttach</code> (or <code>virsh
+        nodedev-reattach</code>) after hot-unplug or stopping the
+        guest.</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 43a4f4c0b8e0e1f48d318a8570bb487d32cdbab1..775d3025aa583bbdaae9481627609ce8151889b1 100644 (file)
--- 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>]
@@ -1260,7 +1261,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>
 
@@ -1302,11 +1304,18 @@ 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, nor by multiple active guests at once.  If the
+<hostdev> description includes the attribute B<managed='yes'>, and the
+hypervisor driver 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 (currently, qemu does this for PCI devices,
+but not USB).  If a device is not marked as managed, then it must
+manually be detached before guests can use it, and manually reattached
+to be returned to the host.  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
 
@@ -1328,7 +1337,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>
 
@@ -1347,10 +1356,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>