From 8cfb40ce4c633a3a648a9300cf9b9b76311c566d Mon Sep 17 00:00:00 2001
From: Martin Kelly <mkelly@xevo.com>
Date: Mon, 30 Apr 2018 10:35:36 -0700
Subject: dev-manual: New section in QEMU for workaround under KVM

As suggested in a recent mail thread by Martin Jansa, there are cases in
which QEMU under KVM will crash because of CPU feature incompatibilities
between compiled binaries and the host CPU under which qemu is run.
Although this is hard to fully escape, we should document the issue to
help people work around it.  I have taked Martin's suggested patch
and did some rewording for the new section.

(From yocto-docs rev: 6c625fcf631a82529bc58ec8fb0c18dbe13188d2)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 documentation/dev-manual/dev-manual-qemu.xml | 34 ++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

(limited to 'documentation/dev-manual')

diff --git a/documentation/dev-manual/dev-manual-qemu.xml b/documentation/dev-manual/dev-manual-qemu.xml
index f4719ebc3c..4e7b5de4e8 100644
--- a/documentation/dev-manual/dev-manual-qemu.xml
+++ b/documentation/dev-manual/dev-manual-qemu.xml
@@ -343,6 +343,40 @@
         </para>
     </section>
 
+    <section id='qemu-kvm-cpu-compatibility'>
+        <title>QEMU CPU Compatibility Under KVM</title>
+
+        <para>
+            By default, the QEMU build compiles for and targets 64-bit and x86
+            <trademark class='registered'>Intel</trademark> <trademark class='trademark'>Core</trademark>2
+            Duo processors and 32-bit x86
+            <trademark class='registered'>Intel</trademark> <trademark class='registered'>Pentium</trademark>
+            II processors.
+            QEMU builds for and targets these CPU types because they display
+            a broad range of CPU feature compatibility with many commonly
+            used CPUs.
+        </para>
+
+        <para>
+            Despite this broad range of compatibility, the CPUs could support
+            a feature that your host CPU does not support.
+            Although this situation is not a problem when QEMU uses software
+            emulation of the feature, it can be a problem when QEMU is
+            running with KVM enabled.
+            Specifically, software compiled with a certain CPU feature crashes
+            when run on a CPU under KVM that does not support that feature.
+            To work around this problem, you can override QEMU's runtime CPU
+            setting by changing the <filename>QB_CPU_KVM</filename>
+            variable in <filename>qemuboot.conf</filename> in the
+            <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory's</ulink>
+            <filename>deploy/image</filename> directory.
+            This setting specifies a <filename>-cpu</filename> option
+            passed into QEMU in the <filename>runqemu</filename> script.
+            Running <filename>qemu -cpu help</filename> returns a list of
+            available supported CPU types.
+        </para>
+    </section>
+
     <section id='qemu-dev-performance'>
         <title>QEMU Performance</title>
 
-- 
cgit v1.2.3-54-g00ecf