This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
[PATCH] floatlib documentation improvements
- From: Roger Sayle <roger at eyesopen dot com>
- To: gcc-patches at gcc dot gnu dot org
- Date: Sun, 5 Oct 2003 15:59:11 -0600 (MDT)
- Subject: [PATCH] floatlib documentation improvements
The following patch to libgcc.texi changes the documented return value
for the __unord[sdt]f2 functions and fixes some mark-up problems in
that part of the GCC internals manual.
The content change is to modify the documentation for __unordsf2,
__unorddf2 and __unordtf2 to state that these functions may return
any non-zero value, not just value one. Inside GCC's middle-end all
calls to these functions are tested for equality or inequality with
zero, so the actual non-zero return value isn't significant. This
change to the documentation will hopefully dissuade callers for testing
against one explicitly, in favour of the preferred test against zero.
There may even be some implementation benefits to relaxing the API.
Describing floatlib's comparison functions consistently also slightly
simplifies a patch I'm working on and makes these functions' APIs
independent of the target macro FLOAT_LIB_COMPARE_RETURNS_BOOL.
Whilst reading this documentation, I also noticed some strange mark-up:
http://gcc.gnu.org/onlinedocs/gccint/Soft-float-library-routines.html#Soft%20float%20library%20routines
For example, at the top of the page, you'll see listed descriptions
of __addsf3, __adddf3 and __addtf3. You'll notice that the function
names __addsf3 and __adddf3 are highlighted, but __addtf3 isn't.
Instead the word "double" is highlighted. Then similarly, "double"
appears in the index instead of __addtf3 which is missing.
The problem is that the @deftypefn and @deftypefnx macros get confused
by multi-word types, such as "long double" and "unsigned int". Although I
couldn't find it documented, the appropriate fix seems to be to group
the type using braces. This survives "make dvi" correcting the index,
with "__addtf3" appearing instead of "double".
The following patch has been tested with "make info" and "make dvi" on
i686-pc-linux-gnu. Unfortunately, "make dvi" is failing on objc.texi for
me, even after updating my texinfo to v4.6. However, this occurs after
gccint.dvi which still "builds" without problems.
Ok for mainline?
2003-10-05 Roger Sayle <roger@eyesopen.com>
* libgcc.texi: Group multi-word types, such as "long double" and
"unsigned int", using braces in @deftypefn and @deftypefnx nodes.
Document __unord?f2 as returning a non-zero value, not just one.
Index: libgcc.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/libgcc.texi,v
retrieving revision 1.2
diff -c -3 -p -r1.2 libgcc.texi
*** libgcc.texi 15 Mar 2003 23:35:46 -0000 1.2
--- libgcc.texi 5 Oct 2003 21:11:43 -0000
*************** for @code{long double} on some architect
*** 160,192 ****
@deftypefn {Runtime Function} float __addsf3 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} double __adddf3 (double @var{a}, double @var{b})
! @deftypefnx {Runtime Function} long double __addtf3 (long double @var{a}, long double @var{b})
These functions return the sum of @var{a} and @var{b}.
@end deftypefn
@deftypefn {Runtime Function} float __subsf3 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} double __subdf3 (double @var{a}, double @var{b})
! @deftypefnx {Runtime Function} long double __subtf3 (long double @var{a}, long double @var{b})
These functions return the difference between @var{b} and @var{a};
that is, @w{@math{@var{a} - @var{b}}}.
@end deftypefn
@deftypefn {Runtime Function} float __mulsf3 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} double __muldf3 (double @var{a}, double @var{b})
! @deftypefnx {Runtime Function} long double __multf3 (long double @var{a}, long double @var{b})
These functions return the product of @var{a} and @var{b}.
@end deftypefn
@deftypefn {Runtime Function} float __divsf3 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} double __divdf3 (double @var{a}, double @var{b})
! @deftypefnx {Runtime Function} long double __divtf3 (long double @var{a}, long double @var{b})
These functions return the quotient of @var{a} and @var{b}; that is,
@w{@math{@var{a} / @var{b}}}.
@end deftypefn
! @deftypefn {Runtime Function} double __negdf2 (double @var{a})
! @deftypefnx {Runtime Function} long double __negtf2 (long double @var{a})
! @deftypefnx {Runtime Function} float __negsf2 (float @var{a})
These functions return the negation of @var{a}. They simply flip the
sign bit, so they can produce negative zero and negative NaN.
@end deftypefn
--- 160,192 ----
@deftypefn {Runtime Function} float __addsf3 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} double __adddf3 (double @var{a}, double @var{b})
! @deftypefnx {Runtime Function} {long double} __addtf3 (long double @var{a}, long double @var{b})
These functions return the sum of @var{a} and @var{b}.
@end deftypefn
@deftypefn {Runtime Function} float __subsf3 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} double __subdf3 (double @var{a}, double @var{b})
! @deftypefnx {Runtime Function} {long double} __subtf3 (long double @var{a}, long double @var{b})
These functions return the difference between @var{b} and @var{a};
that is, @w{@math{@var{a} - @var{b}}}.
@end deftypefn
@deftypefn {Runtime Function} float __mulsf3 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} double __muldf3 (double @var{a}, double @var{b})
! @deftypefnx {Runtime Function} {long double} __multf3 (long double @var{a}, long double @var{b})
These functions return the product of @var{a} and @var{b}.
@end deftypefn
@deftypefn {Runtime Function} float __divsf3 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} double __divdf3 (double @var{a}, double @var{b})
! @deftypefnx {Runtime Function} {long double} __divtf3 (long double @var{a}, long double @var{b})
These functions return the quotient of @var{a} and @var{b}; that is,
@w{@math{@var{a} / @var{b}}}.
@end deftypefn
! @deftypefn {Runtime Function} float __negsf2 (float @var{a})
! @deftypefnx {Runtime Function} double __negdf2 (double @var{a})
! @deftypefnx {Runtime Function} {long double} __negtf2 (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
*** 194,201 ****
@subsection Conversion functions
@deftypefn {Runtime Function} double __extendsfdf2 (float @var{a})
! @deftypefnx {Runtime Function} long double __extendsftf2 (float @var{a})
! @deftypefnx {Runtime Function} long double __extenddftf2 (double @var{a})
These functions extend @var{a} to the wider mode of their return
type.
@end deftypefn
--- 194,201 ----
@subsection Conversion functions
@deftypefn {Runtime Function} double __extendsfdf2 (float @var{a})
! @deftypefnx {Runtime Function} {long double} __extendsftf2 (float @var{a})
! @deftypefnx {Runtime Function} {long double} __extenddftf2 (double @var{a})
These functions extend @var{a} to the wider mode of their return
type.
@end deftypefn
*************** type, rounding toward zero.
*** 213,234 ****
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
--- 213,234 ----
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
*************** functions.
*** 256,262 ****
@deftypefn {Runtime Function} int __unordsf2 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} int __unorddf2 (double @var{a}, double @var{b})
@deftypefnx {Runtime Function} int __unordtf2 (long double @var{a}, long double @var{b})
! These functions return 1 if either argument is NaN, otherwise 0.
@end deftypefn
There is also a complete group of higher level functions which
--- 256,262 ----
@deftypefn {Runtime Function} int __unordsf2 (float @var{a}, float @var{b})
@deftypefnx {Runtime Function} int __unorddf2 (double @var{a}, double @var{b})
@deftypefnx {Runtime Function} int __unordtf2 (long double @var{a}, long double @var{b})
! These functions return a nonzero value if either argument is NaN, otherwise 0.
@end deftypefn
There is also a complete group of higher level functions which
Roger
--
Roger Sayle, E-mail: roger@eyesopen.com
OpenEye Scientific Software, WWW: http://www.eyesopen.com/
Suite 1107, 3600 Cerrillos Road, Tel: (+1) 505-473-7385
Santa Fe, New Mexico, 87507. Fax: (+1) 505-473-0833