From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1422791AbcKPLOs (ORCPT ); Wed, 16 Nov 2016 06:14:48 -0500 Received: from foss.arm.com ([217.140.101.70]:48020 "EHLO foss.arm.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1422667AbcKPLOp (ORCPT ); Wed, 16 Nov 2016 06:14:45 -0500 From: Mark Rutland To: linux-kernel@vger.kernel.org Cc: Mark Rutland , Boqun Feng , Jonathan Corbet , "Paul E. McKenney" , Peter Zijlstra , Will Deacon , linux-doc@vger.kernel.org Subject: [PATCH] Documentation: atomic_ops: use {READ,WRITE}_ONCE() Date: Wed, 16 Nov 2016 11:13:59 +0000 Message-Id: <1479294839-12811-1-git-send-email-mark.rutland@arm.com> X-Mailer: git-send-email 1.9.1 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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 Cc: Boqun Feng Cc: Jonathan Corbet Cc: Paul E. McKenney Cc: Peter Zijlstra Cc: Will Deacon 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