[libvirt] [PATCH] Document that USB hostdevs do not need nodeDettach

[John Ferlan]

On 03/23/2015 01:16 PM, Ján Tomko wrote:
> The virNodeDeviceDettach API only works on PCI devices.
> 
> Originally added by commit 10d3272e, but the API never
> supported USB devices.
> 
> Reported by: Martin Polednik <mpolednik at redhat.com>
> ---
>  docs/formatdomain.html.in | 19 +++++++++----------
>  tools/virsh.pod           | 17 ++++++++---------
>  2 files changed, 17 insertions(+), 19 deletions(-)
> 

ACK -

Should we say to call virNodeDeviceDetachFlags instead of
virNodeDeviceDettach?


John

> diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
> index 82aa14f..d6abe17 100644
> --- a/docs/formatdomain.html.in
> +++ b/docs/formatdomain.html.in
> @@ -3114,21 +3114,20 @@
>          with additional attributes noted.
>          <dl>
>            <dt>usb</dt>
> -          <dd>For USB devices, the user is responsible to call
> -            <code>virNodeDeviceDettach</code> (or
> -            <code>virsh nodedev-detach</code>) before starting the guest
> -            or hot-plugging the device and <code>virNodeDeviceReAttach</code>
> -            (or <code>virsh nodedev-reattach</code>) after hot-unplug or
> -            stopping the guest.
> +          <dd>USB devices are detached from the host on guest startup
> +            and reattached after the guest exits or the device is
> +            hot-unplugged.
>            </dd>
>            <dt>pci</dt>
>            <dd>For PCI devices, when <code>managed</code> is "yes" it is
>              detached from the host before being passed on to the guest
>              and reattached to the host after the guest exits. If
> -            <code>managed</code> is omitted or "no", follow the steps
> -            described for a USB device to detach before starting the
> -            guest or hot-plugging and reattach after stopping the guest
> -            or hot-unplug.
> +            <code>managed</code> is omitted or "no", the user is
> +            responsible to call <code>virNodeDeviceDettach</code>
> +            (or <code>virsh nodedev-detach</code> before starting the 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>scsi</dt>
>            <dd>For SCSI devices, user is responsible to make sure the device
> diff --git a/tools/virsh.pod b/tools/virsh.pod
> index 8262a45..4d825c1 100644
> --- a/tools/virsh.pod
> +++ b/tools/virsh.pod
> @@ -2385,7 +2385,7 @@ attach taking effect the next time libvirt starts the domain.
>  For cdrom and floppy devices, this command only replaces the media
>  within an existing device; consider using B<update-device> for this
>  usage.  For passthrough host devices, see also B<nodedev-detach>,
> -needed if the device does not use managed mode.
> +needed if the PCI device does not use managed mode.
>  
>  If I<--live> is specified, affect a running domain.
>  If I<--config> is specified, affect the next startup of a persistent domain.
> @@ -2646,15 +2646,14 @@ L<http://libvirt.org/formatnode.html>.
>  
>  Passthrough devices cannot be simultaneously used by the host and its
>  guest domains, nor by multiple active guests at once.  If the
> -<hostdev> description includes the attribute B<managed='yes'>, and the
> -hypervisor driver supports it, then the device is in managed mode, and
> +<hostdev> description of a PCI device includes the attribute 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-detach> (guest start, device
>  hot-plug) and B<nodedev-reattach> (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,
> +called at the right points.  If a PCI 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.
>  
> @@ -2712,8 +2711,8 @@ I<cap> and I<--tree> are mutually exclusive.
>  
>  Declare that I<nodedev> is no longer in use by any guests, and that
>  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-detach>.
> +automatically for PCI devices in managed mode and USB devices, but
> +must be done explicitly to match any explicit B<nodedev-detach>.
>  
>  =item B<nodedev-reset> I<nodedev>
>  
>