[PATCH 2/7] spinlock: Document memory barrier rules for spin_lock and spin_unlock().

From: Manfred Spraul
Date: Thu Sep 01 2016 - 11:06:53 EST


In theory, the memory ordering rules for spinlock() and spin_unlock()
are simple: spin_lock is ACQUIRE, spin_unlock is RELEASE.

What is missing is a clear documentation for the corner cases:
- What is covered by the ACQUIRE during spin_lock: only the lock load
or also the lock store?
- spin_unlock_wait() is spin_lock()+spin_unlock().
- No memory ordering is enforced by spin_is_locked().

The patch adds this into Documentation/locking/spinlock.txt.

Signed-off-by: Manfred Spraul <manfred@xxxxxxxxxxxxxxxx>
Cc: Will Deacon <will.deacon@xxxxxxx>
---
Documentation/locking/spinlocks.txt | 9 +++++++++
1 file changed, 9 insertions(+)

diff --git a/Documentation/locking/spinlocks.txt b/Documentation/locking/spinlocks.txt
index ff35e40..653b2fa 100644
--- a/Documentation/locking/spinlocks.txt
+++ b/Documentation/locking/spinlocks.txt
@@ -40,6 +40,15 @@ example, internal driver data structures that nobody else ever touches).
touches a shared variable has to agree about the spinlock they want
to use.

+ NOTE! Code that needs stricter memory barriers than ACQUIRE during
+ LOCK and RELEASE during UNLOCK must use appropriate memory barriers
+ such as smp_mb__before_spinlock(). Especially, the ACQUIRE during
+ LOCK applies to reading the lock state. Operations within the
+ guarded area can happen before the lock store.
+ spin_unlock_wait() behaves like spin_lock();spin_unlock().
+ spin_is_locked() should not be used to build synchronization
+ primitives, no memory ordering is guaranteed.
+
----

Lesson 2: reader-writer spinlocks.
--
2.7.4