xref: /dflybsd-src/share/man/man9/spinlock.9 (revision fb3c2c0caaaa0e5d800e088b7dd7983e9ab009ec)
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