[PATCH 14/12] libgcc _BitInt helper documentation [PR102989]
On Mon, Aug 21, 2023 at 05:32:04PM +, 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-08-22 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. --- gcc/doc/libgcc.texi.jj 2023-01-16 11:52:16.115733593 +0100 +++ gcc/doc/libgcc.texi 2023-08-22 12:35:08.561348126 +0200 @@ -218,6 +218,51 @@ These functions return the number of bit These functions return the @var{a} byteswapped. @end deftypefn +@subsection Bit-precise integer arithmetic functions + +@code{_BitInt(@var{N})} library functions operate on arrays of limbs, where +each limb has @code{__LIBGCC_BITINT_LIMB_WIDTH__} bits and the limbs are +ordered according to @code{__LIBGCC_BITINT_ORDER__} ordering. The most +significant limb if @var{N} is not divisible by +@code{__LIBGCC_BITINT_LIMB_WIDTH__} contains padding bits which should be +ignored on read (sign or zero extended), but extended on write. For the +library functions, all bit-precise integers regardless of @var{N} are +represented like that, even when the target ABI says that for some small +@var{N} they should be represented differently in memory. A pointer +to the array of limbs argument is always accompanied with a bit size +argument. If that argument is positive, it is number of bits and the +number is assumed to be zero-extended to infinite precision, if that +argument is negative, it is negated number of bits above which all bits +are assumed to be sign-extended to infinite precision. These number of bits +arguments don't need to match actual @var{N} for the operation used in the +source, they could be lowered because of sign or zero extensions on the +input or because value-range optimization figures value will need certain +lower number of bits. For big-endian ordering of limbs, when lowering +the bit size argument the pointer argument needs to be adjusted as well. +Negative bit size argument should be always smaller or equal to @code{-2}, +because @code{signed _BitInt(1)} is not valid. +For output arguments, either the corresponding bit size argument should +be always positive (for multiplication and division), or is negative when +the output of conversion from floating-point value is signed and positive +when unsigned. The arrays of limbs output arguments point to should not +overlap any inputs, while input arrays of limbs can overlap. +@code{UBILtype} below stands for unsigned integer type with +@code{__LIBGCC_BITINT_LIMB_WIDTH__} bit precision. + +@deftypefn {Runtime Function} void __mulbitint3 (@code{UBILtype} *@var{ret}, int32_t @var{retprec}, const @code{UBILtype} *u, int32_t @var{uprec}, const @code{UBILtype} *v, int32_t @var{vprec}) +This function multiplies bit-precise integer operands @var{u} and @var{v} and stores +result into @var{retprec} precision bit-precise integer result @var{ret}. +@end deftypefn + +@deftypefn {Runtime Function} void __divmodbitint4 (@code{UBILtype} *@var{q}, int32_t @var{qprec}, @code{UBILtype} *@var{r}, int32_t @var{rprec}, const @code{UBILtype} *u, int32_t @var{uprec}, const @code{UBILtype} *v, int32_t @var{vprec}) +This function divides bit-precise integer operands @var{u} and @var{v} and stores +quotient into @var{qprec} precision bit-precise integer result @var{q} +(unless @var{q} is @code{NULL} and @var{qprec} is 0, in that case quotient +is not stored anywhere) and remainder into @var{rprec} precision bit-precise +integer result @var{r} (similarly, unless @var{r} is @code{NULL} and @var{rprec} +is 0). +@end deftypefn + @node Soft float library routines @section Routines for floating point emulation @cindex soft float library @@ -384,6 +429,27 @@ These functions convert @var{i}, an unsi These functions convert @var{i}, an unsigned long long, to floating point. @end deftypefn +@deftypefn {Runtime Function} void __fixsfbitint (@code{UBILtype} *@var{r}, int32_t @var{rprec}, float @var{a}) +@deftypefnx {Runtime Function} void __fixdfbitint (@code{UBILtype} *@var{r}, int32_t @var{rprec}, double @var{a}) +@deftypefnx {R
Re: [PATCH 14/12] libgcc _BitInt helper documentation [PR102989]
On Tue, 22 Aug 2023, Jakub Jelinek via Gcc-patches wrote: > +significant limb if @var{N} is not divisible by @var{N} should be @var{n}, throughout. > +@deftypefn {Runtime Function} void __bid_fixsdbitint (@code{UBILtype} > *@var{r}, int32_t @var{rprec}, _Decimal32 @var{a}) > +@deftypefnx {Runtime Function} void __bid_fixddbitint (@code{UBILtype} > *@var{r}, int32_t @var{rprec}, _Decimal64 @var{a}) > +@deftypefnx {Runtime Function} void __bid_fixtdbitint (@code{UBILtype} > *@var{r}, int32_t @var{rprec}, _Decimal128 @var{a}) > +These functions convert @var{a} to bit-precise integer @var{r}, rounding > toward zero. > +If @var{rprec} is positive, it converts to unsigned bit-precise integer and > +negative values all become zero, if @var{rprec} is negative, it converts > +to signed bit-precise integer. > +@end deftypefn > + > +@deftypefn {Runtime Function} _Decimal32 __bid_floatbitintsd > (@code{UBILtype} *@var{i}, int32_t @var{iprec}) > +@deftypefnx {Runtime Function} _Decimal64 __bid_floatbitintdd > (@code{UBILtype} *@var{i}, int32_t @var{iprec}) > +@deftypefnx {Runtime Function} _Decimal128 __bid_floatbitinttd > (@code{UBILtype} *@var{i}, int32_t @var{iprec}) > +These functions convert bit-precise integer @var{i} to decimal floating > point. If > +@var{iprec} is positive, it is conversion from unsigned bit-precise integer, > +otherwise from signed bit-precise integer. > +@end deftypefn The documentation for __bid_* should say explicitly that these functions are for BID format (assuming it's intended that functions for DPD format should use __dpd_* when support is added for an architecture using DPD). > +/* 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 depending on if > + RV contains the minimum or maximum signed or unsigned value. */ As I understand it, OVF is also for the case of a zero result from input close to zero, for signed types (when that's not the maximum or minimum) in addition to unsigned types. > +/* 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 large than number of bits in floating-point mantissa and "large than" -> "larger than". This patch is OK with those fixes. -- Joseph S. Myers jos...@codesourcery.com
Re: [PATCH 14/12] libgcc _BitInt helper documentation [PR102989]
On Fri, Sep 01, 2023 at 09:32:22PM +, Joseph Myers wrote: > This patch is OK with those fixes. Thanks, here is the updated patch. Queued with the rest of approved patches. 2023-09-02 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. --- gcc/doc/libgcc.texi.jj 2023-01-16 11:52:16.115733593 +0100 +++ gcc/doc/libgcc.texi 2023-08-22 12:35:08.561348126 +0200 @@ -218,6 +218,51 @@ These functions return the number of bit These functions return the @var{a} byteswapped. @end deftypefn +@subsection Bit-precise integer arithmetic functions + +@code{_BitInt(@var{n})} library functions operate on arrays of limbs, where +each limb has @code{__LIBGCC_BITINT_LIMB_WIDTH__} bits and the limbs are +ordered according to @code{__LIBGCC_BITINT_ORDER__} ordering. The most +significant limb if @var{n} is not divisible by +@code{__LIBGCC_BITINT_LIMB_WIDTH__} contains padding bits which should be +ignored on read (sign or zero extended), but extended on write. For the +library functions, all bit-precise integers regardless of @var{n} are +represented like that, even when the target ABI says that for some small +@var{n} they should be represented differently in memory. A pointer +to the array of limbs argument is always accompanied with a bit size +argument. If that argument is positive, it is number of bits and the +number is assumed to be zero-extended to infinite precision, if that +argument is negative, it is negated number of bits above which all bits +are assumed to be sign-extended to infinite precision. These number of bits +arguments don't need to match actual @var{n} for the operation used in the +source, they could be lowered because of sign or zero extensions on the +input or because value-range optimization figures value will need certain +lower number of bits. For big-endian ordering of limbs, when lowering +the bit size argument the pointer argument needs to be adjusted as well. +Negative bit size argument should be always smaller or equal to @code{-2}, +because @code{signed _BitInt(1)} is not valid. +For output arguments, either the corresponding bit size argument should +be always positive (for multiplication and division), or is negative when +the output of conversion from floating-point value is signed and positive +when unsigned. The arrays of limbs output arguments point to should not +overlap any inputs, while input arrays of limbs can overlap. +@code{UBILtype} below stands for unsigned integer type with +@code{__LIBGCC_BITINT_LIMB_WIDTH__} bit precision. + +@deftypefn {Runtime Function} void __mulbitint3 (@code{UBILtype} *@var{ret}, int32_t @var{retprec}, const @code{UBILtype} *u, int32_t @var{uprec}, const @code{UBILtype} *v, int32_t @var{vprec}) +This function multiplies bit-precise integer operands @var{u} and @var{v} and stores +result into @var{retprec} precision bit-precise integer result @var{ret}. +@end deftypefn + +@deftypefn {Runtime Function} void __divmodbitint4 (@code{UBILtype} *@var{q}, int32_t @var{qprec}, @code{UBILtype} *@var{r}, int32_t @var{rprec}, const @code{UBILtype} *u, int32_t @var{uprec}, const @code{UBILtype} *v, int32_t @var{vprec}) +This function divides bit-precise integer operands @var{u} and @var{v} and stores +quotient into @var{qprec} precision bit-precise integer result @var{q} +(unless @var{q} is @code{NULL} and @var{qprec} is 0, in that case quotient +is not stored anywhere) and remainder into @var{rprec} precision bit-precise +integer result @var{r} (similarly, unless @var{r} is @code{NULL} and @var{rprec} +is 0). +@end deftypefn + @node Soft float library routines @section Routines for floating point emulation @cindex soft float library @@ -384,6 +429,27 @@ These functions convert @var{i}, an unsi These functions convert @var{i}, an unsigned long long, to floating point. @end deftypefn +@deftypefn {Runtime Function} void __fixsfbitint (@code{UBILtype} *@var{r}, int32_t @var{rprec}, float @var{a}) +@deftypefnx {Runtime Function} void __fixdfbitint (@code{UBILtype} *@var{r}, int32_t @var{rprec}, double @var{a}) +@deftypefnx {Runtime Function} void __fixxfbitint (@code{UBILtype} *@var{r}, int32_t @var{rprec}, __float80 @var{a}) +@deftypefnx {Runtime Function} void __fixtfbitint (@code{UBILtype} *@var{r}, int32_t @var{rprec}, _Float128 @var{a}) +These functions convert @var{a} to bit-precise integer @var{r}, rounding toward zero. +If @var{rprec} is positive, it converts to unsigned bi