Re: patch: docs for soft float routines

[Aldy Hernandez <aldyh at redhat dot com>]

> > + 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 at redhat dot 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 at quesejoda dot 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 at  dot 
+
+ @menu
+ * Soft float library routines:: Supporting floating point routines.
+ @end menu
+
+ @include softfloat.texi