documentation/poky-ref-manual/ref-variables.xml: New KMACHINE gloss entry

Created a new glossary entry for the KMACHINE variable.  I used
Bruce Ashfield as my resource for understanding this variable.

(From yocto-docs rev: 1069ddb3fe0b3bd00ba651b51419354258ae57d3)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 88 insertions, 0 deletions

diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index f83844e0a7..9a4e56043e 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -1128,6 +1128,94 @@ recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
+            <glossdef>
+                <para>
+                    The machine as known by the kernel.
+                    Sometimes the machine name used by the kernel does not match the machine name
+                    used by the OpenEmbedded build system.
+                    For example, the machine name that the OpenEmbedded build system understands as 
+                    <filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel.
+                    The kernel understands that machine as <filename>arm_versatile926ejs</filename>.
+                    For cases like these, the <filename>KMACHINE</filename> variable maps the 
+                    kernel machine name to the OpenEmbedded build system machine name.
+                </para>
+
+                <para>
+                    Kernel machine names are initially defined in the 
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink> in 
+                    the <filename>meta/cfg/kernel-cache/bsp/&lt;bsp_name&gt;/&lt;bsp-name&gt;-&lt;kernel-type&gt;.scc</filename> file.
+                    For example, in the <filename>linux-yocto-3.4</filename> kernel in the 
+                    <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file, 
+                    has the following:
+                    <literallayout class='monospaced'>
+     define KMACHINE cedartrail
+     define KTYPE standard
+     define KARCH i386
+
+     include ktypes/standard
+     branch cedartrail
+
+     include cedartrail.scc
+                    </literallayout>
+                    You can see that the kernel understands the machine name for the Cedar Trail BSP as
+                    <filename>cedartrail</filename>.
+                </para>
+
+                <para>
+                    If you look in the Cedar Trail BSP layer in the <filename>meta-intel</filename> source
+                    repository at <filename>meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>,
+                    you will find the following statements among others:
+                    <literallayout class='monospaced'>
+     COMPATIBLE_MACHINE_cedartrail = "cedartrail"
+     KMACHINE_cedartrail  = "cedartrail"
+     KBRANCH_cedartrail  = "yocto/standard/cedartrail"
+     KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc"
+     KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc"
+
+     COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail"
+     KMACHINE_cedartrail-nopvr  = "cedartrail"
+     KBRANCH_cedartrail-nopvr  = "yocto/standard/cedartrail"
+     KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc"
+                    </literallayout>
+                    The <filename>KMACHINE</filename> statements in the kernel's append file make sure that 
+                    the OpenEmbedded build system and the Yocto Linux kernel understand the same machine 
+                    names. 
+                </para>
+
+                <para>
+                    This append file uses two <filename>KMACHINE</filename> statements.
+                    The first is not really necessary but does ensure that the machine known to the 
+                    OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine
+                    in the kernel also known as <filename>cedartrail</filename>:
+                    <literallayout class='monospaced'>
+     KMACHINE_cedartrail  = "cedartrail"
+                    </literallayout>
+                </para>
+
+                <para>
+                    The second statement is a good example of why the <filename>KMACHINE</filename> variable
+                    is needed. 
+                    In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename>
+                    machine name to refer to the Cedar Trail BSP that does not support the propriatory 
+                    PowerVR driver.
+                    The kernel, however, uses the machine name <filename>cedartrail</filename>.
+                    Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to 
+                    the kernel's <filename>cedartrail</filename> name:
+                    <literallayout class='monospaced'>
+     KMACHINE_cedartrail-nopvr  = "cedartrail"
+                    </literallayout>
+                </para>
+
+                <para>
+                    BSPs that ship with the Yocto Project release provide all mappings between the Yocto 
+                    Project kernel machine names and the OpenEmbedded machine names. 
+                    Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine 
+                    name you use is different than that used in the kernel.
+                </para>
+            </glossdef>
+        </glossentry>
+
    </glossdiv>
 
     <glossdiv id='var-glossary-l'><title>L</title>