[PATCH][doc] Update __sync builtins, preferring __atomics.

[PATCH][doc] Update __sync builtins, preferring __atomics.

[Matthew Wahab]

[-- Attachment #1: Type: text/plain, Size: 614 bytes --]

Hello,

The documentation for the __sync builtins calls them legacy but doesn't clearly
say that the __atomic builtins should be prefered. This patch adds a statement
to that effect. It also simplifies some of the text and weakens a suggestion of
future change in the the __syncs behaviour.
	
Tested by looking at the html and info files.

Ok for trunk?
Matthew

2015-04-14  Matthew Wahab  <matthew.wahab@arm.com>

	* doc/extend.texi (__sync Builtins): Simplify some text.  Update
	details about implementation.  Make clear preference for __atomic
	builtins.  Reduce possibility of future change.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: syncsdoc.patch --]
[-- Type: text/x-patch; name=syncsdoc.patch, Size: 2475 bytes --]

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index d4c41c6..7470e40 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -8213,15 +8213,19 @@ identifier, or a sequence of member accesses and array references.
 The following built-in functions
 are intended to be compatible with those described
 in the @cite{Intel Itanium Processor-specific Application Binary Interface},
-section 7.4.  As such, they depart from the normal GCC practice of using
-the @samp{__builtin_} prefix, and further that they are overloaded such that
-they work on multiple types.
+section 7.4.  As such, they depart from normal GCC practice by not using
+the @samp{__builtin_} prefix and also by being overloaded so that they
+work on multiple types.
 
 The definition given in the Intel documentation allows only for the use of
-the types @code{int}, @code{long}, @code{long long} as well as their unsigned
+the types @code{int}, @code{long}, @code{long long} or their unsigned
 counterparts.  GCC allows any integral scalar or pointer type that is
 1, 2, 4 or 8 bytes in length.
 
+These functions are implemented in terms of the @samp{__atomic}
+builtins (@pxref{__atomic Builtins}).  They should not be used for new
+code which should use the @samp{__atomic} builtins instead.
+
 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
@@ -8243,11 +8247,10 @@ after the operation.
 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 @emph{only} the
-following variables are protected, or it could mean that these variables
-should in addition be protected.  At present GCC ignores this list and
-protects all variables that are globally accessible.  If in the future
-we make some use of this list, an empty list will continue to mean all
-globally accessible variables.
+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.
 
 @table @code
 @item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...)

Re: [PATCH][doc] Update __sync builtins, preferring __atomics.

[Jeff Law]

On 04/14/2015 05:11 AM, Matthew Wahab wrote:
> Hello,
>
> The documentation for the __sync builtins calls them legacy but doesn't
> clearly
> say that the __atomic builtins should be prefered. This patch adds a
> statement
> to that effect. It also simplifies some of the text and weakens a
> suggestion of
> future change in the the __syncs behaviour.
>
> Tested by looking at the html and info files.
>
> Ok for trunk?
> Matthew
>
> 2015-04-14  Matthew Wahab  <matthew.wahab@arm.com>
>
>      * doc/extend.texi (__sync Builtins): Simplify some text.  Update
>      details about implementation.  Make clear preference for __atomic
>      builtins.  Reduce possibility of future change.
OK.
jeff

Re: [PATCH][doc] Update __sync builtins, preferring __atomics.

[Matthew Wahab]

Committed with a typo-fix in the text, /an list/a list/, and in the change log
/details about implementation/details about the implementation/.

2015-04-14  Matthew Wahab  <matthew.wahab@arm.com>

	* doc/extend.texi (__sync Builtins): Simplify some text.  Update
	details about the implementation.  Make clear preference for
	__atomic builtins.  Reduce possibility of future change.

Matthew