1.\" 2.\" Copyright (c) 1998 Berkeley Software Design, Inc. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Berkeley Software Design Inc's name may not be used to endorse or 13.\" promote products derived from this software without specific prior 14.\" written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY BERKELEY SOFTWARE DESIGN INC ``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 BERKELEY SOFTWARE DESIGN INC 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 26.\" SUCH DAMAGE. 27.\" 28.\" from BSDI $Id: mutex.4,v 1.1.2.3 1998/04/27 22:53:13 ewv Exp $ 29.\" $FreeBSD$ 30.\" 31.Dd November 16, 2011 32.Dt MUTEX 9 33.Os 34.Sh NAME 35.Nm mutex , 36.Nm mtx_init , 37.Nm mtx_destroy , 38.Nm mtx_lock , 39.Nm mtx_lock_spin , 40.Nm mtx_lock_flags , 41.Nm mtx_lock_spin_flags , 42.Nm mtx_trylock , 43.Nm mtx_trylock_flags , 44.Nm mtx_unlock , 45.Nm mtx_unlock_spin , 46.Nm mtx_unlock_flags , 47.Nm mtx_unlock_spin_flags , 48.Nm mtx_sleep , 49.Nm mtx_initialized , 50.Nm mtx_owned , 51.Nm mtx_recursed , 52.Nm mtx_assert , 53.Nm MTX_SYSINIT 54.Nd kernel synchronization primitives 55.Sh SYNOPSIS 56.In sys/param.h 57.In sys/lock.h 58.In sys/mutex.h 59.Ft void 60.Fn mtx_init "struct mtx *mutex" "const char *name" "const char *type" "int opts" 61.Ft void 62.Fn mtx_destroy "struct mtx *mutex" 63.Ft void 64.Fn mtx_lock "struct mtx *mutex" 65.Ft void 66.Fn mtx_lock_spin "struct mtx *mutex" 67.Ft void 68.Fn mtx_lock_flags "struct mtx *mutex" "int flags" 69.Ft void 70.Fn mtx_lock_spin_flags "struct mtx *mutex" "int flags" 71.Ft int 72.Fn mtx_trylock "struct mtx *mutex" 73.Ft int 74.Fn mtx_trylock_flags "struct mtx *mutex" "int flags" 75.Ft void 76.Fn mtx_unlock "struct mtx *mutex" 77.Ft void 78.Fn mtx_unlock_spin "struct mtx *mutex" 79.Ft void 80.Fn mtx_unlock_flags "struct mtx *mutex" "int flags" 81.Ft void 82.Fn mtx_unlock_spin_flags "struct mtx *mutex" "int flags" 83.Ft int 84.Fn mtx_sleep "void *chan" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo" 85.Ft int 86.Fn mtx_initialized "const struct mtx *mutex" 87.Ft int 88.Fn mtx_owned "const struct mtx *mutex" 89.Ft int 90.Fn mtx_recursed "const struct mtx *mutex" 91.Pp 92.Cd "options INVARIANTS" 93.Cd "options INVARIANT_SUPPORT" 94.Ft void 95.Fn mtx_assert "const struct mtx *mutex" "int what" 96.In sys/kernel.h 97.Fn MTX_SYSINIT "name" "struct mtx *mtx" "const char *description" "int opts" 98.Sh DESCRIPTION 99Mutexes are the most basic and primary method of thread synchronization. 100The major design considerations for mutexes are: 101.Bl -enum 102.It 103Acquiring and releasing uncontested mutexes should be as cheap 104as possible. 105.It 106They must have the information and storage space to support 107priority propagation. 108.It 109A thread must be able to recursively acquire a mutex, 110provided that the mutex is initialized to support recursion. 111.El 112.Pp 113There are currently two flavors of mutexes, those that context switch 114when they block and those that do not. 115.Pp 116By default, 117.Dv MTX_DEF 118mutexes will context switch when they are already held. 119As an optimization, 120they may spin for some amount 121of time before context switching. 122It is important to remember that since a thread may be preempted at any time, 123the possible context switch introduced by acquiring a mutex is guaranteed 124to not break anything that is not already broken. 125.Pp 126Mutexes which do not context switch are 127.Dv MTX_SPIN 128mutexes. 129These should only be used to protect data shared with primary interrupt 130code. 131This includes interrupt filters and low level scheduling code. 132In all architectures both acquiring and releasing of a 133uncontested spin mutex is more expensive than the same operation 134on a non-spin mutex. 135In order to protect an interrupt service routine from blocking 136against itself all interrupts are either blocked or deferred on a processor 137while holding a spin lock. 138It is permissible to hold multiple spin mutexes. 139.Pp 140Once a spin mutex has been acquired it is not permissible to acquire a 141blocking mutex. 142.Pp 143The storage needed to implement a mutex is provided by a 144.Vt struct mtx . 145In general this should be treated as an opaque object and 146referenced only with the mutex primitives. 147.Pp 148The 149.Fn mtx_init 150function must be used to initialize a mutex 151before it can be passed to any of the other mutex functions. 152The 153.Fa name 154option is used to identify the lock in debugging output etc. 155The 156.Fa type 157option is used by the witness code to classify a mutex when doing checks 158of lock ordering. 159If 160.Fa type 161is 162.Dv NULL , 163.Fa name 164is used in its place. 165The pointer passed in as 166.Fa name 167and 168.Fa type 169is saved rather than the data it points to. 170The data pointed to must remain stable 171until the mutex is destroyed. 172The 173.Fa opts 174argument is used to set the type of mutex. 175It may contain either 176.Dv MTX_DEF 177or 178.Dv MTX_SPIN 179but not both. 180See below for additional initialization options. 181It is not permissible to pass the same 182.Fa mutex 183to 184.Fn mtx_init 185multiple times without intervening calls to 186.Fn mtx_destroy . 187.Pp 188The 189.Fn mtx_lock 190function acquires a 191.Dv MTX_DEF 192mutual exclusion lock 193on behalf of the currently running kernel thread. 194If another kernel thread is holding the mutex, 195the caller will be disconnected from the CPU 196until the mutex is available 197(i.e., it will block). 198.Pp 199The 200.Fn mtx_lock_spin 201function acquires a 202.Dv MTX_SPIN 203mutual exclusion lock 204on behalf of the currently running kernel thread. 205If another kernel thread is holding the mutex, 206the caller will spin until the mutex becomes available. 207Interrupts are disabled during the spin and remain disabled 208following the acquiring of the lock. 209.Pp 210It is possible for the same thread to recursively acquire a mutex 211with no ill effects, provided that the 212.Dv MTX_RECURSE 213bit was passed to 214.Fn mtx_init 215during the initialization of the mutex. 216.Pp 217The 218.Fn mtx_lock_flags 219and 220.Fn mtx_lock_spin_flags 221functions acquire a 222.Dv MTX_DEF 223or 224.Dv MTX_SPIN 225lock, respectively, and also accept a 226.Fa flags 227argument. 228In both cases, the only flag presently available for lock acquires is 229.Dv MTX_QUIET . 230If the 231.Dv MTX_QUIET 232bit is turned on in the 233.Fa flags 234argument, then if 235.Dv KTR_LOCK 236tracing is being done, 237it will be silenced during the lock acquire. 238.Pp 239The 240.Fn mtx_trylock 241attempts to acquire the 242.Dv MTX_DEF 243mutex pointed to by 244.Fa mutex . 245If the mutex cannot be immediately acquired 246.Fn mtx_trylock 247will return 0, 248otherwise the mutex will be acquired 249and a non-zero value will be returned. 250.Pp 251The 252.Fn mtx_trylock_flags 253function has the same behavior as 254.Fn mtx_trylock 255but should be used when the caller desires to pass in a 256.Fa flags 257value. 258Presently, the only valid value in the 259.Fn mtx_trylock 260case is 261.Dv MTX_QUIET , 262and its effects are identical to those described for 263.Fn mtx_lock 264above. 265.Pp 266The 267.Fn mtx_unlock 268function releases a 269.Dv MTX_DEF 270mutual exclusion lock. 271The current thread may be preempted if a higher priority thread is waiting 272for the mutex. 273.Pp 274The 275.Fn mtx_unlock_spin 276function releases a 277.Dv MTX_SPIN 278mutual exclusion lock. 279.Pp 280The 281.Fn mtx_unlock_flags 282and 283.Fn mtx_unlock_spin_flags 284functions behave in exactly the same way as do the standard mutex 285unlock routines above, while also allowing a 286.Fa flags 287argument which may specify 288.Dv MTX_QUIET . 289The behavior of 290.Dv MTX_QUIET 291is identical to its behavior in the mutex lock routines. 292.Pp 293The 294.Fn mtx_destroy 295function is used to destroy 296.Fa mutex 297so the data associated with it may be freed 298or otherwise overwritten. 299Any mutex which is destroyed 300must previously have been initialized with 301.Fn mtx_init . 302It is permissible to have a single hold count 303on a mutex when it is destroyed. 304It is not permissible to hold the mutex recursively, 305or have another thread blocked on the mutex 306when it is destroyed. 307.Pp 308The 309.Fn mtx_sleep 310function is used to atomically release 311.Fa mtx 312while waiting for an event. 313For more details on the parameters to this function, 314see 315.Xr sleep 9 . 316.Pp 317The 318.Fn mtx_initialized 319function returns non-zero if 320.Fa mutex 321has been initialized and zero otherwise. 322.Pp 323The 324.Fn mtx_owned 325function returns non-zero 326if the current thread holds 327.Fa mutex . 328If the current thread does not hold 329.Fa mutex 330zero is returned. 331.Pp 332The 333.Fn mtx_recursed 334function returns non-zero if the 335.Fa mutex 336is recursed. 337This check should only be made if the running thread already owns 338.Fa mutex . 339.Pp 340The 341.Fn mtx_assert 342function allows assertions specified in 343.Fa what 344to be made about 345.Fa mutex . 346If the assertions are not true and the kernel is compiled with 347.Cd "options INVARIANTS" 348and 349.Cd "options INVARIANT_SUPPORT" , 350the kernel will panic. 351Currently the following assertions are supported: 352.Bl -tag -width MA_NOTRECURSED 353.It Dv MA_OWNED 354Assert that the current thread 355holds the mutex 356pointed to by the first argument. 357.It Dv MA_NOTOWNED 358Assert that the current thread 359does not hold the mutex 360pointed to by the first argument. 361.It Dv MA_RECURSED 362Assert that the current thread has recursed on the mutex 363pointed to by the first argument. 364This assertion is only valid in conjunction with 365.Dv MA_OWNED . 366.It Dv MA_NOTRECURSED 367Assert that the current thread has not recursed on the mutex 368pointed to by the first argument. 369This assertion is only valid in conjunction with 370.Dv MA_OWNED . 371.El 372.Pp 373The 374.Fn MTX_SYSINIT 375macro is used to generate a call to the 376.Fn mtx_sysinit 377routine at system startup in order to initialize a given mutex lock. 378The parameters are the same as 379.Fn mtx_init 380but with an additional argument, 381.Fa name , 382that is used in generating unique variable names for the related structures associated with the lock and the sysinit routine. 383.Ss The Default Mutex Type 384Most kernel code should use the default lock type, 385.Dv MTX_DEF . 386The default lock type will allow the thread 387to be disconnected from the CPU 388if the lock is already held by another thread. 389The implementation 390may treat the lock as a short term spin lock 391under some circumstances. 392However, it is always safe to use these forms of locks 393in an interrupt thread 394without fear of deadlock 395against an interrupted thread on the same CPU. 396.Ss The Spin Mutex Type 397A 398.Dv MTX_SPIN 399mutex will not relinquish the CPU 400when it cannot immediately get the requested lock, 401but will loop, waiting for the mutex to be released by another CPU. 402This could result in deadlock 403if another thread interrupted the thread which held a mutex 404and then tried to acquire the mutex. 405For this reason spin locks disable all interrupts on the local CPU. 406.Pp 407Spin locks are fairly specialized locks 408that are intended to be held for very short periods of time. 409Their primary purpose is to protect portions of the code 410that implement other synchronization primitives such as default mutexes, 411thread scheduling, and interrupt threads. 412.Ss Initialization Options 413The options passed in the 414.Fa opts 415argument of 416.Fn mtx_init 417specify the mutex type. 418One of the 419.Dv MTX_DEF 420or 421.Dv MTX_SPIN 422options is required and only one of those two options may be specified. 423The possibilities are: 424.Bl -tag -width MTX_NOWITNESS 425.It Dv MTX_DEF 426Default mutexes 427will always allow the current thread to be suspended 428to avoid deadlock conditions against interrupt threads. 429The implementation of this lock type 430may spin for a while before suspending the current thread. 431.It Dv MTX_SPIN 432Spin mutexes 433will never relinquish the CPU. 434All interrupts are disabled on the local CPU 435while any spin lock is held. 436.It Dv MTX_RECURSE 437Specifies that the initialized mutex is allowed to recurse. 438This bit must be present if the mutex is permitted to recurse. 439.It Dv MTX_QUIET 440Do not log any mutex operations for this lock. 441.It Dv MTX_NOWITNESS 442Instruct 443.Xr witness 4 444to ignore this lock. 445.It Dv MTX_DUPOK 446Witness should not log messages about duplicate locks being acquired. 447.It Dv MTX_NOPROFILE 448Do not profile this lock. 449.El 450.Ss Lock and Unlock Flags 451The flags passed to the 452.Fn mtx_lock_flags , 453.Fn mtx_lock_spin_flags , 454.Fn mtx_unlock_flags , 455and 456.Fn mtx_unlock_spin_flags 457functions provide some basic options to the caller, 458and are often used only under special circumstances to modify lock or 459unlock behavior. 460Standard locking and unlocking should be performed with the 461.Fn mtx_lock , 462.Fn mtx_lock_spin , 463.Fn mtx_unlock , 464and 465.Fn mtx_unlock_spin 466functions. 467Only if a flag is required should the corresponding 468flags-accepting routines be used. 469.Pp 470Options that modify mutex behavior: 471.Bl -tag -width MTX_QUIET 472.It Dv MTX_QUIET 473This option is used to quiet logging messages during individual mutex 474operations. 475This can be used to trim superfluous logging messages for debugging purposes. 476.El 477.Ss Giant 478If 479.Va Giant 480must be acquired, it must be acquired prior to acquiring 481other mutexes. 482Put another way: it is impossible to acquire 483.Va Giant 484non-recursively while 485holding another mutex. 486It is possible to acquire other mutexes while holding 487.Va Giant , 488and it is possible to acquire 489.Va Giant 490recursively while holding other mutexes. 491.Ss Sleeping 492Sleeping while holding a mutex (except for 493.Va Giant ) 494is never safe 495and should be avoided. 496There are numerous assertions which will fail if this is attempted. 497.Ss Functions Which Access Memory in Userspace 498No mutexes should be held (except for 499.Va Giant ) 500across functions which 501access memory in userspace, such as 502.Xr copyin 9 , 503.Xr copyout 9 , 504.Xr uiomove 9 , 505.Xr fuword 9 , 506etc. 507No locks are needed when calling these functions. 508.Sh SEE ALSO 509.Xr condvar 9 , 510.Xr LOCK_PROFILING 9 , 511.Xr locking 9 , 512.Xr mtx_pool 9 , 513.Xr panic 9 , 514.Xr rwlock 9 , 515.Xr sema 9 , 516.Xr sleep 9 , 517.Xr sx 9 518.Sh HISTORY 519These 520functions appeared in 521.Bsx 4.1 522and 523.Fx 5.0 . 524