patch: docs for soft float routines

patch: docs for soft float routines

[Aldy Hernandez]

This patch documents libgcc's soft-float routines.  The API has been 
around forever, no harm in documenting it ;-).

OK for mainline?

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

	* Makefile.in (TEXI_GCCINT_FILES): Add softfloat.texi.

	* doc/softfloat.texi: New file.

	* doc/interface.texi (Interface): Add menu for soft float routines.
	(Interface): Include softfloat.texi.

Index: Makefile.in
===================================================================
RCS file: /cvs/gcc/gcc/gcc/Makefile.in,v
retrieving revision 1.1004
diff -c -p -r1.1004 Makefile.in
*** Makefile.in	26 Feb 2003 11:09:29 -0000	1.1004
--- Makefile.in	4 Mar 2003 02:28:58 -0000
*************** TEXI_GCCINT_FILES = $(docdir)/gccint.tex
*** 2584,2590 ****
   	 $(docdir)/gnu.texi $(docdir)/include/gpl.texi \
   	 $(docdir)/include/fdl.texi $(docdir)/contrib.texi \
   	 $(docdir)/languages.texi $(docdir)/sourcebuild.texi \
! 	 $(docdir)/gty.texi

   TEXI_GCCINSTALL_FILES = $(docdir)/install.texi 
$(docdir)/install-old.texi \
   	 $(docdir)/include/fdl.texi
--- 2584,2590 ----
   	 $(docdir)/gnu.texi $(docdir)/include/gpl.texi \
   	 $(docdir)/include/fdl.texi $(docdir)/contrib.texi \
   	 $(docdir)/languages.texi $(docdir)/sourcebuild.texi \
! 	 $(docdir)/gty.texi $(docdir)/softfloat.texi

   TEXI_GCCINSTALL_FILES = $(docdir)/install.texi 
$(docdir)/install-old.texi \
   	 $(docdir)/include/fdl.texi
Index: doc/softfloat.texi
===================================================================
RCS file: doc/softfloat.texi
diff -N doc/softfloat.texi
*** /dev/null	1 Jan 1970 00:00:00 -0000
--- doc/softfloat.texi	4 Mar 2003 02:28:58 -0000
***************
*** 0 ****
--- 1,187 ----
+ @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 Soft float library routines
+ @section Supporting soft floating point library routines
+ @cindex soft library
+ @opindex msoft-float
+
+ Code compiled with GCC may call certain library routines.  Most of
+ them handle arithmetic for which there are no machine instructions.
+ This includes floating point operations for which floating point
+ support is disabled with @option{-msoft-float}.  This section
+ documents the floating point subset of these routines.
+
+ This document assumes @code{float} is a floating point of
+ @code{SF} mode, @code{double} is a floating point of @code{DF}
+ mode, @code{long double} is a floating point of @code{TF} mode,
+ and @code{int} is an integer of @code{SI} mode.
+
+ These functions return the sum of their two arguments.
+
+ @smallexample
+ double __adddf3 (double, double);
+ float __addsf3 (float, float);
+ long double __addtf3 (long double, long double);
+ @end smallexample
+
+ Given two arguments (a and b), these functions compare the two
+ arguments.  If @code{a} is less than @code{b}, the function returns
+ -1.  If @code{a} is greater than @code{b}, the function returns 1.  If
+ @code{a} is equal to @code{b}, the function returns 0.  If either
+ argument is a NAN, the function returns 1.
+
+ @smallexample
+ int __cmpdf2 (double, double);
+ int __cmpsf2 (float, float);
+ int __cmptf2 (long double, long double);
+ @end smallexample
+
+ These functions return the result of dividing the first argument by
+ the second argument.
+
+ @smallexample
+ double __divdf3 (double, double);
+ float __divsf3 (float, float);
+ long double __divtf3 (long double, long double);
+ @end smallexample
+
+ These functions return 0 if their arguments are equal to each other,
+ otherwise a non-zero is returned.  If either argument is a NAN, 1 is
+ return.
+
+ @smallexample
+ int __eqdf2 (double, double);
+ int __eqsf2 (float, float);
+ int __eqtf2 (long double, long double);
+ @end smallexample
+
+ These functions extend their argument to @code{double} and
+ @code{long double} respectively.
+
+ @smallexample
+ double __extendsfdf2 (float);
+ long double __extendsftf2 (float);
+ @end smallexample
+
+ These functions return the result of converting its floating point
+ argument to an integer, still represented in floating point mode, by
+ rounding towards zero.
+
+ @smallexample
+ int __fixdfsi (double);
+ int __fixsfsi (float);
+ int __fixtfsi (long double);
+ @end smallexample
+
+ These functions represent the result of converting its fixed point
+ argument, regarded as signed, to a floating point value.
+
+ @smallexample
+ double __floatsidf (int);
+ float __floatsisf (int);
+ long double __floatsitf (int);
+ @end smallexample
+
+ The same as above, but the argument is regarded as unsigned.
+
+ @smallexample
+ double __floatunsidf (unsigned int);
+ float __floatunsisf (unsigned int);
+ long double __floatunsitf (int);
+ @end smallexample
+
+ These functions return 1 if the first argument is greater or equal
+ than the second argument, or if either argument is a NAN.  Otherwise,
+ 0 is returned.
+
+ @smallexample
+ int __gedf2 (double, double);
+ int __gesf2 (float, float);
+ int __getf2 (long double, long double);
+ @end smallexample
+
+ These functions return 1 if the first argument is less than or equal
+ to the second argument, or if either argument is a NAN.  Otherwise, 0
+ is returned.
+
+ @smallexample
+ int __ledf2 (double, double);
+ int __lesf2 (float, float);
+ int __letf2 (long double, long double);
+ @end smallexample
+
+ These functions return 1 if the first argument is less than the second
+ argument, or if either argument is a NAN.  Otherwise, 0 is returned.
+
+ @smallexample
+ int __ltdf2 (double, double);
+ int __ltsf2 (float, float);
+ int __lttf2 (long double, long double);
+ @end smallexample
+
+ These functions return the result of multiplying their arguments.
+
+ @smallexample
+ double __muldf3 (double, double);
+ float __mulsf3 (float, float);
+ long double __multf3 (long double, long double);
+ @end smallexample
+
+ These functions return 1 if the first argument is not equal to the
+ second argument, or if either argument is a NAN.  Otherwise, 0 is
+ returned.
+
+ @smallexample
+ int __nedf2 (double, double);
+ int __nesf2 (float, float);
+ int __netf2 (long double, long double);
+ @end smallexample
+
+ These functions return the result of negating its argument.
+
+ @smallexample
+ long double __negtf2 (long double);
+ double __negdf2 (double);
+ float __negsf2 (float);
+ @end smallexample
+
+ These functions return the result of subtracting the second argument
+ from the first.
+
+ @smallexample
+ double __subdf3 (double, double);
+ float __subsf3 (float, float);
+ long double __subtf3 (long double, long double);
+ @end smallexample
+
+ These function return the result of truncating the floating argument
+ to the mode indicated by its return type.
+
+ @smallexample
+ float __truncdfsf2 (double);
+ double __trunctfdf2 (long double);
+ float __trunctfsf2 (long double);
+ @end smallexample
+
+ These functions return 1 if either argument is a NAN, otherwise 0 is
+ returned.
+
+ @smallexample
+ int __unorddf2 (double, double);
+ int __unordsf2 (float, float);
+ int __unordtf2 (long double, long double);
+ @end smallexample
+
+ These functions represent the result of converting its floating point
+ argument ot a fixed point value, regarded as unsigned.  How rounding
+ is done is not specified.
+
+ @smallexample
+ unsigned int __fixunsdfsi (double);
+ unsigned int __fixunssfsi (float);
+ unsigned int __fixunstfsi (long double);
+
+ @end smallexample
Index: doc/interface.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/interface.texi,v
retrieving revision 1.2
diff -c -p -r1.2 interface.texi
*** doc/interface.texi	15 Sep 2002 22:48:04 -0000	1.2
--- doc/interface.texi	4 Mar 2003 02:28:58 -0000
*************** they appear in @file{libgcc2.c}.  Others
*** 100,102 ****
--- 100,108 ----
   assembly language for each processor.  Wherever they are defined, they
   are compiled into the support library, @file{libgcc.a}, which is
   automatically searched when you link programs with GCC@.
