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

[Eric Blake]

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   eblake at redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org