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

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(a)redhat.com&gt; --- docs/formatdomain.html.in | 19 +++++++++---------- tools/virsh.pod | 17 ++++++++--------- 2 files changed, 17 insertions(+), 19 deletions(-)

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>