+
+ @menu
+ * Soft float library routines:: Supporting floating point routines.
+ @end menu
+
+ @include softfloat.texi

Re: patch: docs for soft float routines

[Hans-Peter Nilsson]

On Mon, 3 Mar 2003, Aldy Hernandez wrote:

> This patch documents libgcc's soft-float routines.  The API has been
> around forever, no harm in documenting it ;-).
>
> OK for mainline?

You don't mention that these are just default names; that the
actual names depend on target macros (DECLARE_LIBRARY_RENAMES).

brgds, H-P

Re: patch: docs for soft float routines

[Aldy Hernandez]

On Sun, Mar 09, 2003 at 11:59:17AM -0500, Hans-Peter Nilsson wrote:
> On Mon, 3 Mar 2003, Aldy Hernandez wrote:
> 
> > This patch documents libgcc's soft-float routines.  The API has been
> > around forever, no harm in documenting it ;-).
> >
> > OK for mainline?
> 
> You don't mention that these are just default names; that the
> actual names depend on target macros (DECLARE_LIBRARY_RENAMES).

Done.

Tested on powerpc-darwin with make doc.

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

	* Makefile.in (TEXI_GCCINT_FILES): Add softfloat.texi.

	* doc/softfloat.texi: New file.

	* doc/interface.texi (Interface): Add menu for soft float routines.
	(Interface): Include softfloat.texi.

Index: Makefile.in
===================================================================
RCS file: /cvs/gcc/gcc/gcc/Makefile.in,v
retrieving revision 1.1009
diff -c -p -r1.1009 Makefile.in
*** Makefile.in	5 Mar 2003 22:19:30 -0000	1.1009
--- Makefile.in	10 Mar 2003 19:01:41 -0000
*************** TEXI_GCCINT_FILES = $(docdir)/gccint.tex
*** 2589,2595 ****
  	 $(docdir)/gnu.texi $(docdir)/include/gpl.texi \
  	 $(docdir)/include/fdl.texi $(docdir)/contrib.texi \
  	 $(docdir)/languages.texi $(docdir)/sourcebuild.texi \
! 	 $(docdir)/gty.texi
  
  TEXI_GCCINSTALL_FILES = $(docdir)/install.texi $(docdir)/install-old.texi \
  	 $(docdir)/include/fdl.texi
--- 2589,2595 ----
  	 $(docdir)/gnu.texi $(docdir)/include/gpl.texi \
  	 $(docdir)/include/fdl.texi $(docdir)/contrib.texi \
  	 $(docdir)/languages.texi $(docdir)/sourcebuild.texi \
! 	 $(docdir)/gty.texi $(docdir)/softfloat.texi
  
  TEXI_GCCINSTALL_FILES = $(docdir)/install.texi $(docdir)/install-old.texi \
  	 $(docdir)/include/fdl.texi
