External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-22 21:55:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: document managed=yes of hostdev passthrough

Browse Source 
Clarify some of the effects of managed passthrough <hostdev> devices;
with recent changes (commit d093547), a nodedev-reattach is only needed
to pair up to an explicit nodedev-dettach (but beware that older
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.
This commit is contained in:
Eric Blake 2011-10-14 16:59:16 -06:00
parent 646b300773
commit 10d3272ec3
2 changed files with 29 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/formatdomain.html.in
View File

@ -1411,7 +1411,15 @@
"subsystem" and <code>type</code> is "usb" for a USB device and "pci" "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 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 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.
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 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> <dt><code>source</code></dt>
<dd>The source element describes the device as seen from the host. <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 The USB device can either be addressed by vendor / product id using the

32
tools/virsh.pod
View File

@ -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. See the documentation to learn about libvirt XML format for a device.
For cdrom and floppy devices, this command only replaces the media within For cdrom and floppy devices, this command only replaces the media within
the single existing device; consider using B<update-device> for this usage. 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> =item B<attach-disk> I<domain-id> I<source> I<target>
[I<--driver driver>] [I<--subdriver subdriver>] [I<--cache cache>] [I<--driver driver>] [I<--subdriver subdriver>] [I<--cache cache>]
@ -1260,7 +1261,8 @@ will be created automatically.
Detach a device from the domain, takes the same kind of XML descriptions Detach a device from the domain, takes the same kind of XML descriptions
as command B<attach-device>. 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> =item B<detach-disk> I<domain-id> I<target>
@ -1302,11 +1304,18 @@ For more information on node device definition see:
L<http://libvirt.org/formatnode.html>. L<http://libvirt.org/formatnode.html>.
Passthrough devices cannot be simultaneously used by the host and its Passthrough devices cannot be simultaneously used by the host and its
guest domains. Attempts to use a passthrough <hostdev> for a guest may guest domains, nor by multiple active guests at once. If the
have the ability to behave as if B<nodedev-dettach> had been called, <hostdev> description includes the attribute B<managed='yes'>, and the
although making this call explicitly is safe. Once a guest no longer hypervisor driver supports it, then the device is in managed mode, and
needs a passthrough device, reversing the process so that the host can attempts to use that passthrough device in an active guest will
again use the device requires the explicit use of B<nodedev-reattach>. 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 (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 =over 4
@ -1328,7 +1337,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 Detach I<nodedev> from the host, so that it can safely be used by
guests via <hostdev> passthrough. This is reversed with 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> =item B<nodedev-dumpxml> I<nodedev>
@ -1347,10 +1356,9 @@ formatted in a tree representing parents of each node.
=item B<nodedev-reattach> I<nodedev> =item B<nodedev-reattach> I<nodedev>
Declare that I<nodedev> is no longer in use by any guests, and that 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 the host can resume normal use of the device. This is done
sometimes perform an implicit B<nodedev-dettach> when creating a automatically for devices in managed mode, but must be done explicitly
guest, it currently requires an explicit B<nodedev-reattach> after to match any explicit B<nodedev-dettach>.
the last guest use of the device before the host regains full control.
=item B<nodedev-reset> I<nodedev> =item B<nodedev-reset> I<nodedev>