From ef7722f02820d23b3c280fc4a17b2bd862ac67a2 Mon Sep 17 00:00:00 2001 From: sayle Date: Fri, 24 Oct 2003 14:15:45 +0000 Subject: [PATCH] * doc/libgcc.texi: Document some more of the libgcc API. git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@72894 138bc75d-0d04-0410-961f-82ee72b054a4 --- gcc/ChangeLog | 4 + gcc/doc/libgcc.texi | 344 +++++++++++++++++++++++++++++++++++----------------- 2 files changed, 234 insertions(+), 114 deletions(-) diff --git a/gcc/ChangeLog b/gcc/ChangeLog index 6330e5c..45b9fa4 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,7 @@ +2003-10-24 Roger Sayle + + * doc/libgcc.texi: Document some more of the libgcc API. + 2003-10-24 Richard Earnshaw * arm.c (arm_rtx_costs_1, case TARGET_THUMB): Adjust costs for diff --git a/gcc/doc/libgcc.texi b/gcc/doc/libgcc.texi index bbad88d..af6f7be 100644 --- a/gcc/doc/libgcc.texi +++ b/gcc/doc/libgcc.texi @@ -26,6 +26,16 @@ GCC will also generate calls to C library routines, such as 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:: @@ -36,98 +46,170 @@ Builtins,,,gcc, Using the GNU Compiler Collection (GCC)}. @node Integer library routines @section Routines for integer arithmetic -document me! +The integer arithmetic routines are used on platforms that don't provide +hardware support for arithmetic operations on some modes. -@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 +@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 @@ -145,14 +227,6 @@ 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. @@ -161,12 +235,14 @@ for @code{long double} on some architectures. @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 @@ -174,12 +250,14 @@ that is, @w{@math{@var{a} - @var{b}}}. @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 @@ -187,6 +265,7 @@ These functions return the quotient of @var{a} and @var{b}; that is, @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 @@ -195,12 +274,16 @@ sign bit, so they can produce negative zero and negative NaN. @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 __trunctfdf2 (long double @var{a}) +@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 @@ -210,33 +293,68 @@ type, rounding toward zero. @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 __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. +@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 -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. +@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 @@ -359,10 +477,8 @@ document me! @node Miscellaneous routines @section Miscellaneous runtime library routines -document me! - -@example - __clear_cache -@end example +@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 -any others? -- 2.7.4