Index: doc/softfloat.texi
===================================================================
RCS file: doc/softfloat.texi
diff -N doc/softfloat.texi
*** /dev/null	1 Jan 1970 00:00:00 -0000
--- doc/softfloat.texi	10 Mar 2003 19:01:41 -0000
***************
*** 0 ****
--- 1,191 ----
+ @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 Soft float library routines
+ @section Supporting soft floating point library routines
+ @cindex soft library
+ @opindex msoft-float
+ 
+ Code compiled with GCC may call certain library routines.  Most of
+ them handle arithmetic for which there are no machine instructions.
+ This includes floating point operations for which floating point
+ support is disabled with @option{-msoft-float}.  This section
+ documents the floating point subset of these routines.
+ 
+ This section documents these functions using their default library
+ names.  These names can be renamed by defining the macro
+ @code{DECLARE_LIBARRY_RENAMES} in @file{libgcc2.c}.
+ 
+ This document assumes @code{float} is a floating point of
+ @code{SF} mode, @code{double} is a floating point of @code{DF}
+ mode, @code{long double} is a floating point of @code{TF} mode,
+ and @code{int} is an integer of @code{SI} mode.
+ 
+ These functions return the sum of their two arguments.
+ 
+ @smallexample
+ double __adddf3 (double, double);
+ float __addsf3 (float, float);
+ long double __addtf3 (long double, long double);
+ @end smallexample
+ 
+ Given two arguments (a and b), these functions compare the two
+ arguments.  If @code{a} is less than @code{b}, the function returns
+ -1.  If @code{a} is greater than @code{b}, the function returns 1.  If
+ @code{a} is equal to @code{b}, the function returns 0.  If either
+ argument is a NAN, the function returns 1.
+ 
+ @smallexample
+ int __cmpdf2 (double, double);
+ int __cmpsf2 (float, float);
+ int __cmptf2 (long double, long double);
+ @end smallexample
+ 
+ These functions return the result of dividing the first argument by
+ the second argument.
+ 
+ @smallexample
+ double __divdf3 (double, double);
+ float __divsf3 (float, float);
+ long double __divtf3 (long double, long double);
+ @end smallexample
+ 
+ These functions return 0 if their arguments are equal to each other,
+ otherwise a non-zero is returned.  If either argument is a NAN, 1 is
+ return.
+ 
+ @smallexample
+ int __eqdf2 (double, double);
+ int __eqsf2 (float, float);
+ int __eqtf2 (long double, long double);
+ @end smallexample
+ 
+ These functions extend their argument to @code{double} and
+ @code{long double} respectively.
+ 
+ @smallexample
+ double __extendsfdf2 (float);
+ long double __extendsftf2 (float);
+ @end smallexample
+ 
+ These functions return the result of converting its floating point
+ argument to an integer, still represented in floating point mode, by
+ rounding towards zero.
+ 
+ @smallexample
+ int __fixdfsi (double);
+ int __fixsfsi (float);
+ int __fixtfsi (long double);
+ @end smallexample
+ 
+ These functions represent the result of converting its fixed point
+ argument, regarded as signed, to a floating point value.
+ 
+ @smallexample
+ double __floatsidf (int);
+ float __floatsisf (int);
+ long double __floatsitf (int);
+ @end smallexample
+ 
+ The same as above, but the argument is regarded as unsigned.
+ 
+ @smallexample
+ double __floatunsidf (unsigned int);
+ float __floatunsisf (unsigned int);
+ long double __floatunsitf (int);
+ @end smallexample
+ 
+ These functions return 1 if the first argument is greater or equal
+ than the second argument, or if either argument is a NAN.  Otherwise,
+ 0 is returned.
+ 
+ @smallexample
+ int __gedf2 (double, double);
+ int __gesf2 (float, float);
+ int __getf2 (long double, long double);
+ @end smallexample
+ 
+ These functions return 1 if the first argument is less than or equal
+ to the second argument, or if either argument is a NAN.  Otherwise, 0
+ is returned.
+ 
+ @smallexample
+ int __ledf2 (double, double);
+ int __lesf2 (float, float);
+ int __letf2 (long double, long double);
+ @end smallexample
+ 
+ These functions return 1 if the first argument is less than the second
+ argument, or if either argument is a NAN.  Otherwise, 0 is returned.
+ 
+ @smallexample
+ int __ltdf2 (double, double);
+ int __ltsf2 (float, float);
+ int __lttf2 (long double, long double);
+ @end smallexample
+ 
+ These functions return the result of multiplying their arguments.
+ 
+ @smallexample
+ double __muldf3 (double, double);
+ float __mulsf3 (float, float);
+ long double __multf3 (long double, long double);
+ @end smallexample
+ 
+ These functions return 1 if the first argument is not equal to the
+ second argument, or if either argument is a NAN.  Otherwise, 0 is
+ returned.
+ 
+ @smallexample
+ int __nedf2 (double, double);
+ int __nesf2 (float, float);
+ int __netf2 (long double, long double);
+ @end smallexample
+ 
+ These functions return the result of negating its argument.
+ 
+ @smallexample
+ long double __negtf2 (long double);
+ double __negdf2 (double);
+ float __negsf2 (float);
+ @end smallexample
+ 
+ These functions return the result of subtracting the second argument
+ from the first.
+ 
+ @smallexample
+ double __subdf3 (double, double);
+ float __subsf3 (float, float);
+ long double __subtf3 (long double, long double);
+ @end smallexample
+ 
+ These function return the result of truncating the floating argument
+ to the mode indicated by its return type.
+ 
+ @smallexample
+ float __truncdfsf2 (double);
+ double __trunctfdf2 (long double);
+ float __trunctfsf2 (long double);
+ @end smallexample
+ 
+ These functions return 1 if either argument is a NAN, otherwise 0 is
+ returned.
+ 
+ @smallexample
+ int __unorddf2 (double, double);
+ int __unordsf2 (float, float);
+ int __unordtf2 (long double, long double);
+ @end smallexample
+ 
+ These functions represent the result of converting its floating point
+ argument ot a fixed point value, regarded as unsigned.  How rounding
+ is done is not specified.
+ 
+ @smallexample
+ unsigned int __fixunsdfsi (double);
+ unsigned int __fixunssfsi (float);
+ unsigned int __fixunstfsi (long double);
+ 
+ @end smallexample
Index: doc/interface.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/interface.texi,v
retrieving revision 1.2
diff -c -p -r1.2 interface.texi
*** doc/interface.texi	15 Sep 2002 22:48:04 -0000	1.2
--- doc/interface.texi	10 Mar 2003 19:01:41 -0000
*************** they appear in @file{libgcc2.c}.  Others
*** 100,102 ****
--- 100,108 ----
  assembly language for each processor.  Wherever they are defined, they
  are compiled into the support library, @file{libgcc.a}, which is
  automatically searched when you link programs with GCC@.
+ 
+ @menu
+ * Soft float library routines:: Supporting floating point routines.
+ @end menu
+ 
+ @include softfloat.texi

Re: patch: docs for soft float routines

[Richard Henderson]

On Mon, Mar 10, 2003 at 11:03:01AM -0800, Aldy Hernandez wrote:
> + Given two arguments (a and b), these functions compare the two
> + arguments.  If @code{a} is less than @code{b}, the function returns
> + -1.  If @code{a} is greater than @code{b}, the function returns 1.  If
> + @code{a} is equal to @code{b}, the function returns 0.  If either
> + argument is a NAN, the function returns 1.
> + 
> + @smallexample
> + int __cmpdf2 (double, double);
> + int __cmpsf2 (float, float);
> + int __cmptf2 (long double, long double);
> + @end smallexample

> + These functions return the result of converting its floating point
> + argument to an integer, still represented in floating point mode, by
> + rounding towards zero.
> + 
> + @smallexample
> + int __fixdfsi (double);

Um, in what way is the result "still represented in floating point mode"?

> + long double __floatunsitf (int);

Typo: "unsigned".

> + These functions return 1 if the first argument is greater or equal
> + than the second argument, or if either argument is a NAN.  Otherwise,
> + 0 is returned.
> + 
> + @smallexample
> + int __gedf2 (double, double);

Incorrect.  We *don't* return 1 for NaN here, since test for truth
is __gedf2(x,y) >= 0.  We return -1 for NaN.  Similarly for __gt.

> + These functions represent the result of converting its floating point
> + argument ot a fixed point value, regarded as unsigned.  How rounding
> + is done is not specified.
> + 
> + @smallexample
> + unsigned int __fixunsdfsi (double);

I'm pretty sure we expect crop to zero here, not "unspecified".




r~

Re: patch: docs for soft float routines

[Aldy Hernandez]

>> + These functions return the result of converting its floating point
>> + argument to an integer, still represented in floating point mode, by
>> + rounding towards zero.
>> +
>> + @smallexample
>> + int __fixdfsi (double);
>
> Um, in what way is the result "still represented in floating point 
> mode"?

I was just quoting the docs, perhaps:

<<These functions return the result of converting its floating point
argument to an integer, represented as a fixed point float.  Any
rounding done is rounding towards zero.>>

...which I think is what this means (?):

   tmp = a.fraction.ll >> ((FRACBITS + NGARDS) - a.normal_exp);
   return a.sign ? (-tmp) : (tmp);

>> + long double __floatunsitf (int);
>
> Typo: "unsigned".

