[libvirt] [PATCH] docs: formatdomain: Note the caveats for CPU policy option "force"

[Kashyap Chamarthy]

On Fri, Jun 22, 2018 at 02:19:52PM +0200, Jiri Denemark wrote:
> On Tue, Jun 12, 2018 at 10:58:46 +0200, Kashyap Chamarthy wrote:

[...]

> > diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
> > index 6912762f28..4d6c3892ee 100644
> > --- a/docs/formatdomain.html.in
> > +++ b/docs/formatdomain.html.in
> > @@ -1566,8 +1566,17 @@
> >  
> >          <dl>
> >            <dt><code>force</code></dt>
> > -          <dd>The virtual CPU will claim the feature is supported regardless
> > -            of it being supported by host CPU.</dd>
> 
> The original content was indented. Also I don't think you're supposed to
> add two <dd> elements after single <dt>.

Hmm, I made a test locally to see it renders as intented.  Because, I
wnated the second paragraph to be on a separate line.

> 
> > +          <dd>The virtual CPU will claim the feature is supported
> > +          regardless of it being supported by host CPU -- this is only
> > +          true for QEMU version older than 2.9.0.
> 
> I'd suggest
> 
>     Libvirt will ask the hypervisor to enable the feature regardless of
>     it being supported by host CPU. The hypervisor will likely ignore
>     this request if the feature is not supported by the host CPU or if
>     it cannot be emulated. In other words, it is useful for features
>     which do not exist in real hardware, such as 'virt-ssbd', or which
>     can be emulated, such as 'x2apic'.

Yes, your wording is much clearer.

> > I.e. when using the
> > +          CPU mode 'host-model', libvirt identifies which CPU features
> > +          to use by looking at host CPUID.  For that to take effect, it
> > +          is mandatory to use <code>force</code> to tell libvirt that a
> > +          said CPU feature must be used despite it not existing in the
> > +          host -- this applicable only for a very limited set of CPU
> > +          features, such as 'x2apic', virt-ssbd' (for AMD CPUs).</dd>
> > +          <dd>However, when using QEMU 2.9.0 and above, there should
> > +          never be any need to use <code>force</code>.</dd>
> 
> What was the motivation behind this change? I find it quite confusing
> that this is supposed to describe 'force' policy and suddenly you're
> talking about host-model CPU mode.

Hmm, re-reading, indeed the flow from the previous sentence to the "I.e.
when using the CPU mode 'host-model'" seems like a non-sequitur.

My intention was to add a note about in which scenarios specifying
'force' makes sense.  IIRC, I learnt from Dan Berrangé that if you are
using a QEMU version that is older than 2.9.0, then 'force' is required
for a guest that needs features that don't exist in the real CPU.  If
you are using QEMU >= 2.9.0, then 'force' is not required.

-- 
/kashyap