futexes: Document multiprocessor ordering guarantees

#include "locking/rtmutex_common.h"

/*

 * Basic futex operation and ordering guarantees:

 *

 * The waiter reads the futex value in user space and calls

 * futex_wait(). This function computes the hash bucket and acquires

 * the hash bucket lock. After that it reads the futex user space value

 * again and verifies that the data has not changed. If it has not

 * changed it enqueues itself into the hash bucket, releases the hash

 * bucket lock and schedules.

 *

 * The waker side modifies the user space value of the futex and calls

 * futex_wake(). This functions computes the hash bucket and acquires

 * the hash bucket lock. Then it looks for waiters on that futex in the

 * hash bucket and wakes them.

 *

 * Note that the spin_lock serializes waiters and wakers, so that the

 * following scenario is avoided:

 *

 * CPU 0                               CPU 1

 * val = *futex;

 * sys_futex(WAIT, futex, val);

 *   futex_wait(futex, val);

 *   uval = *futex;

 *                                     *futex = newval;

 *                                     sys_futex(WAKE, futex);

 *                                       futex_wake(futex);

 *                                       if (queue_empty())

 *                                         return;

 *   if (uval == val)

 *      lock(hash_bucket(futex));

 *      queue();

 *     unlock(hash_bucket(futex));

 *     schedule();

 *

 * This would cause the waiter on CPU 0 to wait forever because it

 * missed the transition of the user space value from val to newval

 * and the waker did not find the waiter in the hash bucket queue.

 * The spinlock serializes that:

 *

 * CPU 0                               CPU 1

 * val = *futex;

 * sys_futex(WAIT, futex, val);

 *   futex_wait(futex, val);

 *   lock(hash_bucket(futex));

 *   uval = *futex;

 *                                     *futex = newval;

 *                                     sys_futex(WAKE, futex);

 *                                       futex_wake(futex);

 *                                       lock(hash_bucket(futex));

 *   if (uval == val)

 *      queue();

 *     unlock(hash_bucket(futex));

 *     schedule();                       if (!queue_empty())

 *                                         wake_waiters(futex);

 *                                       unlock(hash_bucket(futex));

 */

int __read_mostly futex_cmpxchg_enabled;

/*