[libvirt] [PATCH] Document that USB hostdevs do not need nodeDettach
John Ferlan
jferlan at redhat.com
Tue Mar 24 21:03:08 UTC 2015
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>
>
>
More information about the libvir-list
mailing list