From 05b4cec71bfd2f9ff568c04afee9072a203b115e Mon Sep 17 00:00:00 2001
From: nsz <nsz@port70.net>
Date: Thu, 27 Dec 2012 21:37:03 +0100
Subject: [PATCH] libm: update the ugly part, fix typos

---
 libm/index.html | 83 ++++++++++++++++++++++++++++++++++---------------
 1 file changed, 58 insertions(+), 25 deletions(-)

diff --git a/libm/index.html b/libm/index.html
index e177d6c..2e1ccde 100644
--- a/libm/index.html
+++ b/libm/index.html
@@ -35,7 +35,7 @@ cvs -d <a href="http://openbsd.org/anoncvs.html#CVSROOT">$CVSROOT</a> get src/li
 
 <h3><a name="rules" href="#rules">General rules</a></h3>
 <ul>
-<li>Assumption about floating-point representation and arithmetics
+<li>Assumptions about floating-point representation and arithmetics
 (see <a href="http://port70.net/~nsz/c/c99/n1256.html#F.2">c99 annex F.2</a>):
 <ul>
 <li>float is ieee binary32
@@ -57,7 +57,7 @@ but the last bit may be wrong:
 <pre>
     |error| &lt; 1.5 ulp
 </pre>
-should hold.
+should hold for most functions.
 (error is the difference between the exact result and the calculated
 floating-point value)
 (in theory correct rounding can be achieved but with big implementation cost,
@@ -69,14 +69,16 @@ sqrt, trunc.
 <li>Mathematical properties of functions should be as expected
 (monotonicity, range, symmetries).
 <li>If the FPU precision is altered then nothing is guaranteed to work.
-(ie. when long double does not have full 80bit precision on i386 then things may break)
+(ie. when long double does not have full 80bit precision on i386 then things
+may break, this also means that compiler must spill fpu registers at 80bits
+precision)
 <li>Signaling NaN is not supported
 <li>Quiet NaN is supported but all NaNs are treated equally without special
 attention to the internal representation of a NaN
 (eg. the sign of NaN may not be preserved).
 <li>Most gcc bug workarounds should be removed from the code
 (STRICT_ASSIGN macro is used when excessive precision is harmful and
-FORCE_EVAL when expressions must be evaluated for their sideeffect, other
+FORCE_EVAL when expressions must be evaluated for their side-effect, other
 usage of volatile is not justified, hacks around long double constants are
 not justified eventhough gcc can miscompile those with non-default FPU setting)
 <li>Whenever fenv is accessed the FENV_ACCESS pragma of c99 should be used
@@ -88,13 +90,13 @@ macros should be protected by #ifdef
 (eg signed int must not be used in bit shifts etc when it might invoke
 undefined or implementation defined behaviour).
 <li>POSIX namespace rules must be respected.
-<li>c99 hexfloat syntax (0x1.0p0) should be used when it makes the
-code clearer, but not in public header files
+<li>c99 hexfloat syntax (0x1.0p0) should be used when it makes the code
+clearer, but not in public header files
 (those should be c++ and ansi c compatible)
 <li>The 'f' suffix should be used for single precision values (0.1f) when the
-value cannot be exactly represented ((float)0.1 is not ok, that style may lead
-to double rounding issues, but eg. 1.0 or 0.5 can be used instead of 1.0f or
-0.5f)
+value cannot be exactly represented or the type of the arithmetics is important
+((float)0.1 is not ok, that style may lead to double rounding issues, but eg.
+1.0 or 0.5 may be used instead of 1.0f or 0.5f in some cases)
 <li>Prefer classification macros (eg. isnan) over inplace bit hacks.
 <li>For every math function there should be a c implementation.
 (a notable exception now is sqrtl, since most fpu has instruction for it
@@ -111,6 +113,9 @@ functions they implement.
 <p>
 Binary representation of floating point numbers matter
 because bit hacks are often needed in the math code.
+(in particular bit hacks are used instead of relational operations for nan
+and sign checks becuase relational operators raise invalid fp exception on nan
+and they treat -0.0 and +0.0 equally and more often than not these are not desired)
 <p>
 float and double bit manipulation can be handled in a portable way in c using
 union types:
@@ -308,11 +313,14 @@ static const volatile two52 = 0x1p52;
 </pre>
 and using the '-frounding-math' gcc flag.
 <p>
-(According the freebsd libm code gcc truncates
-long double const literals on i386.
-I haven't yet verified if this still the case,
-but as a workaround double-double arithmetics is used:
-initializing the long double constant from two doubles)
+According to the freebsd libm code gcc truncates long double
+const literals on i386.
+I assume this happens because freebsd uses 64bit long doubles by default
+(double precision) and gcc incorrectly uses the precision setting of the
+host platform instead of the target one, but i did not observe this on linux.
+(as a workaround sometimes double-double arithmetics was used
+to initialize long doubles on i386, but most of these should be
+fixed in musl's math code now)
 
 <li>ld80 vs ld128
 <p>
@@ -358,27 +366,27 @@ but feraiseexcept is not available for some reason,
 then simple arithmetics can be be used just for their
 exception raising side effect
 (eg. 1/0.0 to raise divbyzero), however beaware
-of compiler optimizations (dead code elimination,..).
+of compiler optimizations (constant folding and dead code elimination,..).
 <p>
 Unfortunately gcc does not always take fp exceptions into
 account: a simple x = 1e300*1e300; may not raise overflow
 exception at runtime, but get optimized into x = +inf.
 see compiler optimizations above.
 <p>
-Another x87 gcc bug related to fp exceptions is that
+Another x87 gcc bug related to fp exceptions is that in some cases
 comparision operators (==, &lt;, etc) don't raise invalid
 when an operand is nan
 (eventhough this is required by ieee + c99 annex F).
 (see <a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=52451">gcc bug52451</a>).
 <p>
-The ieee standard defines signaling and quite nan
+The ieee standard defines signaling and quiet nan
 floating-point numbers as well.
 The c99 standard only considers quiet nan, but it allows
 signaling nans to be supported as well.
 Without signaling nans x * 1 is equivalent to x,
 but if signaling nan is supported then the former
 raises an invalid exception.
-This may complicates things further if one wants to write
+This may complicate things further if one wants to write
 portable fp math code.
 <p>
 A further libm design issue is the math_errhandling macro:
@@ -389,8 +397,23 @@ but errno is hard to support: certain library functions
 are implemented as a single asm instruction (eg sqrt),
 the only way to set errno is to query the fp exception flags
 and then set the errno variable based on that.
-So eventhough errno may be convenient in libm it is
+So eventhough errno may be convenient, in libm it is
 not the right thing to do.
+<p>
+For soft-float targets however errno seems to be the only option
+(which means annex K cannot be fully supported, as it requires
+the support of exception flags).
+The problem is that at context switches the fpu status should
+be saved and restored which is done by the kernel on hard-fp
+architectures when the state is in an fpu status word.
+In case of soft-fp emulation this must be done by the c runtime:
+context switches between threads can be supported with thread local
+storage of the exception state, but signal handlers may do floating-point
+arithmetics which should not alter the fenv state.
+Wrapping signal handlers is not possible/difficult for various
+reasons and the compiler cannot know which functions will be used
+as signal handlers, so the c runtime has no way to guarantee that
+signal handlers do not alter the fenv.
 
 <li>Complex arithmetics
 <p>
@@ -429,16 +452,26 @@ in gcc it can be 1.0fi).
 <p>
 The freebsd libm code has many inconsistencies
 (naming conventions, 0x1p0 notation vs decimal notation,..),
-one of them is the integer type used for bitmanipulations:
+one of them is the integer type used for bit manipulations:
 The bits of a double are unpacked into one of
-int32_t, uint32_t and u_int32_t
+int, int32_t, uint32_t and u_int32_t
 integer types.
 <p>
-int32_t is used most often which is wrong because of
-implementation defined signed int representation.
+int32_t is used the most often which is not wrong in itself
+but it is used incorrectly in many places.
+<p>
+int is a bit worse because unlike int32_t it is not guaranteed
+to be 32bit two's complement representation. (but of course in
+practice they are the same)
+<p>
+The issues found so far are left shift of negative integers
+(undefined behaviour), right shift of negative integers
+(implementation defined behaviour), signed overflow
+(implementation defined behaviour), unsigned to signed conversion
+(implementation defined behaviour).
 <p>
-In general signed int is not handled carefully
-in the libm code: scalbn even depends on signed int overflow.
+It is easy to avoid these issues without performance impact,
+but a bit of care should be taken around bit manipulations.
 </ul>
 
 <h3><a name="implementations" href="#implementations">libm implementations</a></h3>
-- 
2.20.1