From: David Howells 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. Signed-off-by: David Howells Signed-off-by: Andrew Morton --- Documentation/memory-barriers.txt | 47 ++++++++++++++++++---------- 1 files changed, 31 insertions(+), 16 deletions(-) diff -puN Documentation/memory-barriers.txt~fix-memory-barrier-docs-wrt-atomic-ops Documentation/memory-barriers.txt --- devel/Documentation/memory-barriers.txt~fix-memory-barrier-docs-wrt-atomic-ops 2006-04-05 02:22:38.000000000 -0700 +++ devel-akpm/Documentation/memory-barriers.txt 2006-04-05 02:22:38.000000000 -0700 @@ -829,8 +829,8 @@ There are some more advanced barrier fun (*) smp_mb__after_atomic_inc(); These are for use with atomic add, subtract, increment and decrement - functions, especially when used for reference counting. These functions - do not imply memory barriers. + functions that don't return a value, especially when used for reference + counting. These functions do not imply memory barriers. As an example, consider a piece of code that marks an object as being dead and then decrements the object's reference count: @@ -1263,15 +1263,15 @@ else. ATOMIC OPERATIONS ----------------- -Though they are technically interprocessor interaction considerations, atomic -operations are noted specially as they do _not_ generally imply memory -barriers. The possible offenders include: +Whilst they are technically interprocessor interaction considerations, atomic +operations are noted specially as some of them imply full memory barriers and +some don't, but they're very heavily relied on as a group throughout the +kernel. + +Any atomic_t operation, for instance, that returns a value implies an +SMP-conditional general memory barrier (smp_mb()) on each side of the actual +operation. These include: - xchg(); - cmpxchg(); - test_and_set_bit(); - test_and_clear_bit(); - test_and_change_bit(); atomic_cmpxchg(); atomic_inc_return(); atomic_dec_return(); @@ -1283,20 +1283,30 @@ barriers. The possible offenders includ atomic_add_negative(); atomic_add_unless(); -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 -operations. +The following, however, do _not_ imply memory barrier effects: + + xchg(); + cmpxchg(); + test_and_set_bit(); + test_and_clear_bit(); + test_and_change_bit(); + +These may be used for such things as implementing LOCK-class operations. In +such cases they need explicit memory barriers. + +The following are also potential offenders as they may be used as UNLOCK-class +operations, amongst other things, but do _not_ imply memory barriers either: set_bit(); clear_bit(); change_bit(); atomic_set(); +With these the appropriate explicit memory barrier should be used if necessary. + -The following are a little tricky: +The following also don't imply memory barriers, and so may be a little tricky: atomic_add(); atomic_sub(); @@ -1322,6 +1332,11 @@ operation is protected by a lock, then i there's another operation within the critical section with respect to which an ordering must be maintained. +[!] Note that special memory barrier primitives are available for these +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. _