On 10/16/2011 08:49 PM, Osier Yang wrote:
Oh, you already made the patch, :)
? 2011?10?15? 07:11, Eric Blake ??:
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.
---
+++ 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>
Should this be more exact? such as "virNodeDeviceDettach" before
attachment, and "virNodeDeviceReattach" after detachment? and it
might be worth to add virsh commands here (nodedev-detach,
nodedev-reattach).
Okay, I see other virsh commands mentioned on this page, so I can
improve the text.
Also not sure how to document for "managed" USB device, we supports
"managed" for USB device XML, however, don't do any work to reattach
the device to host currently.
Well, we should probably change that in the future; but for now, I can
document that limitation.
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
s/hypervisor/hypervisor driver/, hypervisor has no knowledge
of "managed".
Yeah, and mentioning PCI vs. USB as well.
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>.
We might need more documents here to cover following 3 scenarios:
* the device was not bound to any driver before attachment
* the device was bound to pci-stub before attachment
* the device was bound to some driver
Because a user might don't known what device was bound to, but
blindly wants the device reattached to host with a driver he expects,
and I can foresee there will be bug coming for this, though it's really
not bug, Will it be better for us to clarify it more clear to avoid the
upcoming bug?
I don't see any point making a change here. What we really need is
virNodeDeviceReAttachFlags, which lets us specify a flag to choose
between forcing a reprobe (current behavior, always restores device
driver based on the probe) or restoring just to the state prior to the
detach (thus letting a user remove a device from pci-stub, but still
leaving it unattached to any driver rather than reprobing).
I've gone ahead and pushed with these modifications:
diff --git i/docs/formatdomain.html.in w/docs/formatdomain.html.in
index ce5554e..3b94959 100644
--- i/docs/formatdomain.html.in
+++ w/docs/formatdomain.html.in
@@ -1411,10 +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, 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>
+ 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 virsh
+ 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 i/tools/virsh.pod w/tools/virsh.pod
index 37beb3d..8c4bc78 100644
--- i/tools/virsh.pod
+++ w/tools/virsh.pod
@@ -1305,15 +1305,17 @@ L<http://libvirt.org/formatnode.html>.
Passthrough devices cannot be simultaneously used by the host and its
guest domains. If the <hostdev> description includes the attribute
-B<managed='yes'>, and the hypervisor supports it, then the device is
+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. 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.
+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
--
Eric Blake ebl...@redhat.com +1-801-349-2682
Libvirt virtualization library http://libvirt.org
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
