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

[Jiri Denemark]

Signed-off-by: Jiri Denemark <jdenemar at redhat.com>
---
 docs/formatdomain.html.in | 28 ++++++++++++++++++----------
 1 file changed, 18 insertions(+), 10 deletions(-)

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
+          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
+          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>.
           <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
+        (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>
-- 
2.11.1