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 August 24, 2014 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.Nm spin_pool_lock , 43.Nm spin_pool_unlock 44.Nd core spinlocks 45.Sh SYNOPSIS 46.In sys/spinlock.h 47.In sys/spinlock2.h 48.Ft void 49.Fn spin_init "struct spinlock *mtx" "const char *descr" 50.Ft void 51.Fn spin_uninit "struct spinlock *mtx" 52.Ft void 53.Fn spin_lock "struct spinlock *mtx" 54.Ft void 55.Fn spin_lock_quick "globaldata_t gd" "struct spinlock *mtx" 56.Ft boolean_t 57.Fn spin_trylock "struct spinlock *mtx" 58.Ft void 59.Fn spin_unlock "struct spinlock *mtx" 60.Ft void 61.Fn spin_unlock_quick "globaldata_t gd" "struct spinlock *mtx" 62.Sh DESCRIPTION 63The 64.Fa spinlock 65structure and call API are defined in the 66.In sys/spinlock.h 67and 68.In sys/spinlock2.h 69header files, respectively. 70.Pp 71The 72.Fn spin_init 73function initializes a new 74.Fa spinlock 75structure for use. 76An initializer macro, 77.Dv SPINLOCK_INITIALIZER , 78is provided as well, taking the same arguments as 79.Fn spin_init . 80The structure is cleaned up with 81.Fn spin_uninit 82when it is no longer needed. 83.Pp 84The 85.Fn spin_lock 86function obtains an exclusive 87.Em read-write 88spinlock. 89A thread may hold any number of exclusive spinlocks but should always 90be mindful of ordering deadlocks. 91The 92.Fn spin_trylock 93function will return 94.Dv TRUE 95if the spinlock was successfully obtained and 96.Dv FALSE 97if it wasn't. 98If you have the current CPU's 99.Fa globaldata 100pointer in hand you can call 101.Fn spin_lock_quick , 102but most code will just call the normal version. 103A spinlock used only for exclusive access has about the same overhead 104as a mutex based on a locked bus cycle. 105.Pp 106A previously obtained exclusive spinlock is released by calling either 107.Fn spin_unlock 108or 109.Fn spin_unlock_quick . 110.Pp 111The 112.Fn spin_pool_lock 113function locks a pool spinlock associated with a given address. 114The spinlock's lifetime is not tied to any objects at the address. 115The function returns the locked spinlock. 116The 117.Fn spin_pool_unlock 118function unlocks a pool spinlock associated with an address. 119Pool spinlocks need not be initialized. 120.Sh IMPLEMENTATION NOTES 121A thread may not hold any spinlock across a blocking condition or 122thread switch. 123LWKT tokens should be used for situations where you want an exclusive 124run-time lock that will survive a blocking condition or thread switch. 125Tokens will be automatically unlocked when a thread switches away and 126relocked when the thread is switched back in. 127If you want a lock that survives a blocking condition or thread switch 128without being released, use 129.Xr lockmgr 9 130locks or LWKT reader/writer locks. 131.Pp 132.Dx Ap s 133core spinlocks should only be used around small contained sections of 134code. 135For example, to manage a reference count or to implement higher level 136locking mechanisms. 137Both the token code and the 138.Xr lockmgr 9 139code use exclusive spinlocks internally. 140Core spinlocks should not be used around large chunks of code. 141.Pp 142Holding one or more spinlocks will disable thread preemption by 143another thread (e.g. preemption by an interrupt thread), 144and will prevent FAST interrupts or IPIs from running. 145This means that a FAST interrupt, IPI and any threaded interrupt 146(which is basically all interrupts except the clock interrupt) 147will still be scheduled for later execution, 148but will not be able to preempt the current thread. 149.Pp 150A thread may hold any number of exclusive 151.Em read-write 152spinlocks. 153.Pp 154Spinlocks spin. 155A thread will not block, switch away, or lose its critical section 156while obtaining or releasing a spinlock. 157Spinlocks do not use IPIs or other mechanisms. 158They are considered to be a very low level mechanism. 159.Pp 160If a spinlock can not be obtained after one second a warning will be 161printed on the console. 162If a system panic occurs, spinlocks will succeed after one second in 163order to allow the panic operation to proceed. 164.Pp 165If you have a complex structure such as a 166.Xr vnode 9 167which contains a token or 168.Xr lockmgr 9 169lock, it is legal to directly access the internal spinlock embedded 170in those structures for other purposes as long as the spinlock is not 171held when you issue the token or 172.Xr lockmgr 9 173operation. 174.Sh FILES 175The uncontended path of the spinlock implementation is in 176.Pa /sys/sys/spinlock2.h . 177The core of the spinlock implementation is in 178.Pa /sys/kern/kern_spinlock.c . 179.Sh SEE ALSO 180.Xr crit_enter 9 , 181.Xr locking 9 , 182.Xr lockmgr 9 , 183.Xr serializer 9 184.Sh HISTORY 185A 186.Nm spinlock 187implementation first appeared in 188.Dx 1.3 . 189.Sh AUTHORS 190.An -nosplit 191The original 192.Nm spinlock 193implementation was written by 194.An Jeffrey M. Hsu 195and was later extended by 196.An Matthew Dillon . 197This manual page was written by 198.An Matthew Dillon 199and 200.An Sascha Wildner . 201