From patchwork Tue Aug 22 11:28:00 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jakub Jelinek X-Patchwork-Id: 136514 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:b82d:0:b0:3f2:4152:657d with SMTP id z13csp3557672vqi; Tue, 22 Aug 2023 04:30:01 -0700 (PDT) X-Google-Smtp-Source: AGHT+IGrCdyK37t9osgEeFON6JmUubfQqulo+mpNo9VDFgmzoxiaVHry2eCcgHjc14/N8uI87WpI X-Received: by 2002:a17:906:9bdf:b0:994:1eb4:6898 with SMTP id de31-20020a1709069bdf00b009941eb46898mr7709051ejc.9.1692703801391; Tue, 22 Aug 2023 04:30:01 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1692703801; cv=none; d=google.com; s=arc-20160816; b=ieYDhx3SCsnaMz7KdV+dowvZsMbMul6p8H9ezWHlq0/rE/1hm2j8NI2lp7+nuj11Mw 9kOTHB5+EwCvtkARj5ZKz1KNpFU00Swhi6S0f8sSWVT+JfIDgblDNYXFe0ODXDr7DHXj gAIKdYMFZy0lv2+45JMTcViN29+7okUTpPxNfklDjotMmoyZ5F+gsRS2FMFEYy51DBDv 2sHyPMcQSMk4+6Lgb5oyK1YFHRnjr32wJgD4XrqItJsbKcHCR60/PJqWMC4Mrv9bAJ45 ZPT9jR9Z7moI9I2dyv1+yYGT/bIJgdGe7K2KPtKwtkaBHT6kC+CQD5PfOa0HWn4m9yKj T+Pg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:reply-to:from:list-subscribe:list-help:list-post :list-archive:list-unsubscribe:list-id:precedence :content-disposition:in-reply-to:mime-version:references:message-id :subject:cc:to:date:dmarc-filter:delivered-to:dkim-signature :dkim-filter; bh=ve8/9Sz9NcXMaJGs+YuutLs+csP+KOK5K3sBcgpFxVY=; fh=WhQTVvB6y/tLHBV3wqYClh5kFEagurSUhwOQUkCBj9g=; b=e8frMjw+ODapt7SRACj6pY7mqBf5Jq7KUKdtl4XNQ8FwTLq2QkvoQ8F+w9+h/dOiwn ByoGVyow1om/tnAPkStE1yoFCVEp4Xkrnpeh4UbIi90zRlxuwSfdUEyoyxSmdV3tCBoB viFXdp5JCS3FErULmRw6Zv3+uAEqO4Dcoap24IpCry31FmolCeFOmJV8g9xKGePURmXP x8vE24KOqktid8z/zJ5nimFia0oCfSmur1nIomQUCkXq/kOyHEwS8kHbYFsY4ji59oM3 wfw3CXQXNIlblbfvbAHx14DgTceZY+9Mdhee/K2LIZFauZouIHrcD63VeQu1kPbnP5t3 Z51Q== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@gcc.gnu.org header.s=default header.b=gIbYiXB1; spf=pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) smtp.mailfrom="gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gnu.org Received: from server2.sourceware.org (server2.sourceware.org. [2620:52:3:1:0:246e:9693:128c]) by mx.google.com with ESMTPS id i10-20020a1709061e4a00b00997e71d037dsi6906274ejj.624.2023.08.22.04.30.01 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 22 Aug 2023 04:30:01 -0700 (PDT) Received-SPF: pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) client-ip=2620:52:3:1:0:246e:9693:128c; Authentication-Results: mx.google.com; dkim=pass header.i=@gcc.gnu.org header.s=default header.b=gIbYiXB1; spf=pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) smtp.mailfrom="gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gnu.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 5E8EE388202D for ; Tue, 22 Aug 2023 11:28:51 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 5E8EE388202D DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1692703731; bh=ve8/9Sz9NcXMaJGs+YuutLs+csP+KOK5K3sBcgpFxVY=; h=Date:To:Cc:Subject:References:In-Reply-To:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: From:Reply-To:From; b=gIbYiXB1U5lhl8hYc+A75a9R6clftlwE1v0EUAgsSkyf3fvoTBCLpqJ5eokA3Qghf Rwx5hUlcyqv0gpr5sM1Kt/PTCwuzg5K/ZQqct9r8Savn4dkxUQCmmsFZTF6fKnCKXZ xKIOte52nyMwEVrzXEx8I+91Q7ytIbKGnObVRkeA= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id CCCAD38582B0 for ; Tue, 22 Aug 2023 11:28:06 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org CCCAD38582B0 Received: from mimecast-mx02.redhat.com (66.187.233.73 [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-626-RbCRq-I6NpmwI_2K1FLmhQ-1; Tue, 22 Aug 2023 07:28:03 -0400 X-MC-Unique: RbCRq-I6NpmwI_2K1FLmhQ-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id F321A280FEC2; Tue, 22 Aug 2023 11:28:02 +0000 (UTC) Received: from tucnak.zalov.cz (unknown [10.45.225.165]) by smtp.corp.redhat.com (Postfix) with ESMTPS id B8746C15BAE; Tue, 22 Aug 2023 11:28:02 +0000 (UTC) Received: from tucnak.zalov.cz (localhost [127.0.0.1]) by tucnak.zalov.cz (8.17.1/8.17.1) with ESMTPS id 37MBS0Wt2434070 (version=TLSv1.3 cipher=TLS_AES_256_GCM_SHA384 bits=256 verify=NOT); Tue, 22 Aug 2023 13:28:00 +0200 Received: (from jakub@localhost) by tucnak.zalov.cz (8.17.1/8.17.1/Submit) id 37MBS0n32434069; Tue, 22 Aug 2023 13:28:00 +0200 Date: Tue, 22 Aug 2023 13:28:00 +0200 To: Joseph Myers Cc: Richard Biener , gcc-patches@gcc.gnu.org Subject: [PATCH 14/12] libgcc _BitInt helper documentation [PR102989] Message-ID: References: <409a2da3-1c2d-e62-6f7-8a3ec74871c7@codesourcery.com> MIME-Version: 1.0 In-Reply-To: <409a2da3-1c2d-e62-6f7-8a3ec74871c7@codesourcery.com> X-Scanned-By: MIMEDefang 3.1 on 10.11.54.8 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Disposition: inline X-Spam-Status: No, score=-3.7 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL, SPF_HELO_NONE, SPF_NONE, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jakub Jelinek via Gcc-patches From: Jakub Jelinek Reply-To: Jakub Jelinek Errors-To: gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org Sender: "Gcc-patches" X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1774928581327823662 X-GMAIL-MSGID: 1774928581327823662 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-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. Jakub --- 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 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} float __floatbitintsf (@code{UBILtype} *@var{i}, int32_t @var{iprec}) +@deftypefnx {Runtime Function} double __floatbitintdf (@code{UBILtype} *@var{i}, int32_t @var{iprec}) +@deftypefnx {Runtime Function} __float80 __floatbitintxf (@code{UBILtype} *@var{i}, int32_t @var{iprec}) +@deftypefnx {Runtime Function} _Float128 __floatbitinttf (@code{UBILtype} *@var{i}, int32_t @var{iprec}) +@deftypefnx {Runtime Function} _Float16 __floatbitinthf (@code{UBILtype} *@var{i}, int32_t @var{iprec}) +@deftypefnx {Runtime Function} __bf16 __floatbitintbf (@code{UBILtype} *@var{i}, int32_t @var{iprec}) +These functions convert bit-precise integer @var{i} to floating point. If +@var{iprec} is positive, it is conversion from unsigned bit-precise integer, +otherwise from signed bit-precise integer. +@end deftypefn + @subsection Comparison functions There are two sets of basic comparison functions. @@ -707,6 +773,23 @@ These functions convert @var{i}, an unsi These functions convert @var{i}, an unsigned long, to decimal floating point. @end deftypefn +@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 + @subsection Comparison functions @deftypefn {Runtime Function} int __dpd_unordsd2 (_Decimal32 @var{a}, _Decimal32 @var{b}) --- libgcc/libgcc2.c.jj 2023-08-22 11:21:31.549370982 +0200 +++ libgcc/libgcc2.c 2023-08-22 13:24:46.198998697 +0200 @@ -1640,6 +1640,8 @@ __mulbitint3 (UWtype *ret, SItype retpre #endif #ifdef L_divmodbitint4 +/* D = -S. */ + static void bitint_negate (UWtype *d, const UWtype *s, SItype n) { --- libgcc/soft-fp/bitint.h.jj 2023-08-22 11:21:31.583370543 +0200 +++ libgcc/soft-fp/bitint.h 2023-08-22 13:06:01.346092498 +0200 @@ -160,6 +160,9 @@ bitint_reduce_prec (const UBILtype **p, # 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 UBILty 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 depending on if + RV contains the minimum or maximum signed or unsigned value. */ + #define FP_TO_BITINT(r, rn, arprec, shift, rv, rsize, rsigned, ovf, DI) \ if (ovf) \ { \ @@ -232,6 +248,16 @@ bitint_negate (UBILtype *d, const UBILty * 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 large 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 \ { \