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