1*96b9b86cSdlg.\" $OpenBSD: mutex.9,v 1.19 2014/01/19 10:01:35 dlg Exp $ 295534e8aSpedro.\" 3fcbf5195Sjmc.\" Copyright (c) 2005 Pedro Martelletto <pedro@ambientworks.net> 495534e8aSpedro.\" All rights reserved. 595534e8aSpedro.\" 695534e8aSpedro.\" Permission to use, copy, modify, and distribute this software for any 795534e8aSpedro.\" purpose with or without fee is hereby granted, provided that the above 895534e8aSpedro.\" copyright notice and this permission notice appear in all copies. 995534e8aSpedro.\" 1095534e8aSpedro.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 1195534e8aSpedro.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 1295534e8aSpedro.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 1395534e8aSpedro.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 1495534e8aSpedro.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 1595534e8aSpedro.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 1695534e8aSpedro.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 1795534e8aSpedro.\" 18*96b9b86cSdlg.Dd $Mdocdate: January 19 2014 $ 1995534e8aSpedro.Dt MUTEX 9 2095534e8aSpedro.Os 2195534e8aSpedro.Sh NAME 2295534e8aSpedro.Nm mutex , 2395534e8aSpedro.Nm mtx_init , 2495534e8aSpedro.Nm mtx_enter , 25b7266c42Sderaadt.Nm mtx_enter_try , 26ad1eb2f1Sdlg.Nm mtx_leave , 27ad1eb2f1Sdlg.Nm MUTEX_ASSERT_LOCKED , 28ad1eb2f1Sdlg.Nm MUTEX_ASSERT_UNLOCKED , 29ad1eb2f1Sdlg.Nm MUTEX_INITIALIZER 3095534e8aSpedro.Nd interface to CPU mutexes 3195534e8aSpedro.Sh SYNOPSIS 32dddd2645Sschwarze.In sys/mutex.h 3395534e8aSpedro.Ft void 3495534e8aSpedro.Fn mtx_init "struct mutex *mtxp" "int wantipl" 3595534e8aSpedro.Ft void 3695534e8aSpedro.Fn mtx_enter "struct mutex *mtxp" 37761ff03cSdlg.Ft int 38761ff03cSdlg.Fn mtx_enter_try "struct mutex *mtxp" 3995534e8aSpedro.Ft void 4095534e8aSpedro.Fn mtx_leave "struct mutex *mtxp" 412245e4c4Soga.Fn MUTEX_ASSERT_LOCKED "struct mutex *mtxp" 422245e4c4Soga.Fn MUTEX_ASSERT_UNLOCKED "struct mutex *mtxp" 43f27d3bc2Sdlg.Fn MUTEX_INITIALIZER "int wantipl" 4495534e8aSpedro.Sh DESCRIPTION 4595534e8aSpedroThe 4695534e8aSpedro.Nm 4795534e8aSpedroset of functions provides a non-recursive, interrupt-aware spinning mechanism 4895534e8aSpedroto ensure mutual exclusion between different CPUs. 4995534e8aSpedro.Pp 5095534e8aSpedroThe 5195534e8aSpedro.Fn mtx_init 5295534e8aSpedrofunction is used to initiate the mutex pointed to by 5395534e8aSpedro.Fa mtxp . 542217a74eSteduWhen acquired, the mutex will cause the processor interrupt level to be raised 5595534e8aSpedroto 562217a74eStedu.Fa wantipl 572217a74eSteduif necessary. 5895534e8aSpedro.Pp 5995534e8aSpedroThe 6095534e8aSpedro.Fn mtx_enter 6195534e8aSpedrofunction acquires a mutex, spinning if necessary. 6295534e8aSpedro.Pp 6395534e8aSpedroThe 64761ff03cSdlg.Fn mtx_enter_try 65761ff03cSdlgfunction attempts to acquire a mutex. 665f24e8bdSjmcIf it succeeds in acquiring the mutex it will return non-zero, otherwise 67761ff03cSdlgit will return 0. 68761ff03cSdlg.Pp 69761ff03cSdlgThe 7095534e8aSpedro.Fn mtx_leave 7195534e8aSpedrofunction releases a mutex. 7295534e8aSpedroIn case the acquisition of the mutex caused the interrupt level to be changed, 7395534e8aSpedroit is then restored. 742245e4c4Soga.Pp 752245e4c4SogaThe 762245e4c4Soga.Fn MUTEX_ASSERT_LOCKED 772245e4c4Sogaand 782245e4c4Soga.Fn MUTEX_ASSERT_UNLOCKED 792245e4c4Sogamacros may be used to assert that a mutex is held locked or unlocked by 807a5a2541Sjmcthe current CPU. 81f27d3bc2Sdlg.Pp 82f27d3bc2SdlgA mutex declaration may be initialised with the 83f27d3bc2Sdlg.Fn MUTEX_INITIALIZER 84f27d3bc2Sdlgmacro. 85f27d3bc2SdlgWhen acquired, the mutex will cause the processor interrupt level to be raised 86f27d3bc2Sdlgto 87f27d3bc2Sdlg.Fa wantipl 88f27d3bc2Sdlgif necessary. 8995534e8aSpedro.Sh SEE ALSO 9095534e8aSpedro.Xr lockmgr 9 , 91*96b9b86cSdlg.Xr msleep 9 , 92f798b271Sjsg.Xr rwlock 9 , 9395534e8aSpedro.Xr spl 9 9495534e8aSpedro.Sh HISTORY 9595534e8aSpedroThe 9695534e8aSpedro.Nm 9795534e8aSpedrofunctions first appeared in 9895534e8aSpedro.Ox 3.6 . 9995534e8aSpedro.Sh AUTHORS 10095534e8aSpedroThe 10195534e8aSpedro.Nm 10295534e8aSpedrofunctions were written by 103f0641c22Sschwarze.An Artur Grabowski Aq Mt art@openbsd.org . 10495534e8aSpedro.Sh CAVEATS 105c508eb99SjsgAs these are spinning locks, don't sleep while holding one. 106c508eb99Sjsg.Pp 107c508eb99SjsgIf using a mutex in an interrupt handler, locks must be initialised 108c508eb99Sjsgwith the correct IPL or deadlock will occur. 109c508eb99Sjsg.Pp 11095534e8aSpedroMultiple mutexes may be nested, but not interleaved. 11195534e8aSpedroThis is okay: 11295534e8aSpedro.Bd -literal -offset indent 11395534e8aSpedromtx_enter(foo); 11495534e8aSpedromtx_enter(bar); 11595534e8aSpedromtx_leave(bar); 11695534e8aSpedromtx_leave(foo); 11795534e8aSpedro.Ed 11895534e8aSpedro.Pp 11995534e8aSpedroWhile this is 12095534e8aSpedro.Fa not : 12195534e8aSpedro.Bd -literal -offset indent 12295534e8aSpedromtx_enter(foo); 12395534e8aSpedromtx_enter(bar); 12495534e8aSpedromtx_leave(foo); 12595534e8aSpedromtx_leave(bar); 12695534e8aSpedro.Ed 127