documentation/poky-ref-manual/ref-variables.xml: Added KBRANCH entry

New finalized entry for KBRANCH.  Reviewed by Bruce Ashfield.

(From yocto-docs rev: 566e112d20ebe91a1302263b96254f6f66462aaf)

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

1 files changed, 56 insertions, 1 deletions

diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index db9d7370f4..6807c5c309 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -26,7 +26,7 @@
        <link linkend='var-HOMEPAGE'>H</link> 
        <link linkend='var-IMAGE_FEATURES'>I</link> 
 <!--               <link linkend='var-glossary-j'>J</link> -->
-       <link linkend='var-KERNEL_FEATURES'>K</link>
+       <link linkend='var-KBRANCH'>K</link>
        <link linkend='var-LAYERDIR'>L</link> 
        <link linkend='var-MACHINE'>M</link> 
 <!--               <link linkend='var-glossary-n'>N</link> -->
@@ -1035,6 +1035,61 @@ recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
 
    <glossdiv id='var-glossary-k'><title>K</title>
 
+        <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
+            <glossdef>
+                <para>
+                    A regular expression used by the build process to explicitly identify the kernel 
+                    branch that is validated, patched and configured during a build.  
+                    The <filename>KBRANCH</filename> variable is optional.
+                    You can use it to trigger checks to ensure the exact kernel branch you want is 
+                    being used by the build process.
+                </para>
+
+                <para>
+                    Values for this variable are set in the kernel's recipe file and the kernel's 
+                    append file.  
+                    For example, if you are using the Yocto Project kernel that is based on the 
+                    Linux 3.2 kernel, the kernel recipe file is the 
+                    <filename>meta/recipes-kernel/linux/linux-yocto_3.2.bb</filename> file. 
+                    Following is the default value for <filename>KBRANCH</filename> and the five overrides 
+                    for the architectures the Yocto Project supports:
+                    <literallayout class='monospaced'>
+     KBRANCH = "standard/default/base"
+     KBRANCH_qemux86  = "standard/default/common-pc/base"
+     KBRANCH_qemux86-64  = "standard/default/common-pc-64/base"
+     KBRANCH_qemuppc  = "standard/default/qemu-ppc32"
+     KBRANCH_qemumips = "standard/default/mti-malta32-be"
+     KBRANCH_qemuarm  = "standard/default/arm-versatile-926ejs"
+                    </literallayout>
+                    Each of the above branches exist in the <filename>linux-yocto-3.2</filename> kernel Git 
+                    repository <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.2/refs/heads'></ulink>.  
+                </para>
+
+                <para>
+                    This variable is also used from the kernel's append file to identify the kernel 
+                    branch specific to a particular machine or target hardware.  
+                    The kernel's append file is located in the BSP layer for a given machine.  
+                    For example, the kernel append file for the Crown Bay BSP is in the 
+                    <filename>meta-intel</filename> Git repository and is named 
+                    <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.2.bbappend</filename>.  
+                    Here are the related statements from the append file:
+                    <literallayout class='monospaced'>
+     COMPATIBLE_MACHINE_crownbay = "crownbay"
+     KMACHINE_crownbay  = "crownbay"
+     KBRANCH_crownbay  = "standard/default/crownbay"
+     
+     COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
+     KMACHINE_crownbay-noemgd  = "crownbay"
+     KBRANCH_crownbay-noemgd  = "standard/default/crownbay"
+                    </literallayout>
+                        The <filename>KBRANCH_*</filename> statements identify the kernel branch to 
+                        use when building for the Crown Bay BSP.  
+                        In this case there are two identical statements: one for each type of 
+                        Crown Bay machine.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
             <glossdef>
                 <para>Includes additional metadata from the Yocto Project kernel Git repository.