ELFv2-ABI/specification/ch_1.xml

<!--
  Copyright (c) 2016 OpenPOWER Foundation
  
  Licensed under the GNU Free Documentation License, Version 1.3;
  with no Invariants Sections, with no Front-Cover Texts,
  and with no Back-Cover Texts (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

    http://www.gnu.org/licenses/fdl-1.3.txt

-->
<chapter xmlns="http://docbook.org/ns/docbook"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xl="http://www.w3.org/1999/xlink" 
  version="5.0" xml:lang="en"
  xml:id="ch_1">
  <title>Introduction</title>
  
  <para>The Executable and Linking Format (ELF) defines a linking interface
  for executables and shared objects in two parts.</para>
  <itemizedlist>
    <listitem>
      <para>The first part is the generic System V ABI 
      (<link xl:href="http://refspecs.linuxfoundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/normativerefs.html#NORMATIVEREFSSECT">http://refspecs.linuxfoundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/normativerefs.html#NORMATIVEREFSSECT</link>).
      </para>
    </listitem>
    <listitem>
      <para>The second part is a processor-specific supplement.</para>
    </listitem>
  </itemizedlist>
  <para>This document, the OpenPOWER ABI for Linux Supplement for the Power
  Architecture 64-bit ELF V2 ABI, is the OpenPOWER-compliant
  processor-specific supplement for use with ELF V2 on 64-bit IBM Power
  Architecture® systems. This is not a complete System V ABI supplement
  because it does not define any library interfaces.</para>
  <para>This document establishes both big-endian and little-endian
  application binary interfaces (see 
  <xref linkend="dbdoclet.50655240___RefHeading___Toc377640574" />).
  OpenPOWER-compliant processors in the 64-bit Power Architecture can execute
  in either big-endian or little-endian mode. Executables and
  executable-generated data (in general) that subscribe to either byte
  ordering are not portable to a system running in the other mode.</para>
  <itemizedlist>
    <listitem>
      <para>Note: 
        <link xl:href="http://www.power.org/">This ABI specification does not 
        address little-endian byte ordering before Power ISA 2.03.</link>
      </para>
    </listitem>
  </itemizedlist>
  <para>The OpenPOWER ELF V2 ABI is not the same as either the Power
  Architecture 32-bit ABI supplement or the 64-bit IBM PowerPC® ELF ABI (ELF
  V1).</para>
  <para>The Power Architecture 64-bit OpenPOWER ELF V2 ABI supplement is
  intended to use the same structural layout now followed in practice by
  other processor-specific ABIs.</para>

  <section xml:id="dbdoclet.50655239___RefHeading___Toc377640569">
    <title>Reference Documentation</title>
    <para>The archetypal ELF ABI is described by the System V ABI.
    Supersessions and addenda that are specific to OpenPOWER ELF V2 Power
    Architecture (64-bit) processors are described in this document.</para>
    <para>The following documents are complementary to this document and
    equally binding:</para>
    <itemizedlist>
      <listitem>
        <para>
        <emphasis>IBM Power
	Instruction Set Architecture,</emphasis> Versions
	2.07, 3.0, and 3.1, IBM, 2013-2020.
        <emphasis>
          <link xl:href="https://openpowerfoundation.org/technical/resource-catalog/">https://openpowerfoundation.org/technical/resource-catalog/
          </link>
        </emphasis></para>
      </listitem>
      <listitem>
	<para>
	  <emphasis>POWER Vector Intrinsics Programming
	  Reference</emphasis>, Version 1.0.0, OpenPOWER Foundation,
	  2020.
	  <emphasis>
            <link xl:href="https://openpowerfoundation.org/technical/resource-catalog/">https://openpowerfoundation.org/technical/resource-catalog/
            </link>
	  </emphasis>
	</para>
      </listitem>
      <listitem>
        <para>
        <emphasis>DWARF Debugging Information Format,</emphasis> Version 4,
        DWARF Debugging Information Format Workgroup, 2010. 
        <emphasis>
          <link xl:href="http://dwarfstd.org/Dwarf4Std.php">http://dwarfstd.org/Dwarf4Std.php</link>
        </emphasis></para>
      </listitem>
      <listitem>
        <para>
        <emphasis>ISO/IEC 9899:2011: Programming languages—C</emphasis>. 
        <emphasis>
          <link xl:href="http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=57853">http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=57853
          </link>
        </emphasis></para>
      </listitem>
      <listitem xml:id="dbdoclet.50655239_page12">
        <para>Itanium C++ ABI: Exception Handling. Rev 1.22, CodeSourcery,
        2001.
        <emphasis>
          <link xl:href="http://www.codesourcery.com/public/cxx-abi/abi-eh.html">http://www.codesourcery.com/public/cxx-abi/abi-eh.html
          </link>
        </emphasis></para>
      </listitem>
      <listitem>
        <para>
        <emphasis>ISO/IEC TR 24732:2009 &#8211; Programming languages, their
        environments and system software interfaces &#8211; Extension for the
        programming language C to support decimal floating-point
        arithmetic</emphasis>, ISO/IEC, January 05, 2009. Available from ISO. 
        <emphasis>
          <link xl:href="http://www.iso.org/iso/home/store/catalogue_tc/catalogue_tc_browse.htm?commid=45202">http://www.iso.org/iso/home/store/catalogue_tc/catalogue_tc_browse.htm?commid=45202
          </link>
        </emphasis></para>
      </listitem>
      <listitem>
        <para>
        <emphasis>ELF Handling for Thread-Local Storage</emphasis>, Version
        0.20, Ulrich Drepper, Red Hat Inc., December 21, 2005. 
        <emphasis>
          <link xl:href="http://people.redhat.com/drepper/tls.pdf">http://people.redhat.com/drepper/tls.pdf
          </link>
        </emphasis></para>
      </listitem>
      <listitem>
        <para>ELFv2 ABI Compliance TH/TS Specification 1.00, OpenPOWER
	Foundation, June 27, 2017.
          <emphasis>
            <link xl:href="http://cdn.openpowerfoundation.org/wp-content/uploads/resources/openpower-elfv2abi-thts/openpower-elfv2abi-thts-20170627.pdf">

              <citetitle>
	      http://cdn.openpowerfoundation.org/wp-content/uploads/resources/openpower-elfv2abi-thts/openpower-elfv2abi-thts-20170627.pdf</citetitle>
            </link>
          </emphasis>
        </para>
      </listitem>
    </itemizedlist>
    <para>The following documents are of interest for their historical
    information but are not normative in any way.</para>
    <itemizedlist>
      <listitem>
        <para>
          <emphasis>64-bit PowerPC ELF Application Binary Interface Supplement
          1.9.</emphasis>
          <emphasis>
            <link xl:href="http://refspecs.linuxfoundation.org/ELF/ppc64/PPC-elf64abi.html">http://refspecs.linuxfoundation.org/ELF/ppc64/PPC-elf64abi.html
            </link>
          </emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis>IBM PowerOpen™ ABI Application Binary Interface Big-Endian
          32-Bit Hardware Implementation.</emphasis>
          <emphasis>
            <link xl:href="ftp://www.sourceware.org/pub/binutils/ppc-docs/ppc-poweropen/">

              <citetitle>
              ftp://www.sourceware.org/pub/binutils/ppc-docs/ppc-poweropen/</citetitle>
            </link>
          </emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis>Power Architecture 32-bit ABI Supplement 1.0
          Embedded/Linux/Unified.</emphasis>
          <emphasis>
            <link xl:href="https://www.power.org/documentation/power-architecture-32-bit-abi-supplement-1-0-embeddedlinuxunified/">

              <citetitle>
              https://www.power.org/documentation/power-architecture-32-bit-abi-supplement-1-0-embeddedlinuxunified/</citetitle>
            </link>
          </emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
        <emphasis>ALTIVEC PIM: AltiVec™ Technology Programming Interface
        Manual</emphasis>, Freescale Semiconductor, 1999. 
        <emphasis>
          <link xl:href="http://www.freescale.com/files/32bit/doc/ref_manual/ALTIVECPIM.pdf">http://www.freescale.com/files/32bit/doc/ref_manual/ALTIVECPIM.pdf
          </link>
        </emphasis></para>
      </listitem>
      <listitem>
        <para>ELF Assembly User’s Guide, Fourth edition, IBM, 2000.
          <emphasis>
            <link xl:href="https://www-03.ibm.com/technologyconnect/tgcm/TGCMFileServlet.wss/assem_um.pdf?id=109917A251EFD64C872569D900656D07&amp;linkid=1h3000&amp;c_t=md515o6ntgh671shz9ioar20oyfp1grs">

              <citetitle>
              https://www-03.ibm.com/technologyconnect/tgcm/TGCMFileServlet.wss/assem_um.pdf?id=109917A251EFD64C872569D900656D07&amp;linkid=1h3000&amp;c_t=md515o6ntgh671shz9ioar20oyfp1grs</citetitle>
            </link>
          </emphasis>
        </para>
      </listitem>
    </itemizedlist>
  </section>
  <section>
    <title>Changes from Revision 1.4</title>
    <itemizedlist>
      <listitem>
	<para>
	  Errata recorded at <link xl:href="https://openpowerfoundation.org/?resource_lib=openpower-elfv2-errata-elfv2-abi-version-1-4">https://openpowerfoundation.org/?resource_lib=openpower-elfv2-errata-elfv2-abi-version-1-4</link>
	  have been incorporated into this document.
	</para>
      </listitem>
      <listitem>
	<para>
	  PowerISA version 3.1 introduces PC-relative instructions for
	  accessing code and data.  Thus compilers and assembly programmers
	  that target version 3.1 or later can, if desired, avoid usage of
	  a TOC pointer for such accesses.  The ABI has been updated to
	  describe the implications of this new capability.  For specifics,
	  see <xref linkend="dbdoclet.50655241_FnLinkage" />, <xref
	  linkend="dbdoclet.50655240___codealign" />, <xref
	  linkend="dbdoclet.50655240___RefHeading___Toc377640591" />, <xref
	  linkend="dbdoclet.50655241_18894" />, <xref
	  linkend="dbdoclet.50655241_LinkerOpts" />, <xref
	  linkend="dbdoclet.50655242_47739" />, and <xref
	  linkend="dbdoclet.50655242_82622" />.
	</para>
      </listitem>
      <listitem>
	<para>
	  Appendix A, "Predefined Functions for Vector Programming,"
	  and most of Chapter 6, "Vector Programming Interfaces," have
	  been removed from this document.  This material is now
	  incorporated into the <emphasis>POWER Vector Intrinsics
	  Programming Reference</emphasis>.  See <xref
	  linkend="dbdoclet.50655239___RefHeading___Toc377640569" />
	  for a link to this document.
	</para>
      </listitem>
    </itemizedlist>
  </section>
  <section>
    <title>Conformance to this Specification</title>
    <para>
      Compilers, assemblers, linkers, system libraries, and other
      toolchain components that implement this specification should
      fully implement all relevant aspects described in chapters 2
      through 6 of this specification, except for material that is
      specifically denoted as optional, as an optimization, or as
      an example.  Some aspects will only be relevant to a compiler,
      while others will only be relevant to a linker, and so forth.
    </para>
  </section>
</chapter>