[newlib-cygwin] Change the return type of converttoint and document the semantics

[newlib-cygwin] Change the return type of converttoint and document the semantics

[Corinna Vinschen]

https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;h=6a85e1a4e5a01dec3b423eb172b3ad9155487e75

commit 6a85e1a4e5a01dec3b423eb172b3ad9155487e75
Author: Szabolcs Nagy <szabolcs.nagy@arm.com>
Date:   Wed Jul 4 11:09:39 2018 +0100

    Change the return type of converttoint and document the semantics
    
    The roundtoint and converttoint internal functions are only called with small
    values, so 32 bit result is enough for converttoint and it is a signed int
    conversion so the natural return type is int32_t.
    
    The original idea was to help the compiler keeping the result in uint64_t,
    then it's clear that no sign extension is needed and there is no accidental
    undefined or implementation defined signed int arithmetics.
    
    But it turns out gcc does a good job with inlining so changing the type has
    no overhead and the semantics of the conversion is less surprising this way.
    Since we want to allow the asuint64 (x + 0x1.8p52) style conversion, the top
    bits were never usable and the existing code ensures that only the bottom
    32 bits of the conversion result are used.
    
    In newlib with default settings only aarch64 is affected and there is no
    significant code generation change with gcc after the patch.

Diff:
---
 newlib/libm/common/math_config.h | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/newlib/libm/common/math_config.h b/newlib/libm/common/math_config.h
index b46e44e..d5896bb 100644
--- a/newlib/libm/common/math_config.h
+++ b/newlib/libm/common/math_config.h
@@ -71,15 +71,23 @@
 #endif
 
 #if HAVE_FAST_ROUND
+/* When set, the roundtoint and converttoint functions are provided with
+   the semantics documented below.  */
 # define TOINT_INTRINSICS 1
 
+/* Round x to nearest int in all rounding modes, ties have to be rounded
+   consistently with converttoint so the results match.  If the result
+   would be outside of [-2^31, 2^31-1] then the semantics is unspecified.  */
 static inline double_t
 roundtoint (double_t x)
 {
   return round (x);
 }
 
-static inline uint64_t
+/* Convert x to nearest int in all rounding modes, ties have to be rounded
+   consistently with roundtoint.  If the result is not representible in an
+   int32_t then the semantics is unspecified.  */
+static inline int32_t
 converttoint (double_t x)
 {
 # if HAVE_FAST_LROUND