diff options
Diffstat (limited to 'share/doc/gcc/_005f_005fsync-Builtins.html')
| -rw-r--r-- | share/doc/gcc/_005f_005fsync-Builtins.html | 236 |
1 files changed, 236 insertions, 0 deletions
diff --git a/share/doc/gcc/_005f_005fsync-Builtins.html b/share/doc/gcc/_005f_005fsync-Builtins.html new file mode 100644 index 0000000..70a2a2f --- /dev/null +++ b/share/doc/gcc/_005f_005fsync-Builtins.html @@ -0,0 +1,236 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- This file documents the use of the GNU compilers. + +Copyright (C) 1988-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Funding Free Software", the Front-Cover +Texts being (a) (see below), and with the Back-Cover Texts being (b) +(see below). A copy of the license is included in the section entitled +"GNU Free Documentation License". + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>Using the GNU Compiler Collection (GCC): __sync Builtins</title> + +<meta name="description" content="Using the GNU Compiler Collection (GCC): __sync Builtins"> +<meta name="keywords" content="Using the GNU Compiler Collection (GCC): __sync Builtins"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Indices.html#Indices" rel="index" title="Indices"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="C-Extensions.html#C-Extensions" rel="up" title="C Extensions"> +<link href="_005f_005fatomic-Builtins.html#g_t_005f_005fatomic-Builtins" rel="next" title="__atomic Builtins"> +<link href="Offsetof.html#Offsetof" rel="previous" title="Offsetof"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en_US" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="g_t_005f_005fsync-Builtins"></a> +<div class="header"> +<p> +Next: <a href="_005f_005fatomic-Builtins.html#g_t_005f_005fatomic-Builtins" accesskey="n" rel="next">__atomic Builtins</a>, Previous: <a href="Offsetof.html#Offsetof" accesskey="p" rel="previous">Offsetof</a>, Up: <a href="C-Extensions.html#C-Extensions" accesskey="u" rel="up">C Extensions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html#Indices" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Legacy-_005f_005fsync-Built_002din-Functions-for-Atomic-Memory-Access"></a> +<h3 class="section">6.54 Legacy <code>__sync</code> Built-in Functions for Atomic Memory Access</h3> + +<p>The following built-in functions +are intended to be compatible with those described +in the <cite>Intel Itanium Processor-specific Application Binary Interface</cite>, +section 7.4. As such, they depart from normal GCC practice by not using +the ‘<samp>__builtin_</samp>’ prefix and also by being overloaded so that they +work on multiple types. +</p> +<p>The definition given in the Intel documentation allows only for the use of +the types <code>int</code>, <code>long</code>, <code>long long</code> or their unsigned +counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in +size other than the C type <code>_Bool</code> or the C++ type <code>bool</code>. +Operations on pointer arguments are performed as if the operands were +of the <code>uintptr_t</code> type. That is, they are not scaled by the size +of the type to which the pointer points. +</p> +<p>These functions are implemented in terms of the ‘<samp>__atomic</samp>’ +builtins (see <a href="_005f_005fatomic-Builtins.html#g_t_005f_005fatomic-Builtins">__atomic Builtins</a>). They should not be used for new +code which should use the ‘<samp>__atomic</samp>’ builtins instead. +</p> +<p>Not all operations are supported by all target processors. If a particular +operation cannot be implemented on the target processor, a warning is +generated and a call to an external function is generated. The external +function carries the same name as the built-in version, +with an additional suffix +‘<samp>_<var>n</var></samp>’ where <var>n</var> is the size of the data type. +</p> + +<p>In most cases, these built-in functions are considered a <em>full barrier</em>. +That is, +no memory operand is moved across the operation, either forward or +backward. Further, instructions are issued as necessary to prevent the +processor from speculating loads across the operation and from queuing stores +after the operation. +</p> +<p>All of the routines are described in the Intel documentation to take +“an optional list of variables protected by the memory barrier”. It’s +not clear what is meant by that; it could mean that <em>only</em> the +listed variables are protected, or it could mean a list of additional +variables to be protected. The list is ignored by GCC which treats it as +empty. GCC interprets an empty list as meaning that all globally +accessible variables should be protected. +</p> +<dl> +<dt><a name="index-_005f_005fsync_005ffetch_005fand_005fadd"></a>Built-in Function: <em><var>type</var></em> <strong>__sync_fetch_and_add</strong> <em>(<var>type</var> *ptr, <var>type</var> value, ...)</em></dt> +<dt><a name="index-_005f_005fsync_005ffetch_005fand_005fsub"></a>Built-in Function: <em><var>type</var></em> <strong>__sync_fetch_and_sub</strong> <em>(<var>type</var> *ptr, <var>type</var> value, ...)</em></dt> +<dt><a name="index-_005f_005fsync_005ffetch_005fand_005for"></a>Built-in Function: <em><var>type</var></em> <strong>__sync_fetch_and_or</strong> <em>(<var>type</var> *ptr, <var>type</var> value, ...)</em></dt> +<dt><a name="index-_005f_005fsync_005ffetch_005fand_005fand"></a>Built-in Function: <em><var>type</var></em> <strong>__sync_fetch_and_and</strong> <em>(<var>type</var> *ptr, <var>type</var> value, ...)</em></dt> +<dt><a name="index-_005f_005fsync_005ffetch_005fand_005fxor"></a>Built-in Function: <em><var>type</var></em> <strong>__sync_fetch_and_xor</strong> <em>(<var>type</var> *ptr, <var>type</var> value, ...)</em></dt> +<dt><a name="index-_005f_005fsync_005ffetch_005fand_005fnand"></a>Built-in Function: <em><var>type</var></em> <strong>__sync_fetch_and_nand</strong> <em>(<var>type</var> *ptr, <var>type</var> value, ...)</em></dt> +<dd><p>These built-in functions perform the operation suggested by the name, and +returns the value that had previously been in memory. That is, operations +on integer operands have the following semantics. Operations on pointer +arguments are performed as if the operands were of the <code>uintptr_t</code> +type. That is, they are not scaled by the size of the type to which +the pointer points. +</p> +<div class="smallexample"> +<pre class="smallexample">{ tmp = *ptr; *ptr <var>op</var>= value; return tmp; } +{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; } // nand +</pre></div> + +<p>The object pointed to by the first argument must be of integer or pointer +type. It must not be a boolean type. +</p> +<p><em>Note:</em> GCC 4.4 and later implement <code>__sync_fetch_and_nand</code> +as <code>*ptr = ~(tmp & value)</code> instead of <code>*ptr = ~tmp & value</code>. +</p></dd></dl> + +<dl> +<dt><a name="index-_005f_005fsync_005fadd_005fand_005ffetch"></a>Built-in Function: <em><var>type</var></em> <strong>__sync_add_and_fetch</strong> <em>(<var>type</var> *ptr, <var>type</var> value, ...)</em></dt> +<dt><a name="index-_005f_005fsync_005fsub_005fand_005ffetch"></a>Built-in Function: <em><var>type</var></em> <strong>__sync_sub_and_fetch</strong> <em>(<var>type</var> *ptr, <var>type</var> value, ...)</em></dt> +<dt><a name="index-_005f_005fsync_005for_005fand_005ffetch"></a>Built-in Function: <em><var>type</var></em> <strong>__sync_or_and_fetch</strong> <em>(<var>type</var> *ptr, <var>type</var> value, ...)</em></dt> +<dt><a name="index-_005f_005fsync_005fand_005fand_005ffetch"></a>Built-in Function: <em><var>type</var></em> <strong>__sync_and_and_fetch</strong> <em>(<var>type</var> *ptr, <var>type</var> value, ...)</em></dt> +<dt><a name="index-_005f_005fsync_005fxor_005fand_005ffetch"></a>Built-in Function: <em><var>type</var></em> <strong>__sync_xor_and_fetch</strong> <em>(<var>type</var> *ptr, <var>type</var> value, ...)</em></dt> +<dt><a name="index-_005f_005fsync_005fnand_005fand_005ffetch"></a>Built-in Function: <em><var>type</var></em> <strong>__sync_nand_and_fetch</strong> <em>(<var>type</var> *ptr, <var>type</var> value, ...)</em></dt> +<dd><p>These built-in functions perform the operation suggested by the name, and +return the new value. That is, operations on integer operands have +the following semantics. Operations on pointer operands are performed as +if the operand’s type were <code>uintptr_t</code>. +</p> +<div class="smallexample"> +<pre class="smallexample">{ *ptr <var>op</var>= value; return *ptr; } +{ *ptr = ~(*ptr & value); return *ptr; } // nand +</pre></div> + +<p>The same constraints on arguments apply as for the corresponding +<code>__sync_op_and_fetch</code> built-in functions. +</p> +<p><em>Note:</em> GCC 4.4 and later implement <code>__sync_nand_and_fetch</code> +as <code>*ptr = ~(*ptr & value)</code> instead of +<code>*ptr = ~*ptr & value</code>. +</p></dd></dl> + +<dl> +<dt><a name="index-_005f_005fsync_005fbool_005fcompare_005fand_005fswap"></a>Built-in Function: <em>bool</em> <strong>__sync_bool_compare_and_swap</strong> <em>(<var>type</var> *ptr, <var>type</var> oldval, <var>type</var> newval, ...)</em></dt> +<dt><a name="index-_005f_005fsync_005fval_005fcompare_005fand_005fswap"></a>Built-in Function: <em><var>type</var></em> <strong>__sync_val_compare_and_swap</strong> <em>(<var>type</var> *ptr, <var>type</var> oldval, <var>type</var> newval, ...)</em></dt> +<dd><p>These built-in functions perform an atomic compare and swap. +That is, if the current +value of <code>*<var>ptr</var></code> is <var>oldval</var>, then write <var>newval</var> into +<code>*<var>ptr</var></code>. +</p> +<p>The “bool” version returns <code>true</code> if the comparison is successful and +<var>newval</var> is written. The “val” version returns the contents +of <code>*<var>ptr</var></code> before the operation. +</p></dd></dl> + +<dl> +<dt><a name="index-_005f_005fsync_005fsynchronize"></a>Built-in Function: <em>void</em> <strong>__sync_synchronize</strong> <em>(...)</em></dt> +<dd><p>This built-in function issues a full memory barrier. +</p></dd></dl> + +<dl> +<dt><a name="index-_005f_005fsync_005flock_005ftest_005fand_005fset"></a>Built-in Function: <em><var>type</var></em> <strong>__sync_lock_test_and_set</strong> <em>(<var>type</var> *ptr, <var>type</var> value, ...)</em></dt> +<dd><p>This built-in function, as described by Intel, is not a traditional test-and-set +operation, but rather an atomic exchange operation. It writes <var>value</var> +into <code>*<var>ptr</var></code>, and returns the previous contents of +<code>*<var>ptr</var></code>. +</p> +<p>Many targets have only minimal support for such locks, and do not support +a full exchange operation. In this case, a target may support reduced +functionality here by which the <em>only</em> valid value to store is the +immediate constant 1. The exact value actually stored in <code>*<var>ptr</var></code> +is implementation defined. +</p> +<p>This built-in function is not a full barrier, +but rather an <em>acquire barrier</em>. +This means that references after the operation cannot move to (or be +speculated to) before the operation, but previous memory stores may not +be globally visible yet, and previous memory loads may not yet be +satisfied. +</p></dd></dl> + +<dl> +<dt><a name="index-_005f_005fsync_005flock_005frelease"></a>Built-in Function: <em>void</em> <strong>__sync_lock_release</strong> <em>(<var>type</var> *ptr, ...)</em></dt> +<dd><p>This built-in function releases the lock acquired by +<code>__sync_lock_test_and_set</code>. +Normally this means writing the constant 0 to <code>*<var>ptr</var></code>. +</p> +<p>This built-in function is not a full barrier, +but rather a <em>release barrier</em>. +This means that all previous memory stores are globally visible, and all +previous memory loads have been satisfied, but following memory reads +are not prevented from being speculated to before the barrier. +</p></dd></dl> + +<hr> +<div class="header"> +<p> +Next: <a href="_005f_005fatomic-Builtins.html#g_t_005f_005fatomic-Builtins" accesskey="n" rel="next">__atomic Builtins</a>, Previous: <a href="Offsetof.html#Offsetof" accesskey="p" rel="previous">Offsetof</a>, Up: <a href="C-Extensions.html#C-Extensions" accesskey="u" rel="up">C Extensions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html#Indices" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |