d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fix formatting of _umtx_op(2)

Browse Source 
Do not use macros in the -width of a .Bl, since mandoc does not support them.

Fix issues reported by igor and mandoc -Tlint.

Use a .Bl for list of clock IDs instead of a comma list.

MFC after:	3 days
Sponsored by:	Dell EMC
This commit is contained in:
Eric van Gyzen 2017-11-13 17:46:38 +00:00
parent 50a717a67b
commit 9121aedd2f
1 changed files with 70 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
lib/libc/sys/_umtx_op.2
View File

@ -28,7 +28,7 @@
.\"
.\" $FreeBSD$
.\"
.Dd May 23, 2017
.Dd November 13, 2017
.Dt _UMTX_OP 2
.Os
.Sh NAME
@ -61,7 +61,7 @@ All objects require ABI-mandated alignment, but this is not currently
enforced consistently on all architectures.
.Pp
The following flags are defined for flag fields of all structures:
.Bl -tag -width "Dv USYNC_PROCESS_SHARED"
.Bl -tag -width indent
.It Dv USYNC_PROCESS_SHARED
Allow selection of the process-shared sleep queue for the thread sleep
container, when the lock ownership cannot be granted immediately,
@ -77,7 +77,6 @@ See the
.Sx SLEEP QUEUES
subsection below for more details on sleep queues.
.El
.Pp
.Bl -hang -offset indent
.It Sy Mutex
.Bd -literal
@ -96,7 +95,7 @@ It contains either the thread identifier of the lock owner in the
locked state, or zero when the lock is unowned.
The highest bit set indicates that there is contention on the lock.
The constants are defined for special values:
.Bl -tag -width "Dv UMUTEX_RB_OWNERDEAD"
.Bl -tag -width indent
.It Dv UMUTEX_UNOWNED
Zero, the value stored in the unowned lock.
.It Dv UMUTEX_CONTESTED
@ -113,7 +112,7 @@ The
.Dv m_flags
field may contain the following umutex-specific flags, in addition to
the common flags:
.Bl -tag -width "Dv UMUTEX_NONCONSISTENT"
.Bl -tag -width indent
.It Dv UMUTEX_PRIO_INHERIT
Mutex implements
.Em Priority Inheritance
@ -136,8 +135,9 @@ In the manual page, mutexes not having
and
.Dv UMUTEX_PRIO_PROTECT
flags set, are called normal mutexes.
Each type of mutex, i.e. normal mutexes, priority-inherited mutexes,
and priority-protected mutexes, have a separate sleep queue associated
Each type of mutex
.Pq normal, priority-inherited, and priority-protected
has a separate sleep queue associated
with the given key.
.Pp
For priority protected mutexes, the
@ -182,8 +182,8 @@ request.
The
.Dv c_flags
field contains flags.
Only the common flags, i.e.
.Dv USYNC_PROCESS_SHARED ,
Only the common flags
.Pq Dv USYNC_PROCESS_SHARED
are defined for ucond.
.Pp
The
@ -193,23 +193,34 @@ member provides the clock identifier to use for timeout, when the
request has both the
.Dv CVWAIT_CLOCKID
flag and the timeout specified.
Valid clock identifiers are subset of the valid clock ids for the
.Xr clock_gettime 2
syscall, namely,
.Dv CLOCK_REALTIME ,
.Dv CLOCK_VIRTUAL ,
.Dv CLOCK_PROF ,
.Dv CLOCK_MONOTONIC ,
.Dv CLOCK_UPTIME ,
.Dv CLOCK_UPTIME_PRECISE ,
.Dv CLOCK_UPTIME_FAST ,
.Dv CLOCK_REALTIME_PRECISE ,
.Dv CLOCK_REALTIME_FAST ,
.Dv CLOCK_MONOTONIC_PRECISE ,
.Dv CLOCK_MONOTONIC_FAST ,
and
Valid clock identifiers are a subset of those for
.Xr clock_gettime 2 :
.Bl -bullet -compact
.It
.Dv CLOCK_MONOTONIC
.It
.Dv CLOCK_MONOTONIC_FAST
.It
.Dv CLOCK_MONOTONIC_PRECISE
.It
.Dv CLOCK_PROF
.It
.Dv CLOCK_REALTIME
.It
.Dv CLOCK_REALTIME_FAST
.It
.Dv CLOCK_REALTIME_PRECISE
.It
.Dv CLOCK_SECOND
are allowed.
.It
.Dv CLOCK_UPTIME
.It
.Dv CLOCK_UPTIME_FAST
.It
.Dv CLOCK_UPTIME_PRECISE
.It
.Dv CLOCK_VIRTUAL
.El
.It Sy Reader/writer lock
.Bd -literal
struct urwlock {
@ -228,7 +239,7 @@ granted.
Names of the
.Dv rw_state
bits are following:
.Bl -tag -width "Dv URWLOCK_WRITE_WAITERS"
.Bl -tag -width indent
.It Dv URWLOCK_WRITE_OWNER
Write lock was granted.
.It Dv URWLOCK_WRITE_WAITERS
@ -253,7 +264,7 @@ The following flags for the
member of
.Vt struct urwlock
are defined, in addition to the common flags:
.Bl -tag -width "Dv URWLOCK_PREFER_READER"
.Bl -tag -width indent
.It Dv URWLOCK_PREFER_READER
If specified, immediately grant read lock requests when
.Dv urwlock
@ -302,7 +313,7 @@ The
.Dv USEM_COUNT()
macro, applied to the
.Dv _count
word, returns the current semaphore counter, i.e. the number of posts
word, returns the current semaphore counter, which is the number of posts
issued on the semaphore.
.Pp
The following bits for the
@ -310,7 +321,7 @@ The following bits for the
member of
.Vt struct _usem2
are defined, in addition to the common flags:
.Bl -tag -width "Dv USEM_NAMED"
.Bl -tag -width indent
.It Dv USEM_NAMED
Flag is ignored by kernel.
.El
@ -359,7 +370,7 @@ Interval counting is always performed by the monotonic wall clock.
The
.Dv _flags
argument allows the following flags to further define the timeout behaviour:
.Bl -tag -width "It Dv UMTX_ABSTIME"
.Bl -tag -width indent
.It Dv UMTX_ABSTIME
The
.Dv _timeout
@ -374,7 +385,6 @@ start.
.El
.El
.Ss SLEEP QUEUES
.Pp
When a locking request cannot be immediately satisfied, the thread is
typically put to
.Em sleep ,
@ -416,7 +426,7 @@ regardless of the kind of backing memory.
.Pp
Only the address of the start byte of the variable specified as key is
important for determining corresponding sleep queue.
The size of the variable does not matter, so e.g. sleep on the same
The size of the variable does not matter, so, for example, sleep on the same
address interpeted as
.Vt uint32_t
and
@ -505,11 +515,11 @@ error for lock attempts, without granting the lock.
The following operations, requested by the
.Fa op
argument to the function, are implemented:
.Bl -tag -width "It Dv UMTX_OP_WAIT_UINT_PRIVATE"
.Bl -tag -width indent
.It Dv UMTX_OP_WAIT
Wait.
The arguments for the request are:
.Bl -tag -width "It Fa obj"
.Bl -tag -width "obj"
.It Fa obj
Pointer to a variable of type
.Vt long .
@ -558,7 +568,7 @@ Optionally, a timeout for the request may be specified.
Wake the threads possibly sleeping due to
.Dv UMTX_OP_WAIT .
The arguments for the request are:
.Bl -tag -width "It Fa obj"
.Bl -tag -width "obj"
.It Fa obj
Pointer to a variable, used as a key to find sleeping threads.
.It Fa val
@ -572,7 +582,7 @@ to wake up all waiters.
.It Dv UMTX_OP_MUTEX_TRYLOCK
Try to lock umutex.
The arguments to the request are:
.Bl -tag -width "It Fa obj"
.Bl -tag -width "obj"
.It Fa obj
Pointer to the umutex.
.El
@ -585,7 +595,7 @@ instead of sleeping if the lock cannot be obtained immediately.
.It Dv UMTX_OP_MUTEX_LOCK
Lock umutex.
The arguments to the request are:
.Bl -tag -width "It Fa obj"
.Bl -tag -width "obj"
.It Fa obj
Pointer to the umutex.
.El
@ -624,7 +634,7 @@ from a signal handler.
.It Dv UMTX_OP_MUTEX_UNLOCK
Unlock umutex.
The arguments to the request are:
.Bl -tag -width "It Fa obj"
.Bl -tag -width "obj"
.It Fa obj
Pointer to the umutex.
.El
@ -661,7 +671,7 @@ priority protected protocol mutex.
.It Dv UMTX_OP_SET_CEILING
Set ceiling for the priority protected umutex.
The arguments to the request are:
.Bl -tag -width "It Fa obj"
.Bl -tag -width "uaddr"
.It Fa obj
Pointer to the umutex.
.It Fa val
@ -696,7 +706,7 @@ interface.
.It Dv UMTX_OP_CV_WAIT
Wait for a condition.
The arguments to the request are:
.Bl -tag -width "It Fa uaddr2"
.Bl -tag -width "uaddr2"
.It Fa obj
Pointer to the
.Vt struct ucond .
@ -743,7 +753,7 @@ After wakeup, the
umutex is not relocked.
.Pp
The following flags are defined:
.Bl -tag -width "Dv CVWAIT_CLOCKID"
.Bl -tag -width "CVWAIT_CLOCKID"
.It Dv CVWAIT_ABSTIME
Timeout is absolute.
.It Dv CVWAIT_CLOCKID
@ -782,7 +792,7 @@ error.
.It Dv UMTX_OP_CV_SIGNAL
Wake up one condition waiter.
The arguments to the request are:
.Bl -tag -width "It Fa obj"
.Bl -tag -width "obj"
.It Fa obj
Pointer to
.Vt struct ucond .
@ -800,7 +810,7 @@ is cleared.
.It Dv UMTX_OP_CV_BROADCAST
Wake up all condition waiters.
The arguments to the request are:
.Bl -tag -width "It Fa obj"
.Bl -tag -width "obj"
.It Fa obj
Pointer to
.Vt struct ucond .
@ -820,14 +830,14 @@ Same as
but the type of the variable pointed to by
.Fa obj
is
.Vt u_int ,
i.e. 32-bit integer.
.Vt u_int
.Pq a 32-bit integer .
.It Dv UMTX_OP_RW_RDLOCK
Read-lock a
.Vt struct rwlock
lock.
The arguments to the request are:
.Bl -tag -width "It Fa obj"
.Bl -tag -width "obj"
.It Fa obj
Pointer to the lock (of type
.Vt struct rwlock )
@ -837,7 +847,7 @@ Additional flags to augment locking behaviour.
The valid flags in the
.Fa val
argument are:
.Bl -tag -width "It Dv URWLOCK_PREFER_READER"
.Bl -tag -width indent
.It Dv URWLOCK_PREFER_READER
.El
.El
@ -889,7 +899,7 @@ Write-lock a
.Vt struct rwlock
lock.
The arguments to the request are:
.Bl -tag -width "It Fa obj"
.Bl -tag -width "obj"
.It Fa obj
Pointer to the lock (of type
.Vt struct rwlock )
@ -925,7 +935,7 @@ error.
.It Dv UMTX_OP_RW_UNLOCK
Unlock rwlock.
The arguments to the request are:
.Bl -tag -width "It Fa obj"
.Bl -tag -width "obj"
.It Fa obj
Pointer to the lock (of type
.Vt struct rwlock )
@ -967,7 +977,7 @@ but unconditionally select the process-private sleep queue.
.It Dv UMTX_OP_MUTEX_WAIT
Wait for mutex availability.
The arguments to the request are:
.Bl -tag -width "It Fa obj"
.Bl -tag -width "obj"
.It Fa obj
Address of the mutex.
.El
@ -991,7 +1001,6 @@ priority inherited protocol mutexes.
.Pp
Optionally, a timeout for the request may be specified.
.Pp
.Pp
A request with a timeout specified is not restartable.
An unblocked signal delivered during the wait always results in sleep
interruption and
@ -1007,7 +1016,7 @@ member
.It Dv UMTX_OP_NWAKE_PRIVATE
Wake up a batch of sleeping threads.
The arguments to the request are:
.Bl -tag -width "It Fa obj"
.Bl -tag -width "obj"
.It Fa obj
Pointer to the array of pointers.
.It Fa val
@ -1024,7 +1033,7 @@ being the byte addressed by the array element.
.It Dv UMTX_OP_MUTEX_WAKE
Check if a normal umutex is unlocked and wake up a waiter.
The arguments for the request are:
.Bl -tag -width "It Fa obj"
.Bl -tag -width "obj"
.It Fa obj
Pointer to the umutex.
.El
@ -1058,7 +1067,7 @@ bit may then modify freed memory.
.It Dv UMTX_OP_MUTEX_WAKE2
Check if a umutex is unlocked and wake up a waiter.
The arguments for the request are:
.Bl -tag -width "It Fa obj"
.Bl -tag -width "obj"
.It Fa obj
Pointer to the umutex.
.It Fa val
@ -1088,11 +1097,12 @@ word of the
.It Dv UMTX_OP_SEM2_WAIT
Wait until semaphore is available.
The arguments to the request are:
.Bl -tag -width "It Fa obj"
.Bl -tag -width "obj"
.It Fa obj
Pointer to the semaphore (of type
.Vt struct _usem2 ) .
.El
.Pp
Put the requesting thread onto a sleep queue if the semaphore counter
is zero.
If the thread is put to sleep, the
@ -1117,7 +1127,7 @@ error.
.It Dv UMTX_OP_SEM2_WAKE
Wake up waiters on semaphore lock.
The arguments to the request are:
.Bl -tag -width "It Fa obj"
.Bl -tag -width "obj"
.It Fa obj
Pointer to the semaphore (of type
.Vt struct _usem2 ) .
@ -1145,7 +1155,7 @@ The
argument specifies the sub-request of the
.Dv UMTX_OP_SHM
request:
.Bl -tag -width "Dv UMTX_SHM_DESTROY"
.Bl -tag -width indent
.It Dv UMTX_SHM_CREAT
Creates the anonymous shared memory object, which can be looked up
with the specified key
@ -1191,7 +1201,7 @@ creation or lookup.
.It Dv UMTX_OP_ROBUST_LISTS
Register the list heads for the current thread's robust mutex lists.
The arguments to the request are:
.Bl -tag -width "It Fa obj"
.Bl -tag -width "uaddr"
.It Fa val
Size of the structure passed in the
.Fa uaddr
@ -1261,8 +1271,8 @@ variable is set to indicate the error.
.Sh ERRORS
The
.Fn _umtx_op
operations will return the following errors:
.Bl -tag -width "Bq Er ENOTRECOVERABLE"
operations can fail with the following errors:
.Bl -tag -width "[ETIMEDOUT]"
.It Bq Er EFAULT
One of the arguments point to invalid memory.
.It Bq Er EINVAL