libgcc _BitInt helper documentation [PR102989]

On Mon, Aug 21, 2023 at 05:32:04PM +0000, Joseph Myers wrote:
> I think the libgcc functions (i.e. those exported by libgcc, to which
> references are generated by the compiler) need documenting in libgcc.texi.
> Internal functions or macros in the libgcc patch need appropriate comments
> specifying their semantics; especially FP_TO_BITINT and FP_FROM_BITINT
> which have a lot of arguments and no comments saying what the semantics of
> the macros and their arguments are supposed to me.

Here is an incremental patch which does that.

2023-09-06  Jakub Jelinek  <jakub@redhat.com>

	PR c/102989
gcc/
	* doc/libgcc.texi (Bit-precise integer arithmetic functions):
	Document general rules for _BitInt support library functions
	and document __mulbitint3 and __divmodbitint4.
	(Conversion functions): Document __fix{s,d,x,t}fbitint,
	__floatbitint{s,d,x,t,h,b}f, __bid_fix{s,d,t}dbitint and
	__bid_floatbitint{s,d,t}d.
libgcc/
	* libgcc2.c (bitint_negate): Add function comment.
	* soft-fp/bitint.h (bitint_negate): Add function comment.
	(FP_TO_BITINT, FP_FROM_BITINT): Add comment explaining the macros.

2 files changed, 28 insertions, 0 deletions

diff --git a/libgcc/libgcc2.c b/libgcc/libgcc2.c
index d217e33..8b42210 100644
--- a/libgcc/libgcc2.c
+++ b/libgcc/libgcc2.c
@@ -1640,6 +1640,8 @@ __mulbitint3 (UWtype *ret, SItype retprec,
 #endif
 
 #ifdef L_divmodbitint4
+/* D = -S.  */
+
 static void
 bitint_negate (UWtype *d, const UWtype *s, SItype n)
 {
diff --git a/libgcc/soft-fp/bitint.h b/libgcc/soft-fp/bitint.h
index 5e8b764..20cd41b 100644
--- a/libgcc/soft-fp/bitint.h
+++ b/libgcc/soft-fp/bitint.h
@@ -160,6 +160,9 @@ bitint_reduce_prec (const UBILtype **p, SItype prec)
 # define BITINT_END(be, le) (le)
 #endif
 
+/* Negate N limbs from S into D.  D and S should point to
+   the least significant limb.  */
+
 static inline __attribute__((__always_inline__)) void
 bitint_negate (UBILtype *d, const UBILtype *s, SItype n)
 {
@@ -175,6 +178,19 @@ bitint_negate (UBILtype *d, const UBILtype *s, SItype n)
   while (--n);
 }
 
+/* Common final part of __fix?fbitint conversion functions.
+   The A floating point value should have been converted using
+   soft-fp macros into RV, U##DI##type DI##_BITS precise normal
+   integral type and SHIFT, how many bits should that value be
+   shifted to the left.  R is pointer to limbs array passed to the
+   function, RN number of limbs in it, ARPREC absolute value of
+   RPREC argument passed to it, RSIZE number of significant bits in RV.
+   RSIGNED is non-zero if the result is signed bit-precise integer,
+   otherwise zero.  If OVF is true, instead of storing RV shifted left
+   by SHIFT bits and zero or sign extended store minimum or maximum
+   of the signed or unsigned bit-precise integer type or zero depending on if
+   RV contains the minimum or maximum signed or unsigned value or zero.  */
+
 #define FP_TO_BITINT(r, rn, arprec, shift, rv, rsize, rsigned, ovf, DI) \
   if (ovf)								\
     {									\
@@ -232,6 +248,16 @@ bitint_negate (UBILtype *d, const UBILtype *s, SItype n)
 			  * sizeof (UBILtype));				\
     }
 
+/* Common initial part of __floatbitint?f conversion functions.
+   I and IPREC are arguments passed to those functions, convert that
+   into a pair of DI##type IV integer and SHIFT, such that converting
+   IV to floating point and multiplicating that by pow (2, SHIFT)
+   gives the expected result.  IV size needs to be chosen such that
+   it is larger than number of bits in floating-point mantissa and
+   contains there even at least a two bits below the mantissa for
+   rounding purposes.  If any of the SHIFT bits shifted out is non-zero,
+   the least significant bit should be non-zero.  */
+
 #define FP_FROM_BITINT(i, iprec, iv, shift, DI)				\
   do									\
     {									\