[doc] update documentation of x86 -mcx16 option

Hi,

This patch fixes a few issues in documentation of -mcx16 x86 backend option:

- remove implementor-speak ('oword')
- mention alignment restriction and availability only in 64-bit mode
- improve usage example
    existing documentation uses a really silly example (128-bit integer
    counters), it was apparently taken from Wikipedia back in 2007; today,
    Wikipedia uses a far more realistic example ("This is useful for parallel
    algorithms that use compare and swap on data larger than the size of a
    pointer, common in lock-free and wait-free algorithms")
- mention that the instruction is used when expanding __sync builtins, and NOT
  used when expanding __atomic builtins. This is a quiet change in GCC-7, GCC-6
  and earlier used this instruction for __atomic builtins too.

OK for trunk?  For the gcc-7 branch?

Thanks.
Alexander

	* doc/invoke.texi (mcx16): Rewrite.

On 05/26/2017 12:48 PM, Alexander Monakov wrote:
> Hi,
>
> This patch fixes a few issues in documentation of -mcx16 x86 backend option:
>
> - remove implementor-speak ('oword')
> - mention alignment restriction and availability only in 64-bit mode
> - improve usage example
>      existing documentation uses a really silly example (128-bit integer
>      counters), it was apparently taken from Wikipedia back in 2007; today,
>      Wikipedia uses a far more realistic example ("This is useful for parallel
>      algorithms that use compare and swap on data larger than the size of a
>      pointer, common in lock-free and wait-free algorithms")
> - mention that the instruction is used when expanding __sync builtins, and NOT
>    used when expanding __atomic builtins. This is a quiet change in GCC-7, GCC-6
>    and earlier used this instruction for __atomic builtins too.
>
> OK for trunk?  For the gcc-7 branch?
>
> Thanks.
> Alexander
>
> 	* doc/invoke.texi (mcx16): Rewrite.
>
> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> index 3308b63..0b3c296 100644
> --- a/gcc/doc/invoke.texi
> +++ b/gcc/doc/invoke.texi
> @@ -25160,13 +25160,12 @@ This option instructs GCC to use 128-bit AVX instructions instead of
>
>   @item -mcx16
>   @opindex mcx16
> -This option enables GCC to generate @code{CMPXCHG16B} instructions.
> -@code{CMPXCHG16B} allows for atomic operations on 128-bit double quadword
> -(or oword) data types.
> -This is useful for high-resolution counters that can be updated
> -by multiple processors (or cores).  This instruction is generated as part of
> -atomic built-in functions: see @ref{__sync Builtins} or
> -@ref{__atomic Builtins} for details.
> +This option enables GCC to generate @code{CMPXCHG16B} instructions in 64-bit
> +code to implement compare-and-exchange operations on 16-byte aligned 128-bit
> +objects.  This is useful for atomic updates of data structures exceeding one
> +machine word in size.  The compiler uses this instruction to implement
> +@ref{__sync Builtins}.  However, for @ref{__atomic Builtins} operating on
> +128-bit integers, a library call is always used.
>
>   @item -msahf
>   @opindex msahf
>

This is good, thanks.  I think it's fine for GCC 7 branch as well (I 
guess it's not a regression fix, but it seems unlikely to break anything).

-Sandra

On Sun, 4 Jun 2017, Sandra Loosemore wrote:
> This is good, thanks.  I think it's fine for GCC 7 branch as well (I guess
> it's not a regression fix, but it seems unlikely to break anything).

Plus the regression-only rule does not apply for docs. ;-)

Gerald