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
33 .Nd interface for implementation of userspace threading synchronization primitives
40 .Fn _umtx_op "void *obj" "int op" "u_long val" "void *uaddr" "void *uaddr2"
44 system call provides kernel support for userspace implementation of
45 the threading synchronization primitives.
48 uses the syscall to implement
50 pthread locks, like mutexes, condition variables and so on.
52 The operations, performed by the
54 syscall, operate on userspace objects which are described
55 by the following structures.
56 Reserved fields and paddings are omitted.
57 All objects require ABI-mandated alignment, but this is not currently
58 enforced consistently on all architectures.
60 The following flags are defined for flag fields of all structures:
61 .Bl -tag -width indent
62 .It Dv USYNC_PROCESS_SHARED
63 Allow selection of the process-shared sleep queue for the thread sleep
64 container, when the lock ownership cannot be granted immediately,
65 and the operation must sleep.
66 The process-shared or process-private sleep queue is selected based on
67 the attributes of the memory mapping which contains the first byte of
70 Otherwise, if the flag is not specified, the process-private sleep queue
71 is selected regardless of the memory mapping attributes, as an optimization.
75 subsection below for more details on sleep queues.
77 .Bl -hang -offset indent
81 volatile lwpid_t m_owner;
83 uint32_t m_ceilings[2];
90 field is the actual lock.
91 It contains either the thread identifier of the lock owner in the
92 locked state, or zero when the lock is unowned.
93 The highest bit set indicates that there is contention on the lock.
94 The constants are defined for special values:
95 .Bl -tag -width indent
97 Zero, the value stored in the unowned lock.
98 .It Dv UMUTEX_CONTESTED
99 The contention indicator.
100 .It Dv UMUTEX_RB_OWNERDEAD
101 A thread owning the robust mutex terminated.
102 The mutex is in unlocked state.
103 .It Dv UMUTEX_RB_NOTRECOV
104 The robust mutex is in a non-recoverable state.
105 It cannot be locked until reinitialized.
110 field may contain the following umutex-specific flags, in addition to
112 .Bl -tag -width indent
113 .It Dv UMUTEX_PRIO_INHERIT
115 .Em Priority Inheritance
117 .It Dv UMUTEX_PRIO_PROTECT
119 .Em Priority Protection
122 Mutex is robust, as described in the
125 .It Dv UMUTEX_NONCONSISTENT
126 Robust mutex is in a transient non-consistent state.
130 In the manual page, mutexes not having
131 .Dv UMUTEX_PRIO_INHERIT
133 .Dv UMUTEX_PRIO_PROTECT
134 flags set, are called normal mutexes.
136 .Pq normal, priority-inherited, and priority-protected
137 has a separate sleep queue associated
140 For priority protected mutexes, the
142 array contains priority ceiling values.
145 is the ceiling value for the mutex, as specified by
148 .Em Priority Protected
152 is used only for the unlock of a priority protected mutex, when
153 unlock is done in an order other than the reversed lock order.
156 must contain the ceiling value for the last locked priority protected
157 mutex, for proper priority reassignment.
158 If, instead, the unlocking mutex was the last priority propagated
159 mutex locked by the thread,
162 This is required because kernel does not maintain the ordered lock list.
163 .It Sy Condition variable
166 volatile uint32_t c_has_waiters;
174 value indicates that there are in-kernel waiters for the condition,
181 field contains flags.
182 Only the common flags
183 .Pq Dv USYNC_PROCESS_SHARED
184 are defined for ucond.
188 member provides the clock identifier to use for timeout, when the
192 flag and the timeout specified.
193 Valid clock identifiers are a subset of those for
194 .Xr clock_gettime 2 :
199 .Dv CLOCK_MONOTONIC_FAST
201 .Dv CLOCK_MONOTONIC_PRECISE
207 .Dv CLOCK_REALTIME_FAST
209 .Dv CLOCK_REALTIME_PRECISE
215 .Dv CLOCK_UPTIME_FAST
217 .Dv CLOCK_UPTIME_PRECISE
221 .It Sy Reader/writer lock
224 volatile int32_t rw_state;
226 uint32_t rw_blocked_readers;
227 uint32_t rw_blocked_writers;
233 field is the actual lock.
234 It contains both the flags and counter of the read locks which were
239 .Bl -tag -width indent
240 .It Dv URWLOCK_WRITE_OWNER
241 Write lock was granted.
242 .It Dv URWLOCK_WRITE_WAITERS
243 There are write lock waiters.
244 .It Dv URWLOCK_READ_WAITERS
245 There are read lock waiters.
246 .It Dv URWLOCK_READER_COUNT(c)
247 Returns the count of currently granted read locks.
250 At any given time there may be only one thread to which the writer lock
253 and no threads are granted read lock.
254 Or, at the given time, up to
255 .Dv URWLOCK_MAX_READERS
256 threads may be granted the read lock simultaneously, but write lock is
257 not granted to any thread.
259 The following flags for the
263 are defined, in addition to the common flags:
264 .Bl -tag -width indent
265 .It Dv URWLOCK_PREFER_READER
266 If specified, immediately grant read lock requests when
268 is already read-locked, even in presence of unsatisfied write
270 By default, if there is a write lock waiter, further read requests are
271 not granted, to prevent unfair write lock waiter starvation.
275 .Dv rw_blocked_readers
277 .Dv rw_blocked_writers
278 members contain the count of threads which are sleeping in kernel,
279 waiting for the associated request type to be granted.
280 The fields are used by kernel to update the
281 .Dv URWLOCK_READ_WAITERS
283 .Dv URWLOCK_WRITE_WAITERS
286 lock after requesting thread was woken up.
290 volatile uint32_t _count;
297 word represents a counting semaphore.
298 A non-zero value indicates an unlocked (posted) semaphore, while zero
299 represents the locked state.
300 The maximal supported semaphore count is
305 word, besides the counter of posts (unlocks), also contains the
307 bit, which indicates that locked semaphore has waiting threads.
311 macro, applied to the
313 word, returns the current semaphore counter, which is the number of posts
314 issued on the semaphore.
316 The following bits for the
320 are defined, in addition to the common flags:
321 .Bl -tag -width indent
323 Flag is ignored by kernel.
325 .It Sy Timeout parameter
328 struct timespec _timeout;
336 operations allow the blocking time to be limited, failing the request
337 if it cannot be satisfied in the specified time period.
338 The timeout is specified by passing either the address of
339 .Vt struct timespec ,
340 or its extended variant,
341 .Vt struct _umtx_time ,
346 They are distinguished by the
348 value, which must be equal to the size of the structure pointed to by
355 member specifies the time when the timeout should occur.
356 Legal values for clock identifier
363 and use the same underlying clocks.
364 The specified clock is used to obtain the current time value.
365 Interval counting is always performed by the monotonic wall clock.
369 argument allows the following flags to further define the timeout behaviour:
370 .Bl -tag -width indent
374 value is the absolute time.
375 The thread will be unblocked and the request failed when specified
376 clock value is equal or exceeds the
379 If the flag is absent, the timeout value is relative, that is the amount
380 of time, measured by the monotonic wall clock from the moment of the request
385 When a locking request cannot be immediately satisfied, the thread is
388 which is a non-runnable state terminated by the
391 Lock operations include a
393 variant which returns an error rather than sleeping if the lock cannot
397 provides requests which explicitly put the thread to sleep.
399 Wakes need to know which threads to make runnable, so sleeping threads
400 are grouped into containers called
402 A sleep queue is identified by a key, which for
404 is defined as the physical address of some variable.
407 address is used, which means that same variable mapped multiple
408 times will give one key value.
409 This mechanism enables the construction of
413 A related attribute of the key is shareability.
414 Some requests always interpret keys as private for the current process,
415 creating sleep queues with the scope of the current process even if
416 the memory is shared.
417 Others either select the shareability automatically from the
418 mapping attributes, or take additional input as the
419 .Dv USYNC_PROCESS_SHARED
421 This is done as optimization, allowing the lock scope to be limited
422 regardless of the kind of backing memory.
424 Only the address of the start byte of the variable specified as key is
425 important for determining corresponding sleep queue.
426 The size of the variable does not matter, so, for example, sleep on the same
427 address interpeted as
431 on a little-endian 64-bit platform would collide.
433 The last attribute of the key is the object type.
434 The sleep queue to which a sleeping thread is assigned is an individual
435 one for simple wait requests, mutexes, rwlocks, condvars and other
436 primitives, even when the physical address of the key is same.
438 When waking up a limited number of threads from a given sleep queue,
439 the highest priority threads that have been blocked for the longest on
440 the queue are selected.
444 are provided as a substrate for a userspace library to implement
447 A robust umutex must have the
451 On thread termination, the kernel walks two lists of mutexes.
452 The two lists head addresses must be provided by a prior call to
453 .Dv UMTX_OP_ROBUST_LISTS
455 The lists are singly-linked.
456 The link to next element is provided by the
461 Robust list processing is aborted if the kernel finds a mutex
462 with any of the following conditions:
463 .Bl -dash -offset indent -compact
469 not owned by the current thread, except when the mutex is pointed to
473 .Vt struct umtx_robust_lists_params ,
474 registered for the current thread
476 the combination of mutex flags is invalid
478 read of the umutex memory faults
480 the list length limit described in
485 Every mutex in both lists is unlocked as if the
486 .Dv UMTX_OP_MUTEX_UNLOCK
487 request is performed on it, but instead of the
491 field is written with the
492 .Dv UMUTEX_RB_OWNERDEAD
495 .Dv UMUTEX_RB_OWNERDEAD
496 state is locked by kernel due to the
497 .Dv UMTX_OP_MUTEX_TRYLOCK
499 .Dv UMTX_OP_MUTEX_LOCK
500 requests, the lock is granted and
504 Also, the kernel handles the
505 .Dv UMUTEX_RB_NOTRECOV
508 field specially, always returning the
510 error for lock attempts, without granting the lock.
512 The following operations, requested by the
514 argument to the function, are implemented:
515 .Bl -tag -width indent
518 The arguments for the request are:
519 .Bl -tag -width "obj"
521 Pointer to a variable of type
528 The current value of the variable pointed to by the
530 argument is compared with the
532 If they are equal, the requesting thread is put to interruptible sleep
533 until woken up or the optionally specified timeout expires.
535 The comparison and sleep are atomic.
536 In other words, if another thread writes a new value to
540 the request is guaranteed to not miss the wakeup,
541 which might otherwise happen between comparison and blocking.
543 The physical address of memory where the
545 variable is located, is used as a key to index sleeping threads.
547 The read of the current value of the
549 variable is not guarded by barriers.
550 In particular, it is the user's duty to ensure the lock acquire
551 and release memory semantics, if the
555 requests are used as a substrate for implementing a simple lock.
557 The request is not restartable.
558 An unblocked signal delivered during the wait always results in sleep
563 Optionally, a timeout for the request may be specified.
565 Wake the threads possibly sleeping due to
567 The arguments for the request are:
568 .Bl -tag -width "obj"
570 Pointer to a variable, used as a key to find sleeping threads.
574 threads are woken up by this request.
577 to wake up all waiters.
579 .It Dv UMTX_OP_MUTEX_TRYLOCK
581 The arguments to the request are:
582 .Bl -tag -width "obj"
584 Pointer to the umutex.
588 .Dv UMTX_OP_MUTEX_LOCK
591 instead of sleeping if the lock cannot be obtained immediately.
592 .It Dv UMTX_OP_MUTEX_LOCK
594 The arguments to the request are:
595 .Bl -tag -width "obj"
597 Pointer to the umutex.
600 Locking is performed by writing the current thread id into the
604 The write is atomic, preserves the
606 contention indicator, and provides the acquire barrier for
607 lock entrance semantic.
609 If the lock cannot be obtained immediately because another thread owns
610 the lock, the current thread is put to sleep, with
613 Upon wake up, the lock conditions are re-tested.
615 The request adheres to the priority protection or inheritance protocol
616 of the mutex, specified by the
617 .Dv UMUTEX_PRIO_PROTECT
619 .Dv UMUTEX_PRIO_INHERIT
622 Optionally, a timeout for the request may be specified.
624 A request with a timeout specified is not restartable.
625 An unblocked signal delivered during the wait always results in sleep
629 A request without timeout specified is always restarted after return
630 from a signal handler.
631 .It Dv UMTX_OP_MUTEX_UNLOCK
633 The arguments to the request are:
634 .Bl -tag -width "obj"
636 Pointer to the umutex.
639 Unlocks the mutex, by writing
645 The write is done with a release barrier, to provide lock leave semantic.
647 If there are threads sleeping in the sleep queue associated with the
648 umutex, one thread is woken up.
649 If more than one thread sleeps in the sleep queue, the
651 bit is set together with the write of the
656 The request adheres to the priority protection or inheritance protocol
657 of the mutex, specified by the
658 .Dv UMUTEX_PRIO_PROTECT
660 .Dv UMUTEX_PRIO_INHERIT
662 See description of the
666 structure for additional details of the request operation on the
667 priority protected protocol mutex.
668 .It Dv UMTX_OP_SET_CEILING
669 Set ceiling for the priority protected umutex.
670 The arguments to the request are:
671 .Bl -tag -width "uaddr"
673 Pointer to the umutex.
677 Address of a variable of type
681 and the update was successful, the previous ceiling value is
682 written to the location pointed to by
686 The request locks the umutex pointed to by the
688 parameter, waiting for the lock if not immediately available.
689 After the lock is obtained, the new ceiling value
695 after which the umutex is unlocked.
697 The locking does not adhere to the priority protect protocol,
701 .Xr pthread_mutex_setprioceiling 3
703 .It Dv UMTX_OP_CV_WAIT
704 Wait for a condition.
705 The arguments to the request are:
706 .Bl -tag -width "uaddr2"
711 Request flags, see below.
713 Pointer to the umutex.
715 Optional pointer to a
717 for timeout specification.
720 The request must be issued by the thread owning the mutex pointed to
730 argument, is set to an arbitrary non-zero value, after which the
732 mutex is unlocked (following the appropriate protocol), and
733 the current thread is put to sleep on the sleep queue keyed by
737 The operations are performed atomically.
738 It is guaranteed to not miss a wakeup from
739 .Dv UMTX_OP_CV_SIGNAL
741 .Dv UMTX_OP_CV_BROADCAST
742 sent between mutex unlock and putting the current thread on the sleep queue.
744 Upon wakeup, if the timeout expired and no other threads are sleeping in
745 the same sleep queue, the
750 umutex is not relocked.
752 The following flags are defined:
753 .Bl -tag -width "CVWAIT_CLOCKID"
754 .It Dv CVWAIT_ABSTIME
756 .It Dv CVWAIT_CLOCKID
760 Optionally, a timeout for the request may be specified.
761 Unlike other requests, the timeout value is specified directly by a
762 .Vt struct timespec ,
768 flag is provided, the timeout uses the clock from the
777 is used, regardless of the clock identifier possibly specified in the
778 .Vt struct _umtx_time .
781 flag is supplied, the timeout specifies absolute time value, otherwise
782 it denotes a relative time interval.
784 The request is not restartable.
785 An unblocked signal delivered during
786 the wait always results in sleep interruption and
789 .It Dv UMTX_OP_CV_SIGNAL
790 Wake up one condition waiter.
791 The arguments to the request are:
792 .Bl -tag -width "obj"
798 The request wakes up at most one thread sleeping on the sleep queue keyed
802 If the woken up thread was the last on the sleep queue, the
807 .It Dv UMTX_OP_CV_BROADCAST
808 Wake up all condition waiters.
809 The arguments to the request are:
810 .Bl -tag -width "obj"
816 The request wakes up all threads sleeping on the sleep queue keyed by the
824 .It Dv UMTX_OP_WAIT_UINT
827 but the type of the variable pointed to by
831 .Pq a 32-bit integer .
832 .It Dv UMTX_OP_RW_RDLOCK
836 The arguments to the request are:
837 .Bl -tag -width "obj"
839 Pointer to the lock (of type
843 Additional flags to augment locking behaviour.
844 The valid flags in the
847 .Bl -tag -width indent
848 .It Dv URWLOCK_PREFER_READER
852 The request obtains the read lock on the specified
854 by incrementing the count of readers in the
856 word of the structure.
858 .Dv URWLOCK_WRITE_OWNER
859 bit is set in the word
861 the lock was granted to a writer which has not yet relinquished
863 In this case the current thread is put to sleep until it makes sense to
867 .Dv URWLOCK_PREFER_READER
868 flag is set either in the
870 word of the structure, or in the
872 argument of the request, the presence of the threads trying to obtain
873 the write lock on the same structure does not prevent the current thread
874 from trying to obtain the read lock.
875 Otherwise, if the flag is not set, and the
876 .Dv URWLOCK_WRITE_WAITERS
879 the current thread does not attempt to obtain read-lock.
881 .Dv URWLOCK_READ_WAITERS
884 word and puts itself to sleep on corresponding sleep queue.
885 Upon wakeup, the locking conditions are re-evaluated.
887 Optionally, a timeout for the request may be specified.
889 The request is not restartable.
890 An unblocked signal delivered during the wait always results in sleep
894 .It Dv UMTX_OP_RW_WRLOCK
898 The arguments to the request are:
899 .Bl -tag -width "obj"
901 Pointer to the lock (of type
906 The request obtains a write lock on the specified
909 .Dv URWLOCK_WRITE_OWNER
912 word of the structure.
913 If there is already a write lock owner, as indicated by the
914 .Dv URWLOCK_WRITE_OWNER
915 bit being set, or there are read lock owners, as indicated
916 by the read-lock counter, the current thread does not attempt to
917 obtain the write-lock.
919 .Dv URWLOCK_WRITE_WAITERS
922 word and puts itself to sleep on corresponding sleep queue.
923 Upon wakeup, the locking conditions are re-evaluated.
925 Optionally, a timeout for the request may be specified.
927 The request is not restartable.
928 An unblocked signal delivered during the wait always results in sleep
932 .It Dv UMTX_OP_RW_UNLOCK
934 The arguments to the request are:
935 .Bl -tag -width "obj"
937 Pointer to the lock (of type
942 The unlock type (read or write) is determined by the
946 does not save information about the identity of the thread which
949 If there are pending writers after the unlock, and the
950 .Dv URWLOCK_PREFER_READER
951 flag is not set in the
955 structure, one writer is woken up, selected as described in the
959 .Dv URWLOCK_PREFER_READER
960 flag is set, a pending writer is woken up only if there is
963 If there are no pending writers, or, in the case that the
964 .Dv URWLOCK_PREFER_READER
965 flag is set, then all pending readers are woken up by unlock.
966 .It Dv UMTX_OP_WAIT_UINT_PRIVATE
968 .Dv UMTX_OP_WAIT_UINT ,
969 but unconditionally select the process-private sleep queue.
970 .It Dv UMTX_OP_WAKE_PRIVATE
973 but unconditionally select the process-private sleep queue.
974 .It Dv UMTX_OP_MUTEX_WAIT
975 Wait for mutex availability.
976 The arguments to the request are:
977 .Bl -tag -width "obj"
979 Address of the mutex.
983 .Dv UMTX_OP_MUTEX_LOCK ,
984 put the requesting thread to sleep if the mutex lock cannot be obtained
990 word of the mutex to indicate that there is a waiter, before the thread
991 is added to the sleep queue.
993 .Dv UMTX_OP_MUTEX_LOCK
994 request, the lock is not obtained.
996 The operation is not implemented for priority protected and
997 priority inherited protocol mutexes.
999 Optionally, a timeout for the request may be specified.
1001 A request with a timeout specified is not restartable.
1002 An unblocked signal delivered during the wait always results in sleep
1006 A request without a timeout automatically restarts if the signal disposition
1007 requested restart via the
1010 .Vt struct sigaction
1013 .It Dv UMTX_OP_NWAKE_PRIVATE
1014 Wake up a batch of sleeping threads.
1015 The arguments to the request are:
1016 .Bl -tag -width "obj"
1018 Pointer to the array of pointers.
1020 Number of elements in the array pointed to by
1024 For each element in the array pointed to by
1026 wakes up all threads waiting on the
1028 sleep queue with the key
1029 being the byte addressed by the array element.
1030 .It Dv UMTX_OP_MUTEX_WAKE
1031 Check if a normal umutex is unlocked and wake up a waiter.
1032 The arguments for the request are:
1033 .Bl -tag -width "obj"
1035 Pointer to the umutex.
1040 word of the mutex pointed to by the
1042 argument indicates unowned mutex, which has its contention indicator bit
1043 .Dv UMUTEX_CONTESTED
1044 set, clear the bit and wake up one waiter in the sleep queue associated
1045 with the byte addressed by the
1048 Only normal mutexes are supported by the request.
1049 The sleep queue is always one for a normal mutex type.
1051 This request is deprecated in favor of
1052 .Dv UMTX_OP_MUTEX_WAKE2
1053 since mutexes using it cannot synchronize their own destruction.
1056 word has already been set to
1058 when this request is made,
1059 so that another thread can lock, unlock and destroy the mutex
1060 (if no other thread uses the mutex afterwards).
1062 .Dv UMUTEX_CONTESTED
1063 bit may then modify freed memory.
1064 .It Dv UMTX_OP_MUTEX_WAKE2
1065 Check if a umutex is unlocked and wake up a waiter.
1066 The arguments for the request are:
1067 .Bl -tag -width "obj"
1069 Pointer to the umutex.
1074 The request does not read the
1080 argument supplies flag information, in particular, to determine the
1081 sleep queue where the waiters are found for wake up.
1083 If the mutex is unowned, one waiter is woken up.
1085 If the mutex memory cannot be accessed, all waiters are woken up.
1087 If there is more than one waiter on the sleep queue, or there is only
1088 one waiter but the mutex is owned by a thread, the
1089 .Dv UMUTEX_CONTESTED
1094 .It Dv UMTX_OP_SEM2_WAIT
1095 Wait until semaphore is available.
1096 The arguments to the request are:
1097 .Bl -tag -width "obj"
1099 Pointer to the semaphore (of type
1100 .Vt struct _usem2 ) .
1102 Size of the memory passed in via the
1106 Optional pointer to a structure of type
1107 .Vt struct _umtx_time ,
1108 which may be followed by a structure of type
1109 .Vt struct timespec .
1112 Put the requesting thread onto a sleep queue if the semaphore counter
1114 If the thread is put to sleep, the
1115 .Dv USEM_HAS_WAITERS
1118 word to indicate waiters.
1119 The function returns either due to
1121 indicating the semaphore is available (non-zero count due to post),
1123 The return does not guarantee that the semaphore is available,
1124 nor does it consume the semaphore lock on successful return.
1126 Optionally, a timeout for the request may be specified.
1128 A request with non-absolute timeout value is not restartable.
1129 An unblocked signal delivered during such wait results in sleep
1136 was not set, and the operation was interrupted and the caller passed in a
1138 large enough to hold a
1140 following the initial
1141 .Vt struct _umtx_time ,
1144 is updated to contain the unslept amount.
1145 .It Dv UMTX_OP_SEM2_WAKE
1146 Wake up waiters on semaphore lock.
1147 The arguments to the request are:
1148 .Bl -tag -width "obj"
1150 Pointer to the semaphore (of type
1151 .Vt struct _usem2 ) .
1154 The request wakes up one waiter for the semaphore lock.
1155 The function does not increment the semaphore lock count.
1157 .Dv USEM_HAS_WAITERS
1160 word, and the last sleeping thread was woken up, the bit is cleared.
1164 shared memory objects (see
1166 which can be attached to a byte of physical memory, mapped into the
1167 process address space.
1168 The objects are used to implement process-shared locks in
1173 argument specifies the sub-request of the
1176 .Bl -tag -width indent
1177 .It Dv UMTX_SHM_CREAT
1178 Creates the anonymous shared memory object, which can be looked up
1179 with the specified key
1181 If the object associated with the
1183 key already exists, it is returned instead of creating a new object.
1184 The object's size is one page.
1185 On success, the file descriptor referencing the object is returned.
1186 The descriptor can be used for mapping the object using
1188 or for other shared memory operations.
1189 .It Dv UMTX_SHM_LOOKUP
1192 request, but if there is no shared memory object associated with
1195 an error is returned, and no new object is created.
1196 .It Dv UMTX_SHM_DESTROY
1197 De-associate the shared object with the specified key
1199 The object is destroyed after the last open file descriptor is closed
1200 and the last mapping for it is destroyed.
1201 .It Dv UMTX_SHM_ALIVE
1202 Checks whether there is a live shared object associated with the
1205 Returns zero if there is, and an error otherwise.
1206 This request is an optimization of the
1209 It is cheaper when only the liveness of the associated object is asked
1210 for, since no file descriptor is installed in the process fd table
1216 argument specifies the virtual address, which backing physical memory
1217 byte identity is used as a key for the anonymous shared object
1219 .It Dv UMTX_OP_ROBUST_LISTS
1220 Register the list heads for the current thread's robust mutex lists.
1221 The arguments to the request are:
1222 .Bl -tag -width "uaddr"
1224 Size of the structure passed in the
1228 Pointer to the structure of type
1229 .Vt struct umtx_robust_lists_params .
1232 The structure is defined as
1234 struct umtx_robust_lists_params {
1235 uintptr_t robust_list_offset;
1236 uintptr_t robust_priv_list_offset;
1237 uintptr_t robust_inact_offset;
1242 .Dv robust_list_offset
1243 member contains address of the first element in the list of locked
1244 robust shared mutexes.
1246 .Dv robust_priv_list_offset
1247 member contains address of the first element in the list of locked
1248 robust private mutexes.
1249 The private and shared robust locked lists are split to allow fast
1250 termination of the shared list on fork, in the child.
1253 .Dv robust_inact_offset
1254 contains a pointer to the mutex which might be locked in nearby future,
1255 or might have been just unlocked.
1256 It is typically set by the lock or unlock mutex implementation code
1257 around the whole operation, since lists can be only changed race-free
1258 when the thread owns the mutex.
1259 The kernel inspects the
1260 .Dv robust_inact_offset
1261 in addition to walking the shared and private lists.
1262 Also, the mutex pointed to by
1263 .Dv robust_inact_offset
1264 is handled more loosely at the thread termination time,
1265 than other mutexes on the list.
1266 That mutex is allowed to be not owned by the current thread,
1267 in which case list processing is continued.
1270 subsection for details.
1271 .It Dv UMTX_OP_GET_MIN_TIMEOUT
1272 Writes out the current value of minimal umtx operations timeout,
1273 in nanoseconds, into the long integer variable pointed to by
1275 .It Dv UMTX_OP_SET_MIN_TIMEOUT
1276 Set the minimal amount of time, in nanoseconds, the thread is required
1277 to sleep for umtx operations specifying a timeout using absolute clocks.
1278 The value is taken from the
1280 argument of the call.
1281 Zero means no minimum.
1286 argument may be a bitwise OR of a single command from above with one or more of
1287 the following flags:
1288 .Bl -tag -width indent
1289 .It Dv UMTX_OP__I386
1290 Request i386 ABI compatibility from the native
1293 Specifically, this implies that:
1294 .Bl -hang -offset indent
1297 arguments that point to a word, point to a 32-bit integer.
1300 .Dv UMTX_OP_NWAKE_PRIVATE
1302 argument is a pointer to an array of 32-bit pointers.
1308 is a 32-bit pointer.
1311 uses a 32-bit time_t.
1315 has no effect if this flag is set.
1316 This flag is valid for all architectures, but it is ignored on i386.
1317 .It Dv UMTX_OP__32BIT
1318 Request non-i386, 32-bit ABI compatibility from the native
1321 Specifically, this implies that:
1322 .Bl -hang -offset indent
1325 arguments that point to a word, point to a 32-bit integer.
1328 .Dv UMTX_OP_NWAKE_PRIVATE
1330 argument is a pointer to an array of 32-bit pointers.
1336 is a 32-bit pointer.
1339 uses a 64-bit time_t.
1342 This flag has no effect if
1345 This flag is valid for all architectures.
1348 Note that if any 32-bit ABI compatibility is being requested, then care must be
1349 taken with robust lists.
1350 A single thread may not mix 32-bit compatible robust lists with native
1353 .Dv UMTX_OP_ROBUST_LISTS
1354 call in a given thread determines which ABI that thread will use for robust
1355 lists going forward.
1358 all requests, except
1364 request, will return zero.
1369 return a shared memory file descriptor on success.
1370 On error \-1 is returned, and the
1372 variable is set to indicate the error.
1376 operations can fail with the following errors:
1377 .Bl -tag -width "[ETIMEDOUT]"
1379 One of the arguments point to invalid memory.
1381 The clock identifier, specified for the
1382 .Vt struct _umtx_time
1383 timeout parameter, or in the
1389 The type of the mutex, encoded by the
1399 has changed the lock owner thread identifier during unlock.
1406 .Vt struct _umtx_time
1407 is less than zero, or
1409 is greater than 1000000000.
1413 argument specifies invalid operation.
1419 request specifies invalid operation.
1422 .Dv UMTX_OP_SET_CEILING
1423 request specifies non priority protected mutex.
1425 The new ceiling value for the
1426 .Dv UMTX_OP_SET_CEILING
1427 request, or one or more of the values read from the
1429 array during lock or unlock operations, is greater than
1432 Unlock attempted on an object not owned by the current thread.
1433 .It Bq Er EOWNERDEAD
1434 The lock was requested on an umutex where the
1436 field was set to the
1437 .Dv UMUTEX_RB_OWNERDEAD
1438 value, indicating terminated robust mutex.
1439 The lock was granted to the caller, so this error in fact
1440 indicates success with additional conditions.
1441 .It Bq Er ENOTRECOVERABLE
1442 The lock was requested on an umutex which
1444 field is equal to the
1445 .Dv UMUTEX_RB_NOTRECOV
1446 value, indicating abandoned robust mutex after termination.
1447 The lock was not granted to the caller.
1449 The shared memory object, associated with the address passed to the
1453 request, was destroyed.
1456 .Dv UMTX_SHM_LOOKUP ,
1457 .Dv UMTX_SHM_DESTROY ,
1462 request, there is no shared memory object associated with the provided key.
1468 request cannot be satisfied, because allocation of the shared memory object
1474 The maximum number of readers
1475 .Dv ( URWLOCK_MAX_READERS )
1476 were already granted ownership of the given
1480 A try mutex lock operation was not able to obtain the lock.
1482 The request specified a timeout in the
1486 arguments, and timed out before obtaining the lock or being woken up.
1488 A signal was delivered during wait, for a non-restartable operation.
1489 Operations with timeouts are typically non-restartable, but timeouts
1490 specified in absolute time may be restartable.
1492 A signal was delivered during wait, for a restartable operation.
1493 Mutex lock requests without timeout specified are restartable.
1494 The error is not returned to userspace code since restart
1495 is handled by usual adjustment of the instruction counter.
1498 .Xr clock_gettime 2 ,
1508 .Xr thr_set_name 2 ,
1513 system call is non-standard and is used by the
1520 A window between a unlocking robust mutex and resetting the pointer in the
1521 .Dv robust_inact_offset
1522 member of the registered
1523 .Vt struct umtx_robust_lists_params
1524 allows another thread to destroy the mutex, thus making the kernel inspect
1525 freed or reused memory.
1528 implementation is only vulnerable to this race when operating on
1530 A possible fix for the current implementation is to strengthen the checks
1531 for shared mutexes before terminating them, in particular, verifying
1532 that the mutex memory is mapped from a shared memory object allocated
1536 This is not done because it is believed that the race is adequately
1537 covered by other consistency checks, while adding the check would
1538 prevent alternative implementations of