116338e2dSSascha Wildner.\" 216338e2dSSascha Wildner.\" Copyright (c) 2006 The DragonFly Project. All rights reserved. 316338e2dSSascha Wildner.\" 416338e2dSSascha Wildner.\" Redistribution and use in source and binary forms, with or without 516338e2dSSascha Wildner.\" modification, are permitted provided that the following conditions 616338e2dSSascha Wildner.\" are met: 716338e2dSSascha Wildner.\" 816338e2dSSascha Wildner.\" 1. Redistributions of source code must retain the above copyright 916338e2dSSascha Wildner.\" notice, this list of conditions and the following disclaimer. 1016338e2dSSascha Wildner.\" 2. Redistributions in binary form must reproduce the above copyright 1116338e2dSSascha Wildner.\" notice, this list of conditions and the following disclaimer in 1216338e2dSSascha Wildner.\" the documentation and/or other materials provided with the 1316338e2dSSascha Wildner.\" distribution. 1416338e2dSSascha Wildner.\" 3. Neither the name of The DragonFly Project nor the names of its 1516338e2dSSascha Wildner.\" contributors may be used to endorse or promote products derived 1616338e2dSSascha Wildner.\" from this software without specific, prior written permission. 1716338e2dSSascha Wildner.\" 1816338e2dSSascha Wildner.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 1916338e2dSSascha Wildner.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 2016338e2dSSascha Wildner.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 2116338e2dSSascha Wildner.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 2216338e2dSSascha Wildner.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 2316338e2dSSascha Wildner.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 2416338e2dSSascha Wildner.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 2516338e2dSSascha Wildner.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 2616338e2dSSascha Wildner.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 2716338e2dSSascha Wildner.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 2816338e2dSSascha Wildner.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 2916338e2dSSascha Wildner.\" SUCH DAMAGE. 3016338e2dSSascha Wildner.\" 31*edf2e657SSascha Wildner.Dd May 29, 2017 3216338e2dSSascha Wildner.Dt SPINLOCK 9 33fb5b3747SSascha Wildner.Os 3416338e2dSSascha Wildner.Sh NAME 3516338e2dSSascha Wildner.Nm spin_init , 367cfe2b28SAlex Hornung.Nm spin_lock , 377cfe2b28SAlex Hornung.Nm spin_lock_quick , 387cfe2b28SAlex Hornung.Nm spin_trylock , 3916338e2dSSascha Wildner.Nm spin_uninit , 407cfe2b28SAlex Hornung.Nm spin_unlock , 41*edf2e657SSascha Wildner.Nm spin_unlock_quick 4216338e2dSSascha Wildner.Nd core spinlocks 4316338e2dSSascha Wildner.Sh SYNOPSIS 4416338e2dSSascha Wildner.In sys/spinlock.h 4516338e2dSSascha Wildner.In sys/spinlock2.h 4616338e2dSSascha Wildner.Ft void 47ba87a4abSSascha Wildner.Fn spin_init "struct spinlock *mtx" "const char *descr" 4816338e2dSSascha Wildner.Ft void 4916338e2dSSascha Wildner.Fn spin_uninit "struct spinlock *mtx" 5016338e2dSSascha Wildner.Ft void 517cfe2b28SAlex Hornung.Fn spin_lock "struct spinlock *mtx" 5216338e2dSSascha Wildner.Ft void 537cfe2b28SAlex Hornung.Fn spin_lock_quick "globaldata_t gd" "struct spinlock *mtx" 5416338e2dSSascha Wildner.Ft boolean_t 557cfe2b28SAlex Hornung.Fn spin_trylock "struct spinlock *mtx" 5616338e2dSSascha Wildner.Ft void 577cfe2b28SAlex Hornung.Fn spin_unlock "struct spinlock *mtx" 5816338e2dSSascha Wildner.Ft void 597cfe2b28SAlex Hornung.Fn spin_unlock_quick "globaldata_t gd" "struct spinlock *mtx" 6016338e2dSSascha Wildner.Sh DESCRIPTION 6116338e2dSSascha WildnerThe 6216338e2dSSascha Wildner.Fa spinlock 6316338e2dSSascha Wildnerstructure and call API are defined in the 6416338e2dSSascha Wildner.In sys/spinlock.h 6516338e2dSSascha Wildnerand 6616338e2dSSascha Wildner.In sys/spinlock2.h 6716338e2dSSascha Wildnerheader files, respectively. 6816338e2dSSascha Wildner.Pp 6916338e2dSSascha WildnerThe 7016338e2dSSascha Wildner.Fn spin_init 7116338e2dSSascha Wildnerfunction initializes a new 7216338e2dSSascha Wildner.Fa spinlock 7316338e2dSSascha Wildnerstructure for use. 74ba87a4abSSascha WildnerAn initializer macro, 75ba87a4abSSascha Wildner.Dv SPINLOCK_INITIALIZER , 76ba87a4abSSascha Wildneris provided as well, taking the same arguments as 77ba87a4abSSascha Wildner.Fn spin_init . 7816338e2dSSascha WildnerThe structure is cleaned up with 7916338e2dSSascha Wildner.Fn spin_uninit 8016338e2dSSascha Wildnerwhen it is no longer needed. 8116338e2dSSascha Wildner.Pp 8216338e2dSSascha WildnerThe 837cfe2b28SAlex Hornung.Fn spin_lock 8416338e2dSSascha Wildnerfunction obtains an exclusive 8516338e2dSSascha Wildner.Em read-write 8616338e2dSSascha Wildnerspinlock. 8716338e2dSSascha WildnerA thread may hold any number of exclusive spinlocks but should always 8835b4e70bSSascha Wildnerbe mindful of ordering deadlocks. 8916338e2dSSascha WildnerThe 907cfe2b28SAlex Hornung.Fn spin_trylock 9116338e2dSSascha Wildnerfunction will return 9216338e2dSSascha Wildner.Dv TRUE 9316338e2dSSascha Wildnerif the spinlock was successfully obtained and 9416338e2dSSascha Wildner.Dv FALSE 9516338e2dSSascha Wildnerif it wasn't. 9616338e2dSSascha WildnerIf you have the current CPU's 9716338e2dSSascha Wildner.Fa globaldata 9816338e2dSSascha Wildnerpointer in hand you can call 997cfe2b28SAlex Hornung.Fn spin_lock_quick , 10016338e2dSSascha Wildnerbut most code will just call the normal version. 10116338e2dSSascha WildnerA spinlock used only for exclusive access has about the same overhead 10216338e2dSSascha Wildneras a mutex based on a locked bus cycle. 10316338e2dSSascha Wildner.Pp 10416338e2dSSascha WildnerA previously obtained exclusive spinlock is released by calling either 1057cfe2b28SAlex Hornung.Fn spin_unlock 10616338e2dSSascha Wildneror 1077cfe2b28SAlex Hornung.Fn spin_unlock_quick . 10816338e2dSSascha Wildner.Sh IMPLEMENTATION NOTES 10916338e2dSSascha WildnerA thread may not hold any spinlock across a blocking condition or 11016338e2dSSascha Wildnerthread switch. 11116338e2dSSascha WildnerLWKT tokens should be used for situations where you want an exclusive 11216338e2dSSascha Wildnerrun-time lock that will survive a blocking condition or thread switch. 11316338e2dSSascha WildnerTokens will be automatically unlocked when a thread switches away and 11416338e2dSSascha Wildnerrelocked when the thread is switched back in. 11516338e2dSSascha WildnerIf you want a lock that survives a blocking condition or thread switch 11616338e2dSSascha Wildnerwithout being released, use 11716338e2dSSascha Wildner.Xr lockmgr 9 11816338e2dSSascha Wildnerlocks or LWKT reader/writer locks. 11916338e2dSSascha Wildner.Pp 12016338e2dSSascha Wildner.Dx Ap s 12116338e2dSSascha Wildnercore spinlocks should only be used around small contained sections of 12216338e2dSSascha Wildnercode. 12316338e2dSSascha WildnerFor example, to manage a reference count or to implement higher level 12416338e2dSSascha Wildnerlocking mechanisms. 12516338e2dSSascha WildnerBoth the token code and the 12616338e2dSSascha Wildner.Xr lockmgr 9 12716338e2dSSascha Wildnercode use exclusive spinlocks internally. 12816338e2dSSascha WildnerCore spinlocks should not be used around large chunks of code. 12916338e2dSSascha Wildner.Pp 13016338e2dSSascha WildnerHolding one or more spinlocks will disable thread preemption by 1310f4dce5bSSepherosa Ziehauanother thread (e.g. preemption by an interrupt thread), 1320f4dce5bSSepherosa Ziehauand will prevent FAST interrupts or IPIs from running. 1330f4dce5bSSepherosa ZiehauThis means that a FAST interrupt, IPI and any threaded interrupt 1340f4dce5bSSepherosa Ziehau(which is basically all interrupts except the clock interrupt) 1350f4dce5bSSepherosa Ziehauwill still be scheduled for later execution, 1360f4dce5bSSepherosa Ziehaubut will not be able to preempt the current thread. 13716338e2dSSascha Wildner.Pp 13816338e2dSSascha WildnerA thread may hold any number of exclusive 13916338e2dSSascha Wildner.Em read-write 1404331bf91SMatthew Dillonspinlocks. 14116338e2dSSascha Wildner.Pp 14216338e2dSSascha WildnerSpinlocks spin. 14316338e2dSSascha WildnerA thread will not block, switch away, or lose its critical section 14416338e2dSSascha Wildnerwhile obtaining or releasing a spinlock. 14516338e2dSSascha WildnerSpinlocks do not use IPIs or other mechanisms. 14616338e2dSSascha WildnerThey are considered to be a very low level mechanism. 14716338e2dSSascha Wildner.Pp 14816338e2dSSascha WildnerIf a spinlock can not be obtained after one second a warning will be 14916338e2dSSascha Wildnerprinted on the console. 1506196d487SMatthew DillonIf a system panic occurs, spinlocks will succeed after one second in 15116338e2dSSascha Wildnerorder to allow the panic operation to proceed. 15216338e2dSSascha Wildner.Pp 15316338e2dSSascha WildnerIf you have a complex structure such as a 15416338e2dSSascha Wildner.Xr vnode 9 15516338e2dSSascha Wildnerwhich contains a token or 15616338e2dSSascha Wildner.Xr lockmgr 9 15716338e2dSSascha Wildnerlock, it is legal to directly access the internal spinlock embedded 1586196d487SMatthew Dillonin those structures for other purposes as long as the spinlock is not 15935b4e70bSSascha Wildnerheld when you issue the token or 16035b4e70bSSascha Wildner.Xr lockmgr 9 16135b4e70bSSascha Wildneroperation. 162deff95cbSSascha Wildner.Sh FILES 163deff95cbSSascha WildnerThe uncontended path of the spinlock implementation is in 164deff95cbSSascha Wildner.Pa /sys/sys/spinlock2.h . 165deff95cbSSascha WildnerThe core of the spinlock implementation is in 166deff95cbSSascha Wildner.Pa /sys/kern/kern_spinlock.c . 16716338e2dSSascha Wildner.Sh SEE ALSO 168e1700543SSascha Wildner.Xr crit_enter 9 , 169c04308e8SMarkus Pfeiffer.Xr locking 9 , 170a8b21083SSascha Wildner.Xr lockmgr 9 , 171e1700543SSascha Wildner.Xr serializer 9 17216338e2dSSascha Wildner.Sh HISTORY 17316338e2dSSascha WildnerA 17416338e2dSSascha Wildner.Nm spinlock 17516338e2dSSascha Wildnerimplementation first appeared in 17616338e2dSSascha Wildner.Dx 1.3 . 17716338e2dSSascha Wildner.Sh AUTHORS 17816338e2dSSascha Wildner.An -nosplit 17916338e2dSSascha WildnerThe original 18016338e2dSSascha Wildner.Nm spinlock 18116338e2dSSascha Wildnerimplementation was written by 18216338e2dSSascha Wildner.An Jeffrey M. Hsu 18316338e2dSSascha Wildnerand was later extended by 18416338e2dSSascha Wildner.An Matthew Dillon . 18516338e2dSSascha WildnerThis manual page was written by 18616338e2dSSascha Wildner.An Matthew Dillon 18716338e2dSSascha Wildnerand 18816338e2dSSascha Wildner.An Sascha Wildner . 189