Fixed.

>
>> + These functions return 1 if the first argument is greater or equal
>> + than the second argument, or if either argument is a NAN.  
>> Otherwise,
>> + 0 is returned.
>> +
>> + @smallexample
>> + int __gedf2 (double, double);
>
> Incorrect.  We *don't* return 1 for NaN here, since test for truth
> is __gedf2(x,y) >= 0.  We return -1 for NaN.  Similarly for __gt.

Fixed.

>
>> + These functions represent the result of converting its floating 
>> point
>> + argument ot a fixed point value, regarded as unsigned.  How rounding
>> + is done is not specified.
>> +
>> + @smallexample
>> + unsigned int __fixunsdfsi (double);
>
> I'm pretty sure we expect crop to zero here, not "unspecified".

You're right.  It's round to zero in the fp-bit library, but the 
documentation for (fix:M N) and (unsigned_fix:M N) in rtl.texi 
specifies that rounding is unspecified.  Should we be as generous when 
documenting the FP library API, or should we explicitly state 
round-to-zero rounding?

Next version:

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

	* Makefile.in (TEXI_GCCINT_FILES): Add softfloat.texi.

	* doc/softfloat.texi: New file.

	* doc/interface.texi (Interface): Add menu for soft float routines.
	(Interface): Include softfloat.texi.

Index: Makefile.in
===================================================================
RCS file: /cvs/gcc/gcc/gcc/Makefile.in,v
retrieving revision 1.1009
diff -c -p -r1.1009 Makefile.in
*** Makefile.in	5 Mar 2003 22:19:30 -0000	1.1009
--- Makefile.in	11 Mar 2003 16:18:40 -0000
*************** TEXI_GCCINT_FILES = $(docdir)/gccint.tex
*** 2589,2595 ****
   	 $(docdir)/gnu.texi $(docdir)/include/gpl.texi \
   	 $(docdir)/include/fdl.texi $(docdir)/contrib.texi \
   	 $(docdir)/languages.texi $(docdir)/sourcebuild.texi \
! 	 $(docdir)/gty.texi

   TEXI_GCCINSTALL_FILES = $(docdir)/install.texi 
$(docdir)/install-old.texi \
   	 $(docdir)/include/fdl.texi
--- 2589,2595 ----
   	 $(docdir)/gnu.texi $(docdir)/include/gpl.texi \
   	 $(docdir)/include/fdl.texi $(docdir)/contrib.texi \
   	 $(docdir)/languages.texi $(docdir)/sourcebuild.texi \
! 	 $(docdir)/gty.texi $(docdir)/softfloat.texi

   TEXI_GCCINSTALL_FILES = $(docdir)/install.texi 
$(docdir)/install-old.texi \
   	 $(docdir)/include/fdl.texi
Index: doc/softfloat.texi
===================================================================
RCS file: doc/softfloat.texi
diff -N doc/softfloat.texi
*** /dev/null	1 Jan 1970 00:00:00 -0000
--- doc/softfloat.texi	11 Mar 2003 16:18:41 -0000
***************
*** 0 ****
--- 1,190 ----
+ @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 Soft float library routines
+ @section Supporting soft floating point library routines
+ @cindex soft library
+ @opindex msoft-float
+
+ Code compiled with GCC may call certain library routines.  Most of
+ them handle arithmetic for which there are no machine instructions.
+ This includes floating point operations for which floating point
+ support is disabled with @option{-msoft-float}.  This section
+ documents the floating point subset of these routines.
+
+ This section documents these functions using their default library
+ names.  These names can be renamed by defining the macro
+ @code{DECLARE_LIBARRY_RENAMES} in @file{libgcc2.c}.
+
+ This document assumes @code{float} is a floating point of
+ @code{SF} mode, @code{double} is a floating point of @code{DF}
+ mode, @code{long double} is a floating point of @code{TF} mode,
+ and @code{int} is an integer of @code{SI} mode.
+
+ These functions return the sum of their two arguments.
+
+ @smallexample
+ double __adddf3 (double, double);
+ float __addsf3 (float, float);
+ long double __addtf3 (long double, long double);
+ @end smallexample
+
+ Given two arguments (a and b), these functions compare the two
+ arguments.  If @code{a} is less than @code{b}, the function returns
+ -1.  If @code{a} is greater than @code{b}, the function returns 1.  If
+ @code{a} is equal to @code{b}, the function returns 0.  If either
+ argument is a NAN, the function returns 1.
+
+ @smallexample
+ int __cmpdf2 (double, double);
+ int __cmpsf2 (float, float);
+ int __cmptf2 (long double, long double);
+ @end smallexample
+
+ These functions return the result of dividing the first argument by
+ the second argument.
+
+ @smallexample
+ double __divdf3 (double, double);
+ float __divsf3 (float, float);
+ long double __divtf3 (long double, long double);
+ @end smallexample
+
+ These functions return 0 if their arguments are equal to each other,
+ otherwise a non-zero is returned.  If either argument is a NAN, 1 is
+ return.
+
+ @smallexample
+ int __eqdf2 (double, double);
+ int __eqsf2 (float, float);
+ int __eqtf2 (long double, long double);
+ @end smallexample
+
+ These functions extend their argument to @code{double} and
+ @code{long double} respectively.
+
+ @smallexample
+ double __extendsfdf2 (float);
+ long double __extendsftf2 (float);
+ @end smallexample
+
+ These functions return the result of converting its floating point
+ argument to an integer, represented as a fixed point float.  Any
+ rounding done is rounding towards zero.
+
+ @smallexample
+ int __fixdfsi (double);
+ int __fixsfsi (float);
+ int __fixtfsi (long double);
+ @end smallexample
+
+ These functions represent the result of converting its fixed point
+ argument, regarded as signed, to a floating point value.
+
+ @smallexample
+ double __floatsidf (int);
+ float __floatsisf (int);
+ long double __floatsitf (int);
+ @end smallexample
+
+ The same as above, but the argument is regarded as unsigned.
+
+ @smallexample
+ double __floatunsidf (unsigned int);
+ float __floatunsisf (unsigned int);
+ long double __floatunsitf (unsigned int);
+ @end smallexample
+
+ These functions return 1 if the first argument is greater or equal
+ than the second argument, and -1 for a NAN.  Otherwise, 0 is returned.
+
+ @smallexample
+ int __gedf2 (double, double);
+ int __gesf2 (float, float);
+ int __getf2 (long double, long double);
+ @end smallexample
+
+ These functions return 1 if the first argument is less than or equal
+ to the second argument, or if either argument is a NAN.  Otherwise, 0
+ is returned.
+
+ @smallexample
+ int __ledf2 (double, double);
+ int __lesf2 (float, float);
+ int __letf2 (long double, long double);
+ @end smallexample
+
+ These functions return 1 if the first argument is less than the second
+ argument, or if either argument is a NAN.  Otherwise, 0 is returned.
+
+ @smallexample
+ int __ltdf2 (double, double);
+ int __ltsf2 (float, float);
+ int __lttf2 (long double, long double);
+ @end smallexample
+
+ These functions return the result of multiplying their arguments.
+
+ @smallexample
+ double __muldf3 (double, double);
+ float __mulsf3 (float, float);
+ long double __multf3 (long double, long double);
+ @end smallexample
+
+ These functions return 1 if the first argument is not equal to the
+ second argument, or if either argument is a NAN.  Otherwise, 0 is
+ returned.
+
+ @smallexample
+ int __nedf2 (double, double);
+ int __nesf2 (float, float);
+ int __netf2 (long double, long double);
+ @end smallexample
+
+ These functions return the result of negating its argument.
+
+ @smallexample
+ long double __negtf2 (long double);
+ double __negdf2 (double);
+ float __negsf2 (float);
+ @end smallexample
+
+ These functions return the result of subtracting the second argument
+ from the first.
+
+ @smallexample
+ double __subdf3 (double, double);
+ float __subsf3 (float, float);
+ long double __subtf3 (long double, long double);
+ @end smallexample
+
+ These function return the result of truncating the floating argument
+ to the mode indicated by its return type.
+
+ @smallexample
+ float __truncdfsf2 (double);
+ double __trunctfdf2 (long double);
+ float __trunctfsf2 (long double);
+ @end smallexample
+
+ These functions return 1 if either argument is a NAN, otherwise 0 is
+ returned.
+
+ @smallexample
+ int __unorddf2 (double, double);
+ int __unordsf2 (float, float);
+ int __unordtf2 (long double, long double);
+ @end smallexample
+
+ These functions represent the result of converting its floating point
+ argument ot a fixed point value, regarded as unsigned.  Rounding is
+ done by cropping to zero.
+
+ @smallexample
+ unsigned int __fixunsdfsi (double);
+ unsigned int __fixunssfsi (float);
+ unsigned int __fixunstfsi (long double);
+
+ @end smallexample
Index: doc/interface.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/interface.texi,v
retrieving revision 1.2
diff -c -p -r1.2 interface.texi
*** doc/interface.texi	15 Sep 2002 22:48:04 -0000	1.2
--- doc/interface.texi	11 Mar 2003 16:18:41 -0000
*************** they appear in @file{libgcc2.c}.  Others
*** 100,102 ****
--- 100,108 ----
   assembly language for each processor.  Wherever they are defined, they
   are compiled into the support library, @file{libgcc.a}, which is
   automatically searched when you link programs with GCC@.
