003-10-21 Roger Sayle
* doc/libgcc.texi: Document some more of the libgcc API.
Index: doc/libgcc.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/libgcc.texi,v
retrieving revision 1.3
diff -c -3 -p -r1.3 libgcc.texi
*** doc/libgcc.texi 18 Oct 2003 18:17:23 -0000 1.3
--- doc/libgcc.texi 21 Oct 2003 21:40:21 -0000
*************** GCC will also generate calls to C librar
*** 26,31 ****
--- 26,41 ----
that GCC may possibly use is documented in @ref{Other
Builtins,,,gcc, Using the GNU Compiler Collection (GCC)}.
+ 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 chapter the
+ floating point type @code{float} is assumed to correspond to @code{SFmode};
+ @code{double} to @code{DFmode}; and @code{@w{long double}} to both
+ @code{TFmode} and @code{XFmode}. Similarly, the integer types @code{int}
+ and @code{@w{unsigned int}} correspond to @code{SImode}; @code{long} and
+ @code{@w{unsigned long}} to @code{DImode}; and @code{@w{long long}} and
+ @code{@w{unsigned long long}} to @code{TImode}.
+
@menu
* Integer library routines::
* Soft float library routines::
*************** Builtins,,,gcc, Using the GNU Compiler C
*** 36,133 ****
@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
--- 46,215 ----
@node Integer library routines
@section Routines for integer arithmetic
! The integer arithmetic routines are used on platforms that don't provide
! hardware support for arithmetic operations on some modes.
! @subsection Arithmetic functions
!
! @deftypefn {Runtime Function} int __ashlsi3 (int @var{a}, int @var{b})
! @deftypefnx {Runtime Function} long __ashldi3 (long @var{a}, int @var{b})
! @deftypefnx {Runtime Function} {long long} __ashlti3 (long long @var{a}, int @var{b})
! These functions return the result of shifting @var{a} left by @var{b} bits.
! @end deftypefn
!
! @deftypefn {Runtime Function} int __ashrsi3 (int @var{a}, int @var{b})
! @deftypefnx {Runtime Function} long __ashrdi3 (long @var{a}, int @var{b})
! @deftypefnx {Runtime Function} {long long} __ashrti3 (long long @var{a}, int @var{b})
! These functions return the result of arithmetically shifting @var{a} right
! by @var{b} bits.
! @end deftypefn
!
! @deftypefn {Runtime Function} int __divsi3 (int @var{a}, int @var{b})
! @deftypefnx {Runtime Function} long __divdi3 (long @var{a}, long @var{b})
! @deftypefnx {Runtime Function} {long long} __divti3 (long long @var{a}, long long @var{b})
! These functions return the quotient of the signed division of @var{a} and
! @var{b}.
! @end deftypefn
!
! @deftypefn {Runtime Function} int __lshrsi3 (int @var{a}, int @var{b})
! @deftypefnx {Runtime Function} long __lshrdi3 (long @var{a}, int @var{b})
! @deftypefnx {Runtime Function} {long long} __lshrti3 (long long @var{a}, int @var{b})
! These functions return the result of logically shifting @var{a} right by
! @var{b} bits.
! @end deftypefn
!
! @deftypefn {Runtime Function} int __modsi3 (int @var{a}, int @var{b})
! @deftypefnx {Runtime Function} long __moddi3 (long @var{a}, long @var{b})
! @deftypefnx {Runtime Function} {long long} __modti3 (long long @var{a}, long long @var{b})
! These functions return the remainder of the signed division of @var{a}
! and @var{b}.
! @end deftypefn
!
! @deftypefn {Runtime Function} int __mulsi3 (int @var{a}, int @var{b})
! @deftypefnx {Runtime Function} long __muldi3 (long @var{a}, long @var{b})
! @deftypefnx {Runtime Function} {long long} __multi3 (long long @var{a}, long long @var{b})
! These functions return the product of @var{a} and @var{b}.
! @end deftypefn
!
! @deftypefn {Runtime Function} long __negdi2 (long @var{a})
! @deftypefnx {Runtime Function} {long long} __negti2 (long long @var{a})
! These functions return the negation of @var{a}.
! @end deftypefn
!
! @deftypefn {Runtime Function} {unsigned int} __udivsi3 (unsigned int @var{a}, unsigned int @var{b})
! @deftypefnx {Runtime Function} {unsigned long} __udivdi3 (unsigned long @var{a}, unsigned long @var{b})
! @deftypefnx {Runtime Function} {unsigned long long} __udivti3 (unsigned long long @var{a}, unsigned long long @var{b})
! These functions return the quotient of the unsigned division of @var{a}
! and @var{b}.
! @end deftypefn
!
! @deftypefn {Runtime Function} {unsigned long} __udivmoddi3 (unsigned long @var{a}, unsigned long @var{b}, unsigned long *@var{c})
! @deftypefnx {Runtime Function} {unsigned long long} __udivti3 (unsigned long long @var{a}, unsigned long long @var{b}, unsigned long long *@var{c})
! These functions calculate both the quotient and remainder of the unsigned
! division of @var{a} and @var{b}. The return value is the quotient, and
! the remainder is placed in variable pointed to by @var{c}.
! @end deftypefn
!
! @deftypefn {Runtime Function} {unsigned int} __umodsi3 (unsigned int @var{a}, unsigned int @var{b})
! @deftypefnx {Runtime Function} {unsigned long} __umoddi3 (unsigned long @var{a}, unsigned long @var{b})
! @deftypefnx {Runtime Function} {unsigned long long} __umodti3 (unsigned long long @var{a}, unsigned long long @var{b})
! These functions return the remainder of the unsigned division of @var{a}
! and @var{b}.
! @end deftypefn
!
! @subsection Comparison functions
!
! The following functions implement integral comparisons. These functions
! implement a low-level compare, upon which the higher level comparison
! operators (such as less than and greater than or equal to) can be
! constructed. The returned values lie in the range zero to two, to allow
! the high-level operators to be implemented by testing the returned
! result using either signed or unsigned comparison.
!
! @deftypefn {Runtime Function} int __cmpdi2 (long @var{a}, long @var{b})
! @deftypefnx {Runtime Function} int __cmpti2 (long long @var{a}, long long @var{b})
! These functions perform a signed comparison of @var{a} and @var{b}. If
! @var{a} is less than @var{b}, they return 0; if @var{a} is greater than
! @var{b}, they return 2; and if @var{a} and @var{b} are equal they return 1.
! @end deftypefn
!
! @deftypefn {Runtime Function} int __ucmpdi2 (unsigned long @var{a}, unsigned long @var{b})
! @deftypefnx {Runtime Function} int __ucmpti2 (unsigned long long @var{a}, unsigned long long @var{b})
! These functions perform an unsigned comparison of @var{a} and @var{b}.
! If @var{a} is less than @var{b}, they return 0; if @var{a} is greater than
! @var{b}, they return 2; and if @var{a} and @var{b} are equal they return 1.
! @end deftypefn
!
! @subsection Trapping arithmetic functions
!
! The following functions implement trapping arithmetic. These functions
! call the libc function @code{abort} upon signed arithmetic overflow.
!
! @deftypefn {Runtime Function} int __absvsi2 (int @var{a})
! @deftypefnx {Runtime Function} long __absvdi2 (long @var{a})
! These functions return the absolute value of @var{a}.
! @end deftypefn
!
! @deftypefn {Runtime Function} int __addvsi3 (int @var{a}, int @var{b})
! @deftypefnx {Runtime Function} long __addvdi3 (long @var{a}, long @var{b})
! These functions return the sum of @var{a} and @var{b}; that is
! @code{@var{a} + @var{b}}.
! @end deftypefn
!
! @deftypefn {Runtime Function} int __mulvsi3 (int @var{a}, int @var{b})
! @deftypefnx {Runtime Function} long __mulvdi3 (long @var{a}, long @var{b})
! The functions return the product of @var{a} and @var{b}; that is
! @code{@var{a} * @var{b}}.
! @end deftypefn
!
! @deftypefn {Runtime Function} int __negvsi2 (int @var{a})
! @deftypefnx {Runtime Function} long __negvdi2 (long @var{a})
! These functions return the negation of @var{a}; that is @code{-@var{a}}.
! @end deftypefn
+ @deftypefn {Runtime Function} int __subvsi3 (int @var{a}, int @var{b})
+ @deftypefnx {Runtime Function} long __subvdi3 (long @var{a}, long @var{b})
+ These functions return the difference between @var{b} and @var{a};
+ that is @code{@var{a} - @var{b}}.
+ @end deftypefn
+
+ @subsection Bit operations
+
+ @deftypefn {Runtime Function} int __clzsi2 (int @var{a})
+ @deftypefnx {Runtime Function} int __clzdi2 (long @var{a})
+ @deftypefnx {Runtime Function} int __clzti2 (long long @var{a})
+ These functions return the number of leading 0-bits in @var{a}, starting
+ at the most significant bit position. If @var{a} is zero, the result is
+ undefined.
+ @end deftypefn
+
+ @deftypefn {Runtime Function} int __ctzsi2 (int @var{a})
+ @deftypefnx {Runtime Function} int __ctzdi2 (long @var{a})
+ @deftypefnx {Runtime Function} int __ctzti2 (long long @var{a})
+ These functions return the number of trailing 0-bits in @var{a}, starting
+ at the least significant bit position. If @var{a} is zero, the result is
+ undefined.
+ @end deftypefn
+
+ @deftypefn {Runtime Function} int __ffsdi2 (long @var{a})
+ @deftypefnx {Runtime Function} int __ffsti2 (long long @var{a})
+ These functions return the index of the least significant 1-bit in @var{a},
+ or the value zero if @var{a} is zero. The least significant bit is index
+ one.
+ @end deftypefn
+
+ @deftypefn {Runtime Function} int __paritysi2 (int @var{a})
+ @deftypefnx {Runtime Function} int __paritydi2 (long @var{a})
+ @deftypefnx {Runtime Function} int __parityti2 (long long @var{a})
+ These functions return the value zero if the number of bits set in
+ @var{a} is even, and the value one otherwise.
+ @end deftypefn
+
+ @deftypefn {Runtime Function} int __popcountsi2 (int @var{a})
+ @deftypefnx {Runtime Function} int __popcountdi2 (long @var{a})
+ @deftypefnx {Runtime Function} int __popcountti2 (long long @var{a})
+ These functions return the number of bits set in @var{a}.
+ @end deftypefn
@node Soft float library routines
@section Routines for floating point emulation
*************** For compatibility with other compilers,
*** 145,158 ****
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.
--- 227,232 ----
*************** for @code{long double} on some architect
*** 161,172 ****
--- 235,248 ----
@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})
+ @deftypefnx {Runtime Function} {long double} __addxf3 (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})
+ @deftypefnx {Runtime Function} {long double} __subxf3 (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
*************** that is, @w{@math{@var{a} - @var{b}}}.
*** 174,185 ****
--- 250,263 ----
@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})
+ @deftypefnx {Runtime Function} {long double} __mulxf3 (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})
+ @deftypefnx {Runtime Function} {long double} __divxf3 (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
*************** These functions return the quotient of @
*** 187,192 ****
--- 265,271 ----
@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})
+ @deftypefnx {Runtime Function} {long double} __negxf2 (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
*************** sign bit, so they can produce negative z
*** 195,206 ****
@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
--- 274,289 ----
@deftypefn {Runtime Function} double __extendsfdf2 (float @var{a})
@deftypefnx {Runtime Function} {long double} __extendsftf2 (float @var{a})
+ @deftypefnx {Runtime Function} {long double} __extendsfxf2 (float @var{a})
@deftypefnx {Runtime Function} {long double} __extenddftf2 (double @var{a})
+ @deftypefnx {Runtime Function} {long double} __extenddfxf2 (double @var{a})
These functions extend @var{a} to the wider mode of their return
type.
@end deftypefn
! @deftypefn {Runtime Function} double __truncxfdf2 (long double @var{a})
! @deftypefnx {Runtime Function} double __trunctfdf2 (long double @var{a})
! @deftypefnx {Runtime Function} float __truncxfsf2 (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.
*** 210,242 ****
@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
--- 293,360 ----
@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})
+ @deftypefnx {Runtime Function} int __fixxfsi (long double @var{a})
These functions convert @var{a} to a signed integer, rounding toward zero.
@end deftypefn
+ @deftypefn {Runtime Function} long __fixsfdi (float @var{a})
+ @deftypefnx {Runtime Function} long __fixdfdi (double @var{a})
+ @deftypefnx {Runtime Function} long __fixtfdi (long double @var{a})
+ @deftypefnx {Runtime Function} long __fixxfdi (long double @var{a})
+ These functions convert @var{a} to a signed long, rounding toward zero.
+ @end deftypefn
+
+ @deftypefn {Runtime Function} {long long} __fixsfti (float @var{a})
+ @deftypefnx {Runtime Function} {long long} __fixdfti (double @var{a})
+ @deftypefnx {Runtime Function} {long long} __fixtfti (long double @var{a})
+ @deftypefnx {Runtime Function} {long long} __fixxfti (long double @var{a})
+ These functions convert @var{a} to a signed long long, 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})
+ @deftypefnx {Runtime Function} {unsigned int} __fixunsxfsi (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} {unsigned long} __fixunssfdi (float @var{a})
+ @deftypefnx {Runtime Function} {unsigned long} __fixunsdfdi (double @var{a})
+ @deftypefnx {Runtime Function} {unsigned long} __fixunstfdi (long double @var{a})
+ @deftypefnx {Runtime Function} {unsigned long} __fixunsxfdi (long double @var{a})
+ These functions convert @var{a} to an unsigned long, rounding
+ toward zero. Negative values all become zero.
+ @end deftypefn
+
+ @deftypefn {Runtime Function} {unsigned long long} __fixunssfti (float @var{a})
+ @deftypefnx {Runtime Function} {unsigned long long} __fixunsdfti (double @var{a})
+ @deftypefnx {Runtime Function} {unsigned long long} __fixunstfti (long double @var{a})
+ @deftypefnx {Runtime Function} {unsigned long long} __fixunsxfti (long double @var{a})
+ These functions convert @var{a} to an unsigned long long, 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})
+ @deftypefnx {Runtime Function} {long double} __floatsixf (int @var{i})
These functions convert @var{i}, a signed integer, to floating point.
@end deftypefn
! @deftypefn {Runtime Function} float __floatdisf (long @var{i})
! @deftypefnx {Runtime Function} double __floatdidf (long @var{i})
! @deftypefnx {Runtime Function} {long double} __floatditf (long @var{i})
! @deftypefnx {Runtime Function} {long double} __floatdixf (long @var{i})
! These functions convert @var{i}, a signed long, to floating point.
@end deftypefn
! @deftypefn {Runtime Function} float __floattisf (long long @var{i})
! @deftypefnx {Runtime Function} double __floattidf (long long @var{i})
! @deftypefnx {Runtime Function} {long double} __floattitf (long long @var{i})
! @deftypefnx {Runtime Function} {long double} __floattixf (long long @var{i})
! These functions convert @var{i}, a signed long long, to floating point.
! @end deftypefn
@subsection Comparison functions
*************** document me!
*** 359,368 ****
@node Miscellaneous routines
@section Miscellaneous runtime library routines
! document me!
!
! @example
! __clear_cache
! @end example
- any others?
--- 477,484 ----
@node Miscellaneous routines
@section Miscellaneous runtime library routines
! @subsection Cache control functions
! @deftypefn {Runtime Function} void __clear_cache (char *@var{beg}, char *@var{end})
! This function clears the instruction cache between @var{beg} and @var{end}.
! @end deftypefn
