[libvirt] [PATCH] docs: document managed=yes of hostdev passthrough
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> <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 +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. =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>. =item B<nodedev-reset> I<nodedev> -- 1.7.4.4
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
On 10/16/2011 08:49 PM, Osier Yang wrote:
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. ---
+++ 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).
Okay, I see other virsh commands mentioned on this page, so I can improve the text.
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.
Well, we should probably change that in the future; but for now, I can document that limitation.
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".
Yeah, and mentioning PCI vs. USB as well.
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?
I don't see any point making a change here. What we really need is virNodeDeviceReAttachFlags, which lets us specify a flag to choose between forcing a reprobe (current behavior, always restores device driver based on the probe) or restoring just to the state prior to the detach (thus letting a user remove a device from pci-stub, but still leaving it unattached to any driver rather than reprobing). I've gone ahead and pushed with these modifications: diff --git i/docs/formatdomain.html.in w/docs/formatdomain.html.in index ce5554e..3b94959 100644 --- i/docs/formatdomain.html.in +++ w/docs/formatdomain.html.in @@ -1411,10 +1411,15 @@ "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, 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> + 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 virsh + 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> <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 i/tools/virsh.pod w/tools/virsh.pod index 37beb3d..8c4bc78 100644 --- i/tools/virsh.pod +++ w/tools/virsh.pod @@ -1305,15 +1305,17 @@ L<http://libvirt.org/formatnode.html>. Passthrough devices cannot be simultaneously used by the host and its guest domains. If the <hostdev> description includes the attribute -B<managed='yes'>, and the hypervisor supports it, then the device is +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-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. +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 -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
于 2011年10月21日 04:16, Eric Blake 写道:
On 10/16/2011 08:49 PM, Osier Yang wrote:
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. ---
+++ 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).
Okay, I see other virsh commands mentioned on this page, so I can improve the text.
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.
Well, we should probably change that in the future; but for now, I can document that limitation.
OK
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".
Yeah, and mentioning PCI vs. USB as well.
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?
I don't see any point making a change here. What we really need is virNodeDeviceReAttachFlags, which lets us specify a flag to choose between forcing a reprobe (current behavior, always restores device driver based on the probe) or restoring just to the state prior to the detach (thus letting a user remove a device from pci-stub, but still leaving it unattached to any driver rather than reprobing).
Good point, actually current virNodeDeviceReAttach always force the reprobing by "pciDeviceReAttachInit(pci);", I'd like work on this.
I've gone ahead and pushed with these modifications:
diff --git i/docs/formatdomain.html.in w/docs/formatdomain.html.in index ce5554e..3b94959 100644 --- i/docs/formatdomain.html.in +++ w/docs/formatdomain.html.in @@ -1411,10 +1411,15 @@ "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, 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> + 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 virsh + 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> <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 i/tools/virsh.pod w/tools/virsh.pod index 37beb3d..8c4bc78 100644 --- i/tools/virsh.pod +++ w/tools/virsh.pod @@ -1305,15 +1305,17 @@ L<http://libvirt.org/formatnode.html>.
Passthrough devices cannot be simultaneously used by the host and its guest domains. If the <hostdev> description includes the attribute -B<managed='yes'>, and the hypervisor supports it, then the device is +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-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. +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
participants (2)
-
Eric Blake -
Osier Yang