+
+ @menu
+ * Soft float library routines:: Supporting floating point routines.
+ @end menu
+
+ @include softfloat.texi

Re: patch: docs for soft float routines

[Richard Earnshaw]

> 
> <<These functions return the result of converting its floating point
> argument to an integer, represented as a fixed point float.  Any
> rounding done is rounding towards zero.>>
> 

See the discussion in this thread:

http://gcc.gnu.org/ml/gcc-patches/2003-03/msg00798.html

R.

Re: patch: docs for soft float routines

[Aldy Hernandez]

On Tuesday, March 11, 2003, at 08:45  AM, Richard Earnshaw wrote:

>
>>
>> <<These functions return the result of converting its floating point
>> argument to an integer, represented as a fixed point float.  Any
>> rounding done is rounding towards zero.>>
>>
>
> See the discussion in this thread:
>
> http://gcc.gnu.org/ml/gcc-patches/2003-03/msg00798.html
>
> R.
>
>

Ah, in that case, it's rounding towards zero because, in (fix:M N), M 
is a floating point mode.  I missed that subtlety.  So, the patch as I 
just posted, has the wording correct.

Aldy

Re: patch: docs for soft float routines

[Hans-Peter Nilsson]

On Tue, 11 Mar 2003, Aldy Hernandez wrote:
> >> + These functions return the result of converting its floating point
> >> + argument to an integer, still represented in floating point mode, by
> >> + rounding towards zero.
> >> +
> >> + @smallexample
> >> + int __fixdfsi (double);
> >
> > Um, in what way is the result "still represented in floating point
> > mode"?
>
> I was just quoting the docs, perhaps:

What docs?

> <<These functions return the result of converting its floating point
> argument to an integer, represented as a fixed point float.  Any
> rounding done is rounding towards zero.>>

Where's that text?  Can't find it in *.texi

> ...which I think is what this means (?):
>
>    tmp = a.fraction.ll >> ((FRACBITS + NGARDS) - a.normal_exp);
>    return a.sign ? (-tmp) : (tmp);

Looks like conversion to integer represented as integer to me.
So the fixdfsi text above needs fixing (to integer, not floating
point mode).

> Next version:

Uh, I saw another thing.  (Sorry.)  Sometimes it's not apparent
from the name which example the text refers to.  Perhaps change
"these functions" to "the following functions" all over?

For example, the following:

> + @smallexample
> + int __fixdfsi (double);
> + int __fixsfsi (float);
> + int __fixtfsi (long double);
> + @end smallexample
> +
> + These functions represent the result of converting its fixed point
> + argument, regarded as signed, to a floating point value.
> +
> + @smallexample
> + double __floatsidf (int);
> + float __floatsisf (int);
> + long double __floatsitf (int);
> + @end smallexample

brgds, H-P

Re: patch: docs for soft float routines

[Richard Earnshaw]

+ These functions return the sum of their two arguments.
+
+ @smallexample
+ double __adddf3 (double, double);
+ float __addsf3 (float, float);
+ long double __addtf3 (long double, long double);
+ @end smallexample

I think the description should follow the function names.  That's 
generally the way the rest of our documentation is laid out.  We should 
probably also have subheadings (or suitable indentation) and index entries.

Following the md.texi file style, for example would make the above 
something like:

