[libvirt] [PATCH] docs: formatdomain: Document the CPU feature 'name' attribute

[Eduardo Habkost]

On Wed, Jan 17, 2018 at 09:04:26AM +0100, Kashyap Chamarthy wrote:
> On Tue, Jan 16, 2018 at 03:35:20PM -0200, Eduardo Habkost wrote:
> > On Fri, Jan 12, 2018 at 08:31:16PM +0100, Kashyap Chamarthy wrote:
> > > Currently, the CPU feature 'name' XML attribute, as in:
> 
> [...]
> 
> > > ---
> > >  docs/formatdomain.html.in | 17 +++++++++++++++++
> > >  1 file changed, 17 insertions(+)
> > > 
> > > diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
> > > index d272cc1ba..e717fb3aa 100644
> > > --- a/docs/formatdomain.html.in
> > > +++ b/docs/formatdomain.html.in
> > > @@ -1454,6 +1454,23 @@
> > >  
> > >          <span class="since">Since 0.8.5</span> the <code>policy</code>
> > >          attribute can be omitted and will default to <code>require</code>.
> > > +
> > > +        Individual CPU feature names can be specified as part of the
> > > +        <code>name</code> attribute.
> > 
> > Isn't this "should" instead of "can"?  Does it make sense to have
> > a 'feature' element without a 'name' attribute?
> 
> Good catch.  Near as I see, it doesn't.  So I'll: s/can/should.
> 
> > 
> > >                                       The list of known CPU feature
> > > +        names (e.g. 'vmx', 'cmt', et cetera) can be found in the same
> > > +        file as CPU models -- <code>cpu_map.xml</code>. For example,
> > > +        to explicitly specify the 'pcid' feature with Intel IvyBridge
> > > +        CPU model:
> > 
> > Another paragraph above already says "The list of known feature
> > names can be found in the same file as CPU models".   If you think the
> > existing paragraph is not enough, I suggest rewriting it so the
> > document won't repeat exactly the same thing.
> 
> True.  How about this rewrite: 
> 
>     "Once you choose a feature (e.g. 'pcid') from the `cpu_map.xml`, to
>     specify it explicitly with the Intel IvyBridge CPU model [...]"

"Once you choose a feature (e.g. 'pcid') from the `cpu_map.xml`"
doesn't seem to convey any additional information that wasn't
mentioned before.  What about just "For example, to explicitly
specify the 'pcid' feature with Intel IvyBridge CPU model:"?

> 
> I'll consider whether to also add a note that before specifying extra
> CPU feature flags, one should check if the named CPU models provided by
> libvirt already include the said flags.

Maybe this would be too much information.  It's harmless to set a feature
explicitly to 'require' if the CPU model already contains the feature.

-- 
Eduardo