2003-03-15 Aldy Hernandez <aldyh@redhat.com>

	    Zack Weinberg  <zack@codesourcery.com>

	* Makefile.in (TEXI_GCCINT_FILES): Add libgcc.texi.
	* doc/libgcc.texi: New file.
	* doc/interface.texi: Delete paragraph about libgcc interface.
	* doc/gccint.texi: Add libgcc menu entry and @include libgcc.texi.


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@64416 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 368 insertions, 0 deletions

diff --git a/gcc/doc/libgcc.texi b/gcc/doc/libgcc.texi
new file mode 100644
index 00000000000..19074ba985a
--- /dev/null
+++ b/gcc/doc/libgcc.texi
@@ -0,0 +1,368 @@
+@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} double __negdf2 (double @var{a})
+@deftypefnx {Runtime Function} long double __negtf2 (long double @var{a})
+@deftypefnx {Runtime Function} float __negsf2 (float @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 1 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@tie{}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?