@cindex @code{__addsf3} library call
@cindex @code{__adddf3} library call
@cindex @code{__addtf3} library call
@item @samp{float __addsf3 (float, float);
@itemx @samp{double __adddf3 (double, double);}
@itemx @samp{long double __addtf3 (long double, long double);}
These functions return the sum of their two arguments.

+ Given two arguments (a and b), these functions compare the two
+ arguments.  If @code{a} is less than @code{b}, the function returns
+ -1.  If @code{a} is greater than @code{b}, the function returns 1.  If
+ @code{a} is equal to @code{b}, the function returns 0.  If either
+ argument is a NAN, the function returns 1.

FLOAT_LIB_COMPARE_RETURNS_BOOL can change this behaviour.

R.

Re: patch: docs for soft float routines

[Richard Henderson]

On Tue, Mar 11, 2003 at 09:03:58AM -0800, Aldy Hernandez wrote:
> >http://gcc.gnu.org/ml/gcc-patches/2003-03/msg00798.html
> 
> Ah, in that case, it's rounding towards zero because, in (fix:M N), M 
> is a floating point mode.  I missed that subtlety.  So, the patch as I 
> just posted, has the wording correct.

No, now we're mixing topics.  The thread above concerns RTL.
The thread here concerns library routines.  It would be
shockingly stupid to make two libcalls to perform the C
float->int conversion instead of one.


r~

Re: patch: docs for soft float routines

[Aldy Hernandez]

> I think the description should follow the function names.  That's
> generally the way the rest of our documentation is laid out.  We should
> probably also have subheadings (or suitable indentation) and index 
> entries.
>

Sigh, y'all just want to worsen my rsi today ;-).

How about this?

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

	* Makefile.in (TEXI_GCCINT_FILES): Add softfloat.texi.

	* doc/softfloat.texi: New file.

	* doc/interface.texi (Interface): Add menu for soft float routines.
	(Interface): Include softfloat.texi.

Index: Makefile.in
===================================================================
RCS file: /cvs/gcc/gcc/gcc/Makefile.in,v
retrieving revision 1.1009
diff -c -p -r1.1009 Makefile.in
*** Makefile.in	5 Mar 2003 22:19:30 -0000	1.1009
--- Makefile.in	12 Mar 2003 01:19:43 -0000
*************** TEXI_GCCINT_FILES = $(docdir)/gccint.tex
*** 2589,2595 ****
   	 $(docdir)/gnu.texi $(docdir)/include/gpl.texi \
   	 $(docdir)/include/fdl.texi $(docdir)/contrib.texi \
   	 $(docdir)/languages.texi $(docdir)/sourcebuild.texi \
! 	 $(docdir)/gty.texi

   TEXI_GCCINSTALL_FILES = $(docdir)/install.texi 
$(docdir)/install-old.texi \
   	 $(docdir)/include/fdl.texi
--- 2589,2595 ----
   	 $(docdir)/gnu.texi $(docdir)/include/gpl.texi \
   	 $(docdir)/include/fdl.texi $(docdir)/contrib.texi \
   	 $(docdir)/languages.texi $(docdir)/sourcebuild.texi \
! 	 $(docdir)/gty.texi $(docdir)/softfloat.texi

   TEXI_GCCINSTALL_FILES = $(docdir)/install.texi 
$(docdir)/install-old.texi \
   	 $(docdir)/include/fdl.texi
Index: doc/softfloat.texi
===================================================================
RCS file: doc/softfloat.texi
diff -N doc/softfloat.texi
*** /dev/null	1 Jan 1970 00:00:00 -0000
--- doc/softfloat.texi	12 Mar 2003 01:19:43 -0000
***************
*** 0 ****
--- 1,224 ----
+ @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 Soft float library routines
+ @section Supporting soft floating point library routines
+ @cindex soft library
+ @opindex msoft-float
+
+ Code compiled with GCC may call certain library routines.  Most of
+ them handle arithmetic for which there are no machine instructions.
+ This includes floating point operations for which floating point
+ support is disabled with @option{-msoft-float}.  This section
+ documents the floating point subset of these routines.
+
+ This section documents these functions using their default library
+ names.  These names can be renamed by defining the macro
+ @code{DECLARE_LIBARRY_RENAMES} in @file{libgcc2.c}.
+
+ This document assumes @code{float} is a floating point of
+ @code{SF} mode, @code{double} is a floating point of @code{DF}
+ mode, @code{long double} is a floating point of @code{TF} mode,
+ and @code{int} is an integer of @code{SI} mode.
+
+ @cindex @code{__addsf3} library call
+ @cindex @code{__adddf3} library call
+ @cindex @code{__addtf3} library call
+ @table @samp
+ @item @samp{double __adddf3 (double, double);}
+ @itemx @samp{float __addsf3 (float, float);}
+ @itemx @samp{long double __addtf3 (long double, long double);}
+ These functions return the sum of their two arguments.
+ @end table
+
+ @cindex @code{__cmpsf2} library call
+ @cindex @code{__cmpdf2} library call
+ @cindex @code{__cmptf2} library call
+ @table @samp
+ @item @samp{int __cmpdf2 (double, double);}
+ @itemx @samp{int __cmpsf2 (float, float);}
+ @itemx @samp{int __cmptf2 (long double, long double);}
+ Given two arguments (a and b), these functions compare the two
+ arguments.  If @code{a} is less than @code{b}, the function returns
+ -1.  If @code{a} is greater than @code{b}, the function returns 1.  If
+ @code{a} is equal to @code{b}, the function returns 0.  If either
+ argument is a NAN, the function returns 1.
+ @end table
+
+ @cindex @code{__divsf3} library call
+ @cindex @code{__divdf3} library call
+ @cindex @code{__divtf3} library call
+ @table @samp
+ @item @samp{double __divdf3 (double, double);}
+ @itemx @samp{float __divsf3 (float, float);}
+ @itemx @samp{long double __divtf3 (long double, long double);}
+ These function return the result of dividing the first argument by
+ the second argument.
+ @end table
+
+ @cindex @code{__eqsf2} library call
+ @cindex @code{__eqdf2} library call
+ @cindex @code{__eqtf2} library call
+ @table @samp
+ @item @samp{int __eqdf2 (double, double);}
+ @itemx @samp{int __eqsf2 (float, float);}
+ @itemx @samp{int __eqtf2 (long double, long double);}
+ Thes following functions return 0 if their arguments are equal to each
+ other, otherwise a non-zero is returned.  If either argument is a NAN,
+ 1 is return.
+ @end table
+
+ @cindex @code{__extendsfdf2} library call
+ @cindex @code{__extendsftf2} library call
+ @table @samp
+ @item @samp{double __extendsfdf2 (float);}
+ @itemx @samp{long double __extendsftf2 (float);}
+ These  functions extend their argument to @code{double} and
+ @code{long double} respectively.
+ @end table
+
+ @cindex @code{__fixdfsi} library call
+ @cindex @code{__fixsfsi} library call
+ @cindex @code{__fixtfsi} library call
+ @table @samp
+ @item @samp{int __fixdfsi (double);}
+ @itemx @samp{int __fixsfsi (float);}
+ @itemx @samp{int __fixtfsi (long double);}
+ These functions return the result of converting its floating
+ point argument to an integer.  Any rounding done is rounding towards
+ zero.
+ @end table
+
+ @cindex @code{__floatsidf} library call
+ @cindex @code{__floatsisf} library call
+ @table @samp
+ @item @samp{double __floatsidf (int);}
+ @itemx @samp{float __floatsisf (int);}
+ @itemx @samp{long double __floatsitf (int);}
+ These functions represent the result of converting its fixed
+ point argument, regarded as signed, to a floating point value.
+ @end table
+
+ @cindex @code{__floatunsidf} library call
+ @cindex @code{__floatunsisf} library call
+ @table @samp
+ @item @samp{double __floatunsidf (unsigned int);}
+ @itemx @samp{float __floatunsisf (unsigned int);}
+ @itemx @samp{long double __floatunsitf (unsigned int);}
+ The same as above, but the argument is regarded as unsigned.
+ @end table
+
+ @cindex @code{__gedf2} library call
+ @cindex @code{__gesf2} library call
+ @cindex @code{__getf2} library call
+ @table @samp
+ @item @samp{int __gedf2 (double, double);}
+ @itemx @samp{int __gesf2 (float, float);}
+ @itemx @samp{int __getf2 (long double, long double);}
+ Thes following functions return 1 if the first argument is greater or
+ equal than the second argument, and -1 for a NAN.  Otherwise, 0 is
+ returned.
+ @end table
+
+ @cindex @code{__ledf2} library call
+ @cindex @code{__lesf2} library call
+ @cindex @code{__letf2} library call
+ @table @samp
+ @item @samp{int __ledf2 (double, double);}
+ @itemx @samp{int __lesf2 (float, float);}
+ @itemx @samp{int __letf2 (long double, long double);}
+ These functions return 1 if the first argument is less than or
+ equal to the second argument, or if either argument is a NAN.
+ Otherwise, 0 is returned.
+ @end table
+
+ @cindex @code{__ltdf2} library call
+ @cindex @code{__ltsf2} library call
+ @cindex @code{__lttf2} library call
+ @table @samp
+ @item @samp{int __ltdf2 (double, double);}
+ @itemx @samp{int __ltsf2 (float, float);}
+ @itemx @samp{int __lttf2 (long double, long double);}
+ Thes following functions return 1 if the first argument is less than
+ the second argument, or if either argument is a NAN.  Otherwise, 0 is
+ returned.
+ @end table
+
+ @cindex @code{__muldf3} library call
+ @cindex @code{__mulsf3} library call
+ @cindex @code{__multf3} library call
+ @table @samp
+ @item @samp{double __muldf3 (double, double);}
+ @itemx @samp{float __mulsf3 (float, float);}
+ @itemx @samp{long double __multf3 (long double, long double);}
+ These functions return the result of multiplying their arguments.
+ @end table
+
+ @cindex @code{__nedf2} library call
+ @cindex @code{__nesf2} library call
+ @cindex @code{__netf2} library call
+ @table @samp
+ @item @samp{int __nedf2 (double, double);}
+ @itemx @samp{int __nesf2 (float, float);}
+ @itemx @samp{int __netf2 (long double, long double);}
+ These functions return 1 if the first argument is not equal to
+ the second argument, or if either argument is a NAN.  Otherwise, 0 is
+ returned.
+ @end table
+
+ @cindex @code{__negtf2} library call
+ @cindex @code{__negdf2} library call
+ @cindex @code{__negsf2} library call
+ @table @samp
+ @item @samp{long double __negtf2 (long double);}
+ @itemx @samp{double __negdf2 (double);}
+ @itemx @samp{float __negsf2 (float);}
+ These functions return the result of negating its argument.
+ @end table
+
+ @cindex @code{__subsf3} library call
+ @cindex @code{__subdf3} library call
+ @cindex @code{__subtf3} library call
+ @table @samp
+ @item @samp{double __subdf3 (double, double);}
+ @itemx @samp{float __subsf3 (float, float);}
+ @itemx @samp{long double __subtf3 (long double, long double);}
+ These functions return the result of subtracting the second
+ argument from the first.
+ @end table
+
+ @cindex @code{__truncdfsf2} library call
+ @cindex @code{__trunctfdf2} library call
+ @cindex @code{__trunctfsf2} library call
+ @table @samp
+ @item @samp{float __truncdfsf2 (double);}
+ @itemx @samp{double __trunctfdf2 (long double);}
+ @itemx @samp{float __trunctfsf2 (long double);}
+ These functions return the result of truncating the floating
+ argument to the mode indicated by its return type.
+ @end table
+
+ @cindex @code{__unorddf2} library call
+ @cindex @code{__unordsf2} library call
+ @cindex @code{__unordtf2} library call
+ @table @samp
+ @item @samp{int __unorddf2 (double, double);}
+ @itemx @samp{int __unordsf2 (float, float);}
+ @itemx @samp{int __unordtf2 (long double, long double);}
+ These functions return 1 if either argument is a NAN,
+ otherwise 0 is returned.
+ @end table
+
+ @cindex @code{__fixunsdfsi} library call
+ @cindex @code{__fixunssfsi} library call
+ @cindex @code{__fixunstfsi} library call
+ @table @samp
+ @item @samp{unsigned int __fixunsdfsi (double);}
+ @itemx @samp{unsigned int __fixunssfsi (float);}
+ @itemx @samp{unsigned int __fixunstfsi (long double);}
+ These functions represent the result of converting its
+ floating point argument ot a fixed point value, regarded as unsigned.
+ Rounding is done by cropping to zero.
+ @end table
Index: doc/interface.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/interface.texi,v
retrieving revision 1.2
diff -c -p -r1.2 interface.texi
*** doc/interface.texi	15 Sep 2002 22:48:04 -0000	1.2
--- doc/interface.texi	12 Mar 2003 01:19:44 -0000
*************** they appear in @file{libgcc2.c}.  Others
*** 100,102 ****
--- 100,108 ----
   assembly language for each processor.  Wherever they are defined, they
   are compiled into the support library, @file{libgcc.a}, which is
   automatically searched when you link programs with GCC@.
+
+ @menu
+ * Soft float library routines:: Supporting floating point routines.
+ @end menu
+
+ @include softfloat.texi

Re: patch: docs for soft float routines

[Zack Weinberg]

Aldy Hernandez <aldyh@redhat.com> writes:

>> I think the description should follow the function names.  That's
>> generally the way the rest of our documentation is laid out.  We should
>> probably also have subheadings (or suitable indentation) and index
>> entries.
>
> Sigh, y'all just want to worsen my rsi today ;-).
>
> How about this?

I hate to worsen your rsi, but this should really be using
@deftypefun, like so:

> + @cindex @code{__addsf3} library call
> + @cindex @code{__adddf3} library call
> + @cindex @code{__addtf3} library call
> + @table @samp
> + @item @samp{double __adddf3 (double, double);}
> + @itemx @samp{float __addsf3 (float, float);}
> + @itemx @samp{long double __addtf3 (long double, long double);}
> + These functions return the sum of their two arguments.
> + @end table

@deftypefun float __addsf3 (float @var{a}, float @var{b})
@deftypefunx double __adddf3 (double @var{a}, double @var{b})
@deftypefunx {long double} __addtf3 (long double @var{a}, long double @var{b})
These functions return the sum of their two arguments.
@end deftypefun

Also I would prefer ordering by size, not double-first.

zw

Re: patch: docs for soft float routines

[Zack Weinberg]

[-- Attachment #1: Type: text/plain, Size: 837 bytes --]

Zack Weinberg <zack@codesourcery.com> writes:

> I hate to worsen your rsi, but this should really be using
> @deftypefun, like so:

Being a nice guy and all I redid the formatting for you.  And then I
wound up revising the content pretty heavily.  The introductory
paragraphs still need some work.  Another patch is under test in my
working copy right now so I haven't even tried to run makeinfo on this.

Now I'm going to go gibber in the corner for awhile.  The way the
NaN-aware comparison routines work is just ... horrifying.  I would
also like to call attention to this little gem from __fpcmp_parts:

#if 0
  if (isnan (a) && isnan (b))
    {
      return 1;
    }
#endif
  if (isnan (a) || isnan (b))
    {
      return 1;
    }

It has been that way since the epoch of this repository.

z "doomed doomed doomed go home now" w


[-- Attachment #2: softfloat.texi --]
[-- Type: text/plain, Size: 7587 bytes --]

@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 Soft float library routines
@section Supporting soft floating point library routines
@cindex soft float library
@opindex msoft-float

Code compiled with GCC may call certain library routines.  Most of
them handle arithmetic operations for which there are no machine
instructions.  This includes floating point operations, when the
target processor does not support them in hardware, or GCC is
instructed not to generate floating-point instructions with
@option{-msoft-float}.

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.

This document assumes @code{float} is a floating point of
@code{SF} mode, @code{double} is a floating point of @code{DF}
mode, @code{long double} is a floating point of @code{TF} mode,
and @code{int} is an integer of @code{SI} mode.

@subsection Arithmetic functions

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

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

@deftypefun float __mulsf3 (float @var{a}, float @var{b})
@deftypefunx double __muldf3 (double @var{a}, double @var{b})
@deftypefunx long double __multf3 (long double @var{a}, long double @var{b})
These functions return the product of @var{a} and @var{b}
@end deftypefun

@deftypefun float __divsf3 (float @var{a}, float @var{b})
@deftypefunx double __divdf3 (double @var{a}, double @var{b})
@deftypefunx long double __divtf3 (long double @var{a}, long double @var{b})
These functions return the quotient of @var{a} and @var{b}; that is,
@iftex
@math{a\over b}.
@end iftex
@ifnottex
@math{a / b}.
@end ifnottex
@end deftypefun

@deftypefun double __negdf2 (double @var{a})
@deftypefunx long double __negtf2 (long double @var{a})
@deftypefunx 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 deftypefun

@subsection Comparison functions

These are the basic comparison functions.

@deftypefun int __cmpsf2 (float @var{a}, float @var{b})
@deftypefunx int __cmpdf2 (double @var{a}, double @var{b})
@deftypefunx int __cmptf2 (long double @var{a}, long double @var{b})
These functions calculate @math{a <=> b}.  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 other comparison functions.
@end deftypefun

@deftypefun int __unordsf2 (float @var{a}, float @var{b})
@deftypefunx int __unorddf2 (double @var{a}, double @var{b})
@deftypefunx int __unordtf2 (long double @var{a}, long double @var{b})
These functions return 1 if either argument is NaN, otherwise 0.
@end deftypefun

These functions are somewhat higher level; 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 (__unordXf2 (a, b))
    return E;
  return __cmpXf2 (a, b);
@end smallexample

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.

@deftypefun int __eqsf2 (float @var{a}, float @var{b})
@deftypefunx int __eqdf2 (double @var{a}, double @var{b})
@deftypefunx 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 deftypefun

@deftypefun int __nesf2 (float @var{a}, float @var{b})
@deftypefunx int __nedf2 (double @var{a}, double @var{b})
@deftypefunx 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 deftypefun

@deftypefun int __gesf2 (float @var{a}, float @var{b})
@deftypefunx int __gedf2 (double @var{a}, double @var{b})
@deftypefunx 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 deftypefun

@deftypefun int __ltsf2 (float @var{a}, float @var{b})
@deftypefunx int __ltdf2 (double @var{a}, double @var{b})
@deftypefunx 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 deftypefun

@deftypefun int __lesf2 (float @var{a}, float @var{b})
@deftypefunx int __ledf2 (double @var{a}, double @var{b})
@deftypefunx 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 deftypefun

@deftypefun int __gtsf2 (float @var{a}, float @var{b})
@deftypefunx int __gtdf2 (double @var{a}, double @var{b})
@deftypefunx 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 deftypefun

@subsection Conversion functions

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

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

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

@deftypefun unsigned int __fixunssfsi (float @var{a})
@deftypefunx unsigned int __fixunsdfsi (double @var{a})
@deftypefunx 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 deftypefun

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

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

Re: patch: docs for soft float routines

[Richard Earnshaw]

> Zack Weinberg <zack@codesourcery.com> writes:
> 
> > I hate to worsen your rsi, but this should really be using
> > @deftypefun, like so:
> 
> Being a nice guy and all I redid the formatting for you.  And then I
> wound up revising the content pretty heavily.  The introductory
> paragraphs still need some work.  Another patch is under test in my
> working copy right now so I haven't even tried to run makeinfo on this.

Cool.

> @deftypefun float __addsf3 (float @var{a}, float @var{b})
> @deftypefunx double __adddf3 (double @var{a}, double @var{b})
> @deftypefunx long double __addtf3 (long double @var{a}, long double @var{b})
> These functions return the sum of @var{a} and @var{b}.
> @end deftypefun

My knowledge of texinfo is likely to be far more sketchy than yours.  Do 
these add index entries automatically?  Also, I note that @deftypefn 
(note, no u) takes a category first, that might be useful for adding a 
"runtime library" prefix to these.

R.

Re: patch: docs for soft float routines

[Richard Earnshaw]

> On Tue, Mar 11, 2003 at 09:03:58AM -0800, Aldy Hernandez wrote:
> > >http://gcc.gnu.org/ml/gcc-patches/2003-03/msg00798.html
> > 
> > Ah, in that case, it's rounding towards zero because, in (fix:M N), M 
> > is a floating point mode.  I missed that subtlety.  So, the patch as I 
> > just posted, has the wording correct.
> 
> No, now we're mixing topics.  The thread above concerns RTL.
> The thread here concerns library routines.  It would be
> shockingly stupid to make two libcalls to perform the C
> float->int conversion instead of one.

Good point.  I agree entirely.

R.

Re: patch: docs for soft float routines

[Aldy Hernandez]

> Being a nice guy and all I redid the formatting for you.  And then I
> wound up revising the content pretty heavily.  The introductory

Bless your heart.  *sniff* All I want is to get these patches in and
go on vacation--meanwhile, while not destroying my hands.

> paragraphs still need some work.  Another patch is under test in my
> working copy right now so I haven't even tried to run makeinfo on this.

OK for mainline.  Thanks.  I assume you'll take it from here ;-).