1 .\" Copyright (c) 2016 The FreeBSD Foundation, Inc.
2 .\" All rights reserved.
4 .\" This documentation was written by
5 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
6 .\" from the FreeBSD Foundation.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36 .Nd interface for implementation of userspace threading synchronization primitives
43 .Fn _umtx_op "void *obj" "int op" "u_long val" "void *uaddr" "void *uaddr2"
47 system call provides kernel support for userspace implementation of
48 the threading synchronization primitives.
51 uses the syscall to implement
53 pthread locks, like mutexes, condition variables and so on.
55 The operations, performed by the
57 syscall, operate on userspace objects which are described
58 by the following structures.
59 Reserved fields and paddings are omitted.
60 All objects require ABI-mandated alignment, but this is not currently
61 enforced consistently on all architectures.
63 The following flags are defined for flag fields of all structures:
64 .Bl -tag -width indent
65 .It Dv USYNC_PROCESS_SHARED
66 Allow selection of the process-shared sleep queue for the thread sleep
67 container, when the lock ownership cannot be granted immediately,
68 and the operation must sleep.
69 The process-shared or process-private sleep queue is selected based on
70 the attributes of the memory mapping which contains the first byte of
73 Otherwise, if the flag is not specified, the process-private sleep queue
74 is selected regardless of the memory mapping attributes, as an optimization.
78 subsection below for more details on sleep queues.
80 .Bl -hang -offset indent
84 volatile lwpid_t m_owner;
86 uint32_t m_ceilings[2];
93 field is the actual lock.
94 It contains either the thread identifier of the lock owner in the
95 locked state, or zero when the lock is unowned.
96 The highest bit set indicates that there is contention on the lock.
97 The constants are defined for special values:
98 .Bl -tag -width indent
100 Zero, the value stored in the unowned lock.
101 .It Dv UMUTEX_CONTESTED
102 The contention indicator.
103 .It Dv UMUTEX_RB_OWNERDEAD
104 A thread owning the robust mutex terminated.
105 The mutex is in unlocked state.
106 .It Dv UMUTEX_RB_NOTRECOV
107 The robust mutex is in a non-recoverable state.
108 It cannot be locked until reinitialized.
113 field may contain the following umutex-specific flags, in addition to
115 .Bl -tag -width indent
116 .It Dv UMUTEX_PRIO_INHERIT
118 .Em Priority Inheritance
120 .It Dv UMUTEX_PRIO_PROTECT
122 .Em Priority Protection
125 Mutex is robust, as described in the
128 .It Dv UMUTEX_NONCONSISTENT
129 Robust mutex is in a transient non-consistent state.
133 In the manual page, mutexes not having
134 .Dv UMUTEX_PRIO_INHERIT
136 .Dv UMUTEX_PRIO_PROTECT
137 flags set, are called normal mutexes.
139 .Pq normal, priority-inherited, and priority-protected
140 has a separate sleep queue associated
143 For priority protected mutexes, the
145 array contains priority ceiling values.
148 is the ceiling value for the mutex, as specified by
151 .Em Priority Protected
155 is used only for the unlock of a priority protected mutex, when
156 unlock is done in an order other than the reversed lock order.
159 must contain the ceiling value for the last locked priority protected
160 mutex, for proper priority reassignment.
161 If, instead, the unlocking mutex was the last priority propagated
162 mutex locked by the thread,
165 This is required because kernel does not maintain the ordered lock list.
166 .It Sy Condition variable
169 volatile uint32_t c_has_waiters;
177 value indicates that there are in-kernel waiters for the condition,
184 field contains flags.
185 Only the common flags
186 .Pq Dv USYNC_PROCESS_SHARED
187 are defined for ucond.
191 member provides the clock identifier to use for timeout, when the
195 flag and the timeout specified.
196 Valid clock identifiers are a subset of those for
197 .Xr clock_gettime 2 :
202 .Dv CLOCK_MONOTONIC_FAST
204 .Dv CLOCK_MONOTONIC_PRECISE
210 .Dv CLOCK_REALTIME_FAST
212 .Dv CLOCK_REALTIME_PRECISE
218 .Dv CLOCK_UPTIME_FAST
220 .Dv CLOCK_UPTIME_PRECISE
224 .It Sy Reader/writer lock
227 volatile int32_t rw_state;
229 uint32_t rw_blocked_readers;
230 uint32_t rw_blocked_writers;
236 field is the actual lock.
237 It contains both the flags and counter of the read locks which were
242 .Bl -tag -width indent
243 .It Dv URWLOCK_WRITE_OWNER
244 Write lock was granted.
245 .It Dv URWLOCK_WRITE_WAITERS
246 There are write lock waiters.
247 .It Dv URWLOCK_READ_WAITERS
248 There are read lock waiters.
249 .It Dv URWLOCK_READER_COUNT(c)
250 Returns the count of currently granted read locks.
253 At any given time there may be only one thread to which the writer lock
256 and no threads are granted read lock.
257 Or, at the given time, up to
258 .Dv URWLOCK_MAX_READERS
259 threads may be granted the read lock simultaneously, but write lock is
260 not granted to any thread.
262 The following flags for the
266 are defined, in addition to the common flags:
267 .Bl -tag -width indent
268 .It Dv URWLOCK_PREFER_READER
269 If specified, immediately grant read lock requests when
271 is already read-locked, even in presence of unsatisfied write
273 By default, if there is a write lock waiter, further read requests are
274 not granted, to prevent unfair write lock waiter starvation.
278 .Dv rw_blocked_readers
280 .Dv rw_blocked_writers
281 members contain the count of threads which are sleeping in kernel,
282 waiting for the associated request type to be granted.
283 The fields are used by kernel to update the
284 .Dv URWLOCK_READ_WAITERS
286 .Dv URWLOCK_WRITE_WAITERS
289 lock after requesting thread was woken up.
293 volatile uint32_t _count;
300 word represents a counting semaphore.
301 A non-zero value indicates an unlocked (posted) semaphore, while zero
302 represents the locked state.
303 The maximal supported semaphore count is
308 word, besides the counter of posts (unlocks), also contains the
310 bit, which indicates that locked semaphore has waiting threads.
314 macro, applied to the
316 word, returns the current semaphore counter, which is the number of posts
317 issued on the semaphore.
319 The following bits for the
323 are defined, in addition to the common flags:
324 .Bl -tag -width indent
326 Flag is ignored by kernel.
328 .It Sy Timeout parameter
331 struct timespec _timeout;
339 operations allow the blocking time to be limited, failing the request
340 if it cannot be satisfied in the specified time period.
341 The timeout is specified by passing either the address of
342 .Vt struct timespec ,
343 or its extended variant,
344 .Vt struct _umtx_time ,
349 They are distinguished by the
351 value, which must be equal to the size of the structure pointed to by
358 member specifies the time when the timeout should occur.
359 Legal values for clock identifier
366 and use the same underlying clocks.
367 The specified clock is used to obtain the current time value.
368 Interval counting is always performed by the monotonic wall clock.
372 argument allows the following flags to further define the timeout behaviour:
373 .Bl -tag -width indent
377 value is the absolute time.
378 The thread will be unblocked and the request failed when specified
379 clock value is equal or exceeds the
382 If the flag is absent, the timeout value is relative, that is the amount
383 of time, measured by the monotonic wall clock from the moment of the request
388 When a locking request cannot be immediately satisfied, the thread is
391 which is a non-runnable state terminated by the
394 Lock operations include a
396 variant which returns an error rather than sleeping if the lock cannot
400 provides requests which explicitly put the thread to sleep.
402 Wakes need to know which threads to make runnable, so sleeping threads
403 are grouped into containers called
405 A sleep queue is identified by a key, which for
407 is defined as the physical address of some variable.
410 address is used, which means that same variable mapped multiple
411 times will give one key value.
412 This mechanism enables the construction of
416 A related attribute of the key is shareability.
417 Some requests always interpret keys as private for the current process,
418 creating sleep queues with the scope of the current process even if
419 the memory is shared.
420 Others either select the shareability automatically from the
421 mapping attributes, or take additional input as the
422 .Dv USYNC_PROCESS_SHARED
424 This is done as optimization, allowing the lock scope to be limited
425 regardless of the kind of backing memory.
427 Only the address of the start byte of the variable specified as key is
428 important for determining corresponding sleep queue.
429 The size of the variable does not matter, so, for example, sleep on the same
430 address interpeted as
434 on a little-endian 64-bit platform would collide.
436 The last attribute of the key is the object type.
437 The sleep queue to which a sleeping thread is assigned is an individual
438 one for simple wait requests, mutexes, rwlocks, condvars and other
439 primitives, even when the physical address of the key is same.
441 When waking up a limited number of threads from a given sleep queue,
442 the highest priority threads that have been blocked for the longest on
443 the queue are selected.
447 are provided as a substrate for a userspace library to implement
450 A robust umutex must have the
454 On thread termination, the kernel walks two lists of mutexes.
455 The two lists head addresses must be provided by a prior call to
456 .Dv UMTX_OP_ROBUST_LISTS
458 The lists are singly-linked.
459 The link to next element is provided by the
464 Robust list processing is aborted if the kernel finds a mutex
465 with any of the following conditions:
466 .Bl -dash -offset indent -compact
472 not owned by the current thread, except when the mutex is pointed to
476 .Vt struct umtx_robust_lists_params ,
477 registered for the current thread
479 the combination of mutex flags is invalid
481 read of the umutex memory faults
483 the list length limit described in
488 Every mutex in both lists is unlocked as if the
489 .Dv UMTX_OP_MUTEX_UNLOCK
490 request is performed on it, but instead of the
494 field is written with the
495 .Dv UMUTEX_RB_OWNERDEAD
498 .Dv UMUTEX_RB_OWNERDEAD
499 state is locked by kernel due to the
500 .Dv UMTX_OP_MUTEX_TRYLOCK
502 .Dv UMTX_OP_MUTEX_LOCK
503 requests, the lock is granted and
507 Also, the kernel handles the
508 .Dv UMUTEX_RB_NOTRECOV
511 field specially, always returning the
513 error for lock attempts, without granting the lock.
515 The following operations, requested by the
517 argument to the function, are implemented:
518 .Bl -tag -width indent
521 The arguments for the request are:
522 .Bl -tag -width "obj"
524 Pointer to a variable of type
531 The current value of the variable pointed to by the
533 argument is compared with the
535 If they are equal, the requesting thread is put to interruptible sleep
536 until woken up or the optionally specified timeout expires.
538 The comparison and sleep are atomic.
539 In other words, if another thread writes a new value to
543 the request is guaranteed to not miss the wakeup,
544 which might otherwise happen between comparison and blocking.
546 The physical address of memory where the
548 variable is located, is used as a key to index sleeping threads.
550 The read of the current value of the
552 variable is not guarded by barriers.
553 In particular, it is the user's duty to ensure the lock acquire
554 and release memory semantics, if the
558 requests are used as a substrate for implementing a simple lock.
560 The request is not restartable.
561 An unblocked signal delivered during the wait always results in sleep
566 Optionally, a timeout for the request may be specified.
568 Wake the threads possibly sleeping due to
570 The arguments for the request are:
571 .Bl -tag -width "obj"
573 Pointer to a variable, used as a key to find sleeping threads.
577 threads are woken up by this request.
580 to wake up all waiters.
582 .It Dv UMTX_OP_MUTEX_TRYLOCK
584 The arguments to the request are:
585 .Bl -tag -width "obj"
587 Pointer to the umutex.
591 .Dv UMTX_OP_MUTEX_LOCK
594 instead of sleeping if the lock cannot be obtained immediately.
595 .It Dv UMTX_OP_MUTEX_LOCK
597 The arguments to the request are:
598 .Bl -tag -width "obj"
600 Pointer to the umutex.
603 Locking is performed by writing the current thread id into the
607 The write is atomic, preserves the
609 contention indicator, and provides the acquire barrier for
610 lock entrance semantic.
612 If the lock cannot be obtained immediately because another thread owns
613 the lock, the current thread is put to sleep, with
616 Upon wake up, the lock conditions are re-tested.
618 The request adheres to the priority protection or inheritance protocol
619 of the mutex, specified by the
620 .Dv UMUTEX_PRIO_PROTECT
622 .Dv UMUTEX_PRIO_INHERIT
625 Optionally, a timeout for the request may be specified.
627 A request with a timeout specified is not restartable.
628 An unblocked signal delivered during the wait always results in sleep
632 A request without timeout specified is always restarted after return
633 from a signal handler.
634 .It Dv UMTX_OP_MUTEX_UNLOCK
636 The arguments to the request are:
637 .Bl -tag -width "obj"
639 Pointer to the umutex.
642 Unlocks the mutex, by writing
648 The write is done with a release barrier, to provide lock leave semantic.
650 If there are threads sleeping in the sleep queue associated with the
651 umutex, one thread is woken up.
652 If more than one thread sleeps in the sleep queue, the
654 bit is set together with the write of the
659 The request adheres to the priority protection or inheritance protocol
660 of the mutex, specified by the
661 .Dv UMUTEX_PRIO_PROTECT
663 .Dv UMUTEX_PRIO_INHERIT
665 See description of the
669 structure for additional details of the request operation on the
670 priority protected protocol mutex.
671 .It Dv UMTX_OP_SET_CEILING
672 Set ceiling for the priority protected umutex.
673 The arguments to the request are:
674 .Bl -tag -width "uaddr"
676 Pointer to the umutex.
680 Address of a variable of type
684 and the update was successful, the previous ceiling value is
685 written to the location pointed to by
689 The request locks the umutex pointed to by the
691 parameter, waiting for the lock if not immediately available.
692 After the lock is obtained, the new ceiling value
698 after which the umutex is unlocked.
700 The locking does not adhere to the priority protect protocol,
704 .Xr pthread_mutex_setprioceiling 3
706 .It Dv UMTX_OP_CV_WAIT
707 Wait for a condition.
708 The arguments to the request are:
709 .Bl -tag -width "uaddr2"
714 Request flags, see below.
716 Pointer to the umutex.
718 Optional pointer to a
720 for timeout specification.
723 The request must be issued by the thread owning the mutex pointed to
733 argument, is set to an arbitrary non-zero value, after which the
735 mutex is unlocked (following the appropriate protocol), and
736 the current thread is put to sleep on the sleep queue keyed by
740 The operations are performed atomically.
741 It is guaranteed to not miss a wakeup from
742 .Dv UMTX_OP_CV_SIGNAL
744 .Dv UMTX_OP_CV_BROADCAST
745 sent between mutex unlock and putting the current thread on the sleep queue.
747 Upon wakeup, if the timeout expired and no other threads are sleeping in
748 the same sleep queue, the
753 umutex is not relocked.
755 The following flags are defined:
756 .Bl -tag -width "CVWAIT_CLOCKID"
757 .It Dv CVWAIT_ABSTIME
759 .It Dv CVWAIT_CLOCKID
763 Optionally, a timeout for the request may be specified.
764 Unlike other requests, the timeout value is specified directly by a
765 .Vt struct timespec ,
771 flag is provided, the timeout uses the clock from the
780 is used, regardless of the clock identifier possibly specified in the
781 .Vt struct _umtx_time .
784 flag is supplied, the timeout specifies absolute time value, otherwise
785 it denotes a relative time interval.
787 The request is not restartable.
788 An unblocked signal delivered during
789 the wait always results in sleep interruption and
792 .It Dv UMTX_OP_CV_SIGNAL
793 Wake up one condition waiter.
794 The arguments to the request are:
795 .Bl -tag -width "obj"
801 The request wakes up at most one thread sleeping on the sleep queue keyed
805 If the woken up thread was the last on the sleep queue, the
810 .It Dv UMTX_OP_CV_BROADCAST
811 Wake up all condition waiters.
812 The arguments to the request are:
813 .Bl -tag -width "obj"
819 The request wakes up all threads sleeping on the sleep queue keyed by the
827 .It Dv UMTX_OP_WAIT_UINT
830 but the type of the variable pointed to by
834 .Pq a 32-bit integer .
835 .It Dv UMTX_OP_RW_RDLOCK
839 The arguments to the request are:
840 .Bl -tag -width "obj"
842 Pointer to the lock (of type
846 Additional flags to augment locking behaviour.
847 The valid flags in the
850 .Bl -tag -width indent
851 .It Dv URWLOCK_PREFER_READER
855 The request obtains the read lock on the specified
857 by incrementing the count of readers in the
859 word of the structure.
861 .Dv URWLOCK_WRITE_OWNER
862 bit is set in the word
864 the lock was granted to a writer which has not yet relinquished
866 In this case the current thread is put to sleep until it makes sense to
870 .Dv URWLOCK_PREFER_READER
871 flag is set either in the
873 word of the structure, or in the
875 argument of the request, the presence of the threads trying to obtain
876 the write lock on the same structure does not prevent the current thread
877 from trying to obtain the read lock.
878 Otherwise, if the flag is not set, and the
879 .Dv URWLOCK_WRITE_WAITERS
882 the current thread does not attempt to obtain read-lock.
884 .Dv URWLOCK_READ_WAITERS
887 word and puts itself to sleep on corresponding sleep queue.
888 Upon wakeup, the locking conditions are re-evaluated.
890 Optionally, a timeout for the request may be specified.
892 The request is not restartable.
893 An unblocked signal delivered during the wait always results in sleep
897 .It Dv UMTX_OP_RW_WRLOCK
901 The arguments to the request are:
902 .Bl -tag -width "obj"
904 Pointer to the lock (of type
909 The request obtains a write lock on the specified
912 .Dv URWLOCK_WRITE_OWNER
915 word of the structure.
916 If there is already a write lock owner, as indicated by the
917 .Dv URWLOCK_WRITE_OWNER
918 bit being set, or there are read lock owners, as indicated
919 by the read-lock counter, the current thread does not attempt to
920 obtain the write-lock.
922 .Dv URWLOCK_WRITE_WAITERS
925 word and puts itself to sleep on corresponding sleep queue.
926 Upon wakeup, the locking conditions are re-evaluated.
928 Optionally, a timeout for the request may be specified.
930 The request is not restartable.
931 An unblocked signal delivered during the wait always results in sleep
935 .It Dv UMTX_OP_RW_UNLOCK
937 The arguments to the request are:
938 .Bl -tag -width "obj"
940 Pointer to the lock (of type
945 The unlock type (read or write) is determined by the
949 does not save information about the identity of the thread which
952 If there are pending writers after the unlock, and the
953 .Dv URWLOCK_PREFER_READER
954 flag is not set in the
958 structure, one writer is woken up, selected as described in the
962 .Dv URWLOCK_PREFER_READER
963 flag is set, a pending writer is woken up only if there is
966 If there are no pending writers, or, in the case that the
967 .Dv URWLOCK_PREFER_READER
968 flag is set, then all pending readers are woken up by unlock.
969 .It Dv UMTX_OP_WAIT_UINT_PRIVATE
971 .Dv UMTX_OP_WAIT_UINT ,
972 but unconditionally select the process-private sleep queue.
973 .It Dv UMTX_OP_WAKE_PRIVATE
976 but unconditionally select the process-private sleep queue.
977 .It Dv UMTX_OP_MUTEX_WAIT
978 Wait for mutex availability.
979 The arguments to the request are:
980 .Bl -tag -width "obj"
982 Address of the mutex.
986 .Dv UMTX_OP_MUTEX_LOCK ,
987 put the requesting thread to sleep if the mutex lock cannot be obtained
993 word of the mutex to indicate that there is a waiter, before the thread
994 is added to the sleep queue.
996 .Dv UMTX_OP_MUTEX_LOCK
997 request, the lock is not obtained.
999 The operation is not implemented for priority protected and
1000 priority inherited protocol mutexes.
1002 Optionally, a timeout for the request may be specified.
1004 A request with a timeout specified is not restartable.
1005 An unblocked signal delivered during the wait always results in sleep
1009 A request without a timeout automatically restarts if the signal disposition
1010 requested restart via the
1013 .Vt struct sigaction
1016 .It Dv UMTX_OP_NWAKE_PRIVATE
1017 Wake up a batch of sleeping threads.
1018 The arguments to the request are:
1019 .Bl -tag -width "obj"
1021 Pointer to the array of pointers.
1023 Number of elements in the array pointed to by
1027 For each element in the array pointed to by
1029 wakes up all threads waiting on the
1031 sleep queue with the key
1032 being the byte addressed by the array element.
1033 .It Dv UMTX_OP_MUTEX_WAKE
1034 Check if a normal umutex is unlocked and wake up a waiter.
1035 The arguments for the request are:
1036 .Bl -tag -width "obj"
1038 Pointer to the umutex.
1043 word of the mutex pointed to by the
1045 argument indicates unowned mutex, which has its contention indicator bit
1046 .Dv UMUTEX_CONTESTED
1047 set, clear the bit and wake up one waiter in the sleep queue associated
1048 with the byte addressed by the
1051 Only normal mutexes are supported by the request.
1052 The sleep queue is always one for a normal mutex type.
1054 This request is deprecated in favor of
1055 .Dv UMTX_OP_MUTEX_WAKE2
1056 since mutexes using it cannot synchronize their own destruction.
1059 word has already been set to
1061 when this request is made,
1062 so that another thread can lock, unlock and destroy the mutex
1063 (if no other thread uses the mutex afterwards).
1065 .Dv UMUTEX_CONTESTED
1066 bit may then modify freed memory.
1067 .It Dv UMTX_OP_MUTEX_WAKE2
1068 Check if a umutex is unlocked and wake up a waiter.
1069 The arguments for the request are:
1070 .Bl -tag -width "obj"
1072 Pointer to the umutex.
1077 The request does not read the
1083 argument supplies flag information, in particular, to determine the
1084 sleep queue where the waiters are found for wake up.
1086 If the mutex is unowned, one waiter is woken up.
1088 If the mutex memory cannot be accessed, all waiters are woken up.
1090 If there is more than one waiter on the sleep queue, or there is only
1091 one waiter but the mutex is owned by a thread, the
1092 .Dv UMUTEX_CONTESTED
1097 .It Dv UMTX_OP_SEM2_WAIT
1098 Wait until semaphore is available.
1099 The arguments to the request are:
1100 .Bl -tag -width "obj"
1102 Pointer to the semaphore (of type
1103 .Vt struct _usem2 ) .
1106 Put the requesting thread onto a sleep queue if the semaphore counter
1108 If the thread is put to sleep, the
1109 .Dv USEM_HAS_WAITERS
1112 word to indicate waiters.
1113 The function returns either due to
1115 indicating the semaphore is available (non-zero count due to post),
1117 The return does not guarantee that the semaphore is available,
1118 nor does it consume the semaphore lock on successful return.
1120 Optionally, a timeout for the request may be specified.
1122 A request with non-absolute timeout value is not restartable.
1123 An unblocked signal delivered during such wait results in sleep
1127 .It Dv UMTX_OP_SEM2_WAKE
1128 Wake up waiters on semaphore lock.
1129 The arguments to the request are:
1130 .Bl -tag -width "obj"
1132 Pointer to the semaphore (of type
1133 .Vt struct _usem2 ) .
1136 The request wakes up one waiter for the semaphore lock.
1137 The function does not increment the semaphore lock count.
1139 .Dv USEM_HAS_WAITERS
1142 word, and the last sleeping thread was woken up, the bit is cleared.
1146 shared memory objects (see
1148 which can be attached to a byte of physical memory, mapped into the
1149 process address space.
1150 The objects are used to implement process-shared locks in
1155 argument specifies the sub-request of the
1158 .Bl -tag -width indent
1159 .It Dv UMTX_SHM_CREAT
1160 Creates the anonymous shared memory object, which can be looked up
1161 with the specified key
1163 If the object associated with the
1165 key already exists, it is returned instead of creating a new object.
1166 The object's size is one page.
1167 On success, the file descriptor referencing the object is returned.
1168 The descriptor can be used for mapping the object using
1170 or for other shared memory operations.
1171 .It Dv UMTX_SHM_LOOKUP
1174 request, but if there is no shared memory object associated with
1177 an error is returned, and no new object is created.
1178 .It Dv UMTX_SHM_DESTROY
1179 De-associate the shared object with the specified key
1181 The object is destroyed after the last open file descriptor is closed
1182 and the last mapping for it is destroyed.
1183 .It Dv UMTX_SHM_ALIVE
1184 Checks whether there is a live shared object associated with the
1187 Returns zero if there is, and an error otherwise.
1188 This request is an optimization of the
1191 It is cheaper when only the liveness of the associated object is asked
1192 for, since no file descriptor is installed in the process fd table
1198 argument specifies the virtual address, which backing physical memory
1199 byte identity is used as a key for the anonymous shared object
1201 .It Dv UMTX_OP_ROBUST_LISTS
1202 Register the list heads for the current thread's robust mutex lists.
1203 The arguments to the request are:
1204 .Bl -tag -width "uaddr"
1206 Size of the structure passed in the
1210 Pointer to the structure of type
1211 .Vt struct umtx_robust_lists_params .
1214 The structure is defined as
1216 struct umtx_robust_lists_params {
1217 uintptr_t robust_list_offset;
1218 uintptr_t robust_priv_list_offset;
1219 uintptr_t robust_inact_offset;
1224 .Dv robust_list_offset
1225 member contains address of the first element in the list of locked
1226 robust shared mutexes.
1228 .Dv robust_priv_list_offset
1229 member contains address of the first element in the list of locked
1230 robust private mutexes.
1231 The private and shared robust locked lists are split to allow fast
1232 termination of the shared list on fork, in the child.
1235 .Dv robust_inact_offset
1236 contains a pointer to the mutex which might be locked in nearby future,
1237 or might have been just unlocked.
1238 It is typically set by the lock or unlock mutex implementation code
1239 around the whole operation, since lists can be only changed race-free
1240 when the thread owns the mutex.
1241 The kernel inspects the
1242 .Dv robust_inact_offset
1243 in addition to walking the shared and private lists.
1244 Also, the mutex pointed to by
1245 .Dv robust_inact_offset
1246 is handled more loosely at the thread termination time,
1247 than other mutexes on the list.
1248 That mutex is allowed to be not owned by the current thread,
1249 in which case list processing is continued.
1252 subsection for details.
1256 all requests, except
1262 request, will return zero.
1267 return a shared memory file descriptor on success.
1268 On error \-1 is returned, and the
1270 variable is set to indicate the error.
1274 operations can fail with the following errors:
1275 .Bl -tag -width "[ETIMEDOUT]"
1277 One of the arguments point to invalid memory.
1279 The clock identifier, specified for the
1280 .Vt struct _umtx_time
1281 timeout parameter, or in the
1287 The type of the mutex, encoded by the
1297 has changed the lock owner thread identifier during unlock.
1304 .Vt struct _umtx_time
1305 is less than zero, or
1307 is greater than 1000000000.
1311 argument specifies invalid operation.
1317 request specifies invalid operation.
1320 .Dv UMTX_OP_SET_CEILING
1321 request specifies non priority protected mutex.
1323 The new ceiling value for the
1324 .Dv UMTX_OP_SET_CEILING
1325 request, or one or more of the values read from the
1327 array during lock or unlock operations, is greater than
1330 Unlock attempted on an object not owned by the current thread.
1331 .It Bq Er EOWNERDEAD
1332 The lock was requested on an umutex where the
1334 field was set to the
1335 .Dv UMUTEX_RB_OWNERDEAD
1336 value, indicating terminated robust mutex.
1337 The lock was granted to the caller, so this error in fact
1338 indicates success with additional conditions.
1339 .It Bq Er ENOTRECOVERABLE
1340 The lock was requested on an umutex which
1342 field is equal to the
1343 .Dv UMUTEX_RB_NOTRECOV
1344 value, indicating abandoned robust mutex after termination.
1345 The lock was not granted to the caller.
1347 The shared memory object, associated with the address passed to the
1351 request, was destroyed.
1354 .Dv UMTX_SHM_LOOKUP ,
1355 .Dv UMTX_SHM_DESTROY ,
1360 request, there is no shared memory object associated with the provided key.
1366 request cannot be satisfied, because allocation of the shared memory object
1372 The maximum number of readers
1373 .Dv ( URWLOCK_MAX_READERS )
1374 were already granted ownership of the given
1378 A try mutex lock operation was not able to obtain the lock.
1380 The request specified a timeout in the
1384 arguments, and timed out before obtaining the lock or being woken up.
1386 A signal was delivered during wait, for a non-restartable operation.
1387 Operations with timeouts are typically non-restartable, but timeouts
1388 specified in absolute time may be restartable.
1390 A signal was delivered during wait, for a restartable operation.
1391 Mutex lock requests without timeout specified are restartable.
1392 The error is not returned to userspace code since restart
1393 is handled by usual adjustment of the instruction counter.
1396 .Xr clock_gettime 2 ,
1406 .Xr thr_set_name 2 ,
1411 system call is non-standard and is used by the
1418 A window between a unlocking robust mutex and resetting the pointer in the
1419 .Dv robust_inact_offset
1420 member of the registered
1421 .Vt struct umtx_robust_lists_params
1422 allows another thread to destroy the mutex, thus making the kernel inspect
1423 freed or reused memory.
1426 implementation is only vulnerable to this race when operating on
1428 A possible fix for the current implementation is to strengthen the checks
1429 for shared mutexes before terminating them, in particular, verifying
1430 that the mutex memory is mapped from a shared memory object allocated
1434 This is not done because it is believed that the race is adequately
1435 covered by other consistency checks, while adding the check would
1436 prevent alternative implementations of