Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1761625AbXIJX1o (ORCPT ); Mon, 10 Sep 2007 19:27:44 -0400 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1753015AbXIJX1e (ORCPT ); Mon, 10 Sep 2007 19:27:34 -0400 Received: from mx1.redhat.com ([66.187.233.31]:34855 "EHLO mx1.redhat.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751004AbXIJX1c (ORCPT ); Mon, 10 Sep 2007 19:27:32 -0400 Date: Mon, 10 Sep 2007 19:19:44 -0400 From: Chris Snook To: Linus Torvalds Cc: Denys Vlasenko , Kyle Moffett , Arjan van de Ven , Nick Piggin , Satyam Sharma , Herbert Xu , Paul Mackerras , Christoph Lameter , Ilpo Jarvinen , "Paul E. McKenney" , Stefan Richter , Linux Kernel Mailing List , linux-arch@vger.kernel.org, Netdev , Andrew Morton , ak@suse.de, heiko.carstens@de.ibm.com, David Miller , schwidefsky@de.ibm.com, wensong@linux-vs.org, horms@verge.net.au, wjiang@resilience.com, cfriesen@nortel.com, zlynx@acm.org, rpjday@mindspring.com, jesper.juhl@gmail.com, segher@kernel.crashing.org Subject: [PATCH] Document non-semantics of atomic_read() and atomic_set() Message-ID: <20070910231944.GA3484@shell.boston.redhat.com> References: <18115.52863.638655.658466@cargo.ozlabs.ibm.com> <6370BBDF-0C79-41EB-BD2A-02AA0D216924@mac.com> <200709101438.36710.vda.linux@googlemail.com> <200709101516.03234.vda.linux@googlemail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.4.1i Sender: linux-kernel-owner@vger.kernel.org X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 2234 Lines: 53 From: Chris Snook Unambiguously document the fact that atomic_read() and atomic_set() do not imply any ordering or memory access, and that callers are obligated to explicitly invoke barriers as needed to ensure that changes to atomic variables are visible in all contexts that need to see them. Signed-off-by: Chris Snook --- a/Documentation/atomic_ops.txt 2007-07-08 19:32:17.000000000 -0400 +++ b/Documentation/atomic_ops.txt 2007-09-10 19:02:50.000000000 -0400 @@ -12,7 +12,11 @@ C integer type will fail. Something like the following should suffice: - typedef struct { volatile int counter; } atomic_t; + typedef struct { int counter; } atomic_t; + + Historically, counter has been declared volatile. This is now +discouraged. See Documentation/volatile-considered-harmful.txt for the +complete rationale. The first operations to implement for atomic_t's are the initializers and plain reads. @@ -42,6 +46,22 @@ which simply reads the current value of the counter. +*** WARNING: atomic_read() and atomic_set() DO NOT IMPLY BARRIERS! *** + +Some architectures may choose to use the volatile keyword, barriers, or +inline assembly to guarantee some degree of immediacy for atomic_read() +and atomic_set(). This is not uniformly guaranteed, and may change in +the future, so all users of atomic_t should treat atomic_read() and +atomic_set() as simple C assignment statements that may be reordered or +optimized away entirely by the compiler or processor, and explicitly +invoke the appropriate compiler and/or memory barrier for each use case. +Failure to do so will result in code that may suddenly break when used with +different architectures or compiler optimizations, or even changes in +unrelated code which changes how the compiler optimizes the section +accessing atomic_t variables. + +*** YOU HAVE BEEN WARNED! *** + Now, we move onto the actual atomic operation interfaces. void atomic_add(int i, atomic_t *v); - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/