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