From f6e0ec5696ec5f52baed71fe23f978bcef80d458 Mon Sep 17 00:00:00 2001 From: Jakub Jelinek Date: Wed, 6 Sep 2023 17:42:37 +0200 Subject: 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 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. --- libgcc/soft-fp/bitint.h | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'libgcc/soft-fp') 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 \ { \ -- cgit v1.1