[musl] Robust mutex ABI problem (kernel docs regression)

[Rich Felker <dalias@libc.org>]

It came to my attention while reviewing some proposals for additional
error checking in musl libc that the kernel folks introduced a quiet
regression in the futex ABI for robust mutexes.

Prior to kernel commit 9c40365a65d62d7c06a95fb331b3442cb02d2fd9, bit
29 of the futex lock word was reserved, meaning it could never be part
of a TID. This allowed both glibc and musl to use special values like
(glibc):

/* Magic cookie representing robust mutex with dead owner.  */
#define PTHREAD_MUTEX_INCONSISTENT      INT_MAX
/* Magic cookie representing not recoverable robust mutex.  */
#define PTHREAD_MUTEX_NOTRECOVERABLE    (INT_MAX - 1)

to represent special states needed for robust mutex consistency
handling, without the risk that, when masked with FUTEX_TID_MASK
(0x3fffffff), they could be equal to the TID of a real task, which
could result in the kernel robustlist-processing mishandling them.

In practice this is only a documentation regression. The real limit on
TIDs is well below that, at something like 22-bit last I checked.
However to be future-proof, and as other systems may implement the
Linux API/ABI (e.g. things like WSL1, FreeBSD Linux syscall layer,
etc.), I believe it's important that the documented interface be
compatible with the way it actually needs to be used here. This means
either bit 29 should have its reserved status restored, or there
should be a guarantee that the values 0x3fffffff and 0x3ffffffe are
reserved and compare not-equal to any actual TID.

Depending on how folks want to proceed with this, I can propose a
patch to the documentation, or leave that to others.

Rich