From 10d3272ec3ded973d3bcaee8c2721e9e68474636 Mon Sep 17 00:00:00 2001 From: Eric Blake Date: Fri, 14 Oct 2011 16:59:16 -0600 Subject: [PATCH] docs: document managed=yes of hostdev passthrough Clarify some of the effects of managed passthrough 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. --- docs/formatdomain.html.in | 10 +++++++++- tools/virsh.pod | 32 ++++++++++++++++++++------------ 2 files changed, 29 insertions(+), 13 deletions(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 12055c2217..95d33c0baa 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1411,7 +1411,15 @@ "subsystem" and type is "usb" for a USB device and "pci" for a PCI device. When managed is "yes" for a PCI device, it is detached from the host before being passed on to - the guest. + the guest, and reattached to the host after the guest exits. + If managed is omitted or "no", and for USB + devices, the user is responsible to + call virNodeDeviceDettach (or virsh + nodedev-dettach) before starting the guest or + hot-plugging the device, + and virNodeDeviceReAttach (or virsh + nodedev-reattach) after hot-unplug or stopping the + guest.
source
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 43a4f4c0b8..775d3025aa 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 for this usage. -For passthrough host devices, see also B. +For passthrough host devices, see also B, needed if +the device does not use managed mode. =item B I I I [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. -For passthrough host devices, see also B. +For passthrough host devices, see also B, needed if +the device does not use managed mode. =item B I I @@ -1302,11 +1304,18 @@ For more information on node device definition see: L. Passthrough devices cannot be simultaneously used by the host and its -guest domains. Attempts to use a passthrough for a guest may -have the ability to behave as if B 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. +guest domains, nor by multiple active guests at once. If the + description includes the attribute B, 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 (guest start, device +hot-plug) and B (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 from the host, so that it can safely be used by guests via passthrough. This is reversed with -B. +B, and is done automatically for managed devices. =item B I @@ -1347,10 +1356,9 @@ formatted in a tree representing parents of each node. =item B I Declare that I 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 when creating a -guest, it currently requires an explicit B 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. =item B I -- 2.39.5