1.\" $NetBSD: __cpu_simple_lock.9,v 1.1 2022/02/12 17:10:20 riastradh Exp $ 2.\" 3.\" Copyright (c) 2022 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd February 12, 2022 28.Dt __CPU_SIMPLE_LOCK 9 29.Os 30.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 31.Sh NAME 32.Nm __cpu_simple_lock 33.Nd simple spin locks 34.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 35.Sh SYNOPSIS 36.In sys/lock.h 37.\" 38.Ft void 39.Fn __cpu_simple_lock_init "__cpu_simple_lock_t *lock" 40.\" 41.Ft void 42.Fn __cpu_simple_lock "__cpu_simple_lock_t *lock" 43.Ft int 44.Fn __cpu_simple_lock_try "__cpu_simple_lock *lock" 45.Ft void 46.Fn __cpu_simple_unlock "__cpu_simple_lock_t *lock" 47.\" 48.Ft int 49.Fn __SIMPLELOCK_LOCKED_P "__cpu_simple_lock *lock" 50.\" 51.Fd "/* obsolete and for ABI compat only -- do not use */" 52.Ft void 53.Fn __cpu_simple_lock_set "__cpu_simple_Lock *lock" 54.Ft void 55.Fn __cpu_simple_lock_clear "__cpu_simple_lock *lock" 56.Ft int 57.Fn __SIMPLELOCK_UNLOCKED_P "__cpu_simple_lock *lock" 58.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 59.Sh DESCRIPTION 60The 61.Nm 62functions provide a simple spin-lock facility for limited purposes that 63cannot be served by 64.Xr mutex 9 , 65such as inside the implementation of 66.Xr mutex 9 67itself on platforms with limited atomic read/modify/write operations. 68.Pp 69.Nm 70is very limited: 71.Bl -bullet 72.It 73.Nm 74provides no debugging or diagnostic support through the 75.Dv LOCKDEBUG 76option. 77.It 78.Nm 79does not synchronize between code on a CPU and interrupt handlers 80running on that CPU \(em you must use it with 81.Xr spl 9 82for any locks that may be taken in interrupt context; failing to do so 83will likely lead to hard-to-debug deadlock. 84.It 85.Nm 86does not block preemption, so a thread holding a lock may be preempted, 87potentially requiring other callers to spin for long durations until 88the scheduler runs the holder again. 89.It 90.Nm 91does no exponential backoff to reduce memory traffic during 92contention. 93.El 94.Pp 95Unless you know what you are doing, you should use 96.Xr mutex 9 97instead. 98.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 99.Sh FUNCTIONS 100.Bl -tag -width abcd 101.It Fn __cpu_simple_lock_init lock 102Initialize 103.Fa lock 104for use with the other 105.Nm 106functions. 107.Pp 108The caller is responsible for ensuring 109.Fn __cpu_simple_lock_init 110happens before any use of the other functions. 111.Fn __cpu_simple_lock_init 112implies no particular memory ordering on its own. 113.\"""""""""""""""" 114.It Fn __cpu_simple_lock lock 115Acquire 116.Fa lock , 117waiting until it is released if currently held. 118.Pp 119Any memory operations preceding the previous 120.Fn __cpu_simple_unlock 121call that released the lock happen before any memory operations after 122the next 123.Fn __cpu_simple_lock 124call that acquires it. 125.\"""""""""""""""" 126.It Fn __cpu_simple_lock_try lock 127Try to acquire 128.Fa lock , 129without waiting if it is currently held. 130Return 1 if successful, 0 if not. 131.Pp 132Any memory operations preceding the previous 133.Fn __cpu_simple_unlock 134call that released the lock happen before any memory operations after 135the next 136.Em successful 137.Fn __cpu_simple_lock_try 138call that acquires it. 139.\"""""""""""""""" 140.It Fn __cpu_simple_unlock lock 141Release 142.Fa lock . 143.Pp 144Any memory operations preceding 145.Fn __cpu_simple_unlock 146happen before the next call to 147.Fn __cpu_simple_lock , 148or the next successful call to 149.Fn __cpu_simple_lock_try , 150that acquires 151.Fa lock . 152.\"""""""""""""""" 153.It Fn __SIMPLELOCK_LOCKED_P lock 154True if 155.Fa lock 156is currently locked, by anyone. 157.Pp 158This is normally only used for diagnostic assertions, or for loops 159around 160.Fn __cpu_simple_lock_try 161that also have higher-level functions like blocking interrupts and 162performing exponential backoff. 163.Pp 164No memory ordering is implied. 165.El 166.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 167.Sh OBSOLETE FUNCTIONS 168The following functions abuse the 169.Vt __cpu_simple_lock_t 170type to store a boolean. 171They are used inside the 172.Xr pthread 3 173library, and were included in the library ABI, so they can't be removed 174without breaking the 175.Xr pthread 3 176ABI. 177Do not use these in new code 178.Po 179except 180.Fn __SIMPLELOCK_LOCKED_P 181.Pc . 182.Bl -tag -width ".Fn __SIMPLELOCK_UNLOCKED_P lock" 183.It Fn __cpu_simple_lock_set lock 184Set 185.Fa lock 186to true. 187.It Fn __cpu_simple_lock_clear lock 188Set 189.Fa lock 190to false. 191.It Fn __SIMPLELOCK_LOCKED_P lock 192True iff 193.Fa lock 194is true. 195.It Fn __SIMPLELOCK_UNLOCKED_P lock 196True iff 197.Fa lock 198is false. 199.El 200.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 201.Sh CODE REFERENCES 202The 203.Nm 204functions are implemented in 205.Pa sys/arch/$ARCH/include/lock.h . 206.Pp 207A machine-independent implementation, using compiler support for 208atomic and memory barrier builtins, is available in 209.Pa sys/sys/common_lock.h . 210.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 211.Sh SEE ALSO 212.Xr locking 9 , 213.Xr mutex 9 214.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 215.Sh HISTORY 216.Nm 217appeared a long time ago. 218