1 .\" Copyright (c) 2016 The FreeBSD Foundation, Inc.
3 .\" This documentation was written by
4 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
5 .\" from the FreeBSD Foundation.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .Nd interface for implementation of userspace threading synchronization primitives
42 .Fn _umtx_op "void *obj" "int op" "u_long val" "void *uaddr" "void *uaddr2"
46 system call provides kernel support for userspace implementation of
47 the threading synchronization primitives.
50 uses the syscall to implement
52 pthread locks, like mutexes, condition variables and so on.
54 The operations, performed by the
56 syscall, operate on userspace objects which are described
57 by the following structures.
58 Reserved fields and paddings are omitted.
59 All objects require ABI-mandated alignment, but this is not currently
60 enforced consistently on all architectures.
62 The following flags are defined for flag fields of all structures:
63 .Bl -tag -width indent
64 .It Dv USYNC_PROCESS_SHARED
65 Allow selection of the process-shared sleep queue for the thread sleep
66 container, when the lock ownership cannot be granted immediately,
67 and the operation must sleep.
68 The process-shared or process-private sleep queue is selected based on
69 the attributes of the memory mapping which contains the first byte of
72 Otherwise, if the flag is not specified, the process-private sleep queue
73 is selected regardless of the memory mapping attributes, as an optimization.
77 subsection below for more details on sleep queues.
79 .Bl -hang -offset indent
83 volatile lwpid_t m_owner;
85 uint32_t m_ceilings[2];
92 field is the actual lock.
93 It contains either the thread identifier of the lock owner in the
94 locked state, or zero when the lock is unowned.
95 The highest bit set indicates that there is contention on the lock.
96 The constants are defined for special values:
97 .Bl -tag -width indent
99 Zero, the value stored in the unowned lock.
100 .It Dv UMUTEX_CONTESTED
101 The contention indicator.
102 .It Dv UMUTEX_RB_OWNERDEAD
103 A thread owning the robust mutex terminated.
104 The mutex is in unlocked state.
105 .It Dv UMUTEX_RB_NOTRECOV
106 The robust mutex is in a non-recoverable state.
107 It cannot be locked until reinitialized.
112 field may contain the following umutex-specific flags, in addition to
114 .Bl -tag -width indent
115 .It Dv UMUTEX_PRIO_INHERIT
117 .Em Priority Inheritance
119 .It Dv UMUTEX_PRIO_PROTECT
121 .Em Priority Protection
124 Mutex is robust, as described in the
127 .It Dv UMUTEX_NONCONSISTENT
128 Robust mutex is in a transient non-consistent state.
132 In the manual page, mutexes not having
133 .Dv UMUTEX_PRIO_INHERIT
135 .Dv UMUTEX_PRIO_PROTECT
136 flags set, are called normal mutexes.
138 .Pq normal, priority-inherited, and priority-protected
139 has a separate sleep queue associated
142 For priority protected mutexes, the
144 array contains priority ceiling values.
147 is the ceiling value for the mutex, as specified by
150 .Em Priority Protected
154 is used only for the unlock of a priority protected mutex, when
155 unlock is done in an order other than the reversed lock order.
158 must contain the ceiling value for the last locked priority protected
159 mutex, for proper priority reassignment.
160 If, instead, the unlocking mutex was the last priority propagated
161 mutex locked by the thread,
164 This is required because kernel does not maintain the ordered lock list.
165 .It Sy Condition variable
168 volatile uint32_t c_has_waiters;
176 value indicates that there are in-kernel waiters for the condition,
183 field contains flags.
184 Only the common flags
185 .Pq Dv USYNC_PROCESS_SHARED
186 are defined for ucond.
190 member provides the clock identifier to use for timeout, when the
194 flag and the timeout specified.
195 Valid clock identifiers are a subset of those for
196 .Xr clock_gettime 2 :
201 .Dv CLOCK_MONOTONIC_FAST
203 .Dv CLOCK_MONOTONIC_PRECISE
209 .Dv CLOCK_REALTIME_FAST
211 .Dv CLOCK_REALTIME_PRECISE
217 .Dv CLOCK_UPTIME_FAST
219 .Dv CLOCK_UPTIME_PRECISE
223 .It Sy Reader/writer lock
226 volatile int32_t rw_state;
228 uint32_t rw_blocked_readers;
229 uint32_t rw_blocked_writers;
235 field is the actual lock.
236 It contains both the flags and counter of the read locks which were
241 .Bl -tag -width indent
242 .It Dv URWLOCK_WRITE_OWNER
243 Write lock was granted.
244 .It Dv URWLOCK_WRITE_WAITERS
245 There are write lock waiters.
246 .It Dv URWLOCK_READ_WAITERS
247 There are read lock waiters.
248 .It Dv URWLOCK_READER_COUNT(c)
249 Returns the count of currently granted read locks.
252 At any given time there may be only one thread to which the writer lock
255 and no threads are granted read lock.
256 Or, at the given time, up to
257 .Dv URWLOCK_MAX_READERS
258 threads may be granted the read lock simultaneously, but write lock is
259 not granted to any thread.
261 The following flags for the
265 are defined, in addition to the common flags:
266 .Bl -tag -width indent
267 .It Dv URWLOCK_PREFER_READER
268 If specified, immediately grant read lock requests when
270 is already read-locked, even in presence of unsatisfied write
272 By default, if there is a write lock waiter, further read requests are
273 not granted, to prevent unfair write lock waiter starvation.
277 .Dv rw_blocked_readers
279 .Dv rw_blocked_writers
280 members contain the count of threads which are sleeping in kernel,
281 waiting for the associated request type to be granted.
282 The fields are used by kernel to update the
283 .Dv URWLOCK_READ_WAITERS
285 .Dv URWLOCK_WRITE_WAITERS
288 lock after requesting thread was woken up.
292 volatile uint32_t _count;
299 word represents a counting semaphore.
300 A non-zero value indicates an unlocked (posted) semaphore, while zero
301 represents the locked state.
302 The maximal supported semaphore count is
307 word, besides the counter of posts (unlocks), also contains the
309 bit, which indicates that locked semaphore has waiting threads.
313 macro, applied to the
315 word, returns the current semaphore counter, which is the number of posts
316 issued on the semaphore.
318 The following bits for the
322 are defined, in addition to the common flags:
323 .Bl -tag -width indent
325 Flag is ignored by kernel.
327 .It Sy Timeout parameter
330 struct timespec _timeout;
338 operations allow the blocking time to be limited, failing the request
339 if it cannot be satisfied in the specified time period.
340 The timeout is specified by passing either the address of
341 .Vt struct timespec ,
342 or its extended variant,
343 .Vt struct _umtx_time ,
348 They are distinguished by the
350 value, which must be equal to the size of the structure pointed to by
357 member specifies the time when the timeout should occur.
358 Legal values for clock identifier
365 and use the same underlying clocks.
366 The specified clock is used to obtain the current time value.
367 Interval counting is always performed by the monotonic wall clock.
371 argument allows the following flags to further define the timeout behaviour:
372 .Bl -tag -width indent
376 value is the absolute time.
377 The thread will be unblocked and the request failed when specified
378 clock value is equal or exceeds the
381 If the flag is absent, the timeout value is relative, that is the amount
382 of time, measured by the monotonic wall clock from the moment of the request
387 When a locking request cannot be immediately satisfied, the thread is
390 which is a non-runnable state terminated by the
393 Lock operations include a
395 variant which returns an error rather than sleeping if the lock cannot
399 provides requests which explicitly put the thread to sleep.
401 Wakes need to know which threads to make runnable, so sleeping threads
402 are grouped into containers called
404 A sleep queue is identified by a key, which for
406 is defined as the physical address of some variable.
409 address is used, which means that same variable mapped multiple
410 times will give one key value.
411 This mechanism enables the construction of
415 A related attribute of the key is shareability.
416 Some requests always interpret keys as private for the current process,
417 creating sleep queues with the scope of the current process even if
418 the memory is shared.
419 Others either select the shareability automatically from the
420 mapping attributes, or take additional input as the
421 .Dv USYNC_PROCESS_SHARED
423 This is done as optimization, allowing the lock scope to be limited
424 regardless of the kind of backing memory.
426 Only the address of the start byte of the variable specified as key is
427 important for determining corresponding sleep queue.
428 The size of the variable does not matter, so, for example, sleep on the same
429 address interpeted as
433 on a little-endian 64-bit platform would collide.
435 The last attribute of the key is the object type.
436 The sleep queue to which a sleeping thread is assigned is an individual
437 one for simple wait requests, mutexes, rwlocks, condvars and other
438 primitives, even when the physical address of the key is same.
440 When waking up a limited number of threads from a given sleep queue,
441 the highest priority threads that have been blocked for the longest on
442 the queue are selected.
446 are provided as a substrate for a userspace library to implement
449 A robust umutex must have the
453 On thread termination, the kernel walks two lists of mutexes.
454 The two lists head addresses must be provided by a prior call to
455 .Dv UMTX_OP_ROBUST_LISTS
457 The lists are singly-linked.
458 The link to next element is provided by the
463 Robust list processing is aborted if the kernel finds a mutex
464 with any of the following conditions:
465 .Bl -dash -offset indent -compact
471 not owned by the current thread, except when the mutex is pointed to
475 .Vt struct umtx_robust_lists_params ,
476 registered for the current thread
478 the combination of mutex flags is invalid
480 read of the umutex memory faults
482 the list length limit described in
487 Every mutex in both lists is unlocked as if the
488 .Dv UMTX_OP_MUTEX_UNLOCK
489 request is performed on it, but instead of the
493 field is written with the
494 .Dv UMUTEX_RB_OWNERDEAD
497 .Dv UMUTEX_RB_OWNERDEAD
498 state is locked by kernel due to the
499 .Dv UMTX_OP_MUTEX_TRYLOCK
501 .Dv UMTX_OP_MUTEX_LOCK
502 requests, the lock is granted and
506 Also, the kernel handles the
507 .Dv UMUTEX_RB_NOTRECOV
510 field specially, always returning the
512 error for lock attempts, without granting the lock.
514 The following operations, requested by the
516 argument to the function, are implemented:
517 .Bl -tag -width indent
520 The arguments for the request are:
521 .Bl -tag -width "obj"
523 Pointer to a variable of type
530 The current value of the variable pointed to by the
532 argument is compared with the
534 If they are equal, the requesting thread is put to interruptible sleep
535 until woken up or the optionally specified timeout expires.
537 The comparison and sleep are atomic.
538 In other words, if another thread writes a new value to
542 the request is guaranteed to not miss the wakeup,
543 which might otherwise happen between comparison and blocking.
545 The physical address of memory where the
547 variable is located, is used as a key to index sleeping threads.
549 The read of the current value of the
551 variable is not guarded by barriers.
552 In particular, it is the user's duty to ensure the lock acquire
553 and release memory semantics, if the
557 requests are used as a substrate for implementing a simple lock.
559 The request is not restartable.
560 An unblocked signal delivered during the wait always results in sleep
565 Optionally, a timeout for the request may be specified.
567 Wake the threads possibly sleeping due to
569 The arguments for the request are:
570 .Bl -tag -width "obj"
572 Pointer to a variable, used as a key to find sleeping threads.
576 threads are woken up by this request.
579 to wake up all waiters.
581 .It Dv UMTX_OP_MUTEX_TRYLOCK
583 The arguments to the request are:
584 .Bl -tag -width "obj"
586 Pointer to the umutex.
590 .Dv UMTX_OP_MUTEX_LOCK
593 instead of sleeping if the lock cannot be obtained immediately.
594 .It Dv UMTX_OP_MUTEX_LOCK
596 The arguments to the request are:
597 .Bl -tag -width "obj"
599 Pointer to the umutex.
602 Locking is performed by writing the current thread id into the
606 The write is atomic, preserves the
608 contention indicator, and provides the acquire barrier for
609 lock entrance semantic.
611 If the lock cannot be obtained immediately because another thread owns
612 the lock, the current thread is put to sleep, with
615 Upon wake up, the lock conditions are re-tested.
617 The request adheres to the priority protection or inheritance protocol
618 of the mutex, specified by the
619 .Dv UMUTEX_PRIO_PROTECT
621 .Dv UMUTEX_PRIO_INHERIT
624 Optionally, a timeout for the request may be specified.
626 A request with a timeout specified is not restartable.
627 An unblocked signal delivered during the wait always results in sleep
631 A request without timeout specified is always restarted after return
632 from a signal handler.
633 .It Dv UMTX_OP_MUTEX_UNLOCK
635 The arguments to the request are:
636 .Bl -tag -width "obj"
638 Pointer to the umutex.
641 Unlocks the mutex, by writing
647 The write is done with a release barrier, to provide lock leave semantic.
649 If there are threads sleeping in the sleep queue associated with the
650 umutex, one thread is woken up.
651 If more than one thread sleeps in the sleep queue, the
653 bit is set together with the write of the
658 The request adheres to the priority protection or inheritance protocol
659 of the mutex, specified by the
660 .Dv UMUTEX_PRIO_PROTECT
662 .Dv UMUTEX_PRIO_INHERIT
664 See description of the
668 structure for additional details of the request operation on the
669 priority protected protocol mutex.
670 .It Dv UMTX_OP_SET_CEILING
671 Set ceiling for the priority protected umutex.
672 The arguments to the request are:
673 .Bl -tag -width "uaddr"
675 Pointer to the umutex.
679 Address of a variable of type
683 and the update was successful, the previous ceiling value is
684 written to the location pointed to by
688 The request locks the umutex pointed to by the
690 parameter, waiting for the lock if not immediately available.
691 After the lock is obtained, the new ceiling value
697 after which the umutex is unlocked.
699 The locking does not adhere to the priority protect protocol,
703 .Xr pthread_mutex_setprioceiling 3
705 .It Dv UMTX_OP_CV_WAIT
706 Wait for a condition.
707 The arguments to the request are:
708 .Bl -tag -width "uaddr2"
713 Request flags, see below.
715 Pointer to the umutex.
717 Optional pointer to a
719 for timeout specification.
722 The request must be issued by the thread owning the mutex pointed to
732 argument, is set to an arbitrary non-zero value, after which the
734 mutex is unlocked (following the appropriate protocol), and
735 the current thread is put to sleep on the sleep queue keyed by
739 The operations are performed atomically.
740 It is guaranteed to not miss a wakeup from
741 .Dv UMTX_OP_CV_SIGNAL
743 .Dv UMTX_OP_CV_BROADCAST
744 sent between mutex unlock and putting the current thread on the sleep queue.
746 Upon wakeup, if the timeout expired and no other threads are sleeping in
747 the same sleep queue, the
752 umutex is not relocked.
754 The following flags are defined:
755 .Bl -tag -width "CVWAIT_CLOCKID"
756 .It Dv CVWAIT_ABSTIME
758 .It Dv CVWAIT_CLOCKID
762 Optionally, a timeout for the request may be specified.
763 Unlike other requests, the timeout value is specified directly by a
764 .Vt struct timespec ,
770 flag is provided, the timeout uses the clock from the
779 is used, regardless of the clock identifier possibly specified in the
780 .Vt struct _umtx_time .
783 flag is supplied, the timeout specifies absolute time value, otherwise
784 it denotes a relative time interval.
786 The request is not restartable.
787 An unblocked signal delivered during
788 the wait always results in sleep interruption and
791 .It Dv UMTX_OP_CV_SIGNAL
792 Wake up one condition waiter.
793 The arguments to the request are:
794 .Bl -tag -width "obj"
800 The request wakes up at most one thread sleeping on the sleep queue keyed
804 If the woken up thread was the last on the sleep queue, the
809 .It Dv UMTX_OP_CV_BROADCAST
810 Wake up all condition waiters.
811 The arguments to the request are:
812 .Bl -tag -width "obj"
818 The request wakes up all threads sleeping on the sleep queue keyed by the
826 .It Dv UMTX_OP_WAIT_UINT
829 but the type of the variable pointed to by
833 .Pq a 32-bit integer .
834 .It Dv UMTX_OP_RW_RDLOCK
838 The arguments to the request are:
839 .Bl -tag -width "obj"
841 Pointer to the lock (of type
845 Additional flags to augment locking behaviour.
846 The valid flags in the
849 .Bl -tag -width indent
850 .It Dv URWLOCK_PREFER_READER
854 The request obtains the read lock on the specified
856 by incrementing the count of readers in the
858 word of the structure.
860 .Dv URWLOCK_WRITE_OWNER
861 bit is set in the word
863 the lock was granted to a writer which has not yet relinquished
865 In this case the current thread is put to sleep until it makes sense to
869 .Dv URWLOCK_PREFER_READER
870 flag is set either in the
872 word of the structure, or in the
874 argument of the request, the presence of the threads trying to obtain
875 the write lock on the same structure does not prevent the current thread
876 from trying to obtain the read lock.
877 Otherwise, if the flag is not set, and the
878 .Dv URWLOCK_WRITE_WAITERS
881 the current thread does not attempt to obtain read-lock.
883 .Dv URWLOCK_READ_WAITERS
886 word and puts itself to sleep on corresponding sleep queue.
887 Upon wakeup, the locking conditions are re-evaluated.
889 Optionally, a timeout for the request may be specified.
891 The request is not restartable.
892 An unblocked signal delivered during the wait always results in sleep
896 .It Dv UMTX_OP_RW_WRLOCK
900 The arguments to the request are:
901 .Bl -tag -width "obj"
903 Pointer to the lock (of type
908 The request obtains a write lock on the specified
911 .Dv URWLOCK_WRITE_OWNER
914 word of the structure.
915 If there is already a write lock owner, as indicated by the
916 .Dv URWLOCK_WRITE_OWNER
917 bit being set, or there are read lock owners, as indicated
918 by the read-lock counter, the current thread does not attempt to
919 obtain the write-lock.
921 .Dv URWLOCK_WRITE_WAITERS
924 word and puts itself to sleep on corresponding sleep queue.
925 Upon wakeup, the locking conditions are re-evaluated.
927 Optionally, a timeout for the request may be specified.
929 The request is not restartable.
930 An unblocked signal delivered during the wait always results in sleep
934 .It Dv UMTX_OP_RW_UNLOCK
936 The arguments to the request are:
937 .Bl -tag -width "obj"
939 Pointer to the lock (of type
944 The unlock type (read or write) is determined by the
948 does not save information about the identity of the thread which
951 If there are pending writers after the unlock, and the
952 .Dv URWLOCK_PREFER_READER
953 flag is not set in the
957 structure, one writer is woken up, selected as described in the
961 .Dv URWLOCK_PREFER_READER
962 flag is set, a pending writer is woken up only if there is
965 If there are no pending writers, or, in the case that the
966 .Dv URWLOCK_PREFER_READER
967 flag is set, then all pending readers are woken up by unlock.
968 .It Dv UMTX_OP_WAIT_UINT_PRIVATE
970 .Dv UMTX_OP_WAIT_UINT ,
971 but unconditionally select the process-private sleep queue.
972 .It Dv UMTX_OP_WAKE_PRIVATE
975 but unconditionally select the process-private sleep queue.
976 .It Dv UMTX_OP_MUTEX_WAIT
977 Wait for mutex availability.
978 The arguments to the request are:
979 .Bl -tag -width "obj"
981 Address of the mutex.
985 .Dv UMTX_OP_MUTEX_LOCK ,
986 put the requesting thread to sleep if the mutex lock cannot be obtained
992 word of the mutex to indicate that there is a waiter, before the thread
993 is added to the sleep queue.
995 .Dv UMTX_OP_MUTEX_LOCK
996 request, the lock is not obtained.
998 The operation is not implemented for priority protected and
999 priority inherited protocol mutexes.
1001 Optionally, a timeout for the request may be specified.
1003 A request with a timeout specified is not restartable.
1004 An unblocked signal delivered during the wait always results in sleep
1008 A request without a timeout automatically restarts if the signal disposition
1009 requested restart via the
1012 .Vt struct sigaction
1015 .It Dv UMTX_OP_NWAKE_PRIVATE
1016 Wake up a batch of sleeping threads.
1017 The arguments to the request are:
1018 .Bl -tag -width "obj"
1020 Pointer to the array of pointers.
1022 Number of elements in the array pointed to by
1026 For each element in the array pointed to by
1028 wakes up all threads waiting on the
1030 sleep queue with the key
1031 being the byte addressed by the array element.
1032 .It Dv UMTX_OP_MUTEX_WAKE
1033 Check if a normal umutex is unlocked and wake up a waiter.
1034 The arguments for the request are:
1035 .Bl -tag -width "obj"
1037 Pointer to the umutex.
1042 word of the mutex pointed to by the
1044 argument indicates unowned mutex, which has its contention indicator bit
1045 .Dv UMUTEX_CONTESTED
1046 set, clear the bit and wake up one waiter in the sleep queue associated
1047 with the byte addressed by the
1050 Only normal mutexes are supported by the request.
1051 The sleep queue is always one for a normal mutex type.
1053 This request is deprecated in favor of
1054 .Dv UMTX_OP_MUTEX_WAKE2
1055 since mutexes using it cannot synchronize their own destruction.
1058 word has already been set to
1060 when this request is made,
1061 so that another thread can lock, unlock and destroy the mutex
1062 (if no other thread uses the mutex afterwards).
1064 .Dv UMUTEX_CONTESTED
1065 bit may then modify freed memory.
1066 .It Dv UMTX_OP_MUTEX_WAKE2
1067 Check if a umutex is unlocked and wake up a waiter.
1068 The arguments for the request are:
1069 .Bl -tag -width "obj"
1071 Pointer to the umutex.
1076 The request does not read the
1082 argument supplies flag information, in particular, to determine the
1083 sleep queue where the waiters are found for wake up.
1085 If the mutex is unowned, one waiter is woken up.
1087 If the mutex memory cannot be accessed, all waiters are woken up.
1089 If there is more than one waiter on the sleep queue, or there is only
1090 one waiter but the mutex is owned by a thread, the
1091 .Dv UMUTEX_CONTESTED
1096 .It Dv UMTX_OP_SEM2_WAIT
1097 Wait until semaphore is available.
1098 The arguments to the request are:
1099 .Bl -tag -width "obj"
1101 Pointer to the semaphore (of type
1102 .Vt struct _usem2 ) .
1104 Size of the memory passed in via the
1108 Optional pointer to a structure of type
1109 .Vt struct _umtx_time ,
1110 which may be followed by a structure of type
1111 .Vt struct timespec .
1114 Put the requesting thread onto a sleep queue if the semaphore counter
1116 If the thread is put to sleep, the
1117 .Dv USEM_HAS_WAITERS
1120 word to indicate waiters.
1121 The function returns either due to
1123 indicating the semaphore is available (non-zero count due to post),
1125 The return does not guarantee that the semaphore is available,
1126 nor does it consume the semaphore lock on successful return.
1128 Optionally, a timeout for the request may be specified.
1130 A request with non-absolute timeout value is not restartable.
1131 An unblocked signal delivered during such wait results in sleep
1138 was not set, and the operation was interrupted and the caller passed in a
1140 large enough to hold a
1142 following the initial
1143 .Vt struct _umtx_time ,
1146 is updated to contain the unslept amount.
1147 .It Dv UMTX_OP_SEM2_WAKE
1148 Wake up waiters on semaphore lock.
1149 The arguments to the request are:
1150 .Bl -tag -width "obj"
1152 Pointer to the semaphore (of type
1153 .Vt struct _usem2 ) .
1156 The request wakes up one waiter for the semaphore lock.
1157 The function does not increment the semaphore lock count.
1159 .Dv USEM_HAS_WAITERS
1162 word, and the last sleeping thread was woken up, the bit is cleared.
1166 shared memory objects (see
1168 which can be attached to a byte of physical memory, mapped into the
1169 process address space.
1170 The objects are used to implement process-shared locks in
1175 argument specifies the sub-request of the
1178 .Bl -tag -width indent
1179 .It Dv UMTX_SHM_CREAT
1180 Creates the anonymous shared memory object, which can be looked up
1181 with the specified key
1183 If the object associated with the
1185 key already exists, it is returned instead of creating a new object.
1186 The object's size is one page.
1187 On success, the file descriptor referencing the object is returned.
1188 The descriptor can be used for mapping the object using
1190 or for other shared memory operations.
1191 .It Dv UMTX_SHM_LOOKUP
1194 request, but if there is no shared memory object associated with
1197 an error is returned, and no new object is created.
1198 .It Dv UMTX_SHM_DESTROY
1199 De-associate the shared object with the specified key
1201 The object is destroyed after the last open file descriptor is closed
1202 and the last mapping for it is destroyed.
1203 .It Dv UMTX_SHM_ALIVE
1204 Checks whether there is a live shared object associated with the
1207 Returns zero if there is, and an error otherwise.
1208 This request is an optimization of the
1211 It is cheaper when only the liveness of the associated object is asked
1212 for, since no file descriptor is installed in the process fd table
1218 argument specifies the virtual address, which backing physical memory
1219 byte identity is used as a key for the anonymous shared object
1221 .It Dv UMTX_OP_ROBUST_LISTS
1222 Register the list heads for the current thread's robust mutex lists.
1223 The arguments to the request are:
1224 .Bl -tag -width "uaddr"
1226 Size of the structure passed in the
1230 Pointer to the structure of type
1231 .Vt struct umtx_robust_lists_params .
1234 The structure is defined as
1236 struct umtx_robust_lists_params {
1237 uintptr_t robust_list_offset;
1238 uintptr_t robust_priv_list_offset;
1239 uintptr_t robust_inact_offset;
1244 .Dv robust_list_offset
1245 member contains address of the first element in the list of locked
1246 robust shared mutexes.
1248 .Dv robust_priv_list_offset
1249 member contains address of the first element in the list of locked
1250 robust private mutexes.
1251 The private and shared robust locked lists are split to allow fast
1252 termination of the shared list on fork, in the child.
1255 .Dv robust_inact_offset
1256 contains a pointer to the mutex which might be locked in nearby future,
1257 or might have been just unlocked.
1258 It is typically set by the lock or unlock mutex implementation code
1259 around the whole operation, since lists can be only changed race-free
1260 when the thread owns the mutex.
1261 The kernel inspects the
1262 .Dv robust_inact_offset
1263 in addition to walking the shared and private lists.
1264 Also, the mutex pointed to by
1265 .Dv robust_inact_offset
1266 is handled more loosely at the thread termination time,
1267 than other mutexes on the list.
1268 That mutex is allowed to be not owned by the current thread,
1269 in which case list processing is continued.
1272 subsection for details.
1277 argument may be a bitwise OR of a single command from above with one or more of
1278 the following flags:
1279 .Bl -tag -width indent
1280 .It Dv UMTX_OP__I386
1281 Request i386 ABI compatibility from the native
1284 Specifically, this implies that:
1285 .Bl -hang -offset indent
1288 arguments that point to a word, point to a 32-bit integer.
1291 .Dv UMTX_OP_NWAKE_PRIVATE
1293 argument is a pointer to an array of 32-bit pointers.
1299 is a 32-bit pointer.
1302 uses a 32-bit time_t.
1306 has no effect if this flag is set.
1307 This flag is valid for all architectures, but it is ignored on i386.
1308 .It Dv UMTX_OP__32BIT
1309 Request non-i386, 32-bit ABI compatibility from the native
1312 Specifically, this implies that:
1313 .Bl -hang -offset indent
1316 arguments that point to a word, point to a 32-bit integer.
1319 .Dv UMTX_OP_NWAKE_PRIVATE
1321 argument is a pointer to an array of 32-bit pointers.
1327 is a 32-bit pointer.
1330 uses a 64-bit time_t.
1333 This flag has no effect if
1336 This flag is valid for all architectures.
1339 Note that if any 32-bit ABI compatibility is being requested, then care must be
1340 taken with robust lists.
1341 A single thread may not mix 32-bit compatible robust lists with native
1344 .Dv UMTX_OP_ROBUST_LISTS
1345 call in a given thread determines which ABI that thread will use for robust
1346 lists going forward.
1349 all requests, except
1355 request, will return zero.
1360 return a shared memory file descriptor on success.
1361 On error \-1 is returned, and the
1363 variable is set to indicate the error.
1367 operations can fail with the following errors:
1368 .Bl -tag -width "[ETIMEDOUT]"
1370 One of the arguments point to invalid memory.
1372 The clock identifier, specified for the
1373 .Vt struct _umtx_time
1374 timeout parameter, or in the
1380 The type of the mutex, encoded by the
1390 has changed the lock owner thread identifier during unlock.
1397 .Vt struct _umtx_time
1398 is less than zero, or
1400 is greater than 1000000000.
1404 argument specifies invalid operation.
1410 request specifies invalid operation.
1413 .Dv UMTX_OP_SET_CEILING
1414 request specifies non priority protected mutex.
1416 The new ceiling value for the
1417 .Dv UMTX_OP_SET_CEILING
1418 request, or one or more of the values read from the
1420 array during lock or unlock operations, is greater than
1423 Unlock attempted on an object not owned by the current thread.
1424 .It Bq Er EOWNERDEAD
1425 The lock was requested on an umutex where the
1427 field was set to the
1428 .Dv UMUTEX_RB_OWNERDEAD
1429 value, indicating terminated robust mutex.
1430 The lock was granted to the caller, so this error in fact
1431 indicates success with additional conditions.
1432 .It Bq Er ENOTRECOVERABLE
1433 The lock was requested on an umutex which
1435 field is equal to the
1436 .Dv UMUTEX_RB_NOTRECOV
1437 value, indicating abandoned robust mutex after termination.
1438 The lock was not granted to the caller.
1440 The shared memory object, associated with the address passed to the
1444 request, was destroyed.
1447 .Dv UMTX_SHM_LOOKUP ,
1448 .Dv UMTX_SHM_DESTROY ,
1453 request, there is no shared memory object associated with the provided key.
1459 request cannot be satisfied, because allocation of the shared memory object
1465 The maximum number of readers
1466 .Dv ( URWLOCK_MAX_READERS )
1467 were already granted ownership of the given
1471 A try mutex lock operation was not able to obtain the lock.
1473 The request specified a timeout in the
1477 arguments, and timed out before obtaining the lock or being woken up.
1479 A signal was delivered during wait, for a non-restartable operation.
1480 Operations with timeouts are typically non-restartable, but timeouts
1481 specified in absolute time may be restartable.
1483 A signal was delivered during wait, for a restartable operation.
1484 Mutex lock requests without timeout specified are restartable.
1485 The error is not returned to userspace code since restart
1486 is handled by usual adjustment of the instruction counter.
1489 .Xr clock_gettime 2 ,
1499 .Xr thr_set_name 2 ,
1504 system call is non-standard and is used by the
1511 A window between a unlocking robust mutex and resetting the pointer in the
1512 .Dv robust_inact_offset
1513 member of the registered
1514 .Vt struct umtx_robust_lists_params
1515 allows another thread to destroy the mutex, thus making the kernel inspect
1516 freed or reused memory.
1519 implementation is only vulnerable to this race when operating on
1521 A possible fix for the current implementation is to strengthen the checks
1522 for shared mutexes before terminating them, in particular, verifying
1523 that the mutex memory is mapped from a shared memory object allocated
1527 This is not done because it is believed that the race is adequately
1528 covered by other consistency checks, while adding the check would
1529 prevent alternative implementations of