readme - platform/external/fdlibm - Gitiles


 	  *********************************
  	  * Announcing FDLIBM Version 5.3 *
 	  *********************************
 ============================================================
 			FDLIBM
 ============================================================
 	developed at Sun Microsystems, Inc.

 What's new in FDLIBM 5.3?

 CONFIGURE
 	To build FDLIBM, edit the supplied Makefile or create
 	a local Makefile by running "sh configure"
 	using the supplied configure script contributed by Nelson Beebe

 BUGS FIXED

     1. e_pow.c incorrect results when
 	x is very close to -1.0 and y is very large, e.g.
   	pow(-1.0000000000000002e+00,4.5035996273704970e+15) = 0
   	pow(-9.9999999999999978e-01,4.5035996273704970e+15) = 0
 	Correct results are close to -e and -1/e.

     2. k_tan.c error was > 1 ulp target for FDLIBM
 	5.2: Worst error at least 1.45 ulp at
 	tan(1.7765241907548024E+269) = 1.7733884462610958E+16
 	5.3: Worst error 0.96 ulp

 NOT FIXED YET

     3. Compiler failure on non-standard code
 	Statements like
 	            *(1+(int*)&t1) = 0;
 	are not standard C and cause some optimizing compilers (e.g. GCC)
 	to generate bad code under optimization.    These cases
 	are to be addressed in the next release.

 FDLIBM (Freely Distributable LIBM) is a C math library
 for machines that support IEEE 754 floating-point arithmetic.
 In this release, only double precision is supported.

 FDLIBM is intended to provide a reasonably portable (see
 assumptions below), reference quality (below one ulp for
 major functions like sin,cos,exp,log) math library
 (libm.a).  For a copy of FDLIBM, please see
 	http://www.netlib.org/fdlibm/
 or
 	http://www.validlab.com/software/

 --------------
 1. ASSUMPTIONS
 --------------
 FDLIBM (double precision version) assumes:
  a.  IEEE 754 style (if not precise compliance) arithmetic;
  b.  32 bit 2's complement integer arithmetic;
  c.  Each double precision floating-point number must be in IEEE 754
      double format, and that each number can be retrieved as two 32-bit
      integers through the using of pointer bashing as in the example
      below:

      Example: let y = 2.0
 	double fp number y: 	2.0
 	IEEE double format:	0x4000000000000000

 	Referencing y as two integers:
 	*(int*)&y,*(1+(int*)&y) =	{0x40000000,0x0} (on sparc)
 					{0x0,0x40000000} (on 386)

 	Note: Four macros are defined in fdlibm.h to handle this kind of
 	retrieving:

 	__HI(x)		the high part of a double x
 			(sign,exponent,the first 21 significant bits)
 	__LO(x)		the least 32 significant bits of x
 	__HIp(x)	same as __HI except that the argument is a pointer
 			to a double
 	__LOp(x)	same as __LO except that the argument is a pointer
 			to a double

 	To ensure obtaining correct ordering, one must define  __LITTLE_ENDIAN
 	during compilation for little endian machine (like 386,486). The
 	default is big endian.

 	If the behavior of pointer bashing is undefined, one may hack on the
 	macro in fdlibm.h.

   d. IEEE exceptions may trigger "signals" as is common in Unix
      implementations.

 -------------------
 2. EXCEPTION CASES
 -------------------
 All exception cases in the FDLIBM functions will be mapped
 to one of the following four exceptions:

    +-huge*huge, +-tiny*tiny,    +-1.0/0.0,	+-0.0/0.0
     (overflow)	(underflow)  (divided-by-zero) 	(invalid)

 For example, ieee_log(0) is a singularity and is thus mapped to
 	-1.0/0.0 = -infinity.
 That is, FDLIBM's log will compute -one/zero and return the
 computed value.  On an IEEE machine, this will trigger the
 divided-by-zero exception and a negative infinity is returned by
 default.

 Similarly, ieee_exp(-huge) will be mapped to tiny*tiny to generate
 an underflow signal.


 --------------------------------
 3. STANDARD CONFORMANCE WRAPPER
 --------------------------------
 The default FDLIBM functions (compiled with -D_IEEE_LIBM flag)
 are in "IEEE spirit" (i.e., return the most reasonable result in
 floating-point arithmetic). If one wants FDLIBM to comply with
 standards like SVID, X/OPEN, or POSIX/ANSI, then one can
 create a multi-standard compliant FDLIBM. In this case, each
 function in FDLIBM is actually a standard compliant wrapper
 function.

 File organization:
     1. For FDLIBM's kernel (internal) function,
 		File name	Entry point
 		---------------------------
 		k_sin.c		__kernel_sin
 		k_tan.c		__kernel_tan
 		---------------------------
     2. For functions that have no standards conflict
 		File name	Entry point
 		---------------------------
 		s_sin.c		sin
 		s_erf.c		erf
 		---------------------------
     3. Ieee754 core functions
 		File name	Entry point
 		---------------------------
 		e_exp.c		__ieee754_exp
 		e_sinh.c	__ieee754_sinh
 		---------------------------
     4. Wrapper functions
 		File name	Entry point
 		---------------------------
 		w_exp.c		exp
 		w_sinh.c	sinh
 		---------------------------

 Wrapper functions will twist the result of the ieee754
 function to comply to the standard specified by the value
 of _LIB_VERSION
     if _LIB_VERSION = _IEEE_, return the ieee754 result;
     if _LIB_VERSION = _SVID_, return SVID result;
     if _LIB_VERSION = _XOPEN_, return XOPEN result;
     if _LIB_VERSION = _POSIX_, return POSIX/ANSI result.
 (These are macros, see fdlibm.h for their definition.)


 --------------------------------
 4. HOW TO CREATE FDLIBM's libm.a
 --------------------------------
 There are two types of libm.a. One is IEEE only, and the other is
 multi-standard compliant (supports IEEE,XOPEN,POSIX/ANSI,SVID).

 To create the IEEE only libm.a, use
 	    make "CFLAGS = -D_IEEE_LIBM"
 This will create an IEEE libm.a, which is smaller in size, and
 somewhat faster.

 To create a multi-standard compliant libm, use
     make "CFLAGS = -D_IEEE_MODE"   --- multi-standard fdlibm: default
 					 to IEEE
     make "CFLAGS = -D_XOPEN_MODE"  --- multi-standard fdlibm: default
 					 to X/OPEN
     make "CFLAGS = -D_POSIX_MODE"  --- multi-standard fdlibm: default
 					 to POSIX/ANSI
     make "CFLAGS = -D_SVID3_MODE"  --- multi-standard fdlibm: default
 					 to SVID


 Here is how one makes a SVID compliant libm.
     Make the library by
 		make "CFLAGS = -D_SVID3_MODE".
     The libm.a of FDLIBM will be multi-standard compliant and
     _LIB_VERSION is initialized to the value _SVID_ .

     example1:
     ---------
 	    main()
 	    {
 		double ieee_y0();
 		printf("y0(1e300) = %1.20e\n",y0(1e300));
 		exit(0);
 	    }

     % cc example1.c libm.a
     % a.out
     y0: TLOSS error
     ieee_y0(1e300) = 0.00000000000000000000e+00


 It is possible to change the default standard in multi-standard
 fdlibm. Here is an example of how to do it:
     example2:
     ---------
 	#include "fdlibm.h"	/* must include FDLIBM's fdlibm.h */
 	main()
 	{
 		double ieee_y0();
 		_LIB_VERSION =  _IEEE_;
 		printf("IEEE: ieee_y0(1e300) = %1.20e\n",y0(1e300));
 		_LIB_VERSION = _XOPEN_;
 		printf("XOPEN ieee_y0(1e300) = %1.20e\n",y0(1e300));
 		_LIB_VERSION = _POSIX_;
 		printf("POSIX ieee_y0(1e300) = %1.20e\n",y0(1e300));
 		_LIB_VERSION = _SVID_;
 		printf("SVID  ieee_y0(1e300) = %1.20e\n",y0(1e300));
 		exit(0);
 	}

     % cc example2.c libm.a
     % a.out
       IEEE: ieee_y0(1e300) = -1.36813604503424810557e-151
       XOPEN ieee_y0(1e300) = 0.00000000000000000000e+00
       POSIX ieee_y0(1e300) = 0.00000000000000000000e+00
       y0: TLOSS error
       SVID  ieee_y0(1e300) = 0.00000000000000000000e+00

 Note:	Here _LIB_VERSION is a global variable. If global variables
 	are forbidden, then one should modify fdlibm.h to change
 	_LIB_VERSION to be a global constant. In this case, one
 	may not change the value of _LIB_VERSION as in example2.

 ---------------------------
 5. NOTES ON PORTING FDLIBM
 ---------------------------
 	Care must be taken when installing FDLIBM over existing
 	libm.a.
 	All co-existing function prototypes must agree, otherwise
 	users will encounter mysterious failures.

 	So far, the only known likely conflict is the declaration
 	of the IEEE recommended function scalb:

 		double ieee_scalb(double,double)	(1)	SVID3 defined
 		double ieee_scalb(double,int)	(2)	IBM,DEC,...

 	FDLIBM follows Sun definition and use (1) as default.
 	If one's existing libm.a uses (2), then one may raise
 	the flags _SCALB_INT during the compilation of FDLIBM
 	to get the correct function prototype.
 	(E.g., make "CFLAGS = -D_IEEE_LIBM -D_SCALB_INT".)
 	NOTE that if -D_SCALB_INT is raised, it won't be SVID3
 	conformant.

 --------------
 6. PROBLEMS ?
 --------------
 Please send comments and bug reports to the electronic mail address
 suggested by:
 		fdlibm-comments AT sun.com

	*********************************
	* Announcing FDLIBM Version 5.3 *
	*********************************
	============================================================
	FDLIBM
	============================================================
	developed at Sun Microsystems, Inc.

	What's new in FDLIBM 5.3?

	CONFIGURE
	To build FDLIBM, edit the supplied Makefile or create
	a local Makefile by running "sh configure"
	using the supplied configure script contributed by Nelson Beebe

	BUGS FIXED

	1. e_pow.c incorrect results when
	x is very close to -1.0 and y is very large, e.g.
	pow(-1.0000000000000002e+00,4.5035996273704970e+15) = 0
	pow(-9.9999999999999978e-01,4.5035996273704970e+15) = 0
	Correct results are close to -e and -1/e.

	2. k_tan.c error was > 1 ulp target for FDLIBM
	5.2: Worst error at least 1.45 ulp at
	tan(1.7765241907548024E+269) = 1.7733884462610958E+16
	5.3: Worst error 0.96 ulp

	NOT FIXED YET

	3. Compiler failure on non-standard code
	Statements like
	(1+(int)&t1) = 0;
	are not standard C and cause some optimizing compilers (e.g. GCC)
	to generate bad code under optimization. These cases
	are to be addressed in the next release.

	FDLIBM (Freely Distributable LIBM) is a C math library
	for machines that support IEEE 754 floating-point arithmetic.
	In this release, only double precision is supported.

	FDLIBM is intended to provide a reasonably portable (see
	assumptions below), reference quality (below one ulp for
	major functions like sin,cos,exp,log) math library
	(libm.a). For a copy of FDLIBM, please see
	http://www.netlib.org/fdlibm/
	or
	http://www.validlab.com/software/

	--------------
	1. ASSUMPTIONS
	--------------
	FDLIBM (double precision version) assumes:
	a. IEEE 754 style (if not precise compliance) arithmetic;
	b. 32 bit 2's complement integer arithmetic;
	c. Each double precision floating-point number must be in IEEE 754
	double format, and that each number can be retrieved as two 32-bit
	integers through the using of pointer bashing as in the example
	below:

	Example: let y = 2.0
	double fp number y: 2.0
	IEEE double format: 0x4000000000000000

	Referencing y as two integers:
	(int)&y,(1+(int)&y) = {0x40000000,0x0} (on sparc)
	{0x0,0x40000000} (on 386)

	Note: Four macros are defined in fdlibm.h to handle this kind of
	retrieving:

	__HI(x) the high part of a double x
	(sign,exponent,the first 21 significant bits)
	__LO(x) the least 32 significant bits of x
	__HIp(x) same as __HI except that the argument is a pointer
	to a double
	__LOp(x) same as __LO except that the argument is a pointer
	to a double

	To ensure obtaining correct ordering, one must define __LITTLE_ENDIAN
	during compilation for little endian machine (like 386,486). The
	default is big endian.

	If the behavior of pointer bashing is undefined, one may hack on the
	macro in fdlibm.h.

	d. IEEE exceptions may trigger "signals" as is common in Unix
	implementations.

	-------------------
	2. EXCEPTION CASES
	-------------------
	All exception cases in the FDLIBM functions will be mapped
	to one of the following four exceptions:

	+-hugehuge, +-tinytiny, +-1.0/0.0, +-0.0/0.0
	(overflow) (underflow) (divided-by-zero) (invalid)

	For example, ieee_log(0) is a singularity and is thus mapped to
	-1.0/0.0 = -infinity.
	That is, FDLIBM's log will compute -one/zero and return the
	computed value. On an IEEE machine, this will trigger the
	divided-by-zero exception and a negative infinity is returned by
	default.

	Similarly, ieee_exp(-huge) will be mapped to tiny*tiny to generate
	an underflow signal.


	--------------------------------
	3. STANDARD CONFORMANCE WRAPPER
	--------------------------------
	The default FDLIBM functions (compiled with -D_IEEE_LIBM flag)
	are in "IEEE spirit" (i.e., return the most reasonable result in
	floating-point arithmetic). If one wants FDLIBM to comply with
	standards like SVID, X/OPEN, or POSIX/ANSI, then one can
	create a multi-standard compliant FDLIBM. In this case, each
	function in FDLIBM is actually a standard compliant wrapper
	function.

	File organization:
	1. For FDLIBM's kernel (internal) function,
	File name Entry point
	---------------------------
	k_sin.c __kernel_sin
	k_tan.c __kernel_tan
	---------------------------
	2. For functions that have no standards conflict
	File name Entry point
	---------------------------
	s_sin.c sin
	s_erf.c erf
	---------------------------
	3. Ieee754 core functions
	File name Entry point
	---------------------------
	e_exp.c __ieee754_exp
	e_sinh.c __ieee754_sinh
	---------------------------
	4. Wrapper functions
	File name Entry point
	---------------------------
	w_exp.c exp
	w_sinh.c sinh
	---------------------------

	Wrapper functions will twist the result of the ieee754
	function to comply to the standard specified by the value
	of _LIB_VERSION
	if _LIB_VERSION = _IEEE_, return the ieee754 result;
	if _LIB_VERSION = _SVID_, return SVID result;
	if _LIB_VERSION = _XOPEN_, return XOPEN result;
	if _LIB_VERSION = _POSIX_, return POSIX/ANSI result.
	(These are macros, see fdlibm.h for their definition.)


	--------------------------------
	4. HOW TO CREATE FDLIBM's libm.a
	--------------------------------
	There are two types of libm.a. One is IEEE only, and the other is
	multi-standard compliant (supports IEEE,XOPEN,POSIX/ANSI,SVID).

	To create the IEEE only libm.a, use
	make "CFLAGS = -D_IEEE_LIBM"
	This will create an IEEE libm.a, which is smaller in size, and
	somewhat faster.

	To create a multi-standard compliant libm, use
	make "CFLAGS = -D_IEEE_MODE" --- multi-standard fdlibm: default
	to IEEE
	make "CFLAGS = -D_XOPEN_MODE" --- multi-standard fdlibm: default
	to X/OPEN
	make "CFLAGS = -D_POSIX_MODE" --- multi-standard fdlibm: default
	to POSIX/ANSI
	make "CFLAGS = -D_SVID3_MODE" --- multi-standard fdlibm: default
	to SVID


	Here is how one makes a SVID compliant libm.
	Make the library by
	make "CFLAGS = -D_SVID3_MODE".
	The libm.a of FDLIBM will be multi-standard compliant and
	_LIB_VERSION is initialized to the value _SVID_ .

	example1:
	---------
	main()
	{
	double ieee_y0();
	printf("y0(1e300) = %1.20e\n",y0(1e300));
	exit(0);
	}

	% cc example1.c libm.a
	% a.out
	y0: TLOSS error
	ieee_y0(1e300) = 0.00000000000000000000e+00


	It is possible to change the default standard in multi-standard
	fdlibm. Here is an example of how to do it:
	example2:
	---------
	#include "fdlibm.h" /* must include FDLIBM's fdlibm.h */
	main()
	{
	double ieee_y0();
	_LIB_VERSION = _IEEE_;
	printf("IEEE: ieee_y0(1e300) = %1.20e\n",y0(1e300));
	_LIB_VERSION = _XOPEN_;
	printf("XOPEN ieee_y0(1e300) = %1.20e\n",y0(1e300));
	_LIB_VERSION = _POSIX_;
	printf("POSIX ieee_y0(1e300) = %1.20e\n",y0(1e300));
	_LIB_VERSION = _SVID_;
	printf("SVID ieee_y0(1e300) = %1.20e\n",y0(1e300));
	exit(0);
	}

	% cc example2.c libm.a
	% a.out
	IEEE: ieee_y0(1e300) = -1.36813604503424810557e-151
	XOPEN ieee_y0(1e300) = 0.00000000000000000000e+00
	POSIX ieee_y0(1e300) = 0.00000000000000000000e+00
	y0: TLOSS error
	SVID ieee_y0(1e300) = 0.00000000000000000000e+00

	Note: Here _LIB_VERSION is a global variable. If global variables
	are forbidden, then one should modify fdlibm.h to change
	_LIB_VERSION to be a global constant. In this case, one
	may not change the value of _LIB_VERSION as in example2.

	---------------------------
	5. NOTES ON PORTING FDLIBM
	---------------------------
	Care must be taken when installing FDLIBM over existing
	libm.a.
	All co-existing function prototypes must agree, otherwise
	users will encounter mysterious failures.

	So far, the only known likely conflict is the declaration
	of the IEEE recommended function scalb:

	double ieee_scalb(double,double) (1) SVID3 defined
	double ieee_scalb(double,int) (2) IBM,DEC,...

	FDLIBM follows Sun definition and use (1) as default.
	If one's existing libm.a uses (2), then one may raise
	the flags _SCALB_INT during the compilation of FDLIBM
	to get the correct function prototype.
	(E.g., make "CFLAGS = -D_IEEE_LIBM -D_SCALB_INT".)
	NOTE that if -D_SCALB_INT is raised, it won't be SVID3
	conformant.

	--------------
	6. PROBLEMS ?
	--------------
	Please send comments and bug reports to the electronic mail address
	suggested by:
	fdlibm-comments AT sun.com