[RFC patch 6/7] futex.2: Document attached mode

[Thomas Gleixner <tglx@linutronix.de>]

[-- Attachment #1: futex.2--Document-attached-mode.patch --]
[-- Type: text/plain, Size: 3620 bytes --]

At least an attempt to document the futex attached mode extension.

Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
---
 man2/futex.2 |   78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 75 insertions(+), 3 deletions(-)

--- a/man2/futex.2
+++ b/man2/futex.2
@@ -138,8 +138,8 @@ Besides the basic wait and wake-up futex
 futex operations aimed at supporting more complex use cases.
 
 Note that
-no explicit initialization or destruction is necessary to use futexes;
-the kernel maintains a futex
+no explicit initialization or destruction is necessary to use futexes
+except when using futexes in attached mode; the kernel maintains a futex
 (i.e., the kernel-internal implementation artifact)
 only while operations such as
 .BR FUTEX_WAIT ,
@@ -253,6 +253,12 @@ as a relative time,
 measured against the
 .BR CLOCK_MONOTONIC
 clock.
+.TP
+.BR FUTEX_ATTACHED " (since Linux ?.?.?)"
+This option can be employed with all futex operations. It tells the kernel
+that the futex operates in attached mode. See the futex_op
+.BR FUTEX_ATTACH
+for further explanation.
 .PP
 The operation specified in
 .I futex_op
@@ -767,6 +773,63 @@ operations correspond to
 and
 .BR FUTEX_WAKE_BITSET
 operations where the bit masks are all ones.
+
+.\"
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.\"
+.TP
+.BR FUTEX_ATTACH " (since Linux ?.?.?)"
+This operation attaches the futex on the futex address provided by the
+.IR uaddr
+argument.
+
+This operation tells the kernel that the thread is going to operate on that
+futex and therefor it should create a kernel side state for it. This state is
+used in further futex operations instead of the global hash which is used
+without that optimization.
+
+There are two advantages for using attached futexes. Potential hash collisions
+on the global hash are avoided. The kernel state which replaces the global
+hash for attached futexes is allocated on the node on which the thread runs
+and therefor avoids cross node memory access.
+
+For this operation and all subsequent operations on the futex the flag
+.BR FUTEX_ATTACHED
+must be ORed to the
+.I futex_op
+
+The
+.IR val ,
+.IR timeout ,
+.IR uaddr2
+and
+.I val3
+arguments are ignored.
+
+.\"
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.\"
+.TP
+.BR FUTEX_DETACH " (since Linux ?.?.?)"
+This operation detaches the futex on the futex address provided by the
+.I uaddr
+argument from the kernel state.
+
+This operation reverses a previous
+.BR FUTEX_ATTACH
+operation.
+
+If the caller is the last user of the kernel side state, the kernel side state
+is destroyed.
+
+The
+.IR val ,
+.IR timeout ,
+.IR uaddr2
+and
+.I val3
+arguments are ignored.
+
 .\"
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .\"
@@ -1402,6 +1465,10 @@ While requeueing a waiter to the PI fute
 .IR uaddr2 ,
 the kernel detected a deadlock.
 .TP
+.B EEXIST
+.RB ( FUTEX_ATTACH )
+Operation was attempted on a already attached futex.
+.TP
 .B EFAULT
 A required pointer argument (i.e.,
 .IR uaddr ,
@@ -1550,13 +1617,18 @@ Invalid argument.
 .BR ENOMEM
 .RB ( FUTEX_LOCK_PI ,
 .BR FUTEX_TRYLOCK_PI ,
-.BR FUTEX_CMP_REQUEUE_PI )
+.BR FUTEX_CMP_REQUEUE_PI,
+.BR FUTEX_ATTACH )
 The kernel could not allocate memory to hold state information.
 .TP
 .B ENFILE
 .RB ( FUTEX_FD )
 The system-wide limit on the total number of open files has been reached.
 .TP
+.B ENOSPC
+.RB ( FUTEX_ATTACH )
+Operation failed because the limit of attached futexes has been reached.
+.TP
 .B ENOSYS
 Invalid operation specified in
 .IR futex_op .