[PATCH] docs: fix typo in domcaps host-model CPU description

[Jiri Denemark]

On Mon, Mar 23, 2020 at 15:47:49 -0600, Jim Fehlig wrote:
> The domain capabilities documentation contains a small but confusing
> error in the host-model CPU description, referencing the element <mode>
> instead of <model>. Fix this small typo.
> 
> Signed-off-by: Jim Fehlig <jfehlig at suse.com>
> ---
> 
> I only found this small typo (well, I'm pretty sure it's a typo :-)) by
> tring to understand a more confusing observation. On a machine where
> capabilities reports CascaseLake-Server, domcapabilities reports
> 
>     <mode name='host-model' supported='yes'>
>       <model fallback='forbid'>Cascadelake-Server</model>
>       <vendor>Intel</vendor>
>       <feature policy='require' name='ss'/>
>       <feature policy='require' name='hypervisor'/>
>       <feature policy='require' name='tsc_adjust'/>
>       <feature policy='require' name='umip'/>
>       <feature policy='require' name='pku'/>
>       <feature policy='require' name='md-clear'/>
>       <feature policy='require' name='stibp'/>
>       <feature policy='require' name='arch-capabilities'/>
>       <feature policy='require' name='xsaves'/>
>       <feature policy='require' name='invtsc'/>
>     </mode>
>     <mode name='custom' supported='yes'>
>       ...
>       <model usable='no'>Cascadelake-Server</model>
>     </mode>
> 
> So using host-model will result in a CascadeLake-Server CPU, but it
> is not supported when specifying a custom CPU? Interestingly, I see
> something similar from domcapabilities on machine where capabilities
> reports Skylake-Server-IBRS
> 
>     <mode name='host-model' supported='yes'>
>       <model fallback='forbid'>Cascadelake-Server</model>
>       <vendor>Intel</vendor>
>       <feature policy='require' name='ss'/>
>       <feature policy='require' name='hypervisor'/>
>       <feature policy='require' name='tsc_adjust'/>
>       <feature policy='require' name='umip'/>
>       <feature policy='require' name='md-clear'/>
>       <feature policy='require' name='stibp'/>
>       <feature policy='require' name='arch-capabilities'/>
>       <feature policy='require' name='xsaves'/>
>       <feature policy='require' name='invtsc'/>
>       <feature policy='disable' name='pku'/>
>       <feature policy='disable' name='avx512vnni'/>
>     </mode>
>     <mode name='custom' supported='yes'>
>       ...
>       <model usable='no'>Skylake-Server-IBRS</model>
>       <model usable='no'>Skylake-Server</model>
>       <model usable='no'>Cascadelake-Server</model>
>     </mode>
> 
> This seems contradictory to me but perhaps I'm overlooking something?

The usable=yse|no attribute says whether a given CPU model can be
provided to a guest without any modification. That is whether you can
use
        <cpu mode='custom' match='exact'>
          <model fallback='forbid'>Cascadelake-Server</model>
        </cpu>

When usable='no', QEMU will need to disable some of the features that
are part of the Cascadelake-Server CPU model. In other words, the CPU
model is not usable as is.

On the other hand, the <mode name='host-model'> element in domain
capabilities describes the CPU used as a host-model CPU by adding or
removing some specific features. In other words, while using the simple
CPU definition mentioned above would cause QEMU to drop some features,
using a more verbose

      <cpu mode='custom' match='exact'>
        <model fallback='forbid'>Cascadelake-Server</model>
        <vendor>Intel</vendor>
        <feature policy='require' name='ss'/>
        <feature policy='require' name='hypervisor'/>
        <feature policy='require' name='tsc_adjust'/>
        <feature policy='require' name='umip'/>
        <feature policy='require' name='md-clear'/>
        <feature policy='require' name='stibp'/>
        <feature policy='require' name='arch-capabilities'/>
        <feature policy='require' name='xsaves'/>
        <feature policy='require' name='invtsc'/>
        <feature policy='disable' name='pku'/>
        <feature policy='disable' name='avx512vnni'/>
      </cpu>

explicitly asks QEMU to disable pku and avx512vnni features and thus
QEMU will not have to disable anything.

The situation on the first machine is a bit strange as there are no
features disabled in host-model CPU definition, which makes it unclear
why QEMU reports Cascadelake-Server as unusable (QEMU reports the
reason, but we don't do so yet).

Anyway, would you mind running the tests/cputestdata/cpu-gather.sh
script on both machines (make sure to install qemu, python3, and cpuid
packages first) and send us the output so that we can check the CPU
models are properly detected?

>  docs/formatdomaincaps.html.in | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/docs/formatdomaincaps.html.in b/docs/formatdomaincaps.html.in
> index 66e758501b..7fd1f91f73 100644
> --- a/docs/formatdomaincaps.html.in
> +++ b/docs/formatdomaincaps.html.in
> @@ -232,7 +232,7 @@
>        <dt><code>host-model</code></dt>
>        <dd>
>          If <code>host-model</code> is supported by the hypervisor, the
> -        <code>mode</code> describes the guest CPU which will be used when
> +        <code>model</code> describes the guest CPU which will be used when
>          starting a domain with <code>host-model</code> CPU. The hypervisor
>          specifics (such as unsupported CPU models or features, machine type,
>          etc.) may be accounted for in this guest CPU specification and thus

As strange as it seems, there's no typo. The <model> element describes
just a small part of the whole CPU. There are additional <vendor> and
<feature> elements which also belong to the CPU definition. All these
elements are children of the <mode> element and thus the <mode> element
describes the guest CPU. Yes, this is not the best design and having an
entire <cpu> element rather than its children in the
<mode name='host-model' supported='yes'> element would be better, but we
can't really do anything about it now.

Jirka