summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/poky-ref-manual/technical-details.xml113
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 @@
566 </section> 566 </section>
567</section> 567</section>
568 568
569<section id='x32'>
570 <title>x32</title>
571
572 <para>
573 x32 is a new processor-specific Application Binary Interface (psABI) for x86_64.
574 An ABI defines the calling conventions between functions in a processing environment.
575 The interface determines what registers are used and what the sizes are for various C data types.
576 </para>
577
578 <para>
579 Some processing environments prefer using 32-bit applications even when running
580 on Intel 64-bit platforms.
581 Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms.
582 The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources,
583 leaving the system underutilized.
584 Now consider the x86_64 psABI.
585 This ABI is newer and uses 64-bits for data sizes and program pointers.
586 The extra bits increase the footprint size of the programs, libraries, memory, and file system size
587 requirements.
588 Executing under the x32 psABI enables user programs to utilize CPU and system resources
589 more efficiently while keeping the memory footprint of the applications low.
590 Extra bits are used for registers but not for addressing mechanisms.
591 </para>
592
593 <section id='support'>
594 <title>Support</title>
595
596 <para>
597 While the x32 psABI is not fully implemented with this release of the Yocto Project,
598 it is partially functional.
599 As of this release of the Yocto Project, x32 psABI support exists as follows:
600 <itemizedlist>
601 <listitem><para>You can create packages and images using an x32 psABI on x86_64 architecture targets.
602 </para></listitem>
603 <listitem><para>You can use the x32 psABI support through the <filename>meta-x32</filename>
604 layer on top of the OE-core/Yocto layer.</para></listitem>
605 <listitem><para>You can use the toolchain for building x32 psABI program binaries and kernel support
606 from the <filename>experimental/meta-x32</filename> layer.</para></listitem>
607 <listitem><para>You can successfully build many recipes with the x32 toolchain.</para></listitem>
608 <listitem><para>You can create and boot <filename>core-image-minimal</filename> and
609 <filename>core-image-sato</filename> images.</para></listitem>
610 </itemizedlist>
611 </para>
612 </section>
613
614 <section id='future-development-and-limitations'>
615 <title>Future Development and Limitations</title>
616
617 <para>
618 For this release of the Yocto Project, the x32 psABI kernel and library interfaces
619 and their use are not finalized.
620 </para>
621
622 <para>
623 Plans for the x32 psABI in the Yocto Project include the following:
624 <itemizedlist>
625 <listitem><para>Enhance and fix recipes so they fully
626 support x32 toolchains and binaries.</para></listitem>
627 <listitem><para>Complete RPM Package Manager (RPM) support for x32 binaries.</para></listitem>
628 <listitem><para>Support larger images.</para></listitem>
629 <listitem><para>Integrate x32 toolchain and kernel changes from
630 <filename>experimental/meta-x32</filename> into OE-core.</para></listitem>
631 </itemizedlist>
632 </para>
633 </section>
634
635 <section id='using-x32-right-now'>
636 <title>Using x32 Right Now</title>
637
638 <para>
639 Despite the fact that the x32 psABI is incomplete for this release of the Yocto Project, you can
640 use it to some degree.
641 Follow these steps to use the x32 spABI:
642 <itemizedlist>
643 <listitem><para>Add the <filename>experimental/meta-x32</filename> layer to your local
644 <ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-files'>Yocto Project Files</ulink>
645 Git repository.
646 You can find the <filename>experimental/meta-x32</filename> source repository at
647 <ulink url='&YOCTO_GIT_URL;'></ulink>.</para></listitem>
648 <listitem><para>Edit your <filename>conf/bblayers.conf</filename> file so that it includes
649 the <filename>experimental/meta-x32</filename>.
650 Here is an example:
651 <literallayout class='monospaced'>
652 BBLAYERS ?= " \
653 /home/nitin/prj/poky.git/meta \
654 /home/nitin/prj/poky.git/meta-yocto \
655 /home/nitin/prj/meta-x32.git \
656 "
657 </literallayout></para></listitem>
658 <listitem><para>Enable the x32 psABI tuning file for <filename>x86_64</filename>
659 machines by editing the <filename>conf/local.conf</filename> as follows:
660 <literallayout class='monospaced'>
661 MACHINE = "qemux86-64"
662 DEFAULTTUNE = "x86-64-x32"
663 baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \
664 or 'INVALID'), True) or 'lib'}"
665 #MACHINE = "atom-pc"
666 #DEFAULTTUNE = "core2-64-x32"
667 </literallayout></para></listitem>
668 <listitem><para>Use BitBake to build an image that supports the x32 psABI.
669 Here is an example:
670 <literallayout class='monospaced'>
671 $ bitake core-image-sato
672 </literallayout></para></listitem>
673 <listitem><para>Run your image using QUEM:
674 <literallayout class='monospaced'>
675 $ runqemu qemux86-64 core-image-sato
676 </literallayout></para></listitem>
677 </itemizedlist>
678 </para>
679 </section>
680</section>
681
569<section id="licenses"> 682<section id="licenses">
570 <title>Licenses</title> 683 <title>Licenses</title>
571 684