Re: [libvirt] [PATCH] docs: document managed=yes of hostdev passthrough

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