[libvirt] [PATCH v2 08/33] docs: Update description of the host-model CPU mode

[John Ferlan]

On 02/15/2017 11:44 AM, Jiri Denemark wrote:
> Signed-off-by: Jiri Denemark <jdenemar at redhat.com>
> ---
> 
> Notes:
>     Version 2:
>     - no change
> 
>  docs/formatdomain.html.in | 28 ++++++++++++++++++----------
>  1 file changed, 18 insertions(+), 10 deletions(-)
> 

I would think this should be merged with the previous patch, but it's
not necessary...

> diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
> index 294d3c467..9e7f7804e 100644
> --- a/docs/formatdomain.html.in
> +++ b/docs/formatdomain.html.in
> @@ -1272,16 +1272,15 @@
>            model even if the destination host contains more capable CPUs for
>            the running instance of the guest; but shutting down and restarting
>            the guest may present different hardware to the guest according to
> -          the capabilities of the new host. <strong>Beware</strong>, due to the
> -          way libvirt detects host CPU and due to the fact libvirt does not
> -          talk to QEMU/KVM when creating the CPU model, CPU configuration
> -          created using <code>host-model</code> may not work as expected. The
> -          guest CPU may differ from the configuration and it may also confuse
> -          guest OS by using a combination of CPU features and other parameters
> -          (such as CPUID level) that don't work. Until these issues are fixed,
> -          it's a good idea to avoid using <code>host-model</code> and use
> -          <code>custom</code> mode with just the CPU model from host
> -          capabilities XML.
> +          the capabilities of the new host. Libvirt older than 3.1.0 or QEMU
> +          older than 2.9.0 do not support detection of the host CPU model via

How about:

Prior to libvirt 3.1.0 and QEMU 2.9.0 detection of the host CPU model
via QEMU is not supported. Thus the CPU...

> +          QEMU and thus the CPU configuration created using
> +          <code>host-model</code> may not work as expected.
> +          <span class="since">3.1.0 and QEMU 2.9.0</span> this mode works the

s/3.1.0/Since 3.1.0/

> +          way it was designed and it is indicated by the <code>fallback</code>
> +          attribute set to <code>forbid</code> in the host-model CPU
> +          definition advertised in <a href="formatdomaincaps.html#elementsCPU"
> +          >domain capabilities XML</a>.

You may want to keep some simple text to describe what to do for
releases prior to 3.1.0/2.9.0... e.g. "Without the proper support, it's
recommended to use <code>custom</code> mode with just the CPU model from
the host capabilities XML."

Your call on this part - it's just me thinking of those who read this
documentation that do not have 3.1.0 and 2.9.0...


>            <span class="since">Since 1.2.11</span> PowerISA allows
>            processors to run VMs in binary compatibility mode supporting an
>            older version of ISA.  Libvirt on PowerPC architecture uses the
> @@ -1307,6 +1306,15 @@
>            a migration is attempted then the guest may hang or crash upon
>            resuming execution on the destination host.</dd>
>          </dl>
> +
> +        Both <code>host-model</code> and <code>host-passthrough</code> modes
> +        make sense when a domain can run directly on the host CPUs without

without what?


ACK with a couple of tweaks

John
> +        (for example, domains with type <code>kvm</code>). The actual host CPU
> +        is irrelevant for domains with emulated virtual CPUs (such as domains
> +        with type <code>qemu</code>). However, for backward compatibility
> +        <code>host-model</code> may be implemented even for domains running on
> +        emulated CPUs in which case the best CPU the hypervisor is able to
> +        emulate may be used rather then trying to mimic the host CPU model.
>        </dd>
>  
>        <dt><code>model</code></dt>
>