>From 8df60211228042672ba0cd89c3566c5145e8b203 Mon Sep 17 00:00:00 2001 From: Manfred Spraul Date: Fri, 11 Oct 2019 10:33:26 +0200 Subject: [PATCH 4/4] Documentation/memory-barriers.txt: Clarify cmpxchg() The documentation in memory-barriers.txt claims that smp_mb__{before,after}_atomic() are for atomic ops that do not return a value. This is misleading and doesn't match the example in atomic_t.txt, and e.g. smp_mb__before_atomic() may and is used together with cmpxchg_relaxed() in the wake_q code. The purpose of e.g. smp_mb__before_atomic() is to "upgrade" a following RMW atomic operation to a full memory barrier. The return code of the atomic operation has no impact, so all of the following examples are valid: 1) smp_mb__before_atomic(); atomic_add(); 2) smp_mb__before_atomic(); atomic_xchg_relaxed(); 3) smp_mb__before_atomic(); atomic_fetch_add_relaxed(); Invalid would be: smp_mb__before_atomic(); atomic_set(); Signed-off-by: Manfred Spraul Cc: Waiman Long Cc: Davidlohr Bueso Cc: Peter Zijlstra --- Documentation/memory-barriers.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index 1adbb8a371c7..52076b057400 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -1873,12 +1873,13 @@ There are some more advanced barrier functions: (*) smp_mb__before_atomic(); (*) smp_mb__after_atomic(); - These are for use with atomic (such as add, subtract, increment and - decrement) functions that don't return a value, especially when used for - reference counting. These functions do not imply memory barriers. + These are for use with atomic RMW functions (such as add, subtract, + increment, decrement, failed conditional operations, ...) that do + not imply memory barriers, but where the code needs a memory barrier, + for example when used for reference counting. - These are also used for atomic bitop functions that do not return a - value (such as set_bit and clear_bit). + These are also used for atomic RMW bitop functions that do imply a full + memory barrier (such as set_bit and clear_bit). As an example, consider a piece of code that marks an object as being dead and then decrements the object's reference count: -- 2.21.0