[yocto] [yocto-docs][PATCH] dev-manual: document CPU features and QB_CPU_KVM

[Martin Kelly]

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.

Signed-off-by: Martin Kelly <mkelly at xevo.com>
---
 documentation/dev-manual/dev-manual-qemu.xml | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/documentation/dev-manual/dev-manual-qemu.xml b/documentation/dev-manual/dev-manual-qemu.xml
index f4719ebc3..1870a6a8d 100644
--- a/documentation/dev-manual/dev-manual-qemu.xml
+++ b/documentation/dev-manual/dev-manual-qemu.xml
@@ -343,6 +343,28 @@
         </para>
     </section>
 
+    <section id='qemu-kvm-cpu-compatibility'>
+        <title>QEMU CPU Compatiblity under KVM</title>
+
+        <para>
+            By default, the QEMU build compiles for and targets core2duo (for
+            64-bit x86) and pentium2 (for 32-bit x86). These CPUS are chose to
+            have a broad range of CPU feature compatibility with many commonly
+            used CPUs, but in some cases, they still support a CPU feature that
+            your host CPU does not. Although this is not a problem when QEMU
+            uses software emulation of the feature, it can be when running with
+            KVM enabled. Specifically, software compiled with a certain CPU
+            feature will crash when run on a CPU under KVM that does not support
+            that feature. If this becomes a 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 image deploy
+            directory. This setting specifies a <filename>-cpu</filename> option
+            passed into QEMU in the <filename>runqemu</filename> script. Running
+            <filename>qemu -cpu help</filename> will give a list of supported
+            CPU types available.
+        </para>
+    </section>
+
     <section id='qemu-dev-performance'>
         <title>QEMU Performance</title>
 
-- 
2.11.0