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

[Eduardo Habkost]

On Tue, Jun 12, 2018 at 10:58:46AM +0200, Kashyap Chamarthy wrote:
> Eduardo Habkost has pointed out that the current documentation of
> libvirt's CPU feature policy "require" vs. "force" does not match
> QEMU's behaviour.
> 
> Update the documentation by spelling out the QEMU version dependency and
> explain in which scenarios the usage of "policy = 'force'" is applicable
> or not.
> 
> Signed-off-by: Kashyap Chamarthy <kchamart at redhat.com>
> ---
> Wordsmithing / corrections welcome.
> ---
>  docs/formatdomain.html.in | 13 +++++++++++--
>  1 file changed, 11 insertions(+), 2 deletions(-)
> 
> 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>
> +          <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.e. when using the

This isn't true for any QEMU versions.  QEMU never enables a
feature if it's not supported by the host.


> +          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>
>            <dt><code>require</code></dt>
>            <dd>Guest creation will fail unless the feature is supported by the
>              host CPU or the hypervisor is able to emulate it.</dd>
> -- 
> 2.17.0
> 

-- 
Eduardo