You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
ELFv2-ABI/specification/ch_5.xml

365 lines
14 KiB
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:xl="http://www.w3.org/1999/xlink" version="5.0"
xml:lang="en"
xml:id="dbdoclet.50655243_pgfId-1099317">
<title>Libraries</title>
<section xml:id="dbdoclet.50655243___RefHeading___Toc377640665">
<title>Library Requirements</title>
<para>This ABI does not specify any additional interfaces for
general-purpose libraries. However, certain processor-specific support
routines are defined to ensure portability between ABI-conforming
implementations.</para>
<para>Such processor-specific support definitions concern vector and
floating-point alignment, register save and restore routines, variable
argument list layout, and a limited set of data definitions.</para>
<section xml:id="dbdoclet.50655243___RefHeading___Toc377640666">
<title>C Library Conformance with Generic ABI</title>
<para />
<section xml:id="dbdoclet.50655243___RefHeading___Toc377640667">
<title>Malloc Routine Return Pointer Alignment</title>
<para>The malloc( ) routine must always return a pointer with the
alignment of the largest alignment needed for loads and stores of the
built-in data types. This is currently 16 bytes.</para>
</section>
<section xml:id="dbdoclet.50655243___RefHeading___Toc377640668">
<title>Library Handling of Limited-Access Bits in Registers</title>
<para>Requirements for the handling of limited-access bits in certain
registers by standard library functions are defined in
<xref linkend="dbdoclet.50655240___RefHeading___Toc377640581" />.</para>
</section>
</section>
<section xml:id="dbdoclet.50655243_49403">
<title>Save and Restore Routines</title>
<para>All of the save and restore routines described in
<xref linkend="dbdoclet.50655240_24141" /> are required. These routines
use unusual calling conventions due to their special purpose. Parameters
for these functions are described in
<xref linkend="dbdoclet.50655240_41483" />,
<xref linkend="dbdoclet.50655240_56788" />, and
<xref linkend="dbdoclet.50655240_96790" />.</para>
<para>The symbols for these functions shall be hidden and locally
resolved within each module. The symbols so created shall not be
exported.</para>
<para>These functions can either be provided in a utility library that is
linked by the linker to each module, or the functions can be synthesized
by the linker as necessary to resolve symbols.</para>
</section>
<section xml:id="dbdoclet.50655243_page131">
<title xml:id="dbdoclet.50655243___RefHeading___Toc377640670">Types Defined in the Standard Header</title>
<para>The type va_list shall be defined as follows:</para>
<para><literal>typedef void * va_list;</literal></para>
<para>The following integer types are defined in headers, which must be
provided by freestanding implementations, or have their limits defined in
such headers. They shall have the following definitions:</para>
<itemizedlist spacing="compact">
<listitem>
<para>typedef long ptrdiff_t;</para>
</listitem>
<listitem>
<para>typedef unsigned <phrase>long</phrase> size_t;</para>
</listitem>
<listitem>
<para>typedef <phrase>int</phrase> wchar_t;</para>
</listitem>
<listitem>
<para>typedef int sig_atomic_t;</para>
</listitem>
<listitem>
<para>typedef unsigned int wint_t;</para>
</listitem>
<listitem>
<para>typedef signed char int8_t;</para>
</listitem>
<listitem>
<para>typedef short int16_t;</para>
</listitem>
<listitem>
<para>typedef int int32_t;</para>
</listitem>
<listitem>
<para>typedef long int64_t;</para>
</listitem>
<listitem>
<para>typedef unsigned char uint8_t;</para>
</listitem>
<listitem>
<para>typedef unsigned short uint16_t;</para>
</listitem>
<listitem>
<para>typedef unsigned int uint32_t;</para>
</listitem>
<listitem>
<para>typedef unsigned long uint64_t;</para>
</listitem>
<listitem>
<para>typedef signed char int_least8_t;</para>
</listitem>
<listitem>
<para>typedef short int_least16_t;</para>
</listitem>
<listitem xml:id="dbdoclet.50655243_page136">
<para>typedef int int_least32_t;</para>
</listitem>
<listitem>
<para>typedef long int_least64_t;</para>
</listitem>
<listitem>
<para>typedef unsigned char uint_least8_t;</para>
</listitem>
<listitem>
<para>typedef unsigned short uint_least16_t;</para>
</listitem>
<listitem>
<para>typedef unsigned int uint_least32_t;</para>
</listitem>
<listitem>
<para>typedef unsigned long uint_least64_t;</para>
</listitem>
<listitem>
<para>typedef signed char int_fast8_t;</para>
</listitem>
<listitem>
<para>typedef int int_fast16_t;</para>
</listitem>
<listitem>
<para>typedef int int_fast32_t;</para>
</listitem>
<listitem>
<para>typedef long int_fast64_t;</para>
</listitem>
<listitem>
<para>typedef unsigned char uint_fast8_t;</para>
</listitem>
<listitem>
<para>typedef unsigned int uint_fast16_t;</para>
</listitem>
<listitem>
<para>typedef unsigned int uint_fast32_t;</para>
</listitem>
<listitem>
<para>typedef unsigned long uint_fast64_t;</para>
</listitem>
<listitem>
<para>typedef long intptr_t;</para>
</listitem>
<listitem>
<para>typedef unsigned long uintptr_t;</para>
</listitem>
<listitem>
<para>typedef long intmax_t;</para>
</listitem>
<listitem>
<para>typedef unsigned long uintmax_t;</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dbdoclet.50655243_75216">
<title>Predefined Macros</title>
<para>A C preprocessor that conforms to this ABI shall predefine the
macro _CALL_ELF to have a value of 2.</para>
<para>The macros listed in
<xref linkend="dbdoclet.50655243_37910" /> are based on environment
characteristics. They shall be predefined to a value of 1 by conforming C
preprocessors when the corresponding condition applies.</para>
<para> </para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50655243_37910">
<title>Predefined Target Architecture Macros</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" align="center"/>
<colspec colname="c2" colwidth="80*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Macro</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Condition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>__PPC__</para>
<para>__powerpc__</para>
</entry>
<entry>
<para>The target is a Power Architecture processor.</para>
</entry>
</row>
<row>
<entry>
<para>__PPC64__</para>
<para>__powerpc64__</para>
<para>__64BIT__<footnote xml:id="pgfId-1101811">
<para>Phased in.</para>
</footnote></para>
</entry>
<entry>
<para>The target is a Power Architecture processor running in
64-bit mode.</para>
</entry>
</row>
<row>
<entry>
<para>__BIG_ENDIAN__</para>
</entry>
<entry>
<para>The target processor is big endian.</para>
</entry>
</row>
<row>
<entry>
<para>__LITTLE_ENDIAN__</para>
</entry>
<entry>
<para>The target processor is little endian.</para>
</entry>
</row>
<row>
<entry>
<para>_ARCH_PWRn</para>
</entry>
<entry>
<para>Indicates that the target processor supports the Power
ISA level for POWERn or higher. For example, _ARCH_PWR8 supports
the Power ISA for a POWER8 processor.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para> </para>
<para> </para>
<para>The macros in listed
<xref linkend="dbdoclet.50655243_98814" /> are based on the order of the
data elements. They shall be predefined to one of the allowable values by
conforming C preprocessors when the corresponding condition
applies.</para>
<para> </para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50655243_98814">
<title>Predefined Target Data Order Macros</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="30*" align="center"/>
<colspec colname="c2" colwidth="25*" align="center"/>
<colspec colname="c3" colwidth="45*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Macro</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Condition</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="1">
<para>__BYTE_ORDER__</para>
</entry>
<entry>
<para>__ORDER_BIG_ENDIAN__</para>
</entry>
<entry>
<para>The target processor is big endian.</para>
</entry>
</row>
<row>
<entry>
<para>__ORDER_LITTLE_ENDIAN__</para>
</entry>
<entry>
<para>The target processor is little endian.</para>
</entry>
</row>
<row>
<entry morerows="1">
<para>__FLOAT_WORD_ORDER__</para>
</entry>
<entry>
<para>__ORDER_BIG_ENDIAN__</para>
</entry>
<entry>
<para>The target processor is big endian.</para>
</entry>
</row>
<row>
<entry>
<para>__ORDER_LITTLE_ENDIAN__</para>
</entry>
<entry>
<para>The target processor is little endian.</para>
</entry>
</row>
<row>
<entry morerows="1">
<para>__VEC_ELEMENT_REG_ORDER__</para>
<para>For more information, see
<xref linkend="dbdoclet.50655244_25365" />.</para>
</entry>
<entry>
<para>__ORDER_BIG_ENDIAN__</para>
</entry>
<entry>
<para>The target processor is big endian, or big-endian vector
element order has been requested.</para>
</entry>
</row>
<row>
<entry>
<para>__ORDER_LITTLE_ENDIAN__</para>
</entry>
<entry>
<para>The target processor is little endian, and big-endian
vector element order has not been requested.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para> </para>
<para> </para>
</section>
</section>
<section>
<title>POWER ISA-Specific API and ABI Extensions</title>
<para>The Data Stream Control Register (DSCR) affects how the processor
handles data streams that are detected by the hardware and defined by the
software. For more information, see “Data Stream Control Overview, ABI, and
API” at the following link:</para>
<para><link xl:href="https://github.com/paflib/paflib/wiki/Data-Stream-Control-Overview,-ABI,-and-API">https://github.com/paflib/paflib/wiki/Data-Stream-Control-Overview,-ABI,-and-API</link>
</para>
<para>The event-based branching facility generates exceptions when certain
criteria are met. For more information, see the “Event Based Branching
Overview, ABI, and API” section at the following link:</para>
<para><link xl:href="https://github.com/paflib/paflib/wiki/Event-Based-Branching----Overview,-ABI,-and-API">https://github.com/paflib/paflib/wiki/Event-Based-Branching----Overview,-ABI,-and-API</link>
</para>
</section>
</chapter>