Commit dbc8700e authored by David Howells's avatar David Howells Committed by Linus Torvalds

[PATCH] Fix memory barrier docs wrt atomic ops

Fix the memory barrier documentation to attempt to describe atomic ops
correctly.

atomic_t ops that return a value _do_ imply smp_mb() either side, and so
don't actually require smp_mb__*_atomic_*() special barriers.

Also explains why special barriers exist in addition to normal barriers.

Further fix the memory barrier documents to portray bitwise operation
memory barrier effects correctly following Nick Piggin's comments.

It makes the point that any atomic op that both modifies some state in
memory and returns information on that state implies memory barriers on
both sides.
Signed-off-by: default avatarDavid Howells <dhowells@redhat.com>
Signed-off-by: default avatarAndrew Morton <akpm@osdl.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@osdl.org>
parent 235963b2
...@@ -829,8 +829,8 @@ There are some more advanced barrier functions: ...@@ -829,8 +829,8 @@ There are some more advanced barrier functions:
(*) smp_mb__after_atomic_inc(); (*) smp_mb__after_atomic_inc();
These are for use with atomic add, subtract, increment and decrement These are for use with atomic add, subtract, increment and decrement
functions, especially when used for reference counting. These functions functions that don't return a value, especially when used for reference
do not imply memory barriers. counting. These functions do not imply memory barriers.
As an example, consider a piece of code that marks an object as being dead As an example, consider a piece of code that marks an object as being dead
and then decrements the object's reference count: and then decrements the object's reference count:
...@@ -1263,15 +1263,17 @@ else. ...@@ -1263,15 +1263,17 @@ else.
ATOMIC OPERATIONS ATOMIC OPERATIONS
----------------- -----------------
Though they are technically interprocessor interaction considerations, atomic Whilst they are technically interprocessor interaction considerations, atomic
operations are noted specially as they do _not_ generally imply memory operations are noted specially as some of them imply full memory barriers and
barriers. The possible offenders include: some don't, but they're very heavily relied on as a group throughout the
kernel.
Any atomic operation that modifies some state in memory and returns information
about the state (old or new) implies an SMP-conditional general memory barrier
(smp_mb()) on each side of the actual operation. These include:
xchg(); xchg();
cmpxchg(); cmpxchg();
test_and_set_bit();
test_and_clear_bit();
test_and_change_bit();
atomic_cmpxchg(); atomic_cmpxchg();
atomic_inc_return(); atomic_inc_return();
atomic_dec_return(); atomic_dec_return();
...@@ -1282,21 +1284,31 @@ barriers. The possible offenders include: ...@@ -1282,21 +1284,31 @@ barriers. The possible offenders include:
atomic_sub_and_test(); atomic_sub_and_test();
atomic_add_negative(); atomic_add_negative();
atomic_add_unless(); atomic_add_unless();
test_and_set_bit();
test_and_clear_bit();
test_and_change_bit();
These are used for such things as implementing LOCK-class and UNLOCK-class
operations and adjusting reference counters towards object destruction, and as
such the implicit memory barrier effects are necessary.
These may be used for such things as implementing LOCK operations or controlling
the lifetime of objects by decreasing their reference counts. In such cases
they need preceding memory barriers.
The following may also be possible offenders as they may be used as UNLOCK The following operation are potential problems as they do _not_ imply memory
operations. barriers, but might be used for implementing such things as UNLOCK-class
operations:
atomic_set();
set_bit(); set_bit();
clear_bit(); clear_bit();
change_bit(); change_bit();
atomic_set();
With these the appropriate explicit memory barrier should be used if necessary
(smp_mb__before_clear_bit() for instance).
The following are a little tricky: The following also do _not_ imply memory barriers, and so may require explicit
memory barriers under some circumstances (smp_mb__before_atomic_dec() for
instance)):
atomic_add(); atomic_add();
atomic_sub(); atomic_sub();
...@@ -1317,10 +1329,12 @@ specific order. ...@@ -1317,10 +1329,12 @@ specific order.
Basically, each usage case has to be carefully considered as to whether memory Basically, each usage case has to be carefully considered as to whether memory
barriers are needed or not. The simplest rule is probably: if the atomic barriers are needed or not.
operation is protected by a lock, then it does not require a barrier unless
there's another operation within the critical section with respect to which an [!] Note that special memory barrier primitives are available for these
ordering must be maintained. situations because on some CPUs the atomic instructions used imply full memory
barriers, and so barrier instructions are superfluous in conjunction with them,
and in such cases the special barrier primitives will be no-ops.
See Documentation/atomic_ops.txt for more information. See Documentation/atomic_ops.txt for more information.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment