Re: [libvirt] [PATCH 2/2] update documentation of <interface type='hostdev'>

On 05/09/2014 05:09 PM, Jim Fehlig wrote: > Chunyan Liu wrote: > >> <interface type='hostdev' managed='yes'> is supported, but >> nowhere mentions 'managed' in <interface type='hostdev'> syntax. >> Update documentation to cover it. >> >> > Yep, I see the managed attribute is in the schema. > > >> Signed-off-by: Chunyan Liu <cyliu(a)suse.com&gt; >> --- >> docs/formatdomain.html.in | 14 +++++++++++++- >> 1 file changed, 13 insertions(+), 1 deletion(-) >> >> diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in >> index 4f19473..c3b9f5b 100644 >> --- a/docs/formatdomain.html.in >> +++ b/docs/formatdomain.html.in >> @@ -3510,7 +3510,7 @@ >> <pre> >> ... >> &lt;devices&gt; >> - &lt;interface type='hostdev'&gt; >> + &lt;interface type='hostdev' managed='yes'&gt; >> &lt;driver name='vfio'/&gt; >> &lt;source&gt; >> &lt;address type='pci' domain='0x0000' bus='0x00' slot='0x07' function='0x0'/&gt; >> @@ -3523,6 +3523,18 @@ >> &lt;/devices&gt; >> ...</pre> >> >> + <p> >> + Similar to the functionality of a standard &lt;hostdev&gt; device, >> + 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", >> + 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. >> + </p> >> + >> >> > I suppose the only question I have is whether this paragraph should be > before the example XML snippet or after as you have placed it? Anyone > else have a comment about that? Looks good otherwise. > The most important thing of course is just having the information there at all :-). I think it is at least more common to have the the descriptions before examples using them rather than after, though, so I agree with you that the paragraph would be better before the example.

BTW, it's really cool that <interface type='hostdev'> essentially "just works" (with the one small bug fix) after turning the hostdev support functions into a hypervisor-agnostic library :-)