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

[Osier Yang]

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.
> ---
>
> My earlier commit beeab55 was pessimistic on when nodedev-reattach
> was needed, especially in light of today's patches.  Hopefully
> this describes the situation with more accuracy.
>
>   docs/formatdomain.html.in |    5 ++++-
>   tools/virsh.pod           |   30 ++++++++++++++++++------------
>   2 files changed, 22 insertions(+), 13 deletions(-)
>
> diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
> index c007dff..bc20392 100644
> --- a/docs/formatdomain.html.in
> +++ 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).

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.

see https://bugzilla.redhat.com/show_bug.cgi?id=730930

>         <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 74ae647..f9ac6b8 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<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>]
> @@ -1257,7 +1258,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>
>
> @@ -1299,11 +1301,16 @@ 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.  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".

> +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.

This is great doc as it will let us close some bug in future, :-)

>
>   =over 4
>
> @@ -1325,7 +1332,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>
>
> @@ -1344,10 +1351,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>.

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?

Osier
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20111017/2f4bc1a3/attachment-0001.htm>