[PATCH] Documentation: atomic_ops: use {READ,WRITE}_ONCE()

[PATCH] Documentation: atomic_ops: use {READ,WRITE}_ONCE()

[Mark Rutland]

While the {READ,WRITE}_ONCE() macros should be used in preference to
ACCESS_ONCE(), the atomic documentation uses the latter exclusively.

To point people in the right direction, and as a step towards the
eventual removal of ACCESS_ONCE(), update the documentation to use the
{READ,WRITE}_ONCE() macros as appropriate.

Signed-off-by: Mark Rutland <mark.rutland@arm.com>
Cc: Boqun Feng <boqun.feng@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Will Deacon <will.deacon@arm.com>
Cc: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
---
 Documentation/atomic_ops.txt | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/atomic_ops.txt b/Documentation/atomic_ops.txt
index c9d1cac..a1b9a54 100644
--- a/Documentation/atomic_ops.txt
+++ b/Documentation/atomic_ops.txt
@@ -90,10 +90,10 @@ compiler optimizes the section accessing atomic_t variables.
 
 Properly aligned pointers, longs, ints, and chars (and unsigned
 equivalents) may be atomically loaded from and stored to in the same
-sense as described for atomic_read() and atomic_set().  The ACCESS_ONCE()
-macro should be used to prevent the compiler from using optimizations
-that might otherwise optimize accesses out of existence on the one hand,
-or that might create unsolicited accesses on the other.
+sense as described for atomic_read() and atomic_set().  The READ_ONCE()
+and WRITE_ONCE() macros should be used to prevent the compiler from using
+optimizations that might otherwise optimize accesses out of existence on
+the one hand, or that might create unsolicited accesses on the other.
 
 For example consider the following code:
 
@@ -112,7 +112,7 @@ the following:
 If you don't want the compiler to do this (and you probably don't), then
 you should use something like the following:
 
-	while (ACCESS_ONCE(a) < 0)
+	while (READ_ONCE(a) < 0)
 		do_something();
 
 Alternatively, you could place a barrier() call in the loop.
@@ -141,7 +141,7 @@ of registers: reloading from variable a could save a flush to the
 stack and later reload.  To prevent the compiler from attacking your
 code in this manner, write the following:
 
-	tmp_a = ACCESS_ONCE(a);
+	tmp_a = READ_ONCE(a);
 	do_something_with(tmp_a);
 	do_something_else_with(tmp_a);
 
@@ -166,14 +166,14 @@ that expected b to never have the value 42 if a was zero.  To prevent
 the compiler from doing this, write something like:
 
 	if (a)
-		ACCESS_ONCE(b) = 9;
+		WRITE_ONCE(b, 9);
 	else
-		ACCESS_ONCE(b) = 42;
+		WRITE_ONCE(b, 42);
 
 Don't even -think- about doing this without proper use of memory barriers,
 locks, or atomic operations if variable a can change at runtime!
 
-*** WARNING: ACCESS_ONCE() DOES NOT IMPLY A BARRIER! ***
+*** WARNING: READ_ONCE() OR WRITE_ONCE() DO NOT IMPLY A BARRIER! ***
 
 Now, we move onto the atomic operation interfaces typically implemented with
 the help of assembly code.
-- 
1.9.1

Re: [PATCH] Documentation: atomic_ops: use {READ,WRITE}_ONCE()

[Paul E. McKenney]

On Wed, Nov 16, 2016 at 11:13:59AM +0000, Mark Rutland wrote:
> While the {READ,WRITE}_ONCE() macros should be used in preference to
> ACCESS_ONCE(), the atomic documentation uses the latter exclusively.
> 
> To point people in the right direction, and as a step towards the
> eventual removal of ACCESS_ONCE(), update the documentation to use the
> {READ,WRITE}_ONCE() macros as appropriate.
> 
> Signed-off-by: Mark Rutland <mark.rutland@arm.com>
> Cc: Boqun Feng <boqun.feng@gmail.com>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
> Cc: Peter Zijlstra <peterz@infradead.org>
> Cc: Will Deacon <will.deacon@arm.com>
> Cc: linux-doc@vger.kernel.org
> Cc: linux-kernel@vger.kernel.org

Acked-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>

> ---
>  Documentation/atomic_ops.txt | 18 +++++++++---------
>  1 file changed, 9 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/atomic_ops.txt b/Documentation/atomic_ops.txt
> index c9d1cac..a1b9a54 100644
> --- a/Documentation/atomic_ops.txt
> +++ b/Documentation/atomic_ops.txt
> @@ -90,10 +90,10 @@ compiler optimizes the section accessing atomic_t variables.
> 
>  Properly aligned pointers, longs, ints, and chars (and unsigned
>  equivalents) may be atomically loaded from and stored to in the same
> -sense as described for atomic_read() and atomic_set().  The ACCESS_ONCE()
> -macro should be used to prevent the compiler from using optimizations
> -that might otherwise optimize accesses out of existence on the one hand,
> -or that might create unsolicited accesses on the other.
> +sense as described for atomic_read() and atomic_set().  The READ_ONCE()
> +and WRITE_ONCE() macros should be used to prevent the compiler from using
> +optimizations that might otherwise optimize accesses out of existence on
> +the one hand, or that might create unsolicited accesses on the other.
> 
>  For example consider the following code:
> 
> @@ -112,7 +112,7 @@ the following:
>  If you don't want the compiler to do this (and you probably don't), then
>  you should use something like the following:
> 
> -	while (ACCESS_ONCE(a) < 0)
> +	while (READ_ONCE(a) < 0)
>  		do_something();
> 
>  Alternatively, you could place a barrier() call in the loop.
> @@ -141,7 +141,7 @@ of registers: reloading from variable a could save a flush to the
>  stack and later reload.  To prevent the compiler from attacking your
>  code in this manner, write the following:
> 
> -	tmp_a = ACCESS_ONCE(a);
> +	tmp_a = READ_ONCE(a);
>  	do_something_with(tmp_a);
>  	do_something_else_with(tmp_a);
> 
> @@ -166,14 +166,14 @@ that expected b to never have the value 42 if a was zero.  To prevent
>  the compiler from doing this, write something like:
> 
>  	if (a)
> -		ACCESS_ONCE(b) = 9;
> +		WRITE_ONCE(b, 9);
>  	else
> -		ACCESS_ONCE(b) = 42;
> +		WRITE_ONCE(b, 42);
> 
>  Don't even -think- about doing this without proper use of memory barriers,
>  locks, or atomic operations if variable a can change at runtime!
> 
> -*** WARNING: ACCESS_ONCE() DOES NOT IMPLY A BARRIER! ***
> +*** WARNING: READ_ONCE() OR WRITE_ONCE() DO NOT IMPLY A BARRIER! ***
> 
>  Now, we move onto the atomic operation interfaces typically implemented with
>  the help of assembly code.
> -- 
> 1.9.1
> 

Re: [PATCH] Documentation: atomic_ops: use {READ,WRITE}_ONCE()

[Jonathan Corbet]

On Wed, 16 Nov 2016 11:13:59 +0000
Mark Rutland <mark.rutland@arm.com> wrote:

> While the {READ,WRITE}_ONCE() macros should be used in preference to
> ACCESS_ONCE(), the atomic documentation uses the latter exclusively.
> 
> To point people in the right direction, and as a step towards the
> eventual removal of ACCESS_ONCE(), update the documentation to use the
> {READ,WRITE}_ONCE() macros as appropriate.

Applied to the docs tree, thanks.

jon