[libvirt] [PATCH] docs: document managed=yes of hostdev passthrough

[Osier Yang]

于 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
>
>
>