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

[Manfred Spraul]

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 an ACQUIRE.
- 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>
---
 Documentation/locking/spinlocks.txt | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/locking/spinlocks.txt b/Documentation/locking/spinlocks.txt
index ff35e40..0696d68 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() has ACQUIRE semantics.
+   spin_is_locked() is not a memory barrier, callers that use it for
+   locking must add appropriate barriers.
+
 ----
 
 Lesson 2: reader-writer spinlocks.
-- 
2.7.4