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.
365 lines
14 KiB
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>
|