[PATCH 1/2] futex: update comments for ordering guarantees

[Davidlohr Bueso <davidlohr@hp.com>]

Commit 11d4616bd07f (futex: revert back to the explicit waiter counting code)
was a late fix that changed the way we account for waiters on a futex. However,
it made the general documentation we have regarding this topic slightly stale.

Signed-off-by: Davidlohr Bueso <davidlohr@hp.com>
---
 kernel/futex.c | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/kernel/futex.c b/kernel/futex.c
index 08ec814..395e285 100644
--- a/kernel/futex.c
+++ b/kernel/futex.c
@@ -119,7 +119,7 @@
  * sys_futex(WAIT, futex, val);
  *   futex_wait(futex, val);
  *
- *   waiters++;
+ *   waiters++; (a)
  *   mb(); (A) <-- paired with -.
  *                              |
  *   lock(hash_bucket(futex));  |
@@ -134,15 +134,14 @@
  *     queue();
  *     unlock(hash_bucket(futex));
  *     schedule();                         if (waiters)
- *                                           lock(hash_bucket(futex));
- *                                           wake_waiters(futex);
+ *   else                                    lock(hash_bucket(futex));
+ *     waiters--; (b)                        wake_waiters(futex);
  *                                           unlock(hash_bucket(futex));
  *
- * Where (A) orders the waiters increment and the futex value read -- this
- * is guaranteed by the head counter in the hb spinlock; and where (B)
- * orders the write to futex and the waiters read -- this is done by the
- * barriers in get_futex_key_refs(), through either ihold or atomic_inc,
- * depending on the futex type.
+ * Where (A) orders the waiters increment and the futex value read and
+ * where (B) orders the write to futex and the waiters read -- this is
+ * done by the barriers in get_futex_key_refs(), through either ihold
+ * or atomic_inc, depending on the futex type.
  *
  * This yields the following case (where X:=waiters, Y:=futex):
  *
@@ -155,6 +154,10 @@
  * Which guarantees that x==0 && y==0 is impossible; which translates back into
  * the guarantee that we cannot both miss the futex variable change and the
  * enqueue.
+ *
+ * Note that a new waiter is accounted for in (a) even when it is possible that
+ * the wait call can return error, in which case we backtrack from it in (b).
+ * Refer to the comment in queue_lock().
  */
 
 int __read_mostly futex_cmpxchg_enabled;
-- 
1.8.1.4