forked from ryanarn/powerabi
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathchap6-elf32abi.sgml
304 lines (264 loc) · 16.6 KB
/
chap6-elf32abi.sgml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
<!-- Author(s): See <authorgroup> in book-elfabi.sgml -->
<!-- Copyright (c) 2011, Power.org -->
<!-- Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3; with
no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is available in the COPYING.txt file. -->
<chapter id="LIB">
<title>Libraries</title>
<sect1 id="Library-Requirements">
<title>Library Requirements</title>
<para>This ABI doesn't specify any additional interfaces for general-purpose libraries. However, certain processor specific support routines are defined in order to ensure portability between ABI conforming implementations.</para>
<para>Such processor specific support definitions concern floating-point alignment, register save/restore routines, variable argument list layout and a limited set of data definitions.</para>
<sect2 id="C-Library-Conformance-With-Generic-ABI">
<title>C Library Conformance with Generic ABI</title>
<!-- <para>The <varname>malloc()</varname> routine must always return a pointer with the alignment of the largest supported data type.:</para>
<itemizedlist>
<listitem CONDITION="ATR-LONG-DOUBLE-IBM"><para>At least 16-byte (quadword)
aligned, as the required pointer may be used for storing
IBM <trademark class="REGISTERED">AIX</trademark> 128-bit Long Double
data items that require 16-byte alignment.</para>
</listitem>
<listitem CONDITION="ATR-DFP"><para>At least 16-byte (quadword)
aligned, as the required pointer may be used for storing _Decimal128
data items that require 16-byte alignment.</para>
</listitem>
<listitem CONDITION="ATR-CLASSIC-FLOAT || ATR-SPE">
<para>At least 8-byte (doubleword) aligned, as the returned pointer
may be used for storing data items that require 8-byte alignment.</para>
</listitem>
</itemizedlist>
-->
<sect3 id="MALLOC-RETURN-ALIGNMENT">
<title>Malloc Routine Return Pointer Alignment</title>
<para>The <varname>malloc()</varname> routine must always return a pointer with the alignment of the largest supported data type from the following list:</para>
<itemizedlist>
<listitem CONDITION="ATR-LONG-DOUBLE-IBM"><para>At least 16-byte (quadword)
aligned, as the required pointer may be used for storing
IBM AIX 128-bit Long Double
data items that require 16-byte alignment.</para>
</listitem>
<listitem CONDITION="ATR-DFP"><para>At least 16-byte (quadword)
aligned, as the required pointer may be used for storing _Decimal128
data items that require 16-byte alignment.</para>
</listitem>
<listitem CONDITION="!ATR-LONG-DOUBLE-IBM && !ATR-DFP">
<para>At least 8-byte (doubleword) aligned, as the returned pointer
may be used for storing data items that require 8-byte alignment.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="LIMITED-ACCESS-BITS-LIBRARIES">
<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 <emphasis><xref linkend="LIMITED-ACCESS"></emphasis>.</para>
</sect3>
</sect2>
<sect2 id="SAVE-AND-RESTORE-ROUTINES">
<title>Save and Restore Routines</title>
<para>All of the save and restore routines described in
<emphasis><xref linkend="SAVE-RES"></emphasis> are required. These routines
use unusual calling conventions due to their special
purpose.</para>
<sect3 id="SUFFIXES"><title>Save and Restore Routine Suffixes</title>
<para>The following suffix extensions describe the
function templates in <emphasis><xref linkend="SaRRT"></emphasis>.</para>
<variablelist>
<varlistentry><term><emphasis><emphasis role="bold">_m</emphasis></emphasis> (<emphasis>save and restore function variable</emphasis>)</term>
<listitem>
<para>The variable <emphasis>_m</emphasis> represents the first register to be
saved. That is, to save
registers 18 to 31 using 32-bit
saves, one would call
save32gpr_18.</para>
</listitem>
</varlistentry>
<varlistentry CONDITION="ATR-BSS-PLT"><term><emphasis role="bold">_g</emphasis> (<emphasis>save function qualifier</emphasis>)</term>
<listitem>
<para><emphasis role="bold">GOT save functions</emphasis> are represented by the _g qualifier. These functions return to the caller of the save function by branching to the blrl instruction held at _GLOBAL_OFFSET_TABLE_-4.</para>
</listitem>
</varlistentry>
<varlistentry CONDITION="ATR-SECURE-PLT"><term><emphasis role="bold">_g</emphasis> (<emphasis>save function qualifier</emphasis>)</term>
<listitem>
<para><emphasis role="bold">GOT save functions</emphasis> use the _g qualifier. These functions are illegal to use with the <emphasis>Secure-PLT</emphasis> ABI since the Secure-PLT is not executable.</para>
</listitem>
</varlistentry>
<varlistentry><term><emphasis role="bold">_x</emphasis> (<emphasis>restore function qualifier</emphasis>)</term>
<listitem>
<para><emphasis role="bold">Exit restore functions</emphasis> are represented by the _x qualifier. These functions restore the specified registers and use the link-register value in the calling function's LR-save area to return to the caller's parent function after removing the caller's stack frame.</para>
</listitem>
</varlistentry>
<varlistentry><term><emphasis role="bold">_t</emphasis> (<emphasis>restore function qualifier</emphasis>)</term>
<listitem>
<para><emphasis role="bold">Tail restore functions</emphasis> are represented by the _t qualifier. Given the following function call sequence where <emphasis>function3</emphasis> is a tail-call:</para>
<para>
<screen>
function1()
{
function2();
<further calls and code>
return;
}
function2()
{
_rest*_t();
return function3();
}
</screen></para>
<para>The <emphasis role="bold">tail restore functions</emphasis> are called from <emphasis>function2</emphasis> and prepare the register state in <emphasis>function2</emphasis> for a tail-call to <emphasis>function3</emphasis> that is to return directly to <emphasis>function1</emphasis>. They restore the specified registers for <emphasis>function1</emphasis> from <emphasis>function1's</emphasis> stack frame and save the address of <emphasis>function1</emphasis> from the LRSAVE word of <emphasis>function1</emphasis>'s stack frame into R0 before returning control to <emphasis>function2</emphasis>. <emphasis>Function2</emphasis> then sets the LR to the address of <emphasis>function1</emphasis> held in R0 and calls the tail function <emphasis>function3</emphasis>. <emphasis>Function3</emphasis> will perform it's duty and then return directly to <emphasis>function1</emphasis> rather than <emphasis>function2</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry CONDITION="ATR-EABI || ATR_SPE"><term><emphasis role="bold">_ctr</emphasis> (<emphasis>save & restore function qualifier</emphasis>)</term>
<listitem>
<para><emphasis role="bold">CTR register save and restore functions</emphasis> are represented by the <emphasis>_ctr</emphasis> qualifier. These functions set the number of registers to be “saved to” or “restored from” into the CTR register.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="SaRRT"><title>Save and Restore Routine Templates</title>
<itemizedlist>
<listitem><para>_savegpr_m</para></listitem>
<listitem CONDITION="!ATR-SECURE-PLT"><para>_savegpr_m_g</para></listitem>
<listitem CONDITION="ATR-CLASSIC-FLOAT"><para>_savefpr_m</para></listitem>
<listitem CONDITION="ATR-CLASSIC-FLOAT && !ATR-SECURE-PLT"><para>_savefpr_m_g</para></listitem>
<listitem CONDITION="ATR-VECTOR"><para>_savevr_m</para></listitem>
<listitem CONDITION="ATR-CLASSIC-FLOAT"><para>_restfpr_m</para></listitem>
<listitem CONDITION="ATR-CLASSIC-FLOAT"><para>_restfpr_m_x</para></listitem>
<listitem CONDITION="ATR-CLASSIC-FLOAT"><para>_restfpr_m_t</para></listitem>
<listitem CONDITION="ATR-VECTOR"><para>_restvr_m</para></listitem>
<listitem><para>_restgpr_m</para></listitem>
<listitem><para>_restgpr_m_x</para></listitem>
<listitem><para>_restgpr_m_t</para></listitem>
<listitem CONDITION="ATR-SPE"><para>_save32gpr_m</para></listitem>
<listitem CONDITION="ATR-SPE"><para>_save64gpr_m</para></listitem>
<listitem CONDITION="ATR-SPE && ATR-EABI"><para>_save64gpr_ctr_m</para></listitem>
<listitem CONDITION="ATR-SPE && !ATR-SECURE-PLT"><para>_save32gpr_m_g</para></listitem>
<listitem CONDITION="ATR-SPE && !ATR-SECURE-PLT"><para>_save64gpr_m_g</para></listitem>
<listitem CONDITION="ATR-SPE && !ATR-SECURE-PLT && ATR-EABI"><para>_save64gpr_ctr_m_g</para></listitem>
<listitem CONDITION="ATR-SPE"><para>_rest32gpr_m</para></listitem>
<listitem CONDITION="ATR-SPE"><para>_rest64gpr_m</para></listitem>
<listitem CONDITION="ATR-SPE && ATR-EABI"><para>_rest64gpr_ctr_m</para></listitem>
<listitem CONDITION="ATR-SPE"><para>_rest32gpr_m_x</para></listitem>
<listitem CONDITION="ATR-SPE"><para>_rest64gpr_m_x</para></listitem>
<listitem CONDITION="ATR-SPE"><para>_rest32gpr_m_t</para></listitem>
<listitem CONDITION="ATR-SPE"><para>_rest64gpr_m_t</para></listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2 id="STANDARD-TYPES">
<title>Types Defined In Standard Header</title>
<para>The type va_list shall be defined as follows:</para>
<programlisting>
typedef struct __va_list_tag {
unsigned char gpr;
unsigned char fpr;
/* Two bytes padding. */
char *overflow_arg_area;
char *reg_save_area;
} va_list[1];</programlisting>
<para>The names and types of the elements are not part
of the ABI, but the <varname>__va_list_tag</varname> name is part of the
ABI (since it affects C++ name mangling), and the
structure must have the size, alignment and layout
implied by this definition.</para>
<itemizedlist>
<listitem>
<para>The <emphasis role="bold">gpr</emphasis> element holds the index of the
next general-purpose register saved in this area from which an argument would be
retrieved with <varname>va_arg()</varname>, where <emphasis>gpr</emphasis> == N corresponds to
r<emphasis>N</emphasis> + 3. (If the argument is passed as DUAL_GP and <emphasis>gpr</emphasis>
is odd, the next argument would be retrieved from r<emphasis>N</emphasis> +
4 and r<emphasis>N</emphasis> & plus; 5 instead.) If <emphasis>gpr</emphasis> is greater than 7, no
more arguments will be retrieved from general-purpose registers by
<varname>va_arg()</varname>.</para>
</listitem>
<listitem CONDITION="ATR-CLASSIC-FLOAT">
<para>The <emphasis role="bold">fpr</emphasis> element holds the index of the
next floating-point register saved in this area from which an argument would be
retrieved with <varname>va_arg()</varname>.
<itemizedlist>
<listitem><para>Fpr == <emphasis>N</emphasis> corresponds to
f<emphasis>N</emphasis> + 1. If fpr is greater than 7, no more arguments
will be retrieved from floating-point registers by
<varname>va_arg()</varname>. </para></listitem>
<listitem CONDITION="ATR-DFP"><para>If the argument being passed is
_Decimal128 and fpr == <emphasis>N</emphasis> where
<emphasis>N</emphasis> is even then f<emphasis>N</emphasis> + 2 and
f<emphasis>N</emphasis> + 3 are referred to instead. If fpr is
greater than 6, no more arguments will be retrieved from floating-point
registers by <varname>va_arg()</varname>.</para></listitem>
</itemizedlist>
</para></listitem>
<listitem>
<para><emphasis role="bold">reg_save_area</emphasis> points to an 8-byte-aligned
area where registers r3 to r10 are saved, in that order.</para>
<para>Addresses in the area pointed to by <emphasis
role="bold">reg_save_area</emphasis> that correspond to registers used for
passing named arguments, or to unused registers between those used for passing
named arguments, need not correspond to allocated memory; those registers need
not be saved in this area. va_arg shall only access those words required to
load the argument of the type passed.</para>
<para CONDITION="ATR-SPE">Only the low 32 bits of each register are saved in
this area.</para>
<para CONDITION="ATR-CLASSIC-FLOAT">Registers f1 to f8 immediately follow
registers r3 to r10, if CR bit 6 was set when the variable-argument function was
called.</para> </listitem>
<listitem>
<para>The <emphasis role="bold">overflow_arg_area</emphasis> element points to
the word on the stack at the start of the next argument passed on the stack, or
to a prior word that forms part of the padding required for the next argument to
have the required alignment. va_arg shall only access those words required to
load the argument of the type passed; if no arguments were passed on the stack,
this area may not be allocated.</para>
</listitem>
</itemizedlist>
<para>The following integer types are defined in headers required to be provided by freestanding
implementations, or have their limits defined in such headers, and shall have the following
definitions.</para>
<note CONDITION="ATR-EABI"><title>Note</title><para>Note: Freestanding implementations need not
provide the types sig_atomic_t and wint_t.</para></note>
<itemizedlist>
<listitem><para>typedef int ptrdiff_t;</para></listitem>
<listitem><para>typedef unsigned int size_t;</para></listitem>
<listitem><para>typedef long 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 CONDITION="ATR-LINUX"><para>typedef int int32_t;</para></listitem>
<listitem CONDITION="ATR-EABI"><para>typedef long int32_t;</para></listitem>
<listitem><para>typedef long long int64_t;</para></listitem>
<listitem><para>typedef unsigned char uint8_t;</para></listitem>
<listitem><para>typedef unsigned short uint16_t;</para></listitem>
<listitem CONDITION="ATR-LINUX"><para>typedef unsigned int uint32_t;</para></listitem>
<listitem CONDITION="ATR-EABI"><para>typedef unsigned long uint32_t;</para></listitem>
<listitem><para>typedef unsigned long 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 CONDITION="ATR-LINUX"><para>typedef int int_least32_t;</para></listitem>
<listitem CONDITION="ATR-EABI"><para>typedef long int_least32_t;</para></listitem>
<listitem><para>typedef long 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 CONDITION="ATR-LINUX"><para>typedef unsigned int uint_least32_t;</para></listitem>
<listitem CONDITION="ATR-EABI"><para>typedef unsigned long uint_least32_t;</para></listitem>
<listitem><para>typedef unsigned long long uint_least64_t;</para></listitem>
<listitem CONDITION="ATR-LINUX"><para>typedef signed char int_fast8_t;</para></listitem>
<listitem CONDITION="ATR-EABI"><para>typedef int 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 long int_fast64_t;</para></listitem>
<listitem CONDITION="ATR-LINUX"><para>typedef unsigned char uint_fast8_t;</para></listitem>
<listitem CONDITION="ATR-EABI"><para>typedef unsigned int 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 long uint_fast64_t;</para></listitem>
<listitem><para>typedef int intptr_t;</para></listitem>
<listitem><para>typedef unsigned int uintptr_t;</para></listitem>
<listitem><para>typedef long long intmax_t;</para></listitem>
<listitem><para>typedef unsigned long long uintmax_t;</para></listitem>
</itemizedlist>
</sect2>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file Local Variables: mode: sgml sgml-parent-document: ("PPC-elf32abi.sgml" "book" "chapter") End: -->