Documentation/locking/mutex-design: Update to reflect latest changes

Web:        https://git.kernel.org/torvalds/c/79e902382637a2f421b7f295dcf9934d80d84d7d
Commit:     79e902382637a2f421b7f295dcf9934d80d84d7d
Parent:     f1517df8701c9f12dae9ce7f43a5d300a6917619
Refname:    refs/heads/master
Author:     Juri Lelli <[email protected]>
AuthorDate: Fri Feb 9 17:01:14 2018 +0100
Committer:  Ingo Molnar <[email protected]>
CommitDate: Sun Feb 11 12:28:58 2018 +0100

    Documentation/locking/mutex-design: Update to reflect latest changes
    
    Commit 3ca0ff571b09 ("locking/mutex: Rework mutex::owner") reworked the
    basic mutex implementation to deal with several problems. Documentation
    was however left unchanged and became stale.
    
    Update mutex-design.txt to reflect changes introduced by the above commit.
    
    Signed-off-by: Juri Lelli <[email protected]>
    Cc: Andrew Morton <[email protected]>
    Cc: Davidlohr Bueso <[email protected]>
    Cc: Jonathan Corbet <[email protected]>
    Cc: Linus Torvalds <[email protected]>
    Cc: Paul E. McKenney <[email protected]>
    Cc: Peter Zijlstra <[email protected]>
    Cc: Thomas Gleixner <[email protected]>
    Cc: [email protected]
    Link: http://lkml.kernel.org/r/[email protected]
    [ Small readability tweaks to the text. ]
    Signed-off-by: Ingo Molnar <[email protected]>
---
 Documentation/locking/mutex-design.txt | 49 ++++++++++++----------------------
 1 file changed, 17 insertions(+), 32 deletions(-)

diff --git a/Documentation/locking/mutex-design.txt b/Documentation/locking/mutex-design.txt
index 60c482df1a38..818aca19612f 100644
--- a/Documentation/locking/mutex-design.txt
+++ b/Documentation/locking/mutex-design.txt
@@ -21,37 +21,23 @@ Implementation
 --------------
 
 Mutexes are represented by 'struct mutex', defined in include/linux/mutex.h
-and implemented in kernel/locking/mutex.c. These locks use a three
-state atomic counter (->count) to represent the different possible
-transitions that can occur during the lifetime of a lock:
-
-	  1: unlocked
-	  0: locked, no waiters
-   negative: locked, with potential waiters
-
-In its most basic form it also includes a wait-queue and a spinlock
-that serializes access to it. CONFIG_SMP systems can also include
-a pointer to the lock task owner (->owner) as well as a spinner MCS
-lock (->osq), both described below in (ii).
+and implemented in kernel/locking/mutex.c. These locks use an atomic variable
+(->owner) to keep track of the lock state during its lifetime.  Field owner
+actually contains 'struct task_struct *' to the current lock owner and it is
+therefore NULL if not currently owned. Since task_struct pointers are aligned
+at at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g.,
+if waiter list is non-empty).  In its most basic form it also includes a
+wait-queue and a spinlock that serializes access to it. Furthermore,
+CONFIG_MUTEX_SPIN_ON_OWNER=y systems use a spinner MCS lock (->osq), described
+below in (ii).
 
 When acquiring a mutex, there are three possible paths that can be
 taken, depending on the state of the lock:
 
-(i) fastpath: tries to atomically acquire the lock by decrementing the
-    counter. If it was already taken by another task it goes to the next
-    possible path. This logic is architecture specific. On x86-64, the
-    locking fastpath is 2 instructions:
-
-    0000000000000e10 <mutex_lock>:
-    e21:   f0 ff 0b                lock decl (%rbx)
-    e24:   79 08                   jns    e2e <mutex_lock+0x1e>
-
-   the unlocking fastpath is equally tight:
-
-    0000000000000bc0 <mutex_unlock>:
-    bc8:   f0 ff 07                lock incl (%rdi)
-    bcb:   7f 0a                   jg     bd7 <mutex_unlock+0x17>