From patchwork Sat Feb 4 20:33:54 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Roger Sayle X-Patchwork-Id: 64303 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id B8DF438515D7 for ; Sat, 4 Feb 2023 20:34:30 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from server.nextmovesoftware.com (server.nextmovesoftware.com [162.254.253.69]) by sourceware.org (Postfix) with ESMTPS id 2E1AC385B502 for ; Sat, 4 Feb 2023 20:33:57 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 2E1AC385B502 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=nextmovesoftware.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=nextmovesoftware.com DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=nextmovesoftware.com; s=default; h=Content-Type:MIME-Version:Message-ID: Date:Subject:To:From:Sender:Reply-To:Cc:Content-Transfer-Encoding:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:In-Reply-To:References:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=Cd4HQlKR+2zGFdO1ROs5zBANWLA38gNpITVGdOD7rVs=; b=Zygkg0fhqqZ3OdugVAgMOXFVkH X/i+mAto6b2nxYkEYjKrEuaNw7BASIwDvk9pMowNggvArXhiLS2qlg3idan9IeH1w6PIi09DgrvEj GRnKPnIMPyWGYNPEI7TBlG/SIasBMAzDc789Z8xCXNlwO8xKBbf47eQCNaKzBpN90G2NIteMySVq1 2WyaVcLUtv9xwZQmlb6d6UriolY33qd9ll9mE3bBps3++AsR7CxO0UWUL3ES4TaYw0ns04J1tCMNU BGmUg7K9Hi/zbrU9DwkQoB9yzakA68TfYo9sL0MEHs2xifSMZQEemYy2cPvQ/JbPMj76kpbR7Q2hq 2SS0I9Mg==; Received: from host86-163-35-31.range86-163.btcentralplus.com ([86.163.35.31]:49663 helo=Dell) by server.nextmovesoftware.com with esmtpsa (TLS1.2) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.95) (envelope-from ) id 1pOPES-0007DJ-GO for gcc-patches@gcc.gnu.org; Sat, 04 Feb 2023 15:33:56 -0500 From: "Roger Sayle" To: "'GCC Patches'" Subject: [DOC PATCH] Document the VEC_PERM_EXPR tree code (and minor clean-ups). Date: Sat, 4 Feb 2023 20:33:54 -0000 Message-ID: <000f01d938d8$00cdf7d0$0269e770$@nextmovesoftware.com> MIME-Version: 1.0 X-Mailer: Microsoft Outlook 16.0 Content-Language: en-gb Thread-Index: Adk410HweqVyBgGWSBKhqP1RqYUuyw== X-AntiAbuse: This header was added to track abuse, please include it with any abuse report X-AntiAbuse: Primary Hostname - server.nextmovesoftware.com X-AntiAbuse: Original Domain - gcc.gnu.org X-AntiAbuse: Originator/Caller UID/GID - [47 12] / [47 12] X-AntiAbuse: Sender Address Domain - nextmovesoftware.com X-Get-Message-Sender-Via: server.nextmovesoftware.com: authenticated_id: roger@nextmovesoftware.com X-Authenticated-Sender: server.nextmovesoftware.com: roger@nextmovesoftware.com X-Source: X-Source-Args: X-Source-Dir: X-Spam-Status: No, score=-11.8 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, KAM_ASCII_DIVIDERS, SPF_HELO_NONE, SPF_PASS, 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: , Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "Gcc-patches" This patch (primarily) documents the VEC_PERM_EXPR tree code in generic.texi. For ease of review, it is provided below as a pair of diffs. The first contains just the new text added to describe VEC_PERM_EXPR, the second tidies up this part of the documentation by sorting the tree codes into alphabetical order, and providing consistent section naming/capitalization, so changing this section from "Vectors" to "Vector Expressions" (matching the nearby "Unary and Binary Expressions"). Tested with make pdf and make html on x86_64-pc-linux-gnu. The reviewer(s) can decide whether to approve just the new content, or the content+clean-up. Ok for mainline? 2023-02-04 Roger Sayle gcc/ChangeLog * doc/generic.texi : Standardize capitalization of section titles from "Expression trees". : Likewise standardize capitalization from "Language-dependent trees". : Capitalized from "Constant Expressions". : Standardized section name from "Vectors". Document VEC_PERM_EXPR tree code. Sort tree codes alphabetically. Thanks in advance, Roger --- diff --git a/gcc/doc/generic.texi b/gcc/doc/generic.texi index 3f52d30..93b2e00 100644 --- a/gcc/doc/generic.texi +++ b/gcc/doc/generic.texi @@ -38,10 +38,10 @@ seems inelegant. * Types:: Fundamental and aggregate types. * Declarations:: Type declarations and variables. * Attributes:: Declaration and type attributes. -* Expressions: Expression trees. Operating on data. +* Expressions: Expression Trees. Operating on data. * Statements:: Control flow and related trees. * Functions:: Function bodies, linkage, and other aspects. -* Language-dependent trees:: Topics and trees specific to language front ends. +* Language-dependent Trees:: Topics and trees specific to language front ends. * C and C++ Trees:: Trees specific to C and C++. @end menu @@ -976,7 +976,7 @@ This macro returns the attributes on the type @var{type}. @c Expressions @c --------------------------------------------------------------------- -@node Expression trees +@node Expression Trees @section Expressions @cindex expression @findex TREE_TYPE @@ -1021,14 +1021,14 @@ As this example indicates, the operands are zero-indexed. @menu -* Constants: Constant expressions. +* Constants: Constant Expressions. * Storage References:: * Unary and Binary Expressions:: -* Vectors:: +* Vector Expressions:: @end menu -@node Constant expressions -@subsection Constant expressions +@node Constant Expressions +@subsection Constant Expressions @tindex INTEGER_CST @findex tree_int_cst_lt @findex tree_int_cst_equal @@ -1803,36 +1803,119 @@ a value from @code{enum annot_expr_kind}, the third is an @code{INTEGER_CST}. @end table -@node Vectors -@subsection Vectors +@node Vector Expressions +@subsection Vector Expressions +@tindex SAD_EXPR +@tindex VEC_COND_EXPR @tindex VEC_DUPLICATE_EXPR -@tindex VEC_SERIES_EXPR @tindex VEC_LSHIFT_EXPR @tindex VEC_RSHIFT_EXPR +@tindex VEC_PACK_FIX_TRUNC_EXPR +@tindex VEC_PACK_FLOAT_EXPR +@tindex VEC_PACK_SAT_EXPR +@tindex VEC_PACK_TRUNC_EXPR +@tindex VEC_PERM_EXPR +@tindex VEC_SERIES_EXPR +@tindex VEC_UNPACK_FIX_TRUNC_HI_EXPR +@tindex VEC_UNPACK_FIX_TRUNC_LO_EXPR +@tindex VEC_UNPACK_FLOAT_HI_EXPR +@tindex VEC_UNPACK_FLOAT_LO_EXPR +@tindex VEC_UNPACK_HI_EXPR +@tindex VEC_UNPACK_LO_EXPR +@tindex VEC_WIDEN_MINUS_HI_EXPR +@tindex VEC_WIDEN_MINUS_LO_EXPR @tindex VEC_WIDEN_MULT_HI_EXPR @tindex VEC_WIDEN_MULT_LO_EXPR @tindex VEC_WIDEN_PLUS_HI_EXPR @tindex VEC_WIDEN_PLUS_LO_EXPR -@tindex VEC_WIDEN_MINUS_HI_EXPR -@tindex VEC_WIDEN_MINUS_LO_EXPR -@tindex VEC_UNPACK_HI_EXPR -@tindex VEC_UNPACK_LO_EXPR -@tindex VEC_UNPACK_FLOAT_HI_EXPR -@tindex VEC_UNPACK_FLOAT_LO_EXPR -@tindex VEC_UNPACK_FIX_TRUNC_HI_EXPR -@tindex VEC_UNPACK_FIX_TRUNC_LO_EXPR -@tindex VEC_PACK_TRUNC_EXPR -@tindex VEC_PACK_SAT_EXPR -@tindex VEC_PACK_FIX_TRUNC_EXPR -@tindex VEC_PACK_FLOAT_EXPR -@tindex VEC_COND_EXPR -@tindex SAD_EXPR @table @code +@item SAD_EXPR +This node represents the Sum of Absolute Differences operation. The three +operands must be vectors of integral types. The first and second operand +must have the same type. The size of the vector element of the third +operand must be at lease twice of the size of the vector element of the +first and second one. The SAD is calculated between the first and second +operands, added to the third operand, and returned. + +@item VEC_COND_EXPR +These nodes represent @code{?:} expressions. The three operands must be +vectors of the same size and number of elements. The second and third +operands must have the same type as the entire expression. The first +operand is of signed integral vector type. If an element of the first +operand evaluates to a zero value, the corresponding element of the +result is taken from the third operand. If it evaluates to a minus one +value, it is taken from the second operand. It should never evaluate to +any other value currently, but optimizations should not rely on that +property. In contrast with a @code{COND_EXPR}, all operands are always +evaluated. + @item VEC_DUPLICATE_EXPR This node has a single operand and represents a vector in which every element is equal to that operand. +@item VEC_LSHIFT_EXPR +@itemx VEC_RSHIFT_EXPR +These nodes represent whole vector left and right shifts, respectively. +The first operand is the vector to shift; it will always be of vector type. +The second operand is an expression for the number of bits by which to +shift. Note that the result is undefined if the second operand is larger +than or equal to the first operand's type size. + +@item VEC_PACK_FIX_TRUNC_EXPR +This node represents packing of elements of the two input vectors into the +output vector, where the values are converted from floating point +to fixed point. Input operands are vectors that contain the same number +of elements of a floating point type. The result is a vector that contains +twice as many elements of an integral type whose size is half as wide. The +elements of the two vectors are merged (concatenated) to form the output +vector. + +@item VEC_PACK_FLOAT_EXPR +This node represents packing of elements of the two input vectors into the +output vector, where the values are converted from fixed point to floating +point. Input operands are vectors that contain the same number of elements +of an integral type. The result is a vector that contains twice as many +elements of floating point type whose size is half as wide. The elements of +the two vectors are merged (concatenated) to form the output vector. + +@item VEC_PACK_SAT_EXPR +This node represents packing of elements of the two input vectors into the +output vector using saturation. Input operands are vectors that contain +the same number of elements of the same integral type. The result is a +vector that contains twice as many elements of an integral type whose size +is half as wide. The elements of the two vectors are demoted and merged +(concatenated) to form the output vector. + +@item VEC_PACK_TRUNC_EXPR +This node represents packing of truncated elements of the two input vectors +into the output vector. Input operands are vectors that contain the same +number of elements of the same integral or floating point type. The result +is a vector that contains twice as many elements of an integral or floating +point type whose size is half as wide. The elements of the two vectors are +demoted and merged (concatenated) to form the output vector. + +@item VEC_PERM_EXPR +This node represents a vector permute/blend operation. The three operands +must be vectors of the same number of elements. The first and second +operands must be vectors of the same type as the entire expression, and +the third operand, @dfn{selector}, must be an integral vector type. + +The input elements are numbered from 0 in operand 1 through +@math{2*@var{N}-1} in operand 2. The elements of the selector are +interpreted modulo @math{2*@var{N}}. + +The expression +@code{@var{out} = VEC_PERM_EXPR<@var{v0}, @var{v1}, @var{selector}>}, +where @var{v0}, @var{v1} and @var{selector} have @var{N} elements, means +@smallexample + for (int i = 0; i < N; i++) + @{ + int j = selector[i] % (2*N); + out[i] = j < N ? v0[j] : v1[j-N]; + @} +@end smallexample + @item VEC_SERIES_EXPR This node represents a vector formed from a scalar base and step, given as the first and second operands respectively. Element @var{i} @@ -1841,13 +1924,54 @@ of the result is equal to @samp{@var{base} + @var{i}*@var{step}}. This node is restricted to integral types, in order to avoid specifying the rounding behavior for floating-point types. -@item VEC_LSHIFT_EXPR -@itemx VEC_RSHIFT_EXPR -These nodes represent whole vector left and right shifts, respectively. -The first operand is the vector to shift; it will always be of vector type. -The second operand is an expression for the number of bits by which to -shift. Note that the result is undefined if the second operand is larger -than or equal to the first operand's type size. +@item VEC_UNPACK_FIX_TRUNC_HI_EXPR +@itemx VEC_UNPACK_FIX_TRUNC_LO_EXPR +These nodes represent unpacking of the high and low parts of the input vector, +where the values are truncated from floating point to fixed point. The +single operand is a vector that contains @code{N} elements of the same +floating point type. The result is a vector that contains half as many +elements of an integral type whose size is twice as wide. In the case of +@code{VEC_UNPACK_FIX_TRUNC_HI_EXPR} the high @code{N/2} elements of the +vector are extracted and converted with truncation. In the case of +@code{VEC_UNPACK_FIX_TRUNC_LO_EXPR} the low @code{N/2} elements of the +vector are extracted and converted with truncation. + +@item VEC_UNPACK_FLOAT_HI_EXPR +@itemx VEC_UNPACK_FLOAT_LO_EXPR +These nodes represent unpacking of the high and low parts of the input vector, +where the values are converted from fixed point to floating point. The +single operand is a vector that contains @code{N} elements of the same +integral type. The result is a vector that contains half as many elements +of a floating point type whose size is twice as wide. In the case of +@code{VEC_UNPACK_FLOAT_HI_EXPR} the high @code{N/2} elements of the vector are +extracted, converted and widened. In the case of @code{VEC_UNPACK_FLOAT_LO_EXPR} +the low @code{N/2} elements of the vector are extracted, converted and widened. + +@item VEC_UNPACK_HI_EXPR +@itemx VEC_UNPACK_LO_EXPR +These nodes represent unpacking of the high and low parts of the input vector, +respectively. The single operand is a vector that contains @code{N} elements +of the same integral or floating point type. The result is a vector +that contains half as many elements, of an integral or floating point type +whose size is twice as wide. In the case of @code{VEC_UNPACK_HI_EXPR} the +high @code{N/2} elements of the vector are extracted and widened (promoted). +In the case of @code{VEC_UNPACK_LO_EXPR} the low @code{N/2} elements of the +vector are extracted and widened (promoted). + +@item VEC_WIDEN_MINUS_HI_EXPR +@itemx VEC_WIDEN_MINUS_LO_EXPR +These nodes represent widening vector subtraction of the high and low parts of +the two input vectors, respectively. Their operands are vectors that contain +the same number of elements (@code{N}) of the same integral type. The high/low +elements of the second vector are subtracted from the high/low elements of the +first. The result is a vector that contains half as many elements, of an +integral type whose size is twice as wide. In the case of +@code{VEC_WIDEN_MINUS_HI_EXPR} the high @code{N/2} elements of the second +vector are subtracted from the high @code{N/2} of the first to produce the +vector of @code{N/2} products. In the case of +@code{VEC_WIDEN_MINUS_LO_EXPR} the low @code{N/2} elements of the second +vector are subtracted from the low @code{N/2} of the first to produce the +vector of @code{N/2} products. @item VEC_WIDEN_MULT_HI_EXPR @itemx VEC_WIDEN_MULT_LO_EXPR @@ -1873,108 +1997,6 @@ is twice as wide. In the case of @code{VEC_WIDEN_PLUS_HI_EXPR} the high @code{N/2} elements of the two vectors are added to produce the vector of @code{N/2} products. -@item VEC_WIDEN_MINUS_HI_EXPR -@itemx VEC_WIDEN_MINUS_LO_EXPR -These nodes represent widening vector subtraction of the high and low parts of -the two input vectors, respectively. Their operands are vectors that contain -the same number of elements (@code{N}) of the same integral type. The high/low -elements of the second vector are subtracted from the high/low elements of the -first. The result is a vector that contains half as many elements, of an -integral type whose size is twice as wide. In the case of -@code{VEC_WIDEN_MINUS_HI_EXPR} the high @code{N/2} elements of the second -vector are subtracted from the high @code{N/2} of the first to produce the -vector of @code{N/2} products. In the case of -@code{VEC_WIDEN_MINUS_LO_EXPR} the low @code{N/2} elements of the second -vector are subtracted from the low @code{N/2} of the first to produce the -vector of @code{N/2} products. - -@item VEC_UNPACK_HI_EXPR -@itemx VEC_UNPACK_LO_EXPR -These nodes represent unpacking of the high and low parts of the input vector, -respectively. The single operand is a vector that contains @code{N} elements -of the same integral or floating point type. The result is a vector -that contains half as many elements, of an integral or floating point type -whose size is twice as wide. In the case of @code{VEC_UNPACK_HI_EXPR} the -high @code{N/2} elements of the vector are extracted and widened (promoted). -In the case of @code{VEC_UNPACK_LO_EXPR} the low @code{N/2} elements of the -vector are extracted and widened (promoted). - -@item VEC_UNPACK_FLOAT_HI_EXPR -@itemx VEC_UNPACK_FLOAT_LO_EXPR -These nodes represent unpacking of the high and low parts of the input vector, -where the values are converted from fixed point to floating point. The -single operand is a vector that contains @code{N} elements of the same -integral type. The result is a vector that contains half as many elements -of a floating point type whose size is twice as wide. In the case of -@code{VEC_UNPACK_FLOAT_HI_EXPR} the high @code{N/2} elements of the vector are -extracted, converted and widened. In the case of @code{VEC_UNPACK_FLOAT_LO_EXPR} -the low @code{N/2} elements of the vector are extracted, converted and widened. - -@item VEC_UNPACK_FIX_TRUNC_HI_EXPR -@itemx VEC_UNPACK_FIX_TRUNC_LO_EXPR -These nodes represent unpacking of the high and low parts of the input vector, -where the values are truncated from floating point to fixed point. The -single operand is a vector that contains @code{N} elements of the same -floating point type. The result is a vector that contains half as many -elements of an integral type whose size is twice as wide. In the case of -@code{VEC_UNPACK_FIX_TRUNC_HI_EXPR} the high @code{N/2} elements of the -vector are extracted and converted with truncation. In the case of -@code{VEC_UNPACK_FIX_TRUNC_LO_EXPR} the low @code{N/2} elements of the -vector are extracted and converted with truncation. - -@item VEC_PACK_TRUNC_EXPR -This node represents packing of truncated elements of the two input vectors -into the output vector. Input operands are vectors that contain the same -number of elements of the same integral or floating point type. The result -is a vector that contains twice as many elements of an integral or floating -point type whose size is half as wide. The elements of the two vectors are -demoted and merged (concatenated) to form the output vector. - -@item VEC_PACK_SAT_EXPR -This node represents packing of elements of the two input vectors into the -output vector using saturation. Input operands are vectors that contain -the same number of elements of the same integral type. The result is a -vector that contains twice as many elements of an integral type whose size -is half as wide. The elements of the two vectors are demoted and merged -(concatenated) to form the output vector. - -@item VEC_PACK_FIX_TRUNC_EXPR -This node represents packing of elements of the two input vectors into the -output vector, where the values are converted from floating point -to fixed point. Input operands are vectors that contain the same number -of elements of a floating point type. The result is a vector that contains -twice as many elements of an integral type whose size is half as wide. The -elements of the two vectors are merged (concatenated) to form the output -vector. - -@item VEC_PACK_FLOAT_EXPR -This node represents packing of elements of the two input vectors into the -output vector, where the values are converted from fixed point to floating -point. Input operands are vectors that contain the same number of elements -of an integral type. The result is a vector that contains twice as many -elements of floating point type whose size is half as wide. The elements of -the two vectors are merged (concatenated) to form the output vector. - -@item VEC_COND_EXPR -These nodes represent @code{?:} expressions. The three operands must be -vectors of the same size and number of elements. The second and third -operands must have the same type as the entire expression. The first -operand is of signed integral vector type. If an element of the first -operand evaluates to a zero value, the corresponding element of the -result is taken from the third operand. If it evaluates to a minus one -value, it is taken from the second operand. It should never evaluate to -any other value currently, but optimizations should not rely on that -property. In contrast with a @code{COND_EXPR}, all operands are always -evaluated. - -@item SAD_EXPR -This node represents the Sum of Absolute Differences operation. The three -operands must be vectors of integral types. The first and second operand -must have the same type. The size of the vector element of the third -operand must be at lease twice of the size of the vector element of the -first and second one. The SAD is calculated between the first and second -operands, added to the third operand, and returned. - @end table @@ -2698,12 +2720,12 @@ optimization options specified on the command line. @end ftable @c --------------------------------------------------------------------- -@c Language-dependent trees +@c Language-dependent Trees @c --------------------------------------------------------------------- -@node Language-dependent trees -@section Language-dependent trees -@cindex language-dependent trees +@node Language-dependent Trees +@section Language-dependent Trees +@cindex language-dependent Trees Front ends may wish to keep some state associated with various GENERIC trees while parsing. To support this, trees provide a set of flags diff --git a/gcc/doc/generic.texi b/gcc/doc/generic.texi index 3f52d30..4e8f131 100644 --- a/gcc/doc/generic.texi +++ b/gcc/doc/generic.texi @@ -1826,6 +1826,7 @@ a value from @code{enum annot_expr_kind}, the third is an @code{INTEGER_CST}. @tindex VEC_PACK_FIX_TRUNC_EXPR @tindex VEC_PACK_FLOAT_EXPR @tindex VEC_COND_EXPR +@tindex VEC_PERM_EXPR @tindex SAD_EXPR @table @code @@ -1967,6 +1968,27 @@ any other value currently, but optimizations should not rely on that property. In contrast with a @code{COND_EXPR}, all operands are always evaluated. +@item VEC_PERM_EXPR +This node represents a vector permute/blend operation. The three operands +must be vectors of the same number of elements. The first and second +operands must be vectors of the same type as the entire expression, and +the third operand, @dfn{selector}, must be an integral vector type. + +The input elements are numbered from 0 in operand 1 through +@math{2*@var{N}-1} in operand 2. The elements of the selector are +interpreted modulo @math{2*@var{N}}. + +The expression +@code{@var{out} = VEC_PERM_EXPR<@var{v0}, @var{v1}, @var{selector}>}, +where @var{v0}, @var{v1} and @var{selector} have @var{N} elements, means +@smallexample + for (int i = 0; i < N; i++) + @{ + int j = selector[i] % (2*N); + out[i] = j < N ? v0[j] : v1[j-N]; + @} +@end smallexample + @item SAD_EXPR This node represents the Sum of Absolute Differences operation. The three operands must be vectors of integral types. The first and second operand