From patchwork Mon May 14 14:59:25 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kelvin Nilsen X-Patchwork-Id: 913014 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=gcc.gnu.org (client-ip=209.132.180.131; helo=sourceware.org; envelope-from=gcc-patches-return-477651-incoming=patchwork.ozlabs.org@gcc.gnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=linux.ibm.com Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=gcc.gnu.org header.i=@gcc.gnu.org header.b="atX5+oSH"; dkim-atps=neutral Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 40l3mQ1cFzz9s0q for ; Tue, 15 May 2018 01:00:52 +1000 (AEST) DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:to:cc :from:subject:date:mime-version:content-type :content-transfer-encoding:message-id; q=dns; s=default; b=LFL9a wTFO3an41Nc5sI8YkmX0X4hnYPE6eQ8AkquGgIiGpveYNAUdGDQj0R74MzpcMFUD FWmhyb6mZu5elpdlqLjtkUFJ321ErZpcYHb60Df4mTX2kFZWAlyQBqCy6dYVhIRE bCo7WZ90MSz+OaKAvFhKxHKf4fb+tB+RXMgr7g= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:to:cc :from:subject:date:mime-version:content-type :content-transfer-encoding:message-id; s=default; bh=+NCbjsbUmdB LrsgZJjhH4Kuo2Zk=; b=atX5+oSHhP12AuFJW0aN11ziIpraJs3GrGuvIHt3533 1KWG9/UZI9by63a/h5kbIrYU5c4P4Ce/8h4lS/J/NusQ3GkImbqFJ1iNjDGu7rN7 yQ+VaEiNFyCDbqJxtsWW60ymnEG+YqRyewu8eJUB3ayIzFtxeC5pTznwAlcQTO3c = Received: (qmail 55317 invoked by alias); 14 May 2018 15:00:44 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Received: (qmail 55207 invoked by uid 89); 14 May 2018 15:00:36 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-12.1 required=5.0 tests=BAYES_00, GIT_PATCH_2, GIT_PATCH_3, KAM_NUMSUBJECT, RCVD_IN_DNSWL_LOW, SPF_PASS, TIME_LIMIT_EXCEEDED autolearn=unavailable version=3.3.2 spammy= X-HELO: mx0a-001b2d01.pphosted.com Received: from mx0b-001b2d01.pphosted.com (HELO mx0a-001b2d01.pphosted.com) (148.163.158.5) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Mon, 14 May 2018 15:00:25 +0000 Received: from pps.filterd (m0098421.ppops.net [127.0.0.1]) by mx0a-001b2d01.pphosted.com (8.16.0.22/8.16.0.22) with SMTP id w4EF07JP038986 for ; Mon, 14 May 2018 11:00:20 -0400 Received: from e12.ny.us.ibm.com (e12.ny.us.ibm.com [129.33.205.202]) by mx0a-001b2d01.pphosted.com with ESMTP id 2hy9qbgvbf-1 (version=TLSv1.2 cipher=AES256-GCM-SHA384 bits=256 verify=NOT) for ; Mon, 14 May 2018 11:00:10 -0400 Received: from localhost by e12.ny.us.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Mon, 14 May 2018 10:59:30 -0400 Received: from b01cxnp22036.gho.pok.ibm.com (9.57.198.26) by e12.ny.us.ibm.com (146.89.104.199) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; Mon, 14 May 2018 10:59:26 -0400 Received: from b01ledav005.gho.pok.ibm.com (b01ledav005.gho.pok.ibm.com [9.57.199.110]) by b01cxnp22036.gho.pok.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id w4EExQh158130588; Mon, 14 May 2018 14:59:26 GMT Received: from b01ledav005.gho.pok.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id 1D98CAE04B; Mon, 14 May 2018 11:01:26 -0400 (EDT) Received: from kelvins-mbp-2.rchland.ibm.com (unknown [9.10.86.22]) by b01ledav005.gho.pok.ibm.com (Postfix) with ESMTP id D31E4AE034; Mon, 14 May 2018 11:01:25 -0400 (EDT) To: gcc-patches@gcc.gnu.org Cc: segher@gcc.gnu.org From: Kelvin Nilsen Subject: [PATCH, rs6000] Improved Documentation of Built-in Functions Part 2 Date: Mon, 14 May 2018 09:59:25 -0500 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.13; rv:52.0) Gecko/20100101 Thunderbird/52.7.0 MIME-Version: 1.0 X-TM-AS-GCONF: 00 x-cbid: 18051414-0048-0000-0000-0000026CC8A3 X-IBM-SpamModules-Scores: X-IBM-SpamModules-Versions: BY=3.00009024; HX=3.00000241; KW=3.00000007; PH=3.00000004; SC=3.00000260; SDB=6.01032212; UDB=6.00527681; IPR=6.00811343; MB=3.00021107; MTD=3.00000008; XFM=3.00000015; UTC=2018-05-14 14:59:28 X-IBM-AV-DETECTION: SAVI=unused REMOTE=unused XFE=unused x-cbparentid: 18051414-0049-0000-0000-0000451E2786 Message-Id: <4819b798-3dce-10a5-a5e2-03c2a7d473df@linux.ibm.com> X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:, , definitions=2018-05-14_04:, , signatures=0 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 priorityscore=1501 malwarescore=0 suspectscore=1 phishscore=0 bulkscore=0 spamscore=0 clxscore=1011 lowpriorityscore=0 impostorscore=0 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1709140000 definitions=main-1805140155 The focus of this patch is to restructure the section headers within the PowerPC portion of the extend.texi documentation file. Restructuring section headers prepares the foundation for subsequent documentation improvements which will be delivered in follow-on patches. I have bootstrapped and regression tested without regressions on powerpc64le-unknown-linux (P8). I have also confirmed that this patch builds on powerpc-linux (P7 bing-endian, both -m32 and -m64 target options). I have also built and reviewed the gcc.pdf file. Is this ok for the trunk? gcc/ChangeLog: 2018-05-14 Kelvin Nilsen * doc/extend.texi (Basic PowerPC Built-in Functions): Rename this subsection to be "PowerPC Built-in Functions". (PowerPC Altivec/VSX Built-in Functions): Change this subsection to subsubsection and rename as "PowerPC Altivec Built-in Functions Available on ISA 2.05". (PowerPC Built-in Functions Available on ISA 2.06): New subsubsection. (PowerPC Built-in Functions Available on ISA 2.07): Likewise. (PowerPC Built-in Functions Available on ISA 3.0): Likewise. (PowerPC Hardware Transactional Memory Built-in Functions): Split this subsection into two subsubsections named "Basic PowerPC Hardware Transactional Memory Built-in Functions" and "PowerPC Hardware Transactional Memory Built-in Functions". Move the basic subsubsection forward to be next to other basic subsubsections. (PowerPC Atomic Memory Operation Functions): Change this subsection to subsubsection. Index: gcc/doc/extend.texi =================================================================== --- gcc/doc/extend.texi (revision 260182) +++ gcc/doc/extend.texi (working copy) @@ -12477,10 +12477,7 @@ instructions, but allow the compiler to schedule t * MSP430 Built-in Functions:: * NDS32 Built-in Functions:: * picoChip Built-in Functions:: -* Basic PowerPC Built-in Functions:: -* PowerPC AltiVec/VSX Built-in Functions:: -* PowerPC Hardware Transactional Memory Built-in Functions:: -* PowerPC Atomic Memory Operation Functions:: +* PowerPC Built-in Functions:: * RX Built-in Functions:: * S/390 System z Built-in Functions:: * SH Built-in Functions:: @@ -15536,25 +15533,35 @@ implementing assertions. @end table -@node Basic PowerPC Built-in Functions -@subsection Basic PowerPC Built-in Functions +@node PowerPC Built-in Functions +@subsection PowerPC Built-in Functions +This section describes built-in functions that are supported for +various configurations of the PowerPC processor. + @menu * Basic PowerPC Built-in Functions Available on all Configurations:: * Basic PowerPC Built-in Functions Available on ISA 2.05:: * Basic PowerPC Built-in Functions Available on ISA 2.06:: * Basic PowerPC Built-in Functions Available on ISA 2.07:: +* Basic PowerPC Hardware Transactional Memory Built-in Functions:: * Basic PowerPC Built-in Functions Available on ISA 3.0:: +* PowerPC AltiVec Built-in Functions Available on ISA 2.05:: +* PowerPC AltiVec Built-in Functions Available on ISA 2.06:: +* PowerPC AltiVec Built-in Functions Available on ISA 2.07:: +* PowerPC AltiVec Built-in Functions Available on ISA 3.0:: +* PowerPC Hardware Transactional Memory Built-in Functions:: +* PowerPC Atomic Memory Operation Functions:: @end menu -This section describes PowerPC built-in functions that do not require -the inclusion of any special header files to declare prototypes or -provide macro definitions. The sections that follow describe -additional PowerPC built-in functions. - @node Basic PowerPC Built-in Functions Available on all Configurations @subsubsection Basic PowerPC Built-in Functions Available on all Configurations +This section describes PowerPC built-in functions that are supported +on all configurations and do not require +the inclusion of any special header files to declare prototypes or +provide macro definitions. + @deftypefn {Built-in Function} void __builtin_cpu_init (void) This function is a @code{nop} on the PowerPC platform and is included solely to maintain API compatibility with the x86 builtins. @@ -15889,6 +15896,150 @@ addition to the @option{-mpower8-fusion}, @option{ This section intentionally empty. +@node Basic PowerPC Hardware Transactional Memory Built-in Functions +@subsubsection Basic PowerPC Hardware Transactional Memory Built-in Functions + +The following basic built-in functions are available with +@option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later. +They all generate the machine instruction that is part of the name. + +The Hardware Transactional Memory (HTM) builtins (with the exception +of @code{__builtin_tbegin}) return +the full 4-bit condition register value set by their associated hardware +instruction. The header file @code{htmintrin.h} defines some macros that can +be used to decipher the return value. The @code{__builtin_tbegin} builtin +returns a simple true or false value depending on whether a transaction was +successfully started or not. The arguments of the builtins match exactly the +type and order of the associated hardware instruction's operands, except for +the @code{__builtin_tcheck} builtin, which does not take any input arguments. +Refer to the ISA manual for a description of each instruction's operands. + +@smallexample +unsigned int __builtin_tbegin (unsigned int) +unsigned int __builtin_tend (unsigned int) + +unsigned int __builtin_tabort (unsigned int) +unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int) +unsigned int __builtin_tabortdci (unsigned int, unsigned int, int) +unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int) +unsigned int __builtin_tabortwci (unsigned int, unsigned int, int) + +unsigned int __builtin_tcheck (void) +unsigned int __builtin_treclaim (unsigned int) +unsigned int __builtin_trechkpt (void) +unsigned int __builtin_tsr (unsigned int) +@end smallexample + +In addition to the above HTM built-ins, we have added built-ins for +some common extended mnemonics of the HTM instructions: + +@smallexample +unsigned int __builtin_tendall (void) +unsigned int __builtin_tresume (void) +unsigned int __builtin_tsuspend (void) +@end smallexample + +Note that the semantics of the above HTM builtins are required to mimic +the locking semantics used for critical sections. Builtins that are used +to create a new transaction or restart a suspended transaction must have +lock acquisition like semantics while those builtins that end or suspend a +transaction must have lock release like semantics. Specifically, this must +mimic lock semantics as specified by C++11, for example: Lock acquisition is +as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE) +that returns 0, and lock release is as-if an execution of +__atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an +implicit implementation-defined lock used for all transactions. The HTM +instructions associated with with the builtins inherently provide the +correct acquisition and release hardware barriers required. However, +the compiler must also be prohibited from moving loads and stores across +the builtins in a way that would violate their semantics. This has been +accomplished by adding memory barriers to the associated HTM instructions +(which is a conservative approach to provide acquire and release semantics). +Earlier versions of the compiler did not treat the HTM instructions as +memory barriers. A @code{__TM_FENCE__} macro has been added, which can +be used to determine whether the current compiler treats HTM instructions +as memory barriers or not. This allows the user to explicitly add memory +barriers to their code when using an older version of the compiler. + +The following set of built-in functions are available to gain access +to the HTM specific special purpose registers. + +@smallexample +unsigned long __builtin_get_texasr (void) +unsigned long __builtin_get_texasru (void) +unsigned long __builtin_get_tfhar (void) +unsigned long __builtin_get_tfiar (void) + +void __builtin_set_texasr (unsigned long); +void __builtin_set_texasru (unsigned long); +void __builtin_set_tfhar (unsigned long); +void __builtin_set_tfiar (unsigned long); +@end smallexample + +Example usage of these low level built-in functions may look like: + +@smallexample +#include + +int num_retries = 10; + +while (1) + @{ + if (__builtin_tbegin (0)) + @{ + /* Transaction State Initiated. */ + if (is_locked (lock)) + __builtin_tabort (0); + ... transaction code... + __builtin_tend (0); + break; + @} + else + @{ + /* Transaction State Failed. Use locks if the transaction + failure is "persistent" or we've tried too many times. */ + if (num_retries-- <= 0 + || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ())) + @{ + acquire_lock (lock); + ... non transactional fallback path... + release_lock (lock); + break; + @} + @} + @} +@end smallexample + +One final built-in function has been added that returns the value of +the 2-bit Transaction State field of the Machine Status Register (MSR) +as stored in @code{CR0}. + +@smallexample +unsigned long __builtin_ttest (void) +@end smallexample + +This built-in can be used to determine the current transaction state +using the following code example: + +@smallexample +#include + +unsigned char tx_state = _HTM_STATE (__builtin_ttest ()); + +if (tx_state == _HTM_TRANSACTIONAL) + @{ + /* Code to use in transactional state. */ + @} +else if (tx_state == _HTM_NONTRANSACTIONAL) + @{ + /* Code to use in non-transactional state. */ + @} +else if (tx_state == _HTM_SUSPENDED) + @{ + /* Code to use in transaction suspended state. */ + @} +@end smallexample + @node Basic PowerPC Built-in Functions Available on ISA 3.0 @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.0 @@ -16033,11 +16184,9 @@ The @code{__builtin_dfp_dtstsfi_ov_dd} and require that the type of the @code{value} argument be @code{__Decimal64} and @code{__Decimal128} respectively. +@node PowerPC AltiVec Built-in Functions Available on ISA 2.05 +@subsubsection PowerPC AltiVec Built-in Functions on ISA 2.05 - -@node PowerPC AltiVec/VSX Built-in Functions -@subsection PowerPC AltiVec Built-in Functions - GCC provides an interface for the PowerPC family of processors to access the AltiVec operations described in Motorola's AltiVec Programming Interface Manual. The interface is made available by including @@ -19500,160 +19649,20 @@ void vec_xst (vector char, int, char *); void vec_xst (vector unsigned char, int, vector unsigned char *); void vec_xst (vector unsigned char, int, unsigned char *); -@node PowerPC Hardware Transactional Memory Built-in Functions -@subsection PowerPC Hardware Transactional Memory Built-in Functions -GCC provides two interfaces for accessing the Hardware Transactional -Memory (HTM) instructions available on some of the PowerPC family -of processors (eg, POWER8). The two interfaces come in a low level -interface, consisting of built-in functions specific to PowerPC and a -higher level interface consisting of inline functions that are common -between PowerPC and S/390. +@node PowerPC AltiVec Built-in Functions Available on ISA 2.06 +@subsubsection PowerPC AltiVec Built-in Functions on ISA 2.06 -@subsubsection PowerPC HTM Low Level Built-in Functions +@node PowerPC AltiVec Built-in Functions Available on ISA 2.07 +@subsubsection PowerPC AltiVec Built-in Functions on ISA 2.07 -The following low level built-in functions are available with -@option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later. -They all generate the machine instruction that is part of the name. +@node PowerPC AltiVec Built-in Functions Available on ISA 3.0 +@subsubsection PowerPC AltiVec Built-in Functions on ISA 3.0 -The HTM builtins (with the exception of @code{__builtin_tbegin}) return -the full 4-bit condition register value set by their associated hardware -instruction. The header file @code{htmintrin.h} defines some macros that can -be used to decipher the return value. The @code{__builtin_tbegin} builtin -returns a simple true or false value depending on whether a transaction was -successfully started or not. The arguments of the builtins match exactly the -type and order of the associated hardware instruction's operands, except for -the @code{__builtin_tcheck} builtin, which does not take any input arguments. -Refer to the ISA manual for a description of each instruction's operands. +@node PowerPC Hardware Transactional Memory Built-in Functions +@subsubsection PowerPC Hardware Transactional Memory Built-in Functions -@smallexample -unsigned int __builtin_tbegin (unsigned int) -unsigned int __builtin_tend (unsigned int) - -unsigned int __builtin_tabort (unsigned int) -unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int) -unsigned int __builtin_tabortdci (unsigned int, unsigned int, int) -unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int) -unsigned int __builtin_tabortwci (unsigned int, unsigned int, int) - -unsigned int __builtin_tcheck (void) -unsigned int __builtin_treclaim (unsigned int) -unsigned int __builtin_trechkpt (void) -unsigned int __builtin_tsr (unsigned int) -@end smallexample - -In addition to the above HTM built-ins, we have added built-ins for -some common extended mnemonics of the HTM instructions: - -@smallexample -unsigned int __builtin_tendall (void) -unsigned int __builtin_tresume (void) -unsigned int __builtin_tsuspend (void) -@end smallexample - -Note that the semantics of the above HTM builtins are required to mimic -the locking semantics used for critical sections. Builtins that are used -to create a new transaction or restart a suspended transaction must have -lock acquisition like semantics while those builtins that end or suspend a -transaction must have lock release like semantics. Specifically, this must -mimic lock semantics as specified by C++11, for example: Lock acquisition is -as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE) -that returns 0, and lock release is as-if an execution of -__atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an -implicit implementation-defined lock used for all transactions. The HTM -instructions associated with with the builtins inherently provide the -correct acquisition and release hardware barriers required. However, -the compiler must also be prohibited from moving loads and stores across -the builtins in a way that would violate their semantics. This has been -accomplished by adding memory barriers to the associated HTM instructions -(which is a conservative approach to provide acquire and release semantics). -Earlier versions of the compiler did not treat the HTM instructions as -memory barriers. A @code{__TM_FENCE__} macro has been added, which can -be used to determine whether the current compiler treats HTM instructions -as memory barriers or not. This allows the user to explicitly add memory -barriers to their code when using an older version of the compiler. - -The following set of built-in functions are available to gain access -to the HTM specific special purpose registers. - -@smallexample -unsigned long __builtin_get_texasr (void) -unsigned long __builtin_get_texasru (void) -unsigned long __builtin_get_tfhar (void) -unsigned long __builtin_get_tfiar (void) - -void __builtin_set_texasr (unsigned long); -void __builtin_set_texasru (unsigned long); -void __builtin_set_tfhar (unsigned long); -void __builtin_set_tfiar (unsigned long); -@end smallexample - -Example usage of these low level built-in functions may look like: - -@smallexample -#include - -int num_retries = 10; - -while (1) - @{ - if (__builtin_tbegin (0)) - @{ - /* Transaction State Initiated. */ - if (is_locked (lock)) - __builtin_tabort (0); - ... transaction code... - __builtin_tend (0); - break; - @} - else - @{ - /* Transaction State Failed. Use locks if the transaction - failure is "persistent" or we've tried too many times. */ - if (num_retries-- <= 0 - || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ())) - @{ - acquire_lock (lock); - ... non transactional fallback path... - release_lock (lock); - break; - @} - @} - @} -@end smallexample - -One final built-in function has been added that returns the value of -the 2-bit Transaction State field of the Machine Status Register (MSR) -as stored in @code{CR0}. - -@smallexample -unsigned long __builtin_ttest (void) -@end smallexample - -This built-in can be used to determine the current transaction state -using the following code example: - -@smallexample -#include - -unsigned char tx_state = _HTM_STATE (__builtin_ttest ()); - -if (tx_state == _HTM_TRANSACTIONAL) - @{ - /* Code to use in transactional state. */ - @} -else if (tx_state == _HTM_NONTRANSACTIONAL) - @{ - /* Code to use in non-transactional state. */ - @} -else if (tx_state == _HTM_SUSPENDED) - @{ - /* Code to use in transaction suspended state. */ - @} -@end smallexample - -@subsubsection PowerPC HTM High Level Inline Functions - -The following high level HTM interface is made available by including +The Hardware Transactional Memory (HTM) functions +described in this section are made available by including @code{} and using @option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later. This interface is common between PowerPC and S/390, allowing users to write one HTM source implementation that @@ -19718,7 +19727,7 @@ while (1) @end smallexample @node PowerPC Atomic Memory Operation Functions -@subsection PowerPC Atomic Memory Operation Functions +@subsubsection PowerPC Atomic Memory Operation Functions ISA 3.0 of the PowerPC added new atomic memory operation (amo) instructions. GCC provides support for these instructions in 64-bit environments. All of the functions are declared in the include file