| Message ID | 1479294839-12811-1-git-send-email-mark.rutland@arm.com |
|---|---|
| State | Accepted |
| Commit | 47f421221029e8515b71e7e2379eba8406b7f458 |
| Headers | show |
On Wed, Nov 16, 2016 at 11:13:59AM +0000, Mark Rutland wrote: > 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 <mark.rutland@arm.com> > Cc: Boqun Feng <boqun.feng@gmail.com> > Cc: Jonathan Corbet <corbet@lwn.net> > Cc: Paul E. McKenney <paulmck@linux.vnet.ibm.com> > Cc: Peter Zijlstra <peterz@infradead.org> > Cc: Will Deacon <will.deacon@arm.com> > Cc: linux-doc@vger.kernel.org > Cc: linux-kernel@vger.kernel.org Acked-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com> > --- > 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 >
On Wed, 16 Nov 2016 11:13:59 +0000 Mark Rutland <mark.rutland@arm.com> wrote: > 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. Applied to the docs tree, thanks. jon
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.
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 <mark.rutland@arm.com> Cc: Boqun Feng <boqun.feng@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Paul E. McKenney <paulmck@linux.vnet.ibm.com> Cc: Peter Zijlstra <peterz@infradead.org> Cc: Will Deacon <will.deacon@arm.com> 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