Document spin_pool_lock(9) and spin_pool_unlock(9).
[dragonfly.git] / share / man / man9 / spinlock.9
CommitLineData
16338e2d
SW
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.\"
7cfe2b28 31.Dd August 30, 2010
16338e2d 32.Dt SPINLOCK 9
fb5b3747 33.Os
16338e2d
SW
34.Sh NAME
35.Nm spin_init ,
7cfe2b28
AH
36.Nm spin_lock ,
37.Nm spin_lock_quick ,
38.Nm spin_trylock ,
16338e2d 39.Nm spin_uninit ,
7cfe2b28 40.Nm spin_unlock ,
01c7831a
VS
41.Nm spin_unlock_quick ,
42.Nm spin_pool_lock ,
43.Nm spin_pool_unlock
16338e2d
SW
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
7cfe2b28 53.Fn spin_lock "struct spinlock *mtx"
16338e2d 54.Ft void
7cfe2b28 55.Fn spin_lock_quick "globaldata_t gd" "struct spinlock *mtx"
16338e2d 56.Ft boolean_t
7cfe2b28 57.Fn spin_trylock "struct spinlock *mtx"
16338e2d 58.Ft void
7cfe2b28 59.Fn spin_unlock "struct spinlock *mtx"
16338e2d 60.Ft void
7cfe2b28 61.Fn spin_unlock_quick "globaldata_t gd" "struct spinlock *mtx"
16338e2d
SW
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
7cfe2b28 81.Fn spin_lock
16338e2d
SW
82function obtains an exclusive
83.Em read-write
84spinlock.
85A thread may hold any number of exclusive spinlocks but should always
35b4e70b 86be mindful of ordering deadlocks.
16338e2d 87The
7cfe2b28 88.Fn spin_trylock
16338e2d
SW
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
a8b21083 96pointer in hand you can call
7cfe2b28 97.Fn spin_lock_quick ,
16338e2d
SW
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.
16338e2d
SW
101.Pp
102A previously obtained exclusive spinlock is released by calling either
7cfe2b28 103.Fn spin_unlock
16338e2d 104or
7cfe2b28 105.Fn spin_unlock_quick .
01c7831a
VS
106.Pp
107The
108.Fn spin_pool_lock
109function locks a pool spinlock associated with a given address. The spinlock's
110lifetime is not tied to any objects at the address. The function returns the
111locked spinlock. The
112.Fn spin_pool_unlock
113function unlocks a pool spinlock associated with an address. Pool spinlocks
114need not be initialized.
16338e2d
SW
115.Sh IMPLEMENTATION NOTES
116A thread may not hold any spinlock across a blocking condition or
117thread switch.
118LWKT tokens should be used for situations where you want an exclusive
119run-time lock that will survive a blocking condition or thread switch.
120Tokens will be automatically unlocked when a thread switches away and
121relocked when the thread is switched back in.
122If you want a lock that survives a blocking condition or thread switch
123without being released, use
124.Xr lockmgr 9
a8b21083 125locks or LWKT reader/writer locks.
16338e2d
SW
126.Pp
127.Dx Ap s
128core spinlocks should only be used around small contained sections of
129code.
130For example, to manage a reference count or to implement higher level
131locking mechanisms.
132Both the token code and the
133.Xr lockmgr 9
134code use exclusive spinlocks internally.
135Core spinlocks should not be used around large chunks of code.
136.Pp
137Holding one or more spinlocks will disable thread preemption by
138another thread (e.g. preemption by an interrupt thread), but will not
139disable FAST interrupts or IPIs.
30946a66
NA
140This means that a FAST interrupt can still operate during a spinlock,
141and any threaded interrupt (which is basically all interrupts except
142the clock interrupt) will still be scheduled for later execution, but
143will not be able to preempt the current thread.
16338e2d 144If you wish to disable FAST interrupts and IPIs you need to enter a
4331bf91
MD
145critical section prior to obtaining the spinlock.
146.Pp
147Currently, FAST interrupts, including IPI messages, are not allowed to
35b4e70b
SW
148acquire any spinlocks.
149It is possible to work around this if
150.Va mycpu->gd_spinlocks_wr
7cfe2b28 151is 0.
35b4e70b 152If one
4331bf91
MD
153or the other is not zero, the FAST interrupt or IPI cannot acquire
154any spinlocks without risking a deadlock, even if the spinlocks in
155question are not related.
16338e2d
SW
156.Pp
157A thread may hold any number of exclusive
158.Em read-write
4331bf91 159spinlocks.
16338e2d
SW
160.Pp
161Spinlocks spin.
162A thread will not block, switch away, or lose its critical section
163while obtaining or releasing a spinlock.
164Spinlocks do not use IPIs or other mechanisms.
165They are considered to be a very low level mechanism.
166.Pp
167If a spinlock can not be obtained after one second a warning will be
168printed on the console.
6196d487 169If a system panic occurs, spinlocks will succeed after one second in
16338e2d
SW
170order to allow the panic operation to proceed.
171.Pp
172If you have a complex structure such as a
173.Xr vnode 9
174which contains a token or
175.Xr lockmgr 9
176lock, it is legal to directly access the internal spinlock embedded
6196d487 177in those structures for other purposes as long as the spinlock is not
35b4e70b
SW
178held when you issue the token or
179.Xr lockmgr 9
180operation.
deff95cb
SW
181.Sh FILES
182The uncontended path of the spinlock implementation is in
183.Pa /sys/sys/spinlock2.h .
184The core of the spinlock implementation is in
185.Pa /sys/kern/kern_spinlock.c .
16338e2d 186.Sh SEE ALSO
e1700543 187.Xr crit_enter 9 ,
a8b21083 188.Xr lockmgr 9 ,
e1700543 189.Xr serializer 9
16338e2d
SW
190.Sh HISTORY
191A
192.Nm spinlock
193implementation first appeared in
194.Dx 1.3 .
195.Sh AUTHORS
196.An -nosplit
197The original
198.Nm spinlock
199implementation was written by
200.An Jeffrey M. Hsu
201and was later extended by
202.An Matthew Dillon .
203This manual page was written by
204.An Matthew Dillon
205and
206.An Sascha Wildner .