From patchwork Wed Nov 16 11:13:59 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mark Rutland X-Patchwork-Id: 82487 Delivered-To: patch@linaro.org Received: by 10.140.97.165 with SMTP id m34csp92497qge; Wed, 16 Nov 2016 03:14:56 -0800 (PST) X-Received: by 10.99.108.8 with SMTP id h8mr7022272pgc.93.1479294896064; Wed, 16 Nov 2016 03:14:56 -0800 (PST) Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id s68si31449651pgs.208.2016.11.16.03.14.55; Wed, 16 Nov 2016 03:14:56 -0800 (PST) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1422792AbcKPLOs (ORCPT + 26 others); 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 Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.72.51.249]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id F137EAD7; Wed, 16 Nov 2016 03:14:44 -0800 (PST) Received: from leverpostej.cambridge.arm.com (usa-sjc-imap-foss1.foss.arm.com [10.72.51.249]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPA id AC22B3F318; Wed, 16 Nov 2016 03:14:43 -0800 (PST) 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 Precedence: bulk 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(-) -- 1.9.1 Acked-by: Paul E. McKenney 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.