1.\" 2.\" Copyright (c) 2006 The DragonFly Project. 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.\" 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in 12.\" the documentation and/or other materials provided with the 13.\" distribution. 14.\" 3. Neither the name of The DragonFly Project nor the names of its 15.\" contributors may be used to endorse or promote products derived 16.\" from this software without specific, prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 21.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 22.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 23.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 24.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 25.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 26.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 27.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 28.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.Dd May 29, 2017 32.Dt SPINLOCK 9 33.Os 34.Sh NAME 35.Nm spin_init , 36.Nm spin_lock , 37.Nm spin_lock_quick , 38.Nm spin_trylock , 39.Nm spin_uninit , 40.Nm spin_unlock , 41.Nm spin_unlock_quick 42.Nd core spinlocks 43.Sh SYNOPSIS 44.In sys/spinlock.h 45.In sys/spinlock2.h 46.Ft void 47.Fn spin_init "struct spinlock *mtx" "const char *descr" 48.Ft void 49.Fn spin_uninit "struct spinlock *mtx" 50.Ft void 51.Fn spin_lock "struct spinlock *mtx" 52.Ft void 53.Fn spin_lock_quick "globaldata_t gd" "struct spinlock *mtx" 54.Ft boolean_t 55.Fn spin_trylock "struct spinlock *mtx" 56.Ft void 57.Fn spin_unlock "struct spinlock *mtx" 58.Ft void 59.Fn spin_unlock_quick "globaldata_t gd" "struct spinlock *mtx" 60.Sh DESCRIPTION 61The 62.Fa spinlock 63structure and call API are defined in the 64.In sys/spinlock.h 65and 66.In sys/spinlock2.h 67header files, respectively. 68.Pp 69The 70.Fn spin_init 71function initializes a new 72.Fa spinlock 73structure for use. 74An initializer macro, 75.Dv SPINLOCK_INITIALIZER , 76is provided as well, taking the same arguments as 77.Fn spin_init . 78The structure is cleaned up with 79.Fn spin_uninit 80when it is no longer needed. 81.Pp 82The 83.Fn spin_lock 84function obtains an exclusive 85.Em read-write 86spinlock. 87A thread may hold any number of exclusive spinlocks but should always 88be mindful of ordering deadlocks. 89The 90.Fn spin_trylock 91function will return 92.Dv TRUE 93if the spinlock was successfully obtained and 94.Dv FALSE 95if it wasn't. 96If you have the current CPU's 97.Fa globaldata 98pointer in hand you can call 99.Fn spin_lock_quick , 100but most code will just call the normal version. 101A spinlock used only for exclusive access has about the same overhead 102as a mutex based on a locked bus cycle. 103.Pp 104A previously obtained exclusive spinlock is released by calling either 105.Fn spin_unlock 106or 107.Fn spin_unlock_quick . 108.Sh IMPLEMENTATION NOTES 109A thread may not hold any spinlock across a blocking condition or 110thread switch. 111LWKT tokens should be used for situations where you want an exclusive 112run-time lock that will survive a blocking condition or thread switch. 113Tokens will be automatically unlocked when a thread switches away and 114relocked when the thread is switched back in. 115If you want a lock that survives a blocking condition or thread switch 116without being released, use 117.Xr lockmgr 9 118locks or LWKT reader/writer locks. 119.Pp 120.Dx Ap s 121core spinlocks should only be used around small contained sections of 122code. 123For example, to manage a reference count or to implement higher level 124locking mechanisms. 125Both the token code and the 126.Xr lockmgr 9 127code use exclusive spinlocks internally. 128Core spinlocks should not be used around large chunks of code. 129.Pp 130Holding one or more spinlocks will disable thread preemption by 131another thread (e.g. preemption by an interrupt thread), 132and will prevent FAST interrupts or IPIs from running. 133This means that a FAST interrupt, IPI and any threaded interrupt 134(which is basically all interrupts except the clock interrupt) 135will still be scheduled for later execution, 136but will not be able to preempt the current thread. 137.Pp 138A thread may hold any number of exclusive 139.Em read-write 140spinlocks. 141.Pp 142Spinlocks spin. 143A thread will not block, switch away, or lose its critical section 144while obtaining or releasing a spinlock. 145Spinlocks do not use IPIs or other mechanisms. 146They are considered to be a very low level mechanism. 147.Pp 148If a spinlock can not be obtained after one second a warning will be 149printed on the console. 150If a system panic occurs, spinlocks will succeed after one second in 151order to allow the panic operation to proceed. 152.Pp 153If you have a complex structure such as a 154.Xr vnode 9 155which contains a token or 156.Xr lockmgr 9 157lock, it is legal to directly access the internal spinlock embedded 158in those structures for other purposes as long as the spinlock is not 159held when you issue the token or 160.Xr lockmgr 9 161operation. 162.Sh FILES 163The uncontended path of the spinlock implementation is in 164.Pa /sys/sys/spinlock2.h . 165The core of the spinlock implementation is in 166.Pa /sys/kern/kern_spinlock.c . 167.Sh SEE ALSO 168.Xr crit_enter 9 , 169.Xr locking 9 , 170.Xr lockmgr 9 , 171.Xr serializer 9 172.Sh HISTORY 173A 174.Nm spinlock 175implementation first appeared in 176.Dx 1.3 . 177.Sh AUTHORS 178.An -nosplit 179The original 180.Nm spinlock 181implementation was written by 182.An Jeffrey M. Hsu 183and was later extended by 184.An Matthew Dillon . 185This manual page was written by 186.An Matthew Dillon 187and 188.An Sascha Wildner . 189