1Compiler-RT
2================================
3
4This directory and its subdirectories contain source code for the compiler
5support routines.
6
7Compiler-RT is open source software. You may freely distribute it under the
8terms of the license agreement found in LICENSE.txt.
9
10================================
11
12This is a replacement library for libgcc.  Each function is contained
13in its own file.  Each function has a corresponding unit test under
14test/Unit.
15
16A rudimentary script to test each file is in the file called
17test/Unit/test.
18
19Here is the specification for this library:
20
21http://gcc.gnu.org/onlinedocs/gccint/Libgcc.html#Libgcc
22
23Please note that the libgcc specification explicitly mentions actual types of
24arguments and returned values being expressed with machine modes.
25In some cases particular types such as "int", "unsigned", "long long", etc.
26may be specified just as examples there.
27
28Here is a synopsis of the contents of this library:
29
30typedef  int32_t si_int;
31typedef uint32_t su_int;
32
33typedef  int64_t di_int;
34typedef uint64_t du_int;
35
36// Integral bit manipulation
37
38di_int __ashldi3(di_int a, si_int b);      // a << b
39ti_int __ashlti3(ti_int a, si_int b);      // a << b
40
41di_int __ashrdi3(di_int a, si_int b);      // a >> b  arithmetic (sign fill)
42ti_int __ashrti3(ti_int a, si_int b);      // a >> b  arithmetic (sign fill)
43di_int __lshrdi3(di_int a, si_int b);      // a >> b  logical    (zero fill)
44ti_int __lshrti3(ti_int a, si_int b);      // a >> b  logical    (zero fill)
45
46int __clzsi2(si_int a);  // count leading zeros
47int __clzdi2(di_int a);  // count leading zeros
48int __clzti2(ti_int a);  // count leading zeros
49int __ctzsi2(si_int a);  // count trailing zeros
50int __ctzdi2(di_int a);  // count trailing zeros
51int __ctzti2(ti_int a);  // count trailing zeros
52
53int __ffssi2(si_int a);  // find least significant 1 bit
54int __ffsdi2(di_int a);  // find least significant 1 bit
55int __ffsti2(ti_int a);  // find least significant 1 bit
56
57int __paritysi2(si_int a);  // bit parity
58int __paritydi2(di_int a);  // bit parity
59int __parityti2(ti_int a);  // bit parity
60
61int __popcountsi2(si_int a);  // bit population
62int __popcountdi2(di_int a);  // bit population
63int __popcountti2(ti_int a);  // bit population
64
65uint32_t __bswapsi2(uint32_t a);   // a byteswapped
66uint64_t __bswapdi2(uint64_t a);   // a byteswapped
67
68// Integral arithmetic
69
70di_int __negdi2    (di_int a);                         // -a
71ti_int __negti2    (ti_int a);                         // -a
72di_int __muldi3    (di_int a, di_int b);               // a * b
73ti_int __multi3    (ti_int a, ti_int b);               // a * b
74si_int __divsi3    (si_int a, si_int b);               // a / b   signed
75di_int __divdi3    (di_int a, di_int b);               // a / b   signed
76ti_int __divti3    (ti_int a, ti_int b);               // a / b   signed
77su_int __udivsi3   (su_int n, su_int d);               // a / b   unsigned
78du_int __udivdi3   (du_int a, du_int b);               // a / b   unsigned
79tu_int __udivti3   (tu_int a, tu_int b);               // a / b   unsigned
80si_int __modsi3    (si_int a, si_int b);               // a % b   signed
81di_int __moddi3    (di_int a, di_int b);               // a % b   signed
82ti_int __modti3    (ti_int a, ti_int b);               // a % b   signed
83su_int __umodsi3   (su_int a, su_int b);               // a % b   unsigned
84du_int __umoddi3   (du_int a, du_int b);               // a % b   unsigned
85tu_int __umodti3   (tu_int a, tu_int b);               // a % b   unsigned
86du_int __udivmoddi4(du_int a, du_int b, du_int* rem);  // a / b, *rem = a % b  unsigned
87tu_int __udivmodti4(tu_int a, tu_int b, tu_int* rem);  // a / b, *rem = a % b  unsigned
88su_int __udivmodsi4(su_int a, su_int b, su_int* rem);  // a / b, *rem = a % b  unsigned
89si_int __divmodsi4(si_int a, si_int b, si_int* rem);   // a / b, *rem = a % b  signed
90di_int __divmoddi4(di_int a, di_int b, di_int* rem);   // a / b, *rem = a % b  signed
91ti_int __divmodti4(ti_int a, ti_int b, ti_int* rem);   // a / b, *rem = a % b  signed
92
93
94
95//  Integral arithmetic with trapping overflow
96
97si_int __absvsi2(si_int a);           // abs(a)
98di_int __absvdi2(di_int a);           // abs(a)
99ti_int __absvti2(ti_int a);           // abs(a)
100
101si_int __negvsi2(si_int a);           // -a
102di_int __negvdi2(di_int a);           // -a
103ti_int __negvti2(ti_int a);           // -a
104
105si_int __addvsi3(si_int a, si_int b);  // a + b
106di_int __addvdi3(di_int a, di_int b);  // a + b
107ti_int __addvti3(ti_int a, ti_int b);  // a + b
108
109si_int __subvsi3(si_int a, si_int b);  // a - b
110di_int __subvdi3(di_int a, di_int b);  // a - b
111ti_int __subvti3(ti_int a, ti_int b);  // a - b
112
113si_int __mulvsi3(si_int a, si_int b);  // a * b
114di_int __mulvdi3(di_int a, di_int b);  // a * b
115ti_int __mulvti3(ti_int a, ti_int b);  // a * b
116
117
118// Integral arithmetic which returns if overflow
119
120si_int __mulosi4(si_int a, si_int b, int* overflow);  // a * b, overflow set to one if result not in signed range
121di_int __mulodi4(di_int a, di_int b, int* overflow);  // a * b, overflow set to one if result not in signed range
122ti_int __muloti4(ti_int a, ti_int b, int* overflow);  // a * b, overflow set to
123 one if result not in signed range
124
125
126//  Integral comparison: a  < b -> 0
127//                       a == b -> 1
128//                       a  > b -> 2
129
130si_int __cmpdi2 (di_int a, di_int b);
131si_int __cmpti2 (ti_int a, ti_int b);
132si_int __ucmpdi2(du_int a, du_int b);
133si_int __ucmpti2(tu_int a, tu_int b);
134
135//  Integral / floating point conversion
136
137di_int __fixsfdi(      float a);
138di_int __fixdfdi(     double a);
139di_int __fixxfdi(long double a);
140
141ti_int __fixsfti(      float a);
142ti_int __fixdfti(     double a);
143ti_int __fixxfti(long double a);
144uint64_t __fixtfdi(long double input);  // ppc only, doesn't match documentation
145
146su_int __fixunssfsi(      float a);
147su_int __fixunsdfsi(     double a);
148su_int __fixunsxfsi(long double a);
149
150du_int __fixunssfdi(      float a);
151du_int __fixunsdfdi(     double a);
152du_int __fixunsxfdi(long double a);
153
154tu_int __fixunssfti(      float a);
155tu_int __fixunsdfti(     double a);
156tu_int __fixunsxfti(long double a);
157uint64_t __fixunstfdi(long double input);  // ppc only
158
159float       __floatdisf(di_int a);
160double      __floatdidf(di_int a);
161long double __floatdixf(di_int a);
162long double __floatditf(int64_t a);        // ppc only
163
164float       __floattisf(ti_int a);
165double      __floattidf(ti_int a);
166long double __floattixf(ti_int a);
167
168float       __floatundisf(du_int a);
169double      __floatundidf(du_int a);
170long double __floatundixf(du_int a);
171long double __floatunditf(uint64_t a);     // ppc only
172
173float       __floatuntisf(tu_int a);
174double      __floatuntidf(tu_int a);
175long double __floatuntixf(tu_int a);
176
177//  Floating point raised to integer power
178
179float       __powisf2(      float a, int b);  // a ^ b
180double      __powidf2(     double a, int b);  // a ^ b
181long double __powixf2(long double a, int b);  // a ^ b
182long double __powitf2(long double a, int b);  // ppc only, a ^ b
183
184//  Complex arithmetic
185
186//  (a + ib) * (c + id)
187
188      float _Complex __mulsc3( float a,  float b,  float c,  float d);
189     double _Complex __muldc3(double a, double b, double c, double d);
190long double _Complex __mulxc3(long double a, long double b,
191                              long double c, long double d);
192long double _Complex __multc3(long double a, long double b,
193                              long double c, long double d); // ppc only
194
195//  (a + ib) / (c + id)
196
197      float _Complex __divsc3( float a,  float b,  float c,  float d);
198     double _Complex __divdc3(double a, double b, double c, double d);
199long double _Complex __divxc3(long double a, long double b,
200                              long double c, long double d);
201long double _Complex __divtc3(long double a, long double b,
202                              long double c, long double d);  // ppc only
203
204
205//         Runtime support
206
207// __clear_cache() is used to tell process that new instructions have been
208// written to an address range.  Necessary on processors that do not have
209// a unified instruction and data cache.
210void __clear_cache(void* start, void* end);
211
212// __enable_execute_stack() is used with nested functions when a trampoline
213// function is written onto the stack and that page range needs to be made
214// executable.
215void __enable_execute_stack(void* addr);
216
217// __gcc_personality_v0() is normally only called by the system unwinder.
218// C code (as opposed to C++) normally does not need a personality function
219// because there are no catch clauses or destructors to be run.  But there
220// is a C language extension __attribute__((cleanup(func))) which marks local
221// variables as needing the cleanup function "func" to be run when the
222// variable goes out of scope.  That includes when an exception is thrown,
223// so a personality handler is needed.
224_Unwind_Reason_Code __gcc_personality_v0(int version, _Unwind_Action actions,
225         uint64_t exceptionClass, struct _Unwind_Exception* exceptionObject,
226         _Unwind_Context_t context);
227
228// for use with some implementations of assert() in <assert.h>
229void __eprintf(const char* format, const char* assertion_expression,
230				const char* line, const char* file);
231
232// for systems with emulated thread local storage
233void* __emutls_get_address(struct __emutls_control*);
234
235
236//   Power PC specific functions
237
238// There is no C interface to the saveFP/restFP functions.  They are helper
239// functions called by the prolog and epilog of functions that need to save
240// a number of non-volatile float point registers.
241saveFP
242restFP
243
244// PowerPC has a standard template for trampoline functions.  This function
245// generates a custom trampoline function with the specific realFunc
246// and localsPtr values.
247void __trampoline_setup(uint32_t* trampOnStack, int trampSizeAllocated,
248                                const void* realFunc, void* localsPtr);
249
250// adds two 128-bit double-double precision values ( x + y )
251long double __gcc_qadd(long double x, long double y);
252
253// subtracts two 128-bit double-double precision values ( x - y )
254long double __gcc_qsub(long double x, long double y);
255
256// multiples two 128-bit double-double precision values ( x * y )
257long double __gcc_qmul(long double x, long double y);
258
259// divides two 128-bit double-double precision values ( x / y )
260long double __gcc_qdiv(long double a, long double b);
261
262
263//    ARM specific functions
264
265// There is no C interface to the switch* functions.  These helper functions
266// are only needed by Thumb1 code for efficient switch table generation.
267switch16
268switch32
269switch8
270switchu8
271
272// There is no C interface to the *_vfp_d8_d15_regs functions.  There are
273// called in the prolog and epilog of Thumb1 functions.  When the C++ ABI use
274// SJLJ for exceptions, each function with a catch clause or destuctors needs
275// to save and restore all registers in it prolog and epliog.  But there is
276// no way to access vector and high float registers from thumb1 code, so the
277// compiler must add call outs to these helper functions in the prolog and
278// epilog.
279restore_vfp_d8_d15_regs
280save_vfp_d8_d15_regs
281
282
283// Note: long ago ARM processors did not have floating point hardware support.
284// Floating point was done in software and floating point parameters were
285// passed in integer registers.  When hardware support was added for floating
286// point, new *vfp functions were added to do the same operations but with
287// floating point parameters in floating point registers.
288
289// Undocumented functions
290
291float  __addsf3vfp(float a, float b);   // Appears to return a + b
292double __adddf3vfp(double a, double b); // Appears to return a + b
293float  __divsf3vfp(float a, float b);   // Appears to return a / b
294double __divdf3vfp(double a, double b); // Appears to return a / b
295int    __eqsf2vfp(float a, float b);    // Appears to return  one
296                                        //     iff a == b and neither is NaN.
297int    __eqdf2vfp(double a, double b);  // Appears to return  one
298                                        //     iff a == b and neither is NaN.
299double __extendsfdf2vfp(float a);       // Appears to convert from
300                                        //     float to double.
301int    __fixdfsivfp(double a);          // Appears to convert from
302                                        //     double to int.
303int    __fixsfsivfp(float a);           // Appears to convert from
304                                        //     float to int.
305unsigned int __fixunssfsivfp(float a);  // Appears to convert from
306                                        //     float to unsigned int.
307unsigned int __fixunsdfsivfp(double a); // Appears to convert from
308                                        //     double to unsigned int.
309double __floatsidfvfp(int a);           // Appears to convert from
310                                        //     int to double.
311float __floatsisfvfp(int a);            // Appears to convert from
312                                        //     int to float.
313double __floatunssidfvfp(unsigned int a); // Appears to convert from
314                                        //     unisgned int to double.
315float __floatunssisfvfp(unsigned int a); // Appears to convert from
316                                        //     unisgned int to float.
317int __gedf2vfp(double a, double b);     // Appears to return __gedf2
318                                        //     (a >= b)
319int __gesf2vfp(float a, float b);       // Appears to return __gesf2
320                                        //     (a >= b)
321int __gtdf2vfp(double a, double b);     // Appears to return __gtdf2
322                                        //     (a > b)
323int __gtsf2vfp(float a, float b);       // Appears to return __gtsf2
324                                        //     (a > b)
325int __ledf2vfp(double a, double b);     // Appears to return __ledf2
326                                        //     (a <= b)
327int __lesf2vfp(float a, float b);       // Appears to return __lesf2
328                                        //     (a <= b)
329int __ltdf2vfp(double a, double b);     // Appears to return __ltdf2
330                                        //     (a < b)
331int __ltsf2vfp(float a, float b);       // Appears to return __ltsf2
332                                        //     (a < b)
333double __muldf3vfp(double a, double b); // Appears to return a * b
334float __mulsf3vfp(float a, float b);    // Appears to return a * b
335int __nedf2vfp(double a, double b);     // Appears to return __nedf2
336                                        //     (a != b)
337double __negdf2vfp(double a);           // Appears to return -a
338float __negsf2vfp(float a);             // Appears to return -a
339float __negsf2vfp(float a);             // Appears to return -a
340double __subdf3vfp(double a, double b); // Appears to return a - b
341float __subsf3vfp(float a, float b);    // Appears to return a - b
342float __truncdfsf2vfp(double a);        // Appears to convert from
343                                        //     double to float.
344int __unorddf2vfp(double a, double b);  // Appears to return __unorddf2
345int __unordsf2vfp(float a, float b);    // Appears to return __unordsf2
346
347
348Preconditions are listed for each function at the definition when there are any.
349Any preconditions reflect the specification at
350http://gcc.gnu.org/onlinedocs/gccint/Libgcc.html#Libgcc.
351
352Assumptions are listed in "int_lib.h", and in individual files.  Where possible
353assumptions are checked at compile time.
354