Re: [PATCH] Document non-semantics of atomic_read() and atomic_set()

From: Paul E. McKenney
Date: Mon Sep 10 2007 - 19:44:51 EST


On Mon, Sep 10, 2007 at 07:19:44PM -0400, Chris Snook wrote:
> From: Chris Snook <csnook@xxxxxxxxxx>
>
> 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.

Acked-by: Paul E. McKenney <paulmck@xxxxxxxxxxxxxxxxxx>

> Signed-off-by: Chris Snook <csnook@xxxxxxxxxx>
>
> --- 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@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/