documentation/poky-ref-manual/technical-details.xml: new x32 section added.

(From yocto-docs rev: 78f8b0367b3e5bbc71712f71fe87367d929424c8)

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

1 files changed, 113 insertions, 0 deletions

diff --git a/documentation/poky-ref-manual/technical-details.xml b/documentation/poky-ref-manual/technical-details.xml
index f327806eb2..7905697ec0 100644
--- a/documentation/poky-ref-manual/technical-details.xml
+++ b/documentation/poky-ref-manual/technical-details.xml
@@ -566,6 +566,119 @@
     </section>
 </section>
 
+<section id='x32'>
+    <title>x32</title>
+
+    <para>
+        x32 is a new processor-specific Application Binary Interface (psABI) for x86_64. 
+        An ABI defines the calling conventions between functions in a processing environment.  
+        The interface determines what registers are used and what the sizes are for various C data types.
+    </para>
+
+    <para>
+        Some processing environments prefer using 32-bit applications even when running 
+        on Intel 64-bit platforms. 
+        Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms.
+        The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources,
+        leaving the system underutilized. 
+        Now consider the x86_64 psABI.
+        This ABI is newer and uses 64-bits for data sizes and program pointers.
+        The extra bits increase the footprint size of the programs, libraries, memory, and file system size 
+        requirements.
+        Executing under the x32 psABI enables user programs to utilize CPU and system resources 
+        more efficiently while keeping the memory footprint of the applications low.
+        Extra bits are used for registers but not for addressing mechanisms. 
+    </para>
+
+    <section id='support'>
+        <title>Support</title>
+
+        <para>
+            While the x32 psABI is not fully implemented with this release of the Yocto Project, 
+            it is partially functional.
+            As of this release of the Yocto Project, x32 psABI support exists as follows:
+            <itemizedlist>
+                <listitem><para>You can create packages and images using an x32 psABI on x86_64 architecture targets. 
+                    </para></listitem>
+                <listitem><para>You can use the x32 psABI support through the <filename>meta-x32</filename>
+                    layer on top of the OE-core/Yocto layer.</para></listitem>
+                <listitem><para>You can use the toolchain for building x32 psABI program binaries and kernel support 
+                    from the <filename>experimental/meta-x32</filename> layer.</para></listitem>
+                <listitem><para>You can successfully build many recipes with the x32 toolchain.</para></listitem>
+                <listitem><para>You can create and boot <filename>core-image-minimal</filename> and 
+                    <filename>core-image-sato</filename> images.</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='future-development-and-limitations'>
+        <title>Future Development and Limitations</title>
+
+        <para>
+            For this release of the Yocto Project, the x32 psABI kernel and library interfaces 
+            and their use are not finalized.
+        </para>
+
+        <para>
+            Plans for the x32 psABI in the Yocto Project include the following:
+            <itemizedlist>
+                <listitem><para>Enhance and fix recipes so they fully 
+                    support x32 toolchains and binaries.</para></listitem>
+                <listitem><para>Complete RPM Package Manager (RPM) support for x32 binaries.</para></listitem>
+                <listitem><para>Support larger images.</para></listitem>
+                <listitem><para>Integrate x32 toolchain and kernel changes from 
+                    <filename>experimental/meta-x32</filename> into OE-core.</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='using-x32-right-now'>
+        <title>Using x32 Right Now</title>
+
+        <para>
+            Despite the fact that the x32 psABI is incomplete for this release of the Yocto Project, you can 
+            use it to some degree.
+            Follow these steps to use the x32 spABI:
+            <itemizedlist>
+                <listitem><para>Add the <filename>experimental/meta-x32</filename> layer to your local
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-files'>Yocto Project Files</ulink>
+                    Git repository.  
+                    You can find the <filename>experimental/meta-x32</filename> source repository at
+                    <ulink url='&YOCTO_GIT_URL;'></ulink>.</para></listitem>
+                <listitem><para>Edit your <filename>conf/bblayers.conf</filename> file so that it includes
+                    the <filename>experimental/meta-x32</filename>.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     BBLAYERS ?= " \
+        /home/nitin/prj/poky.git/meta \
+        /home/nitin/prj/poky.git/meta-yocto \
+        /home/nitin/prj/meta-x32.git \
+     "
+                    </literallayout></para></listitem>
+                <listitem><para>Enable the x32 psABI tuning file for <filename>x86_64</filename>
+                    machines by editing the <filename>conf/local.conf</filename> as follows:
+                    <literallayout class='monospaced'>
+      MACHINE = "qemux86-64"
+      DEFAULTTUNE = "x86-64-x32"
+      baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \
+         or 'INVALID'), True) or 'lib'}"
+      #MACHINE = "atom-pc"
+      #DEFAULTTUNE = "core2-64-x32"
+                    </literallayout></para></listitem> 
+                <listitem><para>Use BitBake to build an image that supports the x32 psABI.  
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     $ bitake core-image-sato
+                    </literallayout></para></listitem>
+                <listitem><para>Run your image using QUEM:
+                    <literallayout class='monospaced'>
+     $ runqemu qemux86-64 core-image-sato
+                    </literallayout></para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+</section>
+
 <section id="licenses">
     <title>Licenses</title>