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 di_int __fixtfdi(   tf_float a);
 141
 142 ti_int __fixsfti(      float a);
 143 ti_int __fixdfti(     double a);
 144 ti_int __fixxfti(long double a);
 145 ti_int __fixtfti(   tf_float a);
 146
 147 su_int __fixunssfsi(      float a);
 148 su_int __fixunsdfsi(     double a);
 149 su_int __fixunsxfsi(long double a);
 150 su_int __fixunstfsi(   tf_float a);
 151
 152 du_int __fixunssfdi(      float a);
 153 du_int __fixunsdfdi(     double a);
 154 du_int __fixunsxfdi(long double a);
 155 du_int __fixunstfdi(   tf_float a);
 156
 157 tu_int __fixunssfti(      float a);
 158 tu_int __fixunsdfti(     double a);
 159 tu_int __fixunsxfti(long double a);
 160 tu_int __fixunstfti(   tf_float a);
 161
 162 float       __floatdisf(di_int a);
 163 double      __floatdidf(di_int a);
 164 long double __floatdixf(di_int a);
 165 tf_float    __floatditf(int64_t a);
 166
 167 float       __floattisf(ti_int a);
 168 double      __floattidf(ti_int a);
 169 long double __floattixf(ti_int a);
 170 tf_float    __floattitf(ti_int a);
 171
 172 float       __floatundisf(du_int a);
 173 double      __floatundidf(du_int a);
 174 long double __floatundixf(du_int a);
 175 tf_float    __floatunditf(du_int a);
 176
 177 float       __floatuntisf(tu_int a);
 178 double      __floatuntidf(tu_int a);
 179 long double __floatuntixf(tu_int a);
 180 tf_float    __floatuntixf(tu_int a);
 181
 182 //  Floating point raised to integer power
 183
 184 float       __powisf2(      float a, int b);  // a ^ b
 185 double      __powidf2(     double a, int b);  // a ^ b
 186 long double __powixf2(long double a, int b);  // a ^ b
 187 tf_float    __powitf2(   tf_float a, int b);  // a ^ b
 188
 189 //  Complex arithmetic
 190
 191 //  (a + ib) * (c + id)
 192
 193       float _Complex __mulsc3( float a,  float b,  float c,  float d);
 194      double _Complex __muldc3(double a, double b, double c, double d);
 195 long double _Complex __mulxc3(long double a, long double b,
 196                               long double c, long double d);
 197    tf_float _Complex __multc3(tf_float a, tf_float b, tf_float c, tf_float d);
 198
 199 //  (a + ib) / (c + id)
 200
 201       float _Complex __divsc3( float a,  float b,  float c,  float d);
 202      double _Complex __divdc3(double a, double b, double c, double d);
 203 long double _Complex __divxc3(long double a, long double b,
 204                               long double c, long double d);
 205    tf_float _Complex __divtc3(tf_float a, tf_float b, tf_float c, tf_float d);
 206
 207
 208 //         Runtime support
 209
 210 // __clear_cache() is used to tell process that new instructions have been
 211 // written to an address range.  Necessary on processors that do not have
 212 // a unified instruction and data cache.
 213 void __clear_cache(void* start, void* end);
 214
 215 // __enable_execute_stack() is used with nested functions when a trampoline
 216 // function is written onto the stack and that page range needs to be made
 217 // executable.
 218 void __enable_execute_stack(void* addr);
 219
 220 // __gcc_personality_v0() is normally only called by the system unwinder.
 221 // C code (as opposed to C++) normally does not need a personality function
 222 // because there are no catch clauses or destructors to be run.  But there
 223 // is a C language extension __attribute__((cleanup(func))) which marks local
 224 // variables as needing the cleanup function "func" to be run when the
 225 // variable goes out of scope.  That includes when an exception is thrown,
 226 // so a personality handler is needed.
 227 _Unwind_Reason_Code __gcc_personality_v0(int version, _Unwind_Action actions,
 228          uint64_t exceptionClass, struct _Unwind_Exception* exceptionObject,
 229          _Unwind_Context_t context);
 230
 231 // for use with some implementations of assert() in <assert.h>
 232 void __eprintf(const char* format, const char* assertion_expression,
 233                                 const char* line, const char* file);
 234
 235 // for systems with emulated thread local storage
 236 void* __emutls_get_address(struct __emutls_control*);
 237
 238
 239 //   Power PC specific functions
 240
 241 // There is no C interface to the saveFP/restFP functions.  They are helper
 242 // functions called by the prolog and epilog of functions that need to save
 243 // a number of non-volatile float point registers.
 244 saveFP
 245 restFP
 246
 247 // PowerPC has a standard template for trampoline functions.  This function
 248 // generates a custom trampoline function with the specific realFunc
 249 // and localsPtr values.
 250 void __trampoline_setup(uint32_t* trampOnStack, int trampSizeAllocated,
 251                                 const void* realFunc, void* localsPtr);
 252
 253 // adds two 128-bit double-double precision values ( x + y )
 254 long double __gcc_qadd(long double x, long double y);
 255
 256 // subtracts two 128-bit double-double precision values ( x - y )
 257 long double __gcc_qsub(long double x, long double y);
 258
 259 // multiples two 128-bit double-double precision values ( x * y )
 260 long double __gcc_qmul(long double x, long double y);
 261
 262 // divides two 128-bit double-double precision values ( x / y )
 263 long double __gcc_qdiv(long double a, long double b);
 264
 265
 266 //    ARM specific functions
 267
 268 // There is no C interface to the switch* functions.  These helper functions
 269 // are only needed by Thumb1 code for efficient switch table generation.
 270 switch16
 271 switch32
 272 switch8
 273 switchu8
 274
 275 // This function generates a custom trampoline function with the specific
 276 // realFunc and localsPtr values.
 277 void __trampoline_setup(uint32_t* trampOnStack, int trampSizeAllocated,
 278                         const void* realFunc, void* localsPtr);
 279
 280 // There is no C interface to the *_vfp_d8_d15_regs functions.  There are
 281 // called in the prolog and epilog of Thumb1 functions.  When the C++ ABI use
 282 // SJLJ for exceptions, each function with a catch clause or destructors needs
 283 // to save and restore all registers in it prolog and epilog.  But there is
 284 // no way to access vector and high float registers from thumb1 code, so the
 285 // compiler must add call outs to these helper functions in the prolog and
 286 // epilog.
 287 restore_vfp_d8_d15_regs
 288 save_vfp_d8_d15_regs
 289
 290
 291 // Note: long ago ARM processors did not have floating point hardware support.
 292 // Floating point was done in software and floating point parameters were
 293 // passed in integer registers.  When hardware support was added for floating
 294 // point, new *vfp functions were added to do the same operations but with
 295 // floating point parameters in floating point registers.
 296
 297 // Undocumented functions
 298
 299 float  __addsf3vfp(float a, float b);   // Appears to return a + b
 300 double __adddf3vfp(double a, double b); // Appears to return a + b
 301 float  __divsf3vfp(float a, float b);   // Appears to return a / b
 302 double __divdf3vfp(double a, double b); // Appears to return a / b
 303 int    __eqsf2vfp(float a, float b);    // Appears to return  one
 304                                         //     iff a == b and neither is NaN.
 305 int    __eqdf2vfp(double a, double b);  // Appears to return  one
 306                                         //     iff a == b and neither is NaN.
 307 double __extendsfdf2vfp(float a);       // Appears to convert from
 308                                         //     float to double.
 309 int    __fixdfsivfp(double a);          // Appears to convert from
 310                                         //     double to int.
 311 int    __fixsfsivfp(float a);           // Appears to convert from
 312                                         //     float to int.
 313 unsigned int __fixunssfsivfp(float a);  // Appears to convert from
 314                                         //     float to unsigned int.
 315 unsigned int __fixunsdfsivfp(double a); // Appears to convert from
 316                                         //     double to unsigned int.
 317 double __floatsidfvfp(int a);           // Appears to convert from
 318                                         //     int to double.
 319 float __floatsisfvfp(int a);            // Appears to convert from
 320                                         //     int to float.
 321 double __floatunssidfvfp(unsigned int a); // Appears to convert from
 322                                         //     unsigned int to double.
 323 float __floatunssisfvfp(unsigned int a); // Appears to convert from
 324                                         //     unsigned int to float.
 325 int __gedf2vfp(double a, double b);     // Appears to return __gedf2
 326                                         //     (a >= b)
 327 int __gesf2vfp(float a, float b);       // Appears to return __gesf2
 328                                         //     (a >= b)
 329 int __gtdf2vfp(double a, double b);     // Appears to return __gtdf2
 330                                         //     (a > b)
 331 int __gtsf2vfp(float a, float b);       // Appears to return __gtsf2
 332                                         //     (a > b)
 333 int __ledf2vfp(double a, double b);     // Appears to return __ledf2
 334                                         //     (a <= b)
 335 int __lesf2vfp(float a, float b);       // Appears to return __lesf2
 336                                         //     (a <= b)
 337 int __ltdf2vfp(double a, double b);     // Appears to return __ltdf2
 338                                         //     (a < b)
 339 int __ltsf2vfp(float a, float b);       // Appears to return __ltsf2
 340                                         //     (a < b)
 341 double __muldf3vfp(double a, double b); // Appears to return a * b
 342 float __mulsf3vfp(float a, float b);    // Appears to return a * b
 343 int __nedf2vfp(double a, double b);     // Appears to return __nedf2
 344                                         //     (a != b)
 345 double __negdf2vfp(double a);           // Appears to return -a
 346 float __negsf2vfp(float a);             // Appears to return -a
 347 float __negsf2vfp(float a);             // Appears to return -a
 348 double __subdf3vfp(double a, double b); // Appears to return a - b
 349 float __subsf3vfp(float a, float b);    // Appears to return a - b
 350 float __truncdfsf2vfp(double a);        // Appears to convert from
 351                                         //     double to float.
 352 int __unorddf2vfp(double a, double b);  // Appears to return __unorddf2
 353 int __unordsf2vfp(float a, float b);    // Appears to return __unordsf2
 354
 355
 356 Preconditions are listed for each function at the definition when there are any.
 357 Any preconditions reflect the specification at
 358 http://gcc.gnu.org/onlinedocs/gccint/Libgcc.html#Libgcc.
 359
 360 Assumptions are listed in "int_lib.h", and in individual files.  Where possible
 361 assumptions are checked at compile time.