path: root/gcc/doc/libgcc.texi

@c Copyright (C) 2003 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@c Contributed by Aldy Hernandez <aldy@quesejoda.com>

@node Libgcc
@chapter The GCC low-level runtime library

GCC provides a low-level runtime library, @file{libgcc.a} or
@file{libgcc_s.so.1} on some platforms.  GCC generates calls to
routines in this library automatically, whenever it needs to perform
some operation that is too complicated to emit inline code for.

Most of the routines in @code{libgcc} handle arithmetic operations
that the target processor cannot perform directly.  This includes
integer multiply and divide on some machines, and all floating-point
operations on other machines.  @code{libgcc} also includes routines
for exception handling, and a handful of miscellaneous operations.

Some of these routines can be defined in mostly machine-independent C.
Others must be hand-written in assembly language for each processor
that needs them.

GCC will also generate calls to C library routines, such as
@code{memcpy} and @code{memset}, in some cases.  The set of routines
that GCC may possibly use is documented in @ref{Other
Builtins,,,gcc, Using the GNU Compiler Collection (GCC)}.

@menu
* Integer library routines::
* Soft float library routines::
* Exception handling routines::
* Miscellaneous routines:: 
@end menu

@node Integer library routines
@section Routines for integer arithmetic

document me!

@example
  __absvsi2
  __addvsi3
  __ashlsi3
  __ashrsi3
  __divsi3
  __lshrsi3
  __modsi3
  __mulsi3
  __mulvsi3
  __negvsi2
  __subvsi3
  __udivsi3
  __umodsi3

  __absvdi2
  __addvdi3
  __ashldi3
  __ashrdi3
  __cmpdi2
  __divdi3
  __ffsdi2
  __fixdfdi
  __fixsfdi
  __fixtfdi
  __fixxfdi
  __fixunsdfdi
  __fixunsdfsi
  __fixunssfsi
  __fixunssfdi
  __fixunstfdi
  __fixunstfsi
  __fixunsxfdi
  __fixunsxfsi
  __floatdidf
  __floatdisf
  __floatdixf
  __floatditf
  __lshrdi3
  __moddi3
  __muldi3
  __mulvdi3
  __negdi2
  __negvdi2
  __subvdi3
  __ucmpdi2
  __udivdi3
  __udivmoddi4
  __umoddi3

  __ashlti3
  __ashrti3
  __cmpti2
  __divti3
  __ffsti2
  __fixdfti
  __fixsfti
  __fixtfti
  __fixxfti
  __lshrti3
  __modti3
  __multi3
  __negti2
  __ucmpti2
  __udivmodti4
  __udivti3
  __umodti3
  __fixunsdfti
  __fixunssfti
  __fixunstfti
  __fixunsxfti
  __floattidf
  __floattisf
  __floattixf
  __floattitf

  __clzsi2
  __clzdi2
  __clzti2
  __ctzsi2
  __ctzdi2
  __ctzti2
  __popcountsi2
  __popcountdi2
  __popcountti2
  __paritysi2
  __paritydi2
  __parityti2
@end example


@node Soft float library routines
@section Routines for floating point emulation
@cindex soft float library
@cindex arithmetic library
@cindex math library
@opindex msoft-float

The software floating point library is used on machines which do not
have hardware support for floating point.  It is also used whenever
@option{-msoft-float} is used to disable generation of floating point
instructions.  (Not all targets support this switch.)

For compatibility with other compilers, the floating point emulation
routines can be renamed with the @code{DECLARE_LIBRARY_RENAMES} macro
(@pxref{Library Calls}).  In this section, the default names are used.

These routines take arguments and return values of a specific machine
mode, not a specific C type.  @xref{Machine Modes}, for an explanation
of this concept.  For illustrative purposes, in this section
@code{float} is assumed to correspond to @code{SFmode}; @code{double}
to @code{DFmode}; @code{@w{long double}} to @code{TFmode}; and
@code{int} to @code{SImode}.  This is a common mapping, but not the
only possibility.

Presently the library does not support @code{XFmode}, which is used
for @code{long double} on some architectures.

@subsection Arithmetic functions

@deftypefn {Runtime Function} float __addsf3 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} double __adddf3 (double @var{a}, double @var{b})
@deftypefnx {Runtime Function} {long double} __addtf3 (long double @var{a}, long double @var{b})
These functions return the sum of @var{a} and @var{b}.
@end deftypefn

@deftypefn {Runtime Function} float __subsf3 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} double __subdf3 (double @var{a}, double @var{b})
@deftypefnx {Runtime Function} {long double} __subtf3 (long double @var{a}, long double @var{b})
These functions return the difference between @var{b} and @var{a};
that is, @w{@math{@var{a} - @var{b}}}.
@end deftypefn

@deftypefn {Runtime Function} float __mulsf3 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} double __muldf3 (double @var{a}, double @var{b})
@deftypefnx {Runtime Function} {long double} __multf3 (long double @var{a}, long double @var{b})
These functions return the product of @var{a} and @var{b}.
@end deftypefn

@deftypefn {Runtime Function} float __divsf3 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} double __divdf3 (double @var{a}, double @var{b})
@deftypefnx {Runtime Function} {long double} __divtf3 (long double @var{a}, long double @var{b})
These functions return the quotient of @var{a} and @var{b}; that is,
@w{@math{@var{a} / @var{b}}}.
@end deftypefn

@deftypefn {Runtime Function} float __negsf2 (float @var{a})
@deftypefnx {Runtime Function} double __negdf2 (double @var{a})
@deftypefnx {Runtime Function} {long double} __negtf2 (long double @var{a})
These functions return the negation of @var{a}.  They simply flip the
sign bit, so they can produce negative zero and negative NaN.
@end deftypefn

@subsection Conversion functions

@deftypefn {Runtime Function} double __extendsfdf2 (float @var{a})
@deftypefnx {Runtime Function} {long double} __extendsftf2 (float @var{a})
@deftypefnx {Runtime Function} {long double} __extenddftf2 (double @var{a})
These functions extend @var{a} to the wider mode of their return
type.
@end deftypefn

@deftypefn {Runtime Function} double __trunctfdf2 (long double @var{a})
@deftypefnx {Runtime Function} float __trunctfsf2 (long double @var{a})
@deftypefnx {Runtime Function} float __truncdfsf2 (double @var{a})
These functions truncate @var{a} to the narrower mode of their return
type, rounding toward zero.
@end deftypefn

@deftypefn {Runtime Function} int __fixsfsi (float @var{a})
@deftypefnx {Runtime Function} int __fixdfsi (double @var{a})
@deftypefnx {Runtime Function} int __fixtfsi (long double @var{a})
These functions convert @var{a} to a signed integer, rounding toward zero.
@end deftypefn

@deftypefn {Runtime Function} {unsigned int} __fixunssfsi (float @var{a})
@deftypefnx {Runtime Function} {unsigned int} __fixunsdfsi (double @var{a})
@deftypefnx {Runtime Function} {unsigned int} __fixunstfsi (long double @var{a})
These functions convert @var{a} to an unsigned integer, rounding
toward zero.  Negative values all become zero.
@end deftypefn

@deftypefn {Runtime Function} float __floatsisf (int @var{i})
@deftypefnx {Runtime Function} double __floatsidf (int @var{i})
@deftypefnx {Runtime Function} {long double} __floatsitf (int @var{i})
These functions convert @var{i}, a signed integer, to floating point.
@end deftypefn

@deftypefn {Runtime Function} float __floatunsisf (unsigned int @var{n})
@deftypefnx {Runtime Function} double __floatunsidf (unsigned int @var{n})
@deftypefnx {Runtime Function} {long double} __floatunsitf (unsigned int @var{n})
These functions convert @var{n}, an unsigned integer, to floating point.
@end deftypefn

There are no functions to convert @code{DImode} integers to or from
floating point; this reflects the fact that such conversions are rare,
and processors with native 64-bit arithmetic tend to have hardware
floating point support.  If such routines ever get added, they will be
named @code{__fixsfdi}, @code{__floatdisf}, and so on.

@subsection Comparison functions

There are two sets of basic comparison functions.

@deftypefn {Runtime Function} int __cmpsf2 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} int __cmpdf2 (double @var{a}, double @var{b})
@deftypefnx {Runtime Function} int __cmptf2 (long double @var{a}, long double @var{b})
These functions calculate @math{a <=> b}.  That is, if @var{a} is less
than @var{b}, they return -1; if @var{a} is greater than @var{b}, they
return 1; and if @var{a} and @var{b} are equal they return 0.  If
either argument is NaN they return 1, but you should not rely on this;
if NaN is a possibility, use one of the higher-level comparison
functions.
@end deftypefn

@deftypefn {Runtime Function} int __unordsf2 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} int __unorddf2 (double @var{a}, double @var{b})
@deftypefnx {Runtime Function} int __unordtf2 (long double @var{a}, long double @var{b})
These functions return a nonzero value if either argument is NaN, otherwise 0.
@end deftypefn

There is also a complete group of higher level functions which
correspond directly to comparison operators.  They implement the ISO C
semantics for floating-point comparisons, taking NaN into account.
Pay careful attention to the return values defined for each set.
Under the hood, all of these routines are implemented as

@smallexample
  if (__unord@var{X}f2 (a, b))
    return @var{E};
  return __cmp@var{X}f2 (a, b);
@end smallexample

@noindent
where @var{E} is a constant chosen to give the proper behavior for
NaN.  Thus, the meaning of the return value is different for each set.
Do not rely on this implementation; only the semantics documented
below are guaranteed.

@deftypefn {Runtime Function} int __eqsf2 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} int __eqdf2 (double @var{a}, double @var{b})
@deftypefnx {Runtime Function} int __eqtf2 (long double @var{a}, long double @var{b})
These functions return zero if neither argument is NaN, and @var{a} and
@var{b} are equal.
@end deftypefn

@deftypefn {Runtime Function} int __nesf2 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} int __nedf2 (double @var{a}, double @var{b})
@deftypefnx {Runtime Function} int __netf2 (long double @var{a}, long double @var{b})
These functions return a nonzero value if either argument is NaN, or
if @var{a} and @var{b} are unequal.
@end deftypefn

@deftypefn {Runtime Function} int __gesf2 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} int __gedf2 (double @var{a}, double @var{b})
@deftypefnx {Runtime Function} int __getf2 (long double @var{a}, long double @var{b})
These functions return a value greater than or equal to zero if
neither argument is NaN, and @var{a} is greater than or equal to
@var{b}.
@end deftypefn

@deftypefn {Runtime Function} int __ltsf2 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} int __ltdf2 (double @var{a}, double @var{b})
@deftypefnx {Runtime Function} int __lttf2 (long double @var{a}, long double @var{b})
These functions return a value less than zero if neither argument is
NaN, and @var{a} is strictly less than @var{b}.
@end deftypefn

@deftypefn {Runtime Function} int __lesf2 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} int __ledf2 (double @var{a}, double @var{b})
@deftypefnx {Runtime Function} int __letf2 (long double @var{a}, long double @var{b})
These functions return a value less than or equal to zero if neither
argument is NaN, and @var{a} is less than or equal to @var{b}.
@end deftypefn

@deftypefn {Runtime Function} int __gtsf2 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} int __gtdf2 (double @var{a}, double @var{b})
@deftypefnx {Runtime Function} int __gttf2 (long double @var{a}, long double @var{b})
These functions return a value greater than zero if neither argument
is NaN, and @var{a} is strictly greater than @var{b}.
@end deftypefn

@node Exception handling routines
@section Language-independent routines for exception handling

document me!

@example
  _Unwind_DeleteException
  _Unwind_Find_FDE
  _Unwind_ForcedUnwind
  _Unwind_GetGR
  _Unwind_GetIP
  _Unwind_GetLanguageSpecificData
  _Unwind_GetRegionStart
  _Unwind_GetTextRelBase
  _Unwind_GetDataRelBase
  _Unwind_RaiseException
  _Unwind_Resume
  _Unwind_SetGR
  _Unwind_SetIP
  _Unwind_FindEnclosingFunction
  _Unwind_SjLj_Register
  _Unwind_SjLj_Unregister
  _Unwind_SjLj_RaiseException
  _Unwind_SjLj_ForcedUnwind
  _Unwind_SjLj_Resume
  __deregister_frame
  __deregister_frame_info
  __deregister_frame_info_bases
  __register_frame
  __register_frame_info
  __register_frame_info_bases
  __register_frame_info_table
  __register_frame_info_table_bases
  __register_frame_table
@end example

@node Miscellaneous routines
@section Miscellaneous runtime library routines

document me!

@example
  __clear_cache
@end example

any others?