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 Please note that the libgcc specification explicitly mentions actual types of
  24 arguments and returned values being expressed with machine modes.
  25 In some cases particular types such as "int", "unsigned", "long long", etc.
  26 may be specified just as examples there.
  27
  28 Here is a synopsis of the contents of this library:
  29
  30 typedef  int32_t si_int;
  31 typedef uint32_t su_int;
  32
  33 typedef  int64_t di_int;
  34 typedef uint64_t du_int;
  35
  36 // Integral bit manipulation
  37
  38 di_int __ashldi3(di_int a, int b);         // a << b
  39 ti_int __ashlti3(ti_int a, int b);         // a << b
  40
  41 di_int __ashrdi3(di_int a, int b);         // a >> b  arithmetic (sign fill)
  42 ti_int __ashrti3(ti_int a, int b);         // a >> b  arithmetic (sign fill)
  43 di_int __lshrdi3(di_int a, int b);         // a >> b  logical    (zero fill)
  44 ti_int __lshrti3(ti_int a, int b);         // a >> b  logical    (zero fill)
  45
  46 int __clzsi2(si_int a);  // count leading zeros
  47 int __clzdi2(di_int a);  // count leading zeros
  48 int __clzti2(ti_int a);  // count leading zeros
  49 int __ctzsi2(si_int a);  // count trailing zeros
  50 int __ctzdi2(di_int a);  // count trailing zeros
  51 int __ctzti2(ti_int a);  // count trailing zeros
  52
  53 int __ffssi2(si_int a);  // find least significant 1 bit
  54 int __ffsdi2(di_int a);  // find least significant 1 bit
  55 int __ffsti2(ti_int a);  // find least significant 1 bit
  56
  57 int __paritysi2(si_int a);  // bit parity
  58 int __paritydi2(di_int a);  // bit parity
  59 int __parityti2(ti_int a);  // bit parity
  60
  61 int __popcountsi2(si_int a);  // bit population
  62 int __popcountdi2(di_int a);  // bit population
  63 int __popcountti2(ti_int a);  // bit population
  64
  65 uint32_t __bswapsi2(uint32_t a);   // a byteswapped
  66 uint64_t __bswapdi2(uint64_t a);   // a byteswapped
  67
  68 // Integral arithmetic
  69
  70 di_int __negdi2    (di_int a);                         // -a
  71 ti_int __negti2    (ti_int a);                         // -a
  72 di_int __muldi3    (di_int a, di_int b);               // a * b
  73 ti_int __multi3    (ti_int a, ti_int b);               // a * b
  74 si_int __divsi3    (si_int a, si_int b);               // a / b   signed
  75 di_int __divdi3    (di_int a, di_int b);               // a / b   signed
  76 ti_int __divti3    (ti_int a, ti_int b);               // a / b   signed
  77 su_int __udivsi3   (su_int n, su_int d);               // a / b   unsigned
  78 du_int __udivdi3   (du_int a, du_int b);               // a / b   unsigned
  79 tu_int __udivti3   (tu_int a, tu_int b);               // a / b   unsigned
  80 si_int __modsi3    (si_int a, si_int b);               // a % b   signed
  81 di_int __moddi3    (di_int a, di_int b);               // a % b   signed
  82 ti_int __modti3    (ti_int a, ti_int b);               // a % b   signed
  83 su_int __umodsi3   (su_int a, su_int b);               // a % b   unsigned
  84 du_int __umoddi3   (du_int a, du_int b);               // a % b   unsigned
  85 tu_int __umodti3   (tu_int a, tu_int b);               // a % b   unsigned
  86 du_int __udivmoddi4(du_int a, du_int b, du_int* rem);  // a / b, *rem = a % b  unsigned
  87 tu_int __udivmodti4(tu_int a, tu_int b, tu_int* rem);  // a / b, *rem = a % b  unsigned
  88 su_int __udivmodsi4(su_int a, su_int b, su_int* rem);  // a / b, *rem = a % b  unsigned
  89 si_int __divmodsi4(si_int a, si_int b, si_int* rem);   // a / b, *rem = a % b  signed
  90 di_int __divmoddi4(di_int a, di_int b, di_int* rem);   // a / b, *rem = a % b  signed
  91 ti_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
  97 si_int __absvsi2(si_int a);           // abs(a)
  98 di_int __absvdi2(di_int a);           // abs(a)
  99 ti_int __absvti2(ti_int a);           // abs(a)
 100
 101 si_int __negvsi2(si_int a);           // -a
 102 di_int __negvdi2(di_int a);           // -a
 103 ti_int __negvti2(ti_int a);           // -a
 104
 105 si_int __addvsi3(si_int a, si_int b);  // a + b
 106 di_int __addvdi3(di_int a, di_int b);  // a + b
 107 ti_int __addvti3(ti_int a, ti_int b);  // a + b
 108
 109 si_int __subvsi3(si_int a, si_int b);  // a - b
 110 di_int __subvdi3(di_int a, di_int b);  // a - b
 111 ti_int __subvti3(ti_int a, ti_int b);  // a - b
 112
 113 si_int __mulvsi3(si_int a, si_int b);  // a * b
 114 di_int __mulvdi3(di_int a, di_int b);  // a * b
 115 ti_int __mulvti3(ti_int a, ti_int b);  // a * b
 116
 117
 118 // Integral arithmetic which returns if overflow
 119
 120 si_int __mulosi4(si_int a, si_int b, int* overflow);  // a * b, overflow set to one if result not in signed range
 121 di_int __mulodi4(di_int a, di_int b, int* overflow);  // a * b, overflow set to one if result not in signed range
 122 ti_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
 130 si_int __cmpdi2 (di_int a, di_int b);
 131 si_int __cmpti2 (ti_int a, ti_int b);
 132 si_int __ucmpdi2(du_int a, du_int b);
 133 si_int __ucmpti2(tu_int a, tu_int b);
 134
 135 //  Integral / floating point conversion
 136
 137 di_int __fixsfdi(      float a);
 138 di_int __fixdfdi(     double a);
 139 di_int __fixxfdi(long double a);
 140
 141 ti_int __fixsfti(      float a);
 142 ti_int __fixdfti(     double a);
 143 ti_int __fixxfti(long double a);
 144 uint64_t __fixtfdi(long double input);  // ppc only, doesn't match documentation
 145
 146 su_int __fixunssfsi(      float a);
 147 su_int __fixunsdfsi(     double a);
 148 su_int __fixunsxfsi(long double a);
 149
 150 du_int __fixunssfdi(      float a);
 151 du_int __fixunsdfdi(     double a);
 152 du_int __fixunsxfdi(long double a);
 153
 154 tu_int __fixunssfti(      float a);
 155 tu_int __fixunsdfti(     double a);
 156 tu_int __fixunsxfti(long double a);
 157 uint64_t __fixunstfdi(long double input);  // ppc only
 158
 159 float       __floatdisf(di_int a);
 160 double      __floatdidf(di_int a);
 161 long double __floatdixf(di_int a);
 162 long double __floatditf(int64_t a);        // ppc only
 163
 164 float       __floattisf(ti_int a);
 165 double      __floattidf(ti_int a);
 166 long double __floattixf(ti_int a);
 167
 168 float       __floatundisf(du_int a);
 169 double      __floatundidf(du_int a);
 170 long double __floatundixf(du_int a);
 171 long double __floatunditf(uint64_t a);     // ppc only
 172
 173 float       __floatuntisf(tu_int a);
 174 double      __floatuntidf(tu_int a);
 175 long double __floatuntixf(tu_int a);
 176
 177 //  Floating point raised to integer power
 178
 179 float       __powisf2(      float a, int b);  // a ^ b
 180 double      __powidf2(     double a, int b);  // a ^ b
 181 long double __powixf2(long double a, int b);  // a ^ b
 182 long 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);
 190 long double _Complex __mulxc3(long double a, long double b,
 191                               long double c, long double d);
 192 long 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);
 199 long double _Complex __divxc3(long double a, long double b,
 200                               long double c, long double d);
 201 long 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.
 210 void __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.
 215 void __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>
 229 void __eprintf(const char* format, const char* assertion_expression,
 230                                 const char* line, const char* file);
 231
 232 // for systems with emulated thread local storage
 233 void* __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.
 241 saveFP
 242 restFP
 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.
 247 void __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 )
 251 long double __gcc_qadd(long double x, long double y);
 252
 253 // subtracts two 128-bit double-double precision values ( x - y )
 254 long double __gcc_qsub(long double x, long double y);
 255
 256 // multiples two 128-bit double-double precision values ( x * y )
 257 long double __gcc_qmul(long double x, long double y);
 258
 259 // divides two 128-bit double-double precision values ( x / y )
 260 long 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.
 267 switch16
 268 switch32
 269 switch8
 270 switchu8
 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 destructors needs
 275 // to save and restore all registers in it prolog and epilog.  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.
 279 restore_vfp_d8_d15_regs
 280 save_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
 291 float  __addsf3vfp(float a, float b);   // Appears to return a + b
 292 double __adddf3vfp(double a, double b); // Appears to return a + b
 293 float  __divsf3vfp(float a, float b);   // Appears to return a / b
 294 double __divdf3vfp(double a, double b); // Appears to return a / b
 295 int    __eqsf2vfp(float a, float b);    // Appears to return  one
 296                                         //     iff a == b and neither is NaN.
 297 int    __eqdf2vfp(double a, double b);  // Appears to return  one
 298                                         //     iff a == b and neither is NaN.
 299 double __extendsfdf2vfp(float a);       // Appears to convert from
 300                                         //     float to double.
 301 int    __fixdfsivfp(double a);          // Appears to convert from
 302                                         //     double to int.
 303 int    __fixsfsivfp(float a);           // Appears to convert from
 304                                         //     float to int.
 305 unsigned int __fixunssfsivfp(float a);  // Appears to convert from
 306                                         //     float to unsigned int.
 307 unsigned int __fixunsdfsivfp(double a); // Appears to convert from
 308                                         //     double to unsigned int.
 309 double __floatsidfvfp(int a);           // Appears to convert from
 310                                         //     int to double.
 311 float __floatsisfvfp(int a);            // Appears to convert from
 312                                         //     int to float.
 313 double __floatunssidfvfp(unsigned int a); // Appears to convert from
 314                                         //     unsigned int to double.
 315 float __floatunssisfvfp(unsigned int a); // Appears to convert from
 316                                         //     unsigned int to float.
 317 int __gedf2vfp(double a, double b);     // Appears to return __gedf2
 318                                         //     (a >= b)
 319 int __gesf2vfp(float a, float b);       // Appears to return __gesf2
 320                                         //     (a >= b)
 321 int __gtdf2vfp(double a, double b);     // Appears to return __gtdf2
 322                                         //     (a > b)
 323 int __gtsf2vfp(float a, float b);       // Appears to return __gtsf2
 324                                         //     (a > b)
 325 int __ledf2vfp(double a, double b);     // Appears to return __ledf2
 326                                         //     (a <= b)
 327 int __lesf2vfp(float a, float b);       // Appears to return __lesf2
 328                                         //     (a <= b)
 329 int __ltdf2vfp(double a, double b);     // Appears to return __ltdf2
 330                                         //     (a < b)
 331 int __ltsf2vfp(float a, float b);       // Appears to return __ltsf2
 332                                         //     (a < b)
 333 double __muldf3vfp(double a, double b); // Appears to return a * b
 334 float __mulsf3vfp(float a, float b);    // Appears to return a * b
 335 int __nedf2vfp(double a, double b);     // Appears to return __nedf2
 336                                         //     (a != b)
 337 double __negdf2vfp(double a);           // Appears to return -a
 338 float __negsf2vfp(float a);             // Appears to return -a
 339 float __negsf2vfp(float a);             // Appears to return -a
 340 double __subdf3vfp(double a, double b); // Appears to return a - b
 341 float __subsf3vfp(float a, float b);    // Appears to return a - b
 342 float __truncdfsf2vfp(double a);        // Appears to convert from
 343                                         //     double to float.
 344 int __unorddf2vfp(double a, double b);  // Appears to return __unorddf2
 345 int __unordsf2vfp(float a, float b);    // Appears to return __unordsf2
 346
 347
 348 Preconditions are listed for each function at the definition when there are any.
 349 Any preconditions reflect the specification at
 350 http://gcc.gnu.org/onlinedocs/gccint/Libgcc.html#Libgcc.
 351
 352 Assumptions are listed in "int_lib.h", and in individual files.  Where possible
 353 assumptions are checked at compile time.