contrib/compiler-rt/lib/builtins/README.txt

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