[PATCH, rs6000] Improved Documentation of Built-in Functions Part 2
Kelvin Nilsen
kdnilsen@linux.ibm.com
Mon May 14 15:08:00 GMT 2018
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 <kelvin@gcc.gnu.org>
* 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 <htmintrin.h>
+
+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 <htmintrin.h>
+
+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 <htmintrin.h>
-
-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 <htmintrin.h>
-
-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{<htmxlintrin.h>} 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
More information about the Gcc-patches
mailing list