overview-manual, ref-manual, dev-manual: Moved x32 stuff

Fixes [YOCTO #12370]

The section on the x32 psABI topic was in the "technical details"
section of the reference manual.  This section combined conceptual
and "how to" information for x32 psABI.  I moved the conceptual
information to a new chapter in the overview-manual.  I moved the
"how-to" information to a separate topic in the dev-manual.  This
resulted in the mega-manual being updated to take on a new chapter
for the overview-manual (overview-concepts.xml).  No links were
affected.

(From yocto-docs rev: 84da28a4ad0f3f89bfc865f410a5d06b57439beb)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

documentation/dev-manual/dev-manual-common-tasks.xml

@@ -4531,6 +4531,38 @@
         </section>
     </section>
 
+    <section id='using-x32-psabi'>
+        <title>Using x32 psABI</title>
+
+        <para>
+            x32 processor-specific Application Binary Interface
+            (<ulink url='https://software.intel.com/en-us/node/628948'>x32 psABI</ulink>)
+            is a native 32-bit processor-specific ABI for
+            <trademark class='registered'>Intel</trademark> 64 (x86-64)
+            architectures.
+            <note>
+                For more information on x32 psABI, see the
+                "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#x32'>x32 psABI</ulink>"
+                section in the Yocto Project Overview Manual.
+            </note>
+            To use the x32 psABI, you need to edit your
+            <filename>conf/local.conf</filename> configuration file 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'}"
+            </literallayout>
+            Once you have set up your configuration file, use BitBake to
+            build an image that supports the x32 psABI.
+            Here is an example:
+            <literallayout class='monospaced'>
+     $ bitbake core-image-sato
+            </literallayout>
+        </para>
+    </section>
+
     <section id='enabling-gobject-introspection-support'>
         <title>Enabling GObject Introspection Support</title>
 

documentation/mega-manual/mega-manual.xml

@@ -141,6 +141,9 @@
     <xi:include
         xmlns:xi="http://www.w3.org/2003/XInclude" href="../overview-manual/overview-development-environment.xml"/>
 
+    <xi:include
+        xmlns:xi="http://www.w3.org/2003/XInclude" href="../overview-manual/overview-concepts.xml"/>
+
 <!-- Includes dev-manual title image and then dev-manual chapters -->
 
     <para>

documentation/overview-manual/overview-concepts.xml

@@ -0,0 +1,78 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='overview-concepts'>
+<title>Yocto Project Concepts</title>
+
+    <para>
+        This chapter presents key Yocto Project concepts.
+    </para>
+
+<section id='x32'>
+    <title>x32 psABI</title>
+
+    <para>
+        x32 processor-specific Application Binary Interface
+        (<ulink url='https://software.intel.com/en-us/node/628948'>x32 psABI</ulink>)
+        is a native 32-bit processor-specific ABI for
+        <trademark class='registered'>Intel</trademark> 64 (x86-64)
+        architectures.
+        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,
+        and also increases the 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>
+
+    <para>
+        The Yocto Project supports the final specifications of x32 psABI
+        as follows:
+        <itemizedlist>
+            <listitem><para>
+                You can create packages and images in x32 psABI format on
+                x86_64 architecture targets.
+                </para></listitem>
+            <listitem><para>
+                You can successfully build 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>
+            <listitem><para>
+                RPM Package Manager (RPM) support exists for x32 binaries.
+                </para></listitem>
+            <listitem><para>
+                Support for large images exists.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        For steps on how to use x32 psABI, see the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#using-x32-psabi'>Using x32 psABI</ulink>"
+        section in the Yocto Project Development Tasks Manual.
+    </para>
+</section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->

documentation/overview-manual/overview-manual.xml

@@ -86,6 +86,8 @@
 
     <xi:include href="overview-development-environment.xml"/>
 
+    <xi:include href="overview-concepts.xml"/>
+
 </book>
 <!--
 vim: expandtab tw=80 ts=4

documentation/ref-manual/technical-details.xml

@@ -1462,91 +1462,6 @@
     </para>
 </section>
 
-<section id='x32'>
-    <title>x32</title>
-
-    <para>
-        x32 is a 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,
-        and also increases the 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>
-            This Yocto Project release supports the final specifications of x32
-            psABI.
-            Support for x32 psABI exists as follows:
-            <itemizedlist>
-                <listitem><para>You can create packages and images in x32 psABI format on x86_64 architecture targets.
-                    </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='completing-x32'>
-        <title>Completing x32</title>
-
-        <para>
-            Future Plans for the x32 psABI in the Yocto Project include the following:
-            <itemizedlist>
-                <listitem><para>Enhance and fix the few remaining recipes so they
-                    work with and support x32 toolchains.</para></listitem>
-                <listitem><para>Enhance RPM Package Manager (RPM) support for x32 binaries.</para></listitem>
-                <listitem><para>Support larger images.</para></listitem>
-            </itemizedlist>
-        </para>
-    </section>
-
-    <section id='using-x32-right-now'>
-        <title>Using x32 Right Now</title>
-
-        <para>
-            Follow these steps to use the x32 spABI:
-            <itemizedlist>
-                <listitem><para>Enable the x32 psABI tuning file for <filename>x86_64</filename>
-                    machines by editing the <filename>conf/local.conf</filename> like this:
-                    <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 = "genericx86"
-      #DEFAULTTUNE = "core2-64-x32"
-                    </literallayout></para></listitem>
-                <listitem><para>As usual, use BitBake to build an image that supports the x32 psABI.
-                    Here is an example:
-                    <literallayout class='monospaced'>
-     $ bitbake core-image-sato
-                    </literallayout></para></listitem>
-                <listitem><para>As usual, run your image using QEMU:
-                    <literallayout class='monospaced'>
-     $ runqemu qemux86-64 core-image-sato
-                    </literallayout></para></listitem>
-            </itemizedlist>
-        </para>
-    </section>
-</section>
-
 <section id="wayland">
     <title>Wayland</title>