Documentation/locking/robust-futex-ABI.rst

48 kernel, then it can actually have two such structures - one using 32 bit
56   pointer to a single linked list of 'lock entries', one per lock,
58   to itself, 'head'.  The last 'lock entry' points back to the 'head'.
60   The second word, called 'offset', specifies the offset from the
61   address of the associated 'lock entry', plus or minus, of what will
62   be called the 'lock word', from that 'lock entry'.  The 'lock word'
63   is always a 32 bit word, unlike the other words above.  The 'lock
65   of the thread holding the lock in the bottom 30 bits.  See further
69   the address of the 'lock entry', during list insertion and removal,
73 Each 'lock entry' on the single linked list starting at 'head' consists
74 of just a single word, pointing to the next 'lock entry', or back to
75 'head' if there are no more entries.  In addition, nearby to each 'lock
76 entry', at an offset from the 'lock entry' specified by the 'offset'
77 word, is one 'lock word'.
79 The 'lock word' is always 32 bits, and is intended to be the same 32 bit
80 lock variable used by the futex mechanism, in conjunction with
82 waiting for a lock on a threads exit if that next thread used the futex
83 mechanism to register the address of that 'lock word' with the kernel.
85 For each futex lock currently held by a thread, if it wants this
86 robust_futex support for exit cleanup of that lock, it should have one
87 'lock entry' on this list, with its associated 'lock word' at the
88 specified 'offset'.  Should a thread die while holding any such locks,
91 that lock using the futex mechanism.
103 larger, user level locking structures, one per lock.  The kernel
105 long as the 'offset' to the 'lock word' is the same for all
107 it currently holds using the 'lock entry' pointers.  It may also have
123 There may exist thousands of futex lock structures in a threads shared
125 lock structures for locks currently held by that thread should be on
126 that thread's robust_futex linked lock list a given time.
128 A given futex lock structure in a user shared memory region may be held
130 thread currently holding such a lock, if any, is marked with the threads
131 TID in the lower 30 bits of the 'lock word'.
133 When adding or removing a lock from its list of held locks, in order for
134 the kernel to correctly handle lock cleanup regardless of when the task
137 protocol on 'lock entry' insertion and removal:
141  1) set the 'list_op_pending' word to the address of the 'lock entry'
143  2) acquire the futex lock,
144  3) add the lock entry, with its thread id (TID) in the bottom 30 bits
145     of the 'lock word', to the linked list starting at 'head', and
150  1) set the 'list_op_pending' word to the address of the 'lock entry'
152  2) remove the lock entry for this lock from the 'head' list,
153  3) release the futex lock, and
157 'list_op_pending' and the address of each 'lock word' found by walking
159 bits of the 'lock word' at offset 'offset' from that address equals the
165  2) atomically set  bit 30 (0x40000000) in the 'lock word'.
167 In the above, bit 31 was set by futex waiters on that lock to indicate
169 lock owner died holding the lock.
176  2) the calculated location of the 'lock word' (address plus
177     'offset') is not the valid address of a 32 bit user space
182 When the kernel sees a list entry whose 'lock word' doesn't have the