Re: [PATCH] Documentation: circular-buffers: use READ_ONCE()

["Paul E. McKenney" <paulmck@linux.vnet.ibm.com>]

On Wed, Nov 16, 2016 at 11:12:49AM +0000, Mark Rutland wrote:
> While the {READ,WRITE}_ONCE() macros should be used in preference to
> ACCESS_ONCE(), the circular buffer 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
> READ_ONCE(), as ACCESS_ONCE() is only used in a reader context in the
> circular buffer documentation.
> 
> Signed-off-by: Mark Rutland <mark.rutland@arm.com>
> Cc: David Howells <dhowells@redhat.com>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
> Cc: linux-doc@vger.kernel.org
> Cc: linux-kernel@vger.kernel.org

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

> ---
>  Documentation/circular-buffers.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/circular-buffers.txt b/Documentation/circular-buffers.txt
> index 88951b1..4a824d2 100644
> --- a/Documentation/circular-buffers.txt
> +++ b/Documentation/circular-buffers.txt
> @@ -161,7 +161,7 @@ The producer will look something like this:
> 
>  	unsigned long head = buffer->head;
>  	/* The spin_unlock() and next spin_lock() provide needed ordering. */
> -	unsigned long tail = ACCESS_ONCE(buffer->tail);
> +	unsigned long tail = READ_ONCE(buffer->tail);
> 
>  	if (CIRC_SPACE(head, tail, buffer->size) >= 1) {
>  		/* insert one item into the buffer */
> @@ -222,7 +222,7 @@ This will instruct the CPU to make sure the index is up to date before reading
>  the new item, and then it shall make sure the CPU has finished reading the item
>  before it writes the new tail pointer, which will erase the item.
> 
> -Note the use of ACCESS_ONCE() and smp_load_acquire() to read the
> +Note the use of READ_ONCE() and smp_load_acquire() to read the
>  opposition index.  This prevents the compiler from discarding and
>  reloading its cached value - which some compilers will do across
>  smp_read_barrier_depends().  This isn't strictly needed if you can
> -- 
> 1.9.1
>