gcc/doc/libgcc.texi

   1 @c Copyright (C) 2003 Free Software Foundation, Inc.
   2 @c This is part of the GCC manual.
   3 @c For copying conditions, see the file gcc.texi.
   4 @c Contributed by Aldy Hernandez <aldy@quesejoda.com>
   5
   6 @node Libgcc
   7 @chapter The GCC low-level runtime library
   8
   9 GCC provides a low-level runtime library, @file{libgcc.a} or
  10 @file{libgcc_s.so.1} on some platforms.  GCC generates calls to
  11 routines in this library automatically, whenever it needs to perform
  12 some operation that is too complicated to emit inline code for.
  13
  14 Most of the routines in @code{libgcc} handle arithmetic operations
  15 that the target processor cannot perform directly.  This includes
  16 integer multiply and divide on some machines, and all floating-point
  17 operations on other machines.  @code{libgcc} also includes routines
  18 for exception handling, and a handful of miscellaneous operations.
  19
  20 Some of these routines can be defined in mostly machine-independent C.
  21 Others must be hand-written in assembly language for each processor
  22 that needs them.
  23
  24 GCC will also generate calls to C library routines, such as
  25 @code{memcpy} and @code{memset}, in some cases.  The set of routines
  26 that GCC may possibly use is documented in @ref{Other
  27 Builtins,,,gcc, Using the GNU Compiler Collection (GCC)}.
  28
  29 @menu
  30 * Integer library routines::
  31 * Soft float library routines::
  32 * Exception handling routines::
  33 * Miscellaneous routines::
  34 @end menu
  35
  36 @node Integer library routines
  37 @section Routines for integer arithmetic
  38
  39 document me!
  40
  41 @example
  42   __absvsi2
  43   __addvsi3
  44   __ashlsi3
  45   __ashrsi3
  46   __divsi3
  47   __lshrsi3
  48   __modsi3
  49   __mulsi3
  50   __mulvsi3
  51   __negvsi2
  52   __subvsi3
  53   __udivsi3
  54   __umodsi3
  55
  56   __absvdi2
  57   __addvdi3
  58   __ashldi3
  59   __ashrdi3
  60   __cmpdi2
  61   __divdi3
  62   __ffsdi2
  63   __fixdfdi
  64   __fixsfdi
  65   __fixtfdi
  66   __fixxfdi
  67   __fixunsdfdi
  68   __fixunsdfsi
  69   __fixunssfsi
  70   __fixunssfdi
  71   __fixunstfdi
  72   __fixunstfsi
  73   __fixunsxfdi
  74   __fixunsxfsi
  75   __floatdidf
  76   __floatdisf
  77   __floatdixf
  78   __floatditf
  79   __lshrdi3
  80   __moddi3
  81   __muldi3
  82   __mulvdi3
  83   __negdi2
  84   __negvdi2
  85   __subvdi3
  86   __ucmpdi2
  87   __udivdi3
  88   __udivmoddi4
  89   __umoddi3
  90
  91   __ashlti3
  92   __ashrti3
  93   __cmpti2
  94   __divti3
  95   __ffsti2
  96   __fixdfti
  97   __fixsfti
  98   __fixtfti
  99   __fixxfti
 100   __lshrti3
 101   __modti3
 102   __multi3
 103   __negti2
 104   __ucmpti2
 105   __udivmodti4
 106   __udivti3
 107   __umodti3
 108   __fixunsdfti
 109   __fixunssfti
 110   __fixunstfti
 111   __fixunsxfti
 112   __floattidf
 113   __floattisf
 114   __floattixf
 115   __floattitf
 116
 117   __clzsi2
 118   __clzdi2
 119   __clzti2
 120   __ctzsi2
 121   __ctzdi2
 122   __ctzti2
 123   __popcountsi2
 124   __popcountdi2
 125   __popcountti2
 126   __paritysi2
 127   __paritydi2
 128   __parityti2
 129 @end example
 130
 131
 132 @node Soft float library routines
 133 @section Routines for floating point emulation
 134 @cindex soft float library
 135 @cindex arithmetic library
 136 @cindex math library
 137 @opindex msoft-float
 138
 139 The software floating point library is used on machines which do not
 140 have hardware support for floating point.  It is also used whenever
 141 @option{-msoft-float} is used to disable generation of floating point
 142 instructions.  (Not all targets support this switch.)
 143
 144 For compatibility with other compilers, the floating point emulation
 145 routines can be renamed with the @code{DECLARE_LIBRARY_RENAMES} macro
 146 (@pxref{Library Calls}).  In this section, the default names are used.
 147
 148 These routines take arguments and return values of a specific machine
 149 mode, not a specific C type.  @xref{Machine Modes}, for an explanation
 150 of this concept.  For illustrative purposes, in this section
 151 @code{float} is assumed to correspond to @code{SFmode}; @code{double}
 152 to @code{DFmode}; @code{@w{long double}} to @code{TFmode}; and
 153 @code{int} to @code{SImode}.  This is a common mapping, but not the
 154 only possibility.
 155
 156 Presently the library does not support @code{XFmode}, which is used
 157 for @code{long double} on some architectures.
 158
 159 @subsection Arithmetic functions
 160
 161 @deftypefn {Runtime Function} float __addsf3 (float @var{a}, float @var{b})
 162 @deftypefnx {Runtime Function} double __adddf3 (double @var{a}, double @var{b})
 163 @deftypefnx {Runtime Function} long double __addtf3 (long double @var{a}, long double @var{b})
 164 These functions return the sum of @var{a} and @var{b}.
 165 @end deftypefn
 166
 167 @deftypefn {Runtime Function} float __subsf3 (float @var{a}, float @var{b})
 168 @deftypefnx {Runtime Function} double __subdf3 (double @var{a}, double @var{b})
 169 @deftypefnx {Runtime Function} long double __subtf3 (long double @var{a}, long double @var{b})
 170 These functions return the difference between @var{b} and @var{a};
 171 that is, @w{@math{@var{a} - @var{b}}}.
 172 @end deftypefn
 173
 174 @deftypefn {Runtime Function} float __mulsf3 (float @var{a}, float @var{b})
 175 @deftypefnx {Runtime Function} double __muldf3 (double @var{a}, double @var{b})
 176 @deftypefnx {Runtime Function} long double __multf3 (long double @var{a}, long double @var{b})
 177 These functions return the product of @var{a} and @var{b}.
 178 @end deftypefn
 179
 180 @deftypefn {Runtime Function} float __divsf3 (float @var{a}, float @var{b})
 181 @deftypefnx {Runtime Function} double __divdf3 (double @var{a}, double @var{b})
 182 @deftypefnx {Runtime Function} long double __divtf3 (long double @var{a}, long double @var{b})
 183 These functions return the quotient of @var{a} and @var{b}; that is,
 184 @w{@math{@var{a} / @var{b}}}.
 185 @end deftypefn
 186
 187 @deftypefn {Runtime Function} double __negdf2 (double @var{a})
 188 @deftypefnx {Runtime Function} long double __negtf2 (long double @var{a})
 189 @deftypefnx {Runtime Function} float __negsf2 (float @var{a})
 190 These functions return the negation of @var{a}.  They simply flip the
 191 sign bit, so they can produce negative zero and negative NaN.
 192 @end deftypefn
 193
 194 @subsection Conversion functions
 195
 196 @deftypefn {Runtime Function} double __extendsfdf2 (float @var{a})
 197 @deftypefnx {Runtime Function} long double __extendsftf2 (float @var{a})
 198 @deftypefnx {Runtime Function} long double __extenddftf2 (double @var{a})
 199 These functions extend @var{a} to the wider mode of their return
 200 type.
 201 @end deftypefn
 202
 203 @deftypefn {Runtime Function} double __trunctfdf2 (long double @var{a})
 204 @deftypefnx {Runtime Function} float __trunctfsf2 (long double @var{a})
 205 @deftypefnx {Runtime Function} float __truncdfsf2 (double @var{a})
 206 These functions truncate @var{a} to the narrower mode of their return
 207 type, rounding toward zero.
 208 @end deftypefn
 209
 210 @deftypefn {Runtime Function} int __fixsfsi (float @var{a})
 211 @deftypefnx {Runtime Function} int __fixdfsi (double @var{a})
 212 @deftypefnx {Runtime Function} int __fixtfsi (long double @var{a})
 213 These functions convert @var{a} to a signed integer, rounding toward zero.
 214 @end deftypefn
 215
 216 @deftypefn {Runtime Function} unsigned int __fixunssfsi (float @var{a})
 217 @deftypefnx {Runtime Function} unsigned int __fixunsdfsi (double @var{a})
 218 @deftypefnx {Runtime Function} unsigned int __fixunstfsi (long double @var{a})
 219 These functions convert @var{a} to an unsigned integer, rounding
 220 toward zero.  Negative values all become zero.
 221 @end deftypefn
 222
 223 @deftypefn {Runtime Function} float __floatsisf (int @var{i})
 224 @deftypefnx {Runtime Function} double __floatsidf (int @var{i})
 225 @deftypefnx {Runtime Function} long double __floatsitf (int @var{i})
 226 These functions convert @var{i}, a signed integer, to floating point.
 227 @end deftypefn
 228
 229 @deftypefn {Runtime Function} float __floatunsisf (unsigned int @var{n})
 230 @deftypefnx {Runtime Function} double __floatunsidf (unsigned int @var{n})
 231 @deftypefnx {Runtime Function} long double __floatunsitf (unsigned int @var{n})
 232 These functions convert @var{n}, an unsigned integer, to floating point.
 233 @end deftypefn
 234
 235 There are no functions to convert @code{DImode} integers to or from
 236 floating point; this reflects the fact that such conversions are rare,
 237 and processors with native 64-bit arithmetic tend to have hardware
 238 floating point support.  If such routines ever get added, they will be
 239 named @code{__fixsfdi}, @code{__floatdisf}, and so on.
 240
 241 @subsection Comparison functions
 242
 243 There are two sets of basic comparison functions.
 244
 245 @deftypefn {Runtime Function} int __cmpsf2 (float @var{a}, float @var{b})
 246 @deftypefnx {Runtime Function} int __cmpdf2 (double @var{a}, double @var{b})
 247 @deftypefnx {Runtime Function} int __cmptf2 (long double @var{a}, long double @var{b})
 248 These functions calculate @math{a <=> b}.  That is, if @var{a} is less
 249 than @var{b}, they return -1; if @var{a} is greater than @var{b}, they
 250 return 1; and if @var{a} and @var{b} are equal they return 0.  If
 251 either argument is NaN they return 1, but you should not rely on this;
 252 if NaN is a possibility, use one of the higher-level comparison
 253 functions.
 254 @end deftypefn
 255
 256 @deftypefn {Runtime Function} int __unordsf2 (float @var{a}, float @var{b})
 257 @deftypefnx {Runtime Function} int __unorddf2 (double @var{a}, double @var{b})
 258 @deftypefnx {Runtime Function} int __unordtf2 (long double @var{a}, long double @var{b})
 259 These functions return 1 if either argument is NaN, otherwise 0.
 260 @end deftypefn
 261
 262 There is also a complete group of higher level functions which
 263 correspond directly to comparison operators.  They implement the ISO@tie{}C
 264 semantics for floating-point comparisons, taking NaN into account.
 265 Pay careful attention to the return values defined for each set.
 266 Under the hood, all of these routines are implemented as
 267
 268 @smallexample
 269   if (__unord@var{X}f2 (a, b))
 270     return @var{E};
 271   return __cmp@var{X}f2 (a, b);
 272 @end smallexample
 273
 274 @noindent
 275 where @var{E} is a constant chosen to give the proper behavior for
 276 NaN.  Thus, the meaning of the return value is different for each set.
 277 Do not rely on this implementation; only the semantics documented
 278 below are guaranteed.
 279
 280 @deftypefn {Runtime Function} int __eqsf2 (float @var{a}, float @var{b})
 281 @deftypefnx {Runtime Function} int __eqdf2 (double @var{a}, double @var{b})
 282 @deftypefnx {Runtime Function} int __eqtf2 (long double @var{a}, long double @var{b})
 283 These functions return zero if neither argument is NaN, and @var{a} and
 284 @var{b} are equal.
 285 @end deftypefn
 286
 287 @deftypefn {Runtime Function} int __nesf2 (float @var{a}, float @var{b})
 288 @deftypefnx {Runtime Function} int __nedf2 (double @var{a}, double @var{b})
 289 @deftypefnx {Runtime Function} int __netf2 (long double @var{a}, long double @var{b})
 290 These functions return a nonzero value if either argument is NaN, or
 291 if @var{a} and @var{b} are unequal.
 292 @end deftypefn
 293
 294 @deftypefn {Runtime Function} int __gesf2 (float @var{a}, float @var{b})
 295 @deftypefnx {Runtime Function} int __gedf2 (double @var{a}, double @var{b})
 296 @deftypefnx {Runtime Function} int __getf2 (long double @var{a}, long double @var{b})
 297 These functions return a value greater than or equal to zero if
 298 neither argument is NaN, and @var{a} is greater than or equal to
 299 @var{b}.
 300 @end deftypefn
 301
 302 @deftypefn {Runtime Function} int __ltsf2 (float @var{a}, float @var{b})
 303 @deftypefnx {Runtime Function} int __ltdf2 (double @var{a}, double @var{b})
 304 @deftypefnx {Runtime Function} int __lttf2 (long double @var{a}, long double @var{b})
 305 These functions return a value less than zero if neither argument is
 306 NaN, and @var{a} is strictly less than @var{b}.
 307 @end deftypefn
 308
 309 @deftypefn {Runtime Function} int __lesf2 (float @var{a}, float @var{b})
 310 @deftypefnx {Runtime Function} int __ledf2 (double @var{a}, double @var{b})
 311 @deftypefnx {Runtime Function} int __letf2 (long double @var{a}, long double @var{b})
 312 These functions return a value less than or equal to zero if neither
 313 argument is NaN, and @var{a} is less than or equal to @var{b}.
 314 @end deftypefn
 315
 316 @deftypefn {Runtime Function} int __gtsf2 (float @var{a}, float @var{b})
 317 @deftypefnx {Runtime Function} int __gtdf2 (double @var{a}, double @var{b})
 318 @deftypefnx {Runtime Function} int __gttf2 (long double @var{a}, long double @var{b})
 319 These functions return a value greater than zero if neither argument
 320 is NaN, and @var{a} is strictly greater than @var{b}.
 321 @end deftypefn
 322
 323 @node Exception handling routines
 324 @section Language-independent routines for exception handling
 325
 326 document me!
 327
 328 @example
 329   _Unwind_DeleteException
 330   _Unwind_Find_FDE
 331   _Unwind_ForcedUnwind
 332   _Unwind_GetGR
 333   _Unwind_GetIP
 334   _Unwind_GetLanguageSpecificData
 335   _Unwind_GetRegionStart
 336   _Unwind_GetTextRelBase
 337   _Unwind_GetDataRelBase
 338   _Unwind_RaiseException
 339   _Unwind_Resume
 340   _Unwind_SetGR
 341   _Unwind_SetIP
 342   _Unwind_FindEnclosingFunction
 343   _Unwind_SjLj_Register
 344   _Unwind_SjLj_Unregister
 345   _Unwind_SjLj_RaiseException
 346   _Unwind_SjLj_ForcedUnwind
 347   _Unwind_SjLj_Resume
 348   __deregister_frame
 349   __deregister_frame_info
 350   __deregister_frame_info_bases
 351   __register_frame
 352   __register_frame_info
 353   __register_frame_info_bases
 354   __register_frame_info_table
 355   __register_frame_info_table_bases
 356   __register_frame_table
 357 @end example
 358
 359 @node Miscellaneous routines
 360 @section Miscellaneous runtime library routines
 361
 362 document me!
 363
 364 @example
 365   __clear_cache
 366 @end example
 367
 368 any others?