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 January 15, 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" 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), 140and will prevent FAST interrupts or IPIs from running. 141This means that a FAST interrupt, IPI and any threaded interrupt 142(which is basically all interrupts except the clock interrupt) 143will still be scheduled for later execution, 144but will not be able to preempt the current thread. 145.Pp 146A thread may hold any number of exclusive 147.Em read-write 148spinlocks. 149.Pp 150Spinlocks spin. 151A thread will not block, switch away, or lose its critical section 152while obtaining or releasing a spinlock. 153Spinlocks do not use IPIs or other mechanisms. 154They are considered to be a very low level mechanism. 155.Pp 156If a spinlock can not be obtained after one second a warning will be 157printed on the console. 158If a system panic occurs, spinlocks will succeed after one second in 159order to allow the panic operation to proceed. 160.Pp 161If you have a complex structure such as a 162.Xr vnode 9 163which contains a token or 164.Xr lockmgr 9 165lock, it is legal to directly access the internal spinlock embedded 166in those structures for other purposes as long as the spinlock is not 167held when you issue the token or 168.Xr lockmgr 9 169operation. 170.Sh FILES 171The uncontended path of the spinlock implementation is in 172.Pa /sys/sys/spinlock2.h . 173The core of the spinlock implementation is in 174.Pa /sys/kern/kern_spinlock.c . 175.Sh SEE ALSO 176.Xr crit_enter 9 , 177.Xr lockmgr 9 , 178.Xr serializer 9 179.Sh HISTORY 180A 181.Nm spinlock 182implementation first appeared in 183.Dx 1.3 . 184.Sh AUTHORS 185.An -nosplit 186The original 187.Nm spinlock 188implementation was written by 189.An Jeffrey M. Hsu 190and was later extended by 191.An Matthew Dillon . 192This manual page was written by 193.An Matthew Dillon 194and 195.An Sascha Wildner . 196