1 .. _kernel_hacking_lock: 1 .. _kernel_hacking_lock:
2 2
3 =========================== 3 ===========================
4 Unreliable Guide To Locking 4 Unreliable Guide To Locking
5 =========================== 5 ===========================
6 6
7 :Author: Rusty Russell 7 :Author: Rusty Russell
8 8
9 Introduction 9 Introduction
10 ============ 10 ============
11 11
12 Welcome, to Rusty's Remarkably Unreliable Guid 12 Welcome, to Rusty's Remarkably Unreliable Guide to Kernel Locking
13 issues. This document describes the locking sy 13 issues. This document describes the locking systems in the Linux Kernel
14 in 2.6. 14 in 2.6.
15 15
16 With the wide availability of HyperThreading, 16 With the wide availability of HyperThreading, and preemption in the
17 Linux Kernel, everyone hacking on the kernel n 17 Linux Kernel, everyone hacking on the kernel needs to know the
18 fundamentals of concurrency and locking for SM 18 fundamentals of concurrency and locking for SMP.
19 19
20 The Problem With Concurrency 20 The Problem With Concurrency
21 ============================ 21 ============================
22 22
23 (Skip this if you know what a Race Condition i 23 (Skip this if you know what a Race Condition is).
24 24
25 In a normal program, you can increment a count 25 In a normal program, you can increment a counter like so:
26 26
27 :: 27 ::
28 28
29 very_important_count++; 29 very_important_count++;
30 30
31 31
32 This is what they would expect to happen: 32 This is what they would expect to happen:
33 33
34 34
35 .. table:: Expected Results 35 .. table:: Expected Results
36 36
37 +------------------------------------+------ 37 +------------------------------------+------------------------------------+
38 | Instance 1 | Insta 38 | Instance 1 | Instance 2 |
39 +====================================+====== 39 +====================================+====================================+
40 | read very_important_count (5) | 40 | read very_important_count (5) | |
41 +------------------------------------+------ 41 +------------------------------------+------------------------------------+
42 | add 1 (6) | 42 | add 1 (6) | |
43 +------------------------------------+------ 43 +------------------------------------+------------------------------------+
44 | write very_important_count (6) | 44 | write very_important_count (6) | |
45 +------------------------------------+------ 45 +------------------------------------+------------------------------------+
46 | | read 46 | | read very_important_count (6) |
47 +------------------------------------+------ 47 +------------------------------------+------------------------------------+
48 | | add 1 48 | | add 1 (7) |
49 +------------------------------------+------ 49 +------------------------------------+------------------------------------+
50 | | write 50 | | write very_important_count (7) |
51 +------------------------------------+------ 51 +------------------------------------+------------------------------------+
52 52
53 This is what might happen: 53 This is what might happen:
54 54
55 .. table:: Possible Results 55 .. table:: Possible Results
56 56
57 +------------------------------------+------ 57 +------------------------------------+------------------------------------+
58 | Instance 1 | Insta 58 | Instance 1 | Instance 2 |
59 +====================================+====== 59 +====================================+====================================+
60 | read very_important_count (5) | 60 | read very_important_count (5) | |
61 +------------------------------------+------ 61 +------------------------------------+------------------------------------+
62 | | read 62 | | read very_important_count (5) |
63 +------------------------------------+------ 63 +------------------------------------+------------------------------------+
64 | add 1 (6) | 64 | add 1 (6) | |
65 +------------------------------------+------ 65 +------------------------------------+------------------------------------+
66 | | add 1 66 | | add 1 (6) |
67 +------------------------------------+------ 67 +------------------------------------+------------------------------------+
68 | write very_important_count (6) | 68 | write very_important_count (6) | |
69 +------------------------------------+------ 69 +------------------------------------+------------------------------------+
70 | | write 70 | | write very_important_count (6) |
71 +------------------------------------+------ 71 +------------------------------------+------------------------------------+
72 72
73 73
74 Race Conditions and Critical Regions 74 Race Conditions and Critical Regions
75 ------------------------------------ 75 ------------------------------------
76 76
77 This overlap, where the result depends on the 77 This overlap, where the result depends on the relative timing of
78 multiple tasks, is called a race condition. Th 78 multiple tasks, is called a race condition. The piece of code containing
79 the concurrency issue is called a critical reg 79 the concurrency issue is called a critical region. And especially since
80 Linux starting running on SMP machines, they b 80 Linux starting running on SMP machines, they became one of the major
81 issues in kernel design and implementation. 81 issues in kernel design and implementation.
82 82
83 Preemption can have the same effect, even if t 83 Preemption can have the same effect, even if there is only one CPU: by
84 preempting one task during the critical region 84 preempting one task during the critical region, we have exactly the same
85 race condition. In this case the thread which 85 race condition. In this case the thread which preempts might run the
86 critical region itself. 86 critical region itself.
87 87
88 The solution is to recognize when these simult 88 The solution is to recognize when these simultaneous accesses occur, and
89 use locks to make sure that only one instance 89 use locks to make sure that only one instance can enter the critical
90 region at any time. There are many friendly pr 90 region at any time. There are many friendly primitives in the Linux
91 kernel to help you do this. And then there are 91 kernel to help you do this. And then there are the unfriendly
92 primitives, but I'll pretend they don't exist. 92 primitives, but I'll pretend they don't exist.
93 93
94 Locking in the Linux Kernel 94 Locking in the Linux Kernel
95 =========================== 95 ===========================
96 96
97 If I could give you one piece of advice on loc !! 97 If I could give you one piece of advice: never sleep with anyone crazier
>> 98 than yourself. But if I had to give you advice on locking: **keep it
>> 99 simple**.
98 100
99 Be reluctant to introduce new locks. 101 Be reluctant to introduce new locks.
100 102
>> 103 Strangely enough, this last one is the exact reverse of my advice when
>> 104 you **have** slept with someone crazier than yourself. And you should
>> 105 think about getting a big dog.
>> 106
101 Two Main Types of Kernel Locks: Spinlocks and 107 Two Main Types of Kernel Locks: Spinlocks and Mutexes
102 ---------------------------------------------- 108 -----------------------------------------------------
103 109
104 There are two main types of kernel locks. The 110 There are two main types of kernel locks. The fundamental type is the
105 spinlock (``include/asm/spinlock.h``), which i 111 spinlock (``include/asm/spinlock.h``), which is a very simple
106 single-holder lock: if you can't get the spinl 112 single-holder lock: if you can't get the spinlock, you keep trying
107 (spinning) until you can. Spinlocks are very s 113 (spinning) until you can. Spinlocks are very small and fast, and can be
108 used anywhere. 114 used anywhere.
109 115
110 The second type is a mutex (``include/linux/mu 116 The second type is a mutex (``include/linux/mutex.h``): it is like a
111 spinlock, but you may block holding a mutex. I 117 spinlock, but you may block holding a mutex. If you can't lock a mutex,
112 your task will suspend itself, and be woken up 118 your task will suspend itself, and be woken up when the mutex is
113 released. This means the CPU can do something 119 released. This means the CPU can do something else while you are
114 waiting. There are many cases when you simply 120 waiting. There are many cases when you simply can't sleep (see
115 `What Functions Are Safe To Call From Interrup !! 121 `What Functions Are Safe To Call From Interrupts? <#sleeping-things>`__),
116 and so have to use a spinlock instead. 122 and so have to use a spinlock instead.
117 123
118 Neither type of lock is recursive: see 124 Neither type of lock is recursive: see
119 `Deadlock: Simple and Advanced`_. !! 125 `Deadlock: Simple and Advanced <#deadlock>`__.
120 126
121 Locks and Uniprocessor Kernels 127 Locks and Uniprocessor Kernels
122 ------------------------------ 128 ------------------------------
123 129
124 For kernels compiled without ``CONFIG_SMP``, a 130 For kernels compiled without ``CONFIG_SMP``, and without
125 ``CONFIG_PREEMPT`` spinlocks do not exist at a 131 ``CONFIG_PREEMPT`` spinlocks do not exist at all. This is an excellent
126 design decision: when no-one else can run at t 132 design decision: when no-one else can run at the same time, there is no
127 reason to have a lock. 133 reason to have a lock.
128 134
129 If the kernel is compiled without ``CONFIG_SMP 135 If the kernel is compiled without ``CONFIG_SMP``, but ``CONFIG_PREEMPT``
130 is set, then spinlocks simply disable preempti 136 is set, then spinlocks simply disable preemption, which is sufficient to
131 prevent any races. For most purposes, we can t 137 prevent any races. For most purposes, we can think of preemption as
132 equivalent to SMP, and not worry about it sepa 138 equivalent to SMP, and not worry about it separately.
133 139
134 You should always test your locking code with 140 You should always test your locking code with ``CONFIG_SMP`` and
135 ``CONFIG_PREEMPT`` enabled, even if you don't 141 ``CONFIG_PREEMPT`` enabled, even if you don't have an SMP test box,
136 because it will still catch some kinds of lock 142 because it will still catch some kinds of locking bugs.
137 143
138 Mutexes still exist, because they are required 144 Mutexes still exist, because they are required for synchronization
139 between user contexts, as we will see below. 145 between user contexts, as we will see below.
140 146
141 Locking Only In User Context 147 Locking Only In User Context
142 ---------------------------- 148 ----------------------------
143 149
144 If you have a data structure which is only eve 150 If you have a data structure which is only ever accessed from user
145 context, then you can use a simple mutex (``in 151 context, then you can use a simple mutex (``include/linux/mutex.h``) to
146 protect it. This is the most trivial case: you 152 protect it. This is the most trivial case: you initialize the mutex.
147 Then you can call mutex_lock_interruptible() t !! 153 Then you can call :c:func:`mutex_lock_interruptible()` to grab the
148 mutex, and mutex_unlock() to release it. There !! 154 mutex, and :c:func:`mutex_unlock()` to release it. There is also a
149 mutex_lock(), which should be avoided, because !! 155 :c:func:`mutex_lock()`, which should be avoided, because it will
150 not return if a signal is received. 156 not return if a signal is received.
151 157
152 Example: ``net/netfilter/nf_sockopt.c`` allows 158 Example: ``net/netfilter/nf_sockopt.c`` allows registration of new
153 setsockopt() and getsockopt() calls, with !! 159 :c:func:`setsockopt()` and :c:func:`getsockopt()` calls, with
154 nf_register_sockopt(). Registration and de-reg !! 160 :c:func:`nf_register_sockopt()`. Registration and de-registration
155 are only done on module load and unload (and b 161 are only done on module load and unload (and boot time, where there is
156 no concurrency), and the list of registrations 162 no concurrency), and the list of registrations is only consulted for an
157 unknown setsockopt() or getsockopt() system !! 163 unknown :c:func:`setsockopt()` or :c:func:`getsockopt()` system
158 call. The ``nf_sockopt_mutex`` is perfect to p 164 call. The ``nf_sockopt_mutex`` is perfect to protect this, especially
159 since the setsockopt and getsockopt calls may 165 since the setsockopt and getsockopt calls may well sleep.
160 166
161 Locking Between User Context and Softirqs 167 Locking Between User Context and Softirqs
162 ----------------------------------------- 168 -----------------------------------------
163 169
164 If a softirq shares data with user context, yo 170 If a softirq shares data with user context, you have two problems.
165 Firstly, the current user context can be inter 171 Firstly, the current user context can be interrupted by a softirq, and
166 secondly, the critical region could be entered 172 secondly, the critical region could be entered from another CPU. This is
167 where spin_lock_bh() (``include/linux/spinlock !! 173 where :c:func:`spin_lock_bh()` (``include/linux/spinlock.h``) is
168 used. It disables softirqs on that CPU, then g 174 used. It disables softirqs on that CPU, then grabs the lock.
169 spin_unlock_bh() does the reverse. (The '_bh' !! 175 :c:func:`spin_unlock_bh()` does the reverse. (The '_bh' suffix is
170 a historical reference to "Bottom Halves", the 176 a historical reference to "Bottom Halves", the old name for software
171 interrupts. It should really be called spin_lo 177 interrupts. It should really be called spin_lock_softirq()' in a
172 perfect world). 178 perfect world).
173 179
174 Note that you can also use spin_lock_irq() or !! 180 Note that you can also use :c:func:`spin_lock_irq()` or
175 spin_lock_irqsave() here, which stop hardware !! 181 :c:func:`spin_lock_irqsave()` here, which stop hardware interrupts
176 as well: see `Hard IRQ Context`_. !! 182 as well: see `Hard IRQ Context <#hard-irq-context>`__.
177 183
178 This works perfectly for UP as well: the spin 184 This works perfectly for UP as well: the spin lock vanishes, and this
179 macro simply becomes local_bh_disable() !! 185 macro simply becomes :c:func:`local_bh_disable()`
180 (``include/linux/interrupt.h``), which protect 186 (``include/linux/interrupt.h``), which protects you from the softirq
181 being run. 187 being run.
182 188
183 Locking Between User Context and Tasklets 189 Locking Between User Context and Tasklets
184 ----------------------------------------- 190 -----------------------------------------
185 191
186 This is exactly the same as above, because tas 192 This is exactly the same as above, because tasklets are actually run
187 from a softirq. 193 from a softirq.
188 194
189 Locking Between User Context and Timers 195 Locking Between User Context and Timers
190 --------------------------------------- 196 ---------------------------------------
191 197
192 This, too, is exactly the same as above, becau 198 This, too, is exactly the same as above, because timers are actually run
193 from a softirq. From a locking point of view, 199 from a softirq. From a locking point of view, tasklets and timers are
194 identical. 200 identical.
195 201
196 Locking Between Tasklets/Timers 202 Locking Between Tasklets/Timers
197 ------------------------------- 203 -------------------------------
198 204
199 Sometimes a tasklet or timer might want to sha 205 Sometimes a tasklet or timer might want to share data with another
200 tasklet or timer. 206 tasklet or timer.
201 207
202 The Same Tasklet/Timer 208 The Same Tasklet/Timer
203 ~~~~~~~~~~~~~~~~~~~~~~ 209 ~~~~~~~~~~~~~~~~~~~~~~
204 210
205 Since a tasklet is never run on two CPUs at on 211 Since a tasklet is never run on two CPUs at once, you don't need to
206 worry about your tasklet being reentrant (runn 212 worry about your tasklet being reentrant (running twice at once), even
207 on SMP. 213 on SMP.
208 214
209 Different Tasklets/Timers 215 Different Tasklets/Timers
210 ~~~~~~~~~~~~~~~~~~~~~~~~~ 216 ~~~~~~~~~~~~~~~~~~~~~~~~~
211 217
212 If another tasklet/timer wants to share data w 218 If another tasklet/timer wants to share data with your tasklet or timer
213 , you will both need to use spin_lock() and !! 219 , you will both need to use :c:func:`spin_lock()` and
214 spin_unlock() calls. spin_lock_bh() is !! 220 :c:func:`spin_unlock()` calls. :c:func:`spin_lock_bh()` is
215 unnecessary here, as you are already in a task 221 unnecessary here, as you are already in a tasklet, and none will be run
216 on the same CPU. 222 on the same CPU.
217 223
218 Locking Between Softirqs 224 Locking Between Softirqs
219 ------------------------ 225 ------------------------
220 226
221 Often a softirq might want to share data with 227 Often a softirq might want to share data with itself or a tasklet/timer.
222 228
223 The Same Softirq 229 The Same Softirq
224 ~~~~~~~~~~~~~~~~ 230 ~~~~~~~~~~~~~~~~
225 231
226 The same softirq can run on the other CPUs: yo 232 The same softirq can run on the other CPUs: you can use a per-CPU array
227 (see `Per-CPU Data`_) for better performance. !! 233 (see `Per-CPU Data <#per-cpu-data>`__) for better performance. If you're
228 going so far as to use a softirq, you probably 234 going so far as to use a softirq, you probably care about scalable
229 performance enough to justify the extra comple 235 performance enough to justify the extra complexity.
230 236
231 You'll need to use spin_lock() and !! 237 You'll need to use :c:func:`spin_lock()` and
232 spin_unlock() for shared data. !! 238 :c:func:`spin_unlock()` for shared data.
233 239
234 Different Softirqs 240 Different Softirqs
235 ~~~~~~~~~~~~~~~~~~ 241 ~~~~~~~~~~~~~~~~~~
236 242
237 You'll need to use spin_lock() and !! 243 You'll need to use :c:func:`spin_lock()` and
238 spin_unlock() for shared data, whether it be a !! 244 :c:func:`spin_unlock()` for shared data, whether it be a timer,
239 tasklet, different softirq or the same or anot 245 tasklet, different softirq or the same or another softirq: any of them
240 could be running on a different CPU. 246 could be running on a different CPU.
241 247
242 Hard IRQ Context 248 Hard IRQ Context
243 ================ 249 ================
244 250
245 Hardware interrupts usually communicate with a 251 Hardware interrupts usually communicate with a tasklet or softirq.
246 Frequently this involves putting work in a que 252 Frequently this involves putting work in a queue, which the softirq will
247 take out. 253 take out.
248 254
249 Locking Between Hard IRQ and Softirqs/Tasklets 255 Locking Between Hard IRQ and Softirqs/Tasklets
250 ---------------------------------------------- 256 ----------------------------------------------
251 257
252 If a hardware irq handler shares data with a s 258 If a hardware irq handler shares data with a softirq, you have two
253 concerns. Firstly, the softirq processing can 259 concerns. Firstly, the softirq processing can be interrupted by a
254 hardware interrupt, and secondly, the critical 260 hardware interrupt, and secondly, the critical region could be entered
255 by a hardware interrupt on another CPU. This i 261 by a hardware interrupt on another CPU. This is where
256 spin_lock_irq() is used. It is defined to disa !! 262 :c:func:`spin_lock_irq()` is used. It is defined to disable
257 interrupts on that cpu, then grab the lock. 263 interrupts on that cpu, then grab the lock.
258 spin_unlock_irq() does the reverse. !! 264 :c:func:`spin_unlock_irq()` does the reverse.
259 265
260 The irq handler does not need to use spin_lock !! 266 The irq handler does not to use :c:func:`spin_lock_irq()`, because
261 the softirq cannot run while the irq handler i 267 the softirq cannot run while the irq handler is running: it can use
262 spin_lock(), which is slightly faster. The onl !! 268 :c:func:`spin_lock()`, which is slightly faster. The only exception
263 would be if a different hardware irq handler u 269 would be if a different hardware irq handler uses the same lock:
264 spin_lock_irq() will stop that from interrupti !! 270 :c:func:`spin_lock_irq()` will stop that from interrupting us.
265 271
266 This works perfectly for UP as well: the spin 272 This works perfectly for UP as well: the spin lock vanishes, and this
267 macro simply becomes local_irq_disable() !! 273 macro simply becomes :c:func:`local_irq_disable()`
268 (``include/asm/smp.h``), which protects you fr 274 (``include/asm/smp.h``), which protects you from the softirq/tasklet/BH
269 being run. 275 being run.
270 276
271 spin_lock_irqsave() (``include/linux/spinlock. !! 277 :c:func:`spin_lock_irqsave()` (``include/linux/spinlock.h``) is a
272 variant which saves whether interrupts were on 278 variant which saves whether interrupts were on or off in a flags word,
273 which is passed to spin_unlock_irqrestore(). T !! 279 which is passed to :c:func:`spin_unlock_irqrestore()`. This means
274 that the same code can be used inside an hard 280 that the same code can be used inside an hard irq handler (where
275 interrupts are already off) and in softirqs (w 281 interrupts are already off) and in softirqs (where the irq disabling is
276 required). 282 required).
277 283
278 Note that softirqs (and hence tasklets and tim 284 Note that softirqs (and hence tasklets and timers) are run on return
279 from hardware interrupts, so spin_lock_irq() a !! 285 from hardware interrupts, so :c:func:`spin_lock_irq()` also stops
280 these. In that sense, spin_lock_irqsave() is t !! 286 these. In that sense, :c:func:`spin_lock_irqsave()` is the most
281 general and powerful locking function. 287 general and powerful locking function.
282 288
283 Locking Between Two Hard IRQ Handlers 289 Locking Between Two Hard IRQ Handlers
284 ------------------------------------- 290 -------------------------------------
285 291
286 It is rare to have to share data between two I 292 It is rare to have to share data between two IRQ handlers, but if you
287 do, spin_lock_irqsave() should be used: it is !! 293 do, :c:func:`spin_lock_irqsave()` should be used: it is
288 architecture-specific whether all interrupts a 294 architecture-specific whether all interrupts are disabled inside irq
289 handlers themselves. 295 handlers themselves.
290 296
291 Cheat Sheet For Locking 297 Cheat Sheet For Locking
292 ======================= 298 =======================
293 299
294 Pete Zaitcev gives the following summary: 300 Pete Zaitcev gives the following summary:
295 301
296 - If you are in a process context (any syscal 302 - If you are in a process context (any syscall) and want to lock other
297 process out, use a mutex. You can take a mu 303 process out, use a mutex. You can take a mutex and sleep
298 (``copy_from_user()`` or ``kmalloc(x,GFP_KE !! 304 (``copy_from_user*(`` or ``kmalloc(x,GFP_KERNEL)``).
299 305
300 - Otherwise (== data can be touched in an int 306 - Otherwise (== data can be touched in an interrupt), use
301 spin_lock_irqsave() and !! 307 :c:func:`spin_lock_irqsave()` and
302 spin_unlock_irqrestore(). !! 308 :c:func:`spin_unlock_irqrestore()`.
303 309
304 - Avoid holding spinlock for more than 5 line 310 - Avoid holding spinlock for more than 5 lines of code and across any
305 function call (except accessors like readb( !! 311 function call (except accessors like :c:func:`readb()`).
306 312
307 Table of Minimum Requirements 313 Table of Minimum Requirements
308 ----------------------------- 314 -----------------------------
309 315
310 The following table lists the **minimum** lock 316 The following table lists the **minimum** locking requirements between
311 various contexts. In some cases, the same cont 317 various contexts. In some cases, the same context can only be running on
312 one CPU at a time, so no locking is required f 318 one CPU at a time, so no locking is required for that context (eg. a
313 particular thread can only run on one CPU at a 319 particular thread can only run on one CPU at a time, but if it needs
314 shares data with another thread, locking is re 320 shares data with another thread, locking is required).
315 321
316 Remember the advice above: you can always use 322 Remember the advice above: you can always use
317 spin_lock_irqsave(), which is a superset of al !! 323 :c:func:`spin_lock_irqsave()`, which is a superset of all other
318 spinlock primitives. 324 spinlock primitives.
319 325
320 ============== ============= ============= === 326 ============== ============= ============= ========= ========= ========= ========= ======= ======= ============== ==============
321 . IRQ Handler A IRQ Handler B Sof 327 . IRQ Handler A IRQ Handler B Softirq A Softirq B Tasklet A Tasklet B Timer A Timer B User Context A User Context B
322 ============== ============= ============= === 328 ============== ============= ============= ========= ========= ========= ========= ======= ======= ============== ==============
323 IRQ Handler A None 329 IRQ Handler A None
324 IRQ Handler B SLIS None 330 IRQ Handler B SLIS None
325 Softirq A SLI SLI SL 331 Softirq A SLI SLI SL
326 Softirq B SLI SLI SL 332 Softirq B SLI SLI SL SL
327 Tasklet A SLI SLI SL 333 Tasklet A SLI SLI SL SL None
328 Tasklet B SLI SLI SL 334 Tasklet B SLI SLI SL SL SL None
329 Timer A SLI SLI SL 335 Timer A SLI SLI SL SL SL SL None
330 Timer B SLI SLI SL 336 Timer B SLI SLI SL SL SL SL SL None
331 User Context A SLI SLI SLB 337 User Context A SLI SLI SLBH SLBH SLBH SLBH SLBH SLBH None
332 User Context B SLI SLI SLB 338 User Context B SLI SLI SLBH SLBH SLBH SLBH SLBH SLBH MLI None
333 ============== ============= ============= === 339 ============== ============= ============= ========= ========= ========= ========= ======= ======= ============== ==============
334 340
335 Table: Table of Locking Requirements 341 Table: Table of Locking Requirements
336 342
337 +--------+----------------------------+ 343 +--------+----------------------------+
338 | SLIS | spin_lock_irqsave | 344 | SLIS | spin_lock_irqsave |
339 +--------+----------------------------+ 345 +--------+----------------------------+
340 | SLI | spin_lock_irq | 346 | SLI | spin_lock_irq |
341 +--------+----------------------------+ 347 +--------+----------------------------+
342 | SL | spin_lock | 348 | SL | spin_lock |
343 +--------+----------------------------+ 349 +--------+----------------------------+
344 | SLBH | spin_lock_bh | 350 | SLBH | spin_lock_bh |
345 +--------+----------------------------+ 351 +--------+----------------------------+
346 | MLI | mutex_lock_interruptible | 352 | MLI | mutex_lock_interruptible |
347 +--------+----------------------------+ 353 +--------+----------------------------+
348 354
349 Table: Legend for Locking Requirements Table 355 Table: Legend for Locking Requirements Table
350 356
351 The trylock Functions 357 The trylock Functions
352 ===================== 358 =====================
353 359
354 There are functions that try to acquire a lock 360 There are functions that try to acquire a lock only once and immediately
355 return a value telling about success or failur 361 return a value telling about success or failure to acquire the lock.
356 They can be used if you need no access to the 362 They can be used if you need no access to the data protected with the
357 lock when some other thread is holding the loc 363 lock when some other thread is holding the lock. You should acquire the
358 lock later if you then need access to the data 364 lock later if you then need access to the data protected with the lock.
359 365
360 spin_trylock() does not spin but returns non-z !! 366 :c:func:`spin_trylock()` does not spin but returns non-zero if it
361 acquires the spinlock on the first try or 0 if 367 acquires the spinlock on the first try or 0 if not. This function can be
362 used in all contexts like spin_lock(): you mus !! 368 used in all contexts like :c:func:`spin_lock()`: you must have
363 disabled the contexts that might interrupt you 369 disabled the contexts that might interrupt you and acquire the spin
364 lock. 370 lock.
365 371
366 mutex_trylock() does not suspend your task but !! 372 :c:func:`mutex_trylock()` does not suspend your task but returns
367 non-zero if it could lock the mutex on the fir 373 non-zero if it could lock the mutex on the first try or 0 if not. This
368 function cannot be safely used in hardware or 374 function cannot be safely used in hardware or software interrupt
369 contexts despite not sleeping. 375 contexts despite not sleeping.
370 376
371 Common Examples 377 Common Examples
372 =============== 378 ===============
373 379
374 Let's step through a simple example: a cache o 380 Let's step through a simple example: a cache of number to name mappings.
375 The cache keeps a count of how often each of t 381 The cache keeps a count of how often each of the objects is used, and
376 when it gets full, throws out the least used o 382 when it gets full, throws out the least used one.
377 383
378 All In User Context 384 All In User Context
379 ------------------- 385 -------------------
380 386
381 For our first example, we assume that all oper 387 For our first example, we assume that all operations are in user context
382 (ie. from system calls), so we can sleep. This 388 (ie. from system calls), so we can sleep. This means we can use a mutex
383 to protect the cache and all the objects withi 389 to protect the cache and all the objects within it. Here's the code::
384 390
385 #include <linux/list.h> 391 #include <linux/list.h>
386 #include <linux/slab.h> 392 #include <linux/slab.h>
387 #include <linux/string.h> 393 #include <linux/string.h>
388 #include <linux/mutex.h> 394 #include <linux/mutex.h>
389 #include <asm/errno.h> 395 #include <asm/errno.h>
390 396
391 struct object 397 struct object
392 { 398 {
393 struct list_head list; 399 struct list_head list;
394 int id; 400 int id;
395 char name[32]; 401 char name[32];
396 int popularity; 402 int popularity;
397 }; 403 };
398 404
399 /* Protects the cache, cache_num, and the 405 /* Protects the cache, cache_num, and the objects within it */
400 static DEFINE_MUTEX(cache_lock); 406 static DEFINE_MUTEX(cache_lock);
401 static LIST_HEAD(cache); 407 static LIST_HEAD(cache);
402 static unsigned int cache_num = 0; 408 static unsigned int cache_num = 0;
403 #define MAX_CACHE_SIZE 10 409 #define MAX_CACHE_SIZE 10
404 410
405 /* Must be holding cache_lock */ 411 /* Must be holding cache_lock */
406 static struct object *__cache_find(int id) 412 static struct object *__cache_find(int id)
407 { 413 {
408 struct object *i; 414 struct object *i;
409 415
410 list_for_each_entry(i, &cache, lis 416 list_for_each_entry(i, &cache, list)
411 if (i->id == id) { 417 if (i->id == id) {
412 i->popularity++; 418 i->popularity++;
413 return i; 419 return i;
414 } 420 }
415 return NULL; 421 return NULL;
416 } 422 }
417 423
418 /* Must be holding cache_lock */ 424 /* Must be holding cache_lock */
419 static void __cache_delete(struct object * 425 static void __cache_delete(struct object *obj)
420 { 426 {
421 BUG_ON(!obj); 427 BUG_ON(!obj);
422 list_del(&obj->list); 428 list_del(&obj->list);
423 kfree(obj); 429 kfree(obj);
424 cache_num--; 430 cache_num--;
425 } 431 }
426 432
427 /* Must be holding cache_lock */ 433 /* Must be holding cache_lock */
428 static void __cache_add(struct object *obj 434 static void __cache_add(struct object *obj)
429 { 435 {
430 list_add(&obj->list, &cache); 436 list_add(&obj->list, &cache);
431 if (++cache_num > MAX_CACHE_SIZE) 437 if (++cache_num > MAX_CACHE_SIZE) {
432 struct object *i, *outcast 438 struct object *i, *outcast = NULL;
433 list_for_each_entry(i, &ca 439 list_for_each_entry(i, &cache, list) {
434 if (!outcast || i- 440 if (!outcast || i->popularity < outcast->popularity)
435 outcast = 441 outcast = i;
436 } 442 }
437 __cache_delete(outcast); 443 __cache_delete(outcast);
438 } 444 }
439 } 445 }
440 446
441 int cache_add(int id, const char *name) 447 int cache_add(int id, const char *name)
442 { 448 {
443 struct object *obj; 449 struct object *obj;
444 450
445 if ((obj = kmalloc(sizeof(*obj), G 451 if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
446 return -ENOMEM; 452 return -ENOMEM;
447 453
448 strscpy(obj->name, name, sizeof(ob 454 strscpy(obj->name, name, sizeof(obj->name));
449 obj->id = id; 455 obj->id = id;
450 obj->popularity = 0; 456 obj->popularity = 0;
451 457
452 mutex_lock(&cache_lock); 458 mutex_lock(&cache_lock);
453 __cache_add(obj); 459 __cache_add(obj);
454 mutex_unlock(&cache_lock); 460 mutex_unlock(&cache_lock);
455 return 0; 461 return 0;
456 } 462 }
457 463
458 void cache_delete(int id) 464 void cache_delete(int id)
459 { 465 {
460 mutex_lock(&cache_lock); 466 mutex_lock(&cache_lock);
461 __cache_delete(__cache_find(id)); 467 __cache_delete(__cache_find(id));
462 mutex_unlock(&cache_lock); 468 mutex_unlock(&cache_lock);
463 } 469 }
464 470
465 int cache_find(int id, char *name) 471 int cache_find(int id, char *name)
466 { 472 {
467 struct object *obj; 473 struct object *obj;
468 int ret = -ENOENT; 474 int ret = -ENOENT;
469 475
470 mutex_lock(&cache_lock); 476 mutex_lock(&cache_lock);
471 obj = __cache_find(id); 477 obj = __cache_find(id);
472 if (obj) { 478 if (obj) {
473 ret = 0; 479 ret = 0;
474 strcpy(name, obj->name); 480 strcpy(name, obj->name);
475 } 481 }
476 mutex_unlock(&cache_lock); 482 mutex_unlock(&cache_lock);
477 return ret; 483 return ret;
478 } 484 }
479 485
480 Note that we always make sure we have the cach 486 Note that we always make sure we have the cache_lock when we add,
481 delete, or look up the cache: both the cache i 487 delete, or look up the cache: both the cache infrastructure itself and
482 the contents of the objects are protected by t 488 the contents of the objects are protected by the lock. In this case it's
483 easy, since we copy the data for the user, and 489 easy, since we copy the data for the user, and never let them access the
484 objects directly. 490 objects directly.
485 491
486 There is a slight (and common) optimization he 492 There is a slight (and common) optimization here: in
487 cache_add() we set up the fields of the object !! 493 :c:func:`cache_add()` we set up the fields of the object before
488 grabbing the lock. This is safe, as no-one els 494 grabbing the lock. This is safe, as no-one else can access it until we
489 put it in cache. 495 put it in cache.
490 496
491 Accessing From Interrupt Context 497 Accessing From Interrupt Context
492 -------------------------------- 498 --------------------------------
493 499
494 Now consider the case where cache_find() can b !! 500 Now consider the case where :c:func:`cache_find()` can be called
495 from interrupt context: either a hardware inte 501 from interrupt context: either a hardware interrupt or a softirq. An
496 example would be a timer which deletes object 502 example would be a timer which deletes object from the cache.
497 503
498 The change is shown below, in standard patch f 504 The change is shown below, in standard patch format: the ``-`` are lines
499 which are taken away, and the ``+`` are lines 505 which are taken away, and the ``+`` are lines which are added.
500 506
501 :: 507 ::
502 508
503 --- cache.c.usercontext 2003-12-09 13:58:5 509 --- cache.c.usercontext 2003-12-09 13:58:54.000000000 +1100
504 +++ cache.c.interrupt 2003-12-09 14:07:4 510 +++ cache.c.interrupt 2003-12-09 14:07:49.000000000 +1100
505 @@ -12,7 +12,7 @@ 511 @@ -12,7 +12,7 @@
506 int popularity; 512 int popularity;
507 }; 513 };
508 514
509 -static DEFINE_MUTEX(cache_lock); 515 -static DEFINE_MUTEX(cache_lock);
510 +static DEFINE_SPINLOCK(cache_lock); 516 +static DEFINE_SPINLOCK(cache_lock);
511 static LIST_HEAD(cache); 517 static LIST_HEAD(cache);
512 static unsigned int cache_num = 0; 518 static unsigned int cache_num = 0;
513 #define MAX_CACHE_SIZE 10 519 #define MAX_CACHE_SIZE 10
514 @@ -55,6 +55,7 @@ 520 @@ -55,6 +55,7 @@
515 int cache_add(int id, const char *name) 521 int cache_add(int id, const char *name)
516 { 522 {
517 struct object *obj; 523 struct object *obj;
518 + unsigned long flags; 524 + unsigned long flags;
519 525
520 if ((obj = kmalloc(sizeof(*obj), 526 if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
521 return -ENOMEM; 527 return -ENOMEM;
522 @@ -63,30 +64,33 @@ 528 @@ -63,30 +64,33 @@
523 obj->id = id; 529 obj->id = id;
524 obj->popularity = 0; 530 obj->popularity = 0;
525 531
526 - mutex_lock(&cache_lock); 532 - mutex_lock(&cache_lock);
527 + spin_lock_irqsave(&cache_lock, fl 533 + spin_lock_irqsave(&cache_lock, flags);
528 __cache_add(obj); 534 __cache_add(obj);
529 - mutex_unlock(&cache_lock); 535 - mutex_unlock(&cache_lock);
530 + spin_unlock_irqrestore(&cache_loc 536 + spin_unlock_irqrestore(&cache_lock, flags);
531 return 0; 537 return 0;
532 } 538 }
533 539
534 void cache_delete(int id) 540 void cache_delete(int id)
535 { 541 {
536 - mutex_lock(&cache_lock); 542 - mutex_lock(&cache_lock);
537 + unsigned long flags; 543 + unsigned long flags;
538 + 544 +
539 + spin_lock_irqsave(&cache_lock, fl 545 + spin_lock_irqsave(&cache_lock, flags);
540 __cache_delete(__cache_find(id)); 546 __cache_delete(__cache_find(id));
541 - mutex_unlock(&cache_lock); 547 - mutex_unlock(&cache_lock);
542 + spin_unlock_irqrestore(&cache_loc 548 + spin_unlock_irqrestore(&cache_lock, flags);
543 } 549 }
544 550
545 int cache_find(int id, char *name) 551 int cache_find(int id, char *name)
546 { 552 {
547 struct object *obj; 553 struct object *obj;
548 int ret = -ENOENT; 554 int ret = -ENOENT;
549 + unsigned long flags; 555 + unsigned long flags;
550 556
551 - mutex_lock(&cache_lock); 557 - mutex_lock(&cache_lock);
552 + spin_lock_irqsave(&cache_lock, fl 558 + spin_lock_irqsave(&cache_lock, flags);
553 obj = __cache_find(id); 559 obj = __cache_find(id);
554 if (obj) { 560 if (obj) {
555 ret = 0; 561 ret = 0;
556 strcpy(name, obj->name); 562 strcpy(name, obj->name);
557 } 563 }
558 - mutex_unlock(&cache_lock); 564 - mutex_unlock(&cache_lock);
559 + spin_unlock_irqrestore(&cache_loc 565 + spin_unlock_irqrestore(&cache_lock, flags);
560 return ret; 566 return ret;
561 } 567 }
562 568
563 Note that the spin_lock_irqsave() will turn of !! 569 Note that the :c:func:`spin_lock_irqsave()` will turn off
564 interrupts if they are on, otherwise does noth 570 interrupts if they are on, otherwise does nothing (if we are already in
565 an interrupt handler), hence these functions a 571 an interrupt handler), hence these functions are safe to call from any
566 context. 572 context.
567 573
568 Unfortunately, cache_add() calls kmalloc() !! 574 Unfortunately, :c:func:`cache_add()` calls :c:func:`kmalloc()`
569 with the ``GFP_KERNEL`` flag, which is only le 575 with the ``GFP_KERNEL`` flag, which is only legal in user context. I
570 have assumed that cache_add() is still only ca !! 576 have assumed that :c:func:`cache_add()` is still only called in
571 user context, otherwise this should become a p 577 user context, otherwise this should become a parameter to
572 cache_add(). !! 578 :c:func:`cache_add()`.
573 579
574 Exposing Objects Outside This File 580 Exposing Objects Outside This File
575 ---------------------------------- 581 ----------------------------------
576 582
577 If our objects contained more information, it 583 If our objects contained more information, it might not be sufficient to
578 copy the information in and out: other parts o 584 copy the information in and out: other parts of the code might want to
579 keep pointers to these objects, for example, r 585 keep pointers to these objects, for example, rather than looking up the
580 id every time. This produces two problems. 586 id every time. This produces two problems.
581 587
582 The first problem is that we use the ``cache_l 588 The first problem is that we use the ``cache_lock`` to protect objects:
583 we'd need to make this non-static so the rest 589 we'd need to make this non-static so the rest of the code can use it.
584 This makes locking trickier, as it is no longe 590 This makes locking trickier, as it is no longer all in one place.
585 591
586 The second problem is the lifetime problem: if 592 The second problem is the lifetime problem: if another structure keeps a
587 pointer to an object, it presumably expects th 593 pointer to an object, it presumably expects that pointer to remain
588 valid. Unfortunately, this is only guaranteed 594 valid. Unfortunately, this is only guaranteed while you hold the lock,
589 otherwise someone might call cache_delete() an !! 595 otherwise someone might call :c:func:`cache_delete()` and even
590 worse, add another object, re-using the same a 596 worse, add another object, re-using the same address.
591 597
592 As there is only one lock, you can't hold it f 598 As there is only one lock, you can't hold it forever: no-one else would
593 get any work done. 599 get any work done.
594 600
595 The solution to this problem is to use a refer 601 The solution to this problem is to use a reference count: everyone who
596 has a pointer to the object increases it when 602 has a pointer to the object increases it when they first get the object,
597 and drops the reference count when they're fin 603 and drops the reference count when they're finished with it. Whoever
598 drops it to zero knows it is unused, and can a 604 drops it to zero knows it is unused, and can actually delete it.
599 605
600 Here is the code:: 606 Here is the code::
601 607
602 --- cache.c.interrupt 2003-12-09 14:25:4 608 --- cache.c.interrupt 2003-12-09 14:25:43.000000000 +1100
603 +++ cache.c.refcnt 2003-12-09 14:33:05.00 609 +++ cache.c.refcnt 2003-12-09 14:33:05.000000000 +1100
604 @@ -7,6 +7,7 @@ 610 @@ -7,6 +7,7 @@
605 struct object 611 struct object
606 { 612 {
607 struct list_head list; 613 struct list_head list;
608 + unsigned int refcnt; 614 + unsigned int refcnt;
609 int id; 615 int id;
610 char name[32]; 616 char name[32];
611 int popularity; 617 int popularity;
612 @@ -17,6 +18,35 @@ 618 @@ -17,6 +18,35 @@
613 static unsigned int cache_num = 0; 619 static unsigned int cache_num = 0;
614 #define MAX_CACHE_SIZE 10 620 #define MAX_CACHE_SIZE 10
615 621
616 +static void __object_put(struct object *o 622 +static void __object_put(struct object *obj)
617 +{ 623 +{
618 + if (--obj->refcnt == 0) 624 + if (--obj->refcnt == 0)
619 + kfree(obj); 625 + kfree(obj);
620 +} 626 +}
621 + 627 +
622 +static void __object_get(struct object *o 628 +static void __object_get(struct object *obj)
623 +{ 629 +{
624 + obj->refcnt++; 630 + obj->refcnt++;
625 +} 631 +}
626 + 632 +
627 +void object_put(struct object *obj) 633 +void object_put(struct object *obj)
628 +{ 634 +{
629 + unsigned long flags; 635 + unsigned long flags;
630 + 636 +
631 + spin_lock_irqsave(&cache_lock, fl 637 + spin_lock_irqsave(&cache_lock, flags);
632 + __object_put(obj); 638 + __object_put(obj);
633 + spin_unlock_irqrestore(&cache_loc 639 + spin_unlock_irqrestore(&cache_lock, flags);
634 +} 640 +}
635 + 641 +
636 +void object_get(struct object *obj) 642 +void object_get(struct object *obj)
637 +{ 643 +{
638 + unsigned long flags; 644 + unsigned long flags;
639 + 645 +
640 + spin_lock_irqsave(&cache_lock, fl 646 + spin_lock_irqsave(&cache_lock, flags);
641 + __object_get(obj); 647 + __object_get(obj);
642 + spin_unlock_irqrestore(&cache_loc 648 + spin_unlock_irqrestore(&cache_lock, flags);
643 +} 649 +}
644 + 650 +
645 /* Must be holding cache_lock */ 651 /* Must be holding cache_lock */
646 static struct object *__cache_find(int id 652 static struct object *__cache_find(int id)
647 { 653 {
648 @@ -35,6 +65,7 @@ 654 @@ -35,6 +65,7 @@
649 { 655 {
650 BUG_ON(!obj); 656 BUG_ON(!obj);
651 list_del(&obj->list); 657 list_del(&obj->list);
652 + __object_put(obj); 658 + __object_put(obj);
653 cache_num--; 659 cache_num--;
654 } 660 }
655 661
656 @@ -63,6 +94,7 @@ 662 @@ -63,6 +94,7 @@
657 strscpy(obj->name, name, sizeof(o 663 strscpy(obj->name, name, sizeof(obj->name));
658 obj->id = id; 664 obj->id = id;
659 obj->popularity = 0; 665 obj->popularity = 0;
660 + obj->refcnt = 1; /* The cache hol 666 + obj->refcnt = 1; /* The cache holds a reference */
661 667
662 spin_lock_irqsave(&cache_lock, fl 668 spin_lock_irqsave(&cache_lock, flags);
663 __cache_add(obj); 669 __cache_add(obj);
664 @@ -79,18 +111,15 @@ 670 @@ -79,18 +111,15 @@
665 spin_unlock_irqrestore(&cache_loc 671 spin_unlock_irqrestore(&cache_lock, flags);
666 } 672 }
667 673
668 -int cache_find(int id, char *name) 674 -int cache_find(int id, char *name)
669 +struct object *cache_find(int id) 675 +struct object *cache_find(int id)
670 { 676 {
671 struct object *obj; 677 struct object *obj;
672 - int ret = -ENOENT; 678 - int ret = -ENOENT;
673 unsigned long flags; 679 unsigned long flags;
674 680
675 spin_lock_irqsave(&cache_lock, fl 681 spin_lock_irqsave(&cache_lock, flags);
676 obj = __cache_find(id); 682 obj = __cache_find(id);
677 - if (obj) { 683 - if (obj) {
678 - ret = 0; 684 - ret = 0;
679 - strcpy(name, obj->name); 685 - strcpy(name, obj->name);
680 - } 686 - }
681 + if (obj) 687 + if (obj)
682 + __object_get(obj); 688 + __object_get(obj);
683 spin_unlock_irqrestore(&cache_loc 689 spin_unlock_irqrestore(&cache_lock, flags);
684 - return ret; 690 - return ret;
685 + return obj; 691 + return obj;
686 } 692 }
687 693
688 We encapsulate the reference counting in the s 694 We encapsulate the reference counting in the standard 'get' and 'put'
689 functions. Now we can return the object itself 695 functions. Now we can return the object itself from
690 cache_find() which has the advantage that the !! 696 :c:func:`cache_find()` which has the advantage that the user can
691 now sleep holding the object (eg. to copy_to_u !! 697 now sleep holding the object (eg. to :c:func:`copy_to_user()` to
692 name to userspace). 698 name to userspace).
693 699
694 The other point to note is that I said a refer 700 The other point to note is that I said a reference should be held for
695 every pointer to the object: thus the referenc 701 every pointer to the object: thus the reference count is 1 when first
696 inserted into the cache. In some versions the 702 inserted into the cache. In some versions the framework does not hold a
697 reference count, but they are more complicated 703 reference count, but they are more complicated.
698 704
699 Using Atomic Operations For The Reference Coun 705 Using Atomic Operations For The Reference Count
700 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 706 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
701 707
702 In practice, :c:type:`atomic_t` would usually 708 In practice, :c:type:`atomic_t` would usually be used for refcnt. There are a
703 number of atomic operations defined in ``inclu 709 number of atomic operations defined in ``include/asm/atomic.h``: these
704 are guaranteed to be seen atomically from all 710 are guaranteed to be seen atomically from all CPUs in the system, so no
705 lock is required. In this case, it is simpler 711 lock is required. In this case, it is simpler than using spinlocks,
706 although for anything non-trivial using spinlo 712 although for anything non-trivial using spinlocks is clearer. The
707 atomic_inc() and atomic_dec_and_test() !! 713 :c:func:`atomic_inc()` and :c:func:`atomic_dec_and_test()`
708 are used instead of the standard increment and 714 are used instead of the standard increment and decrement operators, and
709 the lock is no longer used to protect the refe 715 the lock is no longer used to protect the reference count itself.
710 716
711 :: 717 ::
712 718
713 --- cache.c.refcnt 2003-12-09 15:00:35.00 719 --- cache.c.refcnt 2003-12-09 15:00:35.000000000 +1100
714 +++ cache.c.refcnt-atomic 2003-12-11 15: 720 +++ cache.c.refcnt-atomic 2003-12-11 15:49:42.000000000 +1100
715 @@ -7,7 +7,7 @@ 721 @@ -7,7 +7,7 @@
716 struct object 722 struct object
717 { 723 {
718 struct list_head list; 724 struct list_head list;
719 - unsigned int refcnt; 725 - unsigned int refcnt;
720 + atomic_t refcnt; 726 + atomic_t refcnt;
721 int id; 727 int id;
722 char name[32]; 728 char name[32];
723 int popularity; 729 int popularity;
724 @@ -18,33 +18,15 @@ 730 @@ -18,33 +18,15 @@
725 static unsigned int cache_num = 0; 731 static unsigned int cache_num = 0;
726 #define MAX_CACHE_SIZE 10 732 #define MAX_CACHE_SIZE 10
727 733
728 -static void __object_put(struct object *o 734 -static void __object_put(struct object *obj)
729 -{ 735 -{
730 - if (--obj->refcnt == 0) 736 - if (--obj->refcnt == 0)
731 - kfree(obj); 737 - kfree(obj);
732 -} 738 -}
733 - 739 -
734 -static void __object_get(struct object *o 740 -static void __object_get(struct object *obj)
735 -{ 741 -{
736 - obj->refcnt++; 742 - obj->refcnt++;
737 -} 743 -}
738 - 744 -
739 void object_put(struct object *obj) 745 void object_put(struct object *obj)
740 { 746 {
741 - unsigned long flags; 747 - unsigned long flags;
742 - 748 -
743 - spin_lock_irqsave(&cache_lock, fl 749 - spin_lock_irqsave(&cache_lock, flags);
744 - __object_put(obj); 750 - __object_put(obj);
745 - spin_unlock_irqrestore(&cache_loc 751 - spin_unlock_irqrestore(&cache_lock, flags);
746 + if (atomic_dec_and_test(&obj->ref 752 + if (atomic_dec_and_test(&obj->refcnt))
747 + kfree(obj); 753 + kfree(obj);
748 } 754 }
749 755
750 void object_get(struct object *obj) 756 void object_get(struct object *obj)
751 { 757 {
752 - unsigned long flags; 758 - unsigned long flags;
753 - 759 -
754 - spin_lock_irqsave(&cache_lock, fl 760 - spin_lock_irqsave(&cache_lock, flags);
755 - __object_get(obj); 761 - __object_get(obj);
756 - spin_unlock_irqrestore(&cache_loc 762 - spin_unlock_irqrestore(&cache_lock, flags);
757 + atomic_inc(&obj->refcnt); 763 + atomic_inc(&obj->refcnt);
758 } 764 }
759 765
760 /* Must be holding cache_lock */ 766 /* Must be holding cache_lock */
761 @@ -65,7 +47,7 @@ 767 @@ -65,7 +47,7 @@
762 { 768 {
763 BUG_ON(!obj); 769 BUG_ON(!obj);
764 list_del(&obj->list); 770 list_del(&obj->list);
765 - __object_put(obj); 771 - __object_put(obj);
766 + object_put(obj); 772 + object_put(obj);
767 cache_num--; 773 cache_num--;
768 } 774 }
769 775
770 @@ -94,7 +76,7 @@ 776 @@ -94,7 +76,7 @@
771 strscpy(obj->name, name, sizeof(o 777 strscpy(obj->name, name, sizeof(obj->name));
772 obj->id = id; 778 obj->id = id;
773 obj->popularity = 0; 779 obj->popularity = 0;
774 - obj->refcnt = 1; /* The cache hol 780 - obj->refcnt = 1; /* The cache holds a reference */
775 + atomic_set(&obj->refcnt, 1); /* T 781 + atomic_set(&obj->refcnt, 1); /* The cache holds a reference */
776 782
777 spin_lock_irqsave(&cache_lock, fl 783 spin_lock_irqsave(&cache_lock, flags);
778 __cache_add(obj); 784 __cache_add(obj);
779 @@ -119,7 +101,7 @@ 785 @@ -119,7 +101,7 @@
780 spin_lock_irqsave(&cache_lock, fl 786 spin_lock_irqsave(&cache_lock, flags);
781 obj = __cache_find(id); 787 obj = __cache_find(id);
782 if (obj) 788 if (obj)
783 - __object_get(obj); 789 - __object_get(obj);
784 + object_get(obj); 790 + object_get(obj);
785 spin_unlock_irqrestore(&cache_loc 791 spin_unlock_irqrestore(&cache_lock, flags);
786 return obj; 792 return obj;
787 } 793 }
788 794
789 Protecting The Objects Themselves 795 Protecting The Objects Themselves
790 --------------------------------- 796 ---------------------------------
791 797
792 In these examples, we assumed that the objects 798 In these examples, we assumed that the objects (except the reference
793 counts) never changed once they are created. I 799 counts) never changed once they are created. If we wanted to allow the
794 name to change, there are three possibilities: 800 name to change, there are three possibilities:
795 801
796 - You can make ``cache_lock`` non-static, and 802 - You can make ``cache_lock`` non-static, and tell people to grab that
797 lock before changing the name in any object 803 lock before changing the name in any object.
798 804
799 - You can provide a cache_obj_rename() which !! 805 - You can provide a :c:func:`cache_obj_rename()` which grabs this
800 lock and changes the name for the caller, a 806 lock and changes the name for the caller, and tell everyone to use
801 that function. 807 that function.
802 808
803 - You can make the ``cache_lock`` protect onl 809 - You can make the ``cache_lock`` protect only the cache itself, and
804 use another lock to protect the name. 810 use another lock to protect the name.
805 811
806 Theoretically, you can make the locks as fine- 812 Theoretically, you can make the locks as fine-grained as one lock for
807 every field, for every object. In practice, th 813 every field, for every object. In practice, the most common variants
808 are: 814 are:
809 815
810 - One lock which protects the infrastructure 816 - One lock which protects the infrastructure (the ``cache`` list in
811 this example) and all the objects. This is 817 this example) and all the objects. This is what we have done so far.
812 818
813 - One lock which protects the infrastructure 819 - One lock which protects the infrastructure (including the list
814 pointers inside the objects), and one lock 820 pointers inside the objects), and one lock inside the object which
815 protects the rest of that object. 821 protects the rest of that object.
816 822
817 - Multiple locks to protect the infrastructur 823 - Multiple locks to protect the infrastructure (eg. one lock per hash
818 chain), possibly with a separate per-object 824 chain), possibly with a separate per-object lock.
819 825
820 Here is the "lock-per-object" implementation: 826 Here is the "lock-per-object" implementation:
821 827
822 :: 828 ::
823 829
824 --- cache.c.refcnt-atomic 2003-12-11 15: 830 --- cache.c.refcnt-atomic 2003-12-11 15:50:54.000000000 +1100
825 +++ cache.c.perobjectlock 2003-12-11 17: 831 +++ cache.c.perobjectlock 2003-12-11 17:15:03.000000000 +1100
826 @@ -6,11 +6,17 @@ 832 @@ -6,11 +6,17 @@
827 833
828 struct object 834 struct object
829 { 835 {
830 + /* These two protected by cache_l 836 + /* These two protected by cache_lock. */
831 struct list_head list; 837 struct list_head list;
832 + int popularity; 838 + int popularity;
833 + 839 +
834 atomic_t refcnt; 840 atomic_t refcnt;
835 + 841 +
836 + /* Doesn't change once created. * 842 + /* Doesn't change once created. */
837 int id; 843 int id;
838 + 844 +
839 + spinlock_t lock; /* Protects the 845 + spinlock_t lock; /* Protects the name */
840 char name[32]; 846 char name[32];
841 - int popularity; 847 - int popularity;
842 }; 848 };
843 849
844 static DEFINE_SPINLOCK(cache_lock); 850 static DEFINE_SPINLOCK(cache_lock);
845 @@ -77,6 +84,7 @@ 851 @@ -77,6 +84,7 @@
846 obj->id = id; 852 obj->id = id;
847 obj->popularity = 0; 853 obj->popularity = 0;
848 atomic_set(&obj->refcnt, 1); /* T 854 atomic_set(&obj->refcnt, 1); /* The cache holds a reference */
849 + spin_lock_init(&obj->lock); 855 + spin_lock_init(&obj->lock);
850 856
851 spin_lock_irqsave(&cache_lock, fl 857 spin_lock_irqsave(&cache_lock, flags);
852 __cache_add(obj); 858 __cache_add(obj);
853 859
854 Note that I decide that the popularity count s 860 Note that I decide that the popularity count should be protected by the
855 ``cache_lock`` rather than the per-object lock 861 ``cache_lock`` rather than the per-object lock: this is because it (like
856 the :c:type:`struct list_head <list_head>` ins 862 the :c:type:`struct list_head <list_head>` inside the object)
857 is logically part of the infrastructure. This 863 is logically part of the infrastructure. This way, I don't need to grab
858 the lock of every object in __cache_add() when !! 864 the lock of every object in :c:func:`__cache_add()` when seeking
859 the least popular. 865 the least popular.
860 866
861 I also decided that the id member is unchangea 867 I also decided that the id member is unchangeable, so I don't need to
862 grab each object lock in __cache_find() to exa !! 868 grab each object lock in :c:func:`__cache_find()` to examine the
863 id: the object lock is only used by a caller w 869 id: the object lock is only used by a caller who wants to read or write
864 the name field. 870 the name field.
865 871
866 Note also that I added a comment describing wh 872 Note also that I added a comment describing what data was protected by
867 which locks. This is extremely important, as i 873 which locks. This is extremely important, as it describes the runtime
868 behavior of the code, and can be hard to gain 874 behavior of the code, and can be hard to gain from just reading. And as
869 Alan Cox says, “Lock data, not code”. 875 Alan Cox says, “Lock data, not code”.
870 876
871 Common Problems 877 Common Problems
872 =============== 878 ===============
873 879
874 Deadlock: Simple and Advanced 880 Deadlock: Simple and Advanced
875 ----------------------------- 881 -----------------------------
876 882
877 There is a coding bug where a piece of code tr 883 There is a coding bug where a piece of code tries to grab a spinlock
878 twice: it will spin forever, waiting for the l 884 twice: it will spin forever, waiting for the lock to be released
879 (spinlocks, rwlocks and mutexes are not recurs 885 (spinlocks, rwlocks and mutexes are not recursive in Linux). This is
880 trivial to diagnose: not a 886 trivial to diagnose: not a
881 stay-up-five-nights-talk-to-fluffy-code-bunnie 887 stay-up-five-nights-talk-to-fluffy-code-bunnies kind of problem.
882 888
883 For a slightly more complex case, imagine you 889 For a slightly more complex case, imagine you have a region shared by a
884 softirq and user context. If you use a spin_lo !! 890 softirq and user context. If you use a :c:func:`spin_lock()` call
885 to protect it, it is possible that the user co 891 to protect it, it is possible that the user context will be interrupted
886 by the softirq while it holds the lock, and th 892 by the softirq while it holds the lock, and the softirq will then spin
887 forever trying to get the same lock. 893 forever trying to get the same lock.
888 894
889 Both of these are called deadlock, and as show 895 Both of these are called deadlock, and as shown above, it can occur even
890 with a single CPU (although not on UP compiles 896 with a single CPU (although not on UP compiles, since spinlocks vanish
891 on kernel compiles with ``CONFIG_SMP``\ =n. Yo 897 on kernel compiles with ``CONFIG_SMP``\ =n. You'll still get data
892 corruption in the second example). 898 corruption in the second example).
893 899
894 This complete lockup is easy to diagnose: on S 900 This complete lockup is easy to diagnose: on SMP boxes the watchdog
895 timer or compiling with ``DEBUG_SPINLOCK`` set 901 timer or compiling with ``DEBUG_SPINLOCK`` set
896 (``include/linux/spinlock.h``) will show this 902 (``include/linux/spinlock.h``) will show this up immediately when it
897 happens. 903 happens.
898 904
899 A more complex problem is the so-called 'deadl 905 A more complex problem is the so-called 'deadly embrace', involving two
900 or more locks. Say you have a hash table: each 906 or more locks. Say you have a hash table: each entry in the table is a
901 spinlock, and a chain of hashed objects. Insid 907 spinlock, and a chain of hashed objects. Inside a softirq handler, you
902 sometimes want to alter an object from one pla 908 sometimes want to alter an object from one place in the hash to another:
903 you grab the spinlock of the old hash chain an 909 you grab the spinlock of the old hash chain and the spinlock of the new
904 hash chain, and delete the object from the old 910 hash chain, and delete the object from the old one, and insert it in the
905 new one. 911 new one.
906 912
907 There are two problems here. First, if your co 913 There are two problems here. First, if your code ever tries to move the
908 object to the same chain, it will deadlock wit 914 object to the same chain, it will deadlock with itself as it tries to
909 lock it twice. Secondly, if the same softirq o 915 lock it twice. Secondly, if the same softirq on another CPU is trying to
910 move another object in the reverse direction, 916 move another object in the reverse direction, the following could
911 happen: 917 happen:
912 918
913 +-----------------------+--------------------- 919 +-----------------------+-----------------------+
914 | CPU 1 | CPU 2 920 | CPU 1 | CPU 2 |
915 +=======================+===================== 921 +=======================+=======================+
916 | Grab lock A -> OK | Grab lock B -> OK 922 | Grab lock A -> OK | Grab lock B -> OK |
917 +-----------------------+--------------------- 923 +-----------------------+-----------------------+
918 | Grab lock B -> spin | Grab lock A -> spin 924 | Grab lock B -> spin | Grab lock A -> spin |
919 +-----------------------+--------------------- 925 +-----------------------+-----------------------+
920 926
921 Table: Consequences 927 Table: Consequences
922 928
923 The two CPUs will spin forever, waiting for th 929 The two CPUs will spin forever, waiting for the other to give up their
924 lock. It will look, smell, and feel like a cra 930 lock. It will look, smell, and feel like a crash.
925 931
926 Preventing Deadlock 932 Preventing Deadlock
927 ------------------- 933 -------------------
928 934
929 Textbooks will tell you that if you always loc 935 Textbooks will tell you that if you always lock in the same order, you
930 will never get this kind of deadlock. Practice 936 will never get this kind of deadlock. Practice will tell you that this
931 approach doesn't scale: when I create a new lo 937 approach doesn't scale: when I create a new lock, I don't understand
932 enough of the kernel to figure out where in th 938 enough of the kernel to figure out where in the 5000 lock hierarchy it
933 will fit. 939 will fit.
934 940
935 The best locks are encapsulated: they never ge 941 The best locks are encapsulated: they never get exposed in headers, and
936 are never held around calls to non-trivial fun 942 are never held around calls to non-trivial functions outside the same
937 file. You can read through this code and see t 943 file. You can read through this code and see that it will never
938 deadlock, because it never tries to grab anoth 944 deadlock, because it never tries to grab another lock while it has that
939 one. People using your code don't even need to 945 one. People using your code don't even need to know you are using a
940 lock. 946 lock.
941 947
942 A classic problem here is when you provide cal 948 A classic problem here is when you provide callbacks or hooks: if you
943 call these with the lock held, you risk simple 949 call these with the lock held, you risk simple deadlock, or a deadly
944 embrace (who knows what the callback will do?) !! 950 embrace (who knows what the callback will do?). Remember, the other
>> 951 programmers are out to get you, so don't do this.
945 952
946 Overzealous Prevention Of Deadlocks 953 Overzealous Prevention Of Deadlocks
947 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 954 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
948 955
949 Deadlocks are problematic, but not as bad as d 956 Deadlocks are problematic, but not as bad as data corruption. Code which
950 grabs a read lock, searches a list, fails to f 957 grabs a read lock, searches a list, fails to find what it wants, drops
951 the read lock, grabs a write lock and inserts 958 the read lock, grabs a write lock and inserts the object has a race
952 condition. 959 condition.
953 960
>> 961 If you don't see why, please stay the fuck away from my code.
>> 962
954 Racing Timers: A Kernel Pastime 963 Racing Timers: A Kernel Pastime
955 ------------------------------- 964 -------------------------------
956 965
957 Timers can produce their own special problems 966 Timers can produce their own special problems with races. Consider a
958 collection of objects (list, hash, etc) where 967 collection of objects (list, hash, etc) where each object has a timer
959 which is due to destroy it. 968 which is due to destroy it.
960 969
961 If you want to destroy the entire collection ( 970 If you want to destroy the entire collection (say on module removal),
962 you might do the following:: 971 you might do the following::
963 972
964 /* THIS CODE BAD BAD BAD BAD: IF I 973 /* THIS CODE BAD BAD BAD BAD: IF IT WAS ANY WORSE IT WOULD USE
965 HUNGARIAN NOTATION */ 974 HUNGARIAN NOTATION */
966 spin_lock_bh(&list_lock); 975 spin_lock_bh(&list_lock);
967 976
968 while (list) { 977 while (list) {
969 struct foo *next = list->n 978 struct foo *next = list->next;
970 timer_delete(&list->timer) !! 979 del_timer(&list->timer);
971 kfree(list); 980 kfree(list);
972 list = next; 981 list = next;
973 } 982 }
974 983
975 spin_unlock_bh(&list_lock); 984 spin_unlock_bh(&list_lock);
976 985
977 986
978 Sooner or later, this will crash on SMP, becau 987 Sooner or later, this will crash on SMP, because a timer can have just
979 gone off before the spin_lock_bh(), and it wil !! 988 gone off before the :c:func:`spin_lock_bh()`, and it will only get
980 the lock after we spin_unlock_bh(), and then t !! 989 the lock after we :c:func:`spin_unlock_bh()`, and then try to free
981 the element (which has already been freed!). 990 the element (which has already been freed!).
982 991
983 This can be avoided by checking the result of 992 This can be avoided by checking the result of
984 timer_delete(): if it returns 1, the timer has !! 993 :c:func:`del_timer()`: if it returns 1, the timer has been deleted.
985 If 0, it means (in this case) that it is curre 994 If 0, it means (in this case) that it is currently running, so we can
986 do:: 995 do::
987 996
988 retry: 997 retry:
989 spin_lock_bh(&list_lock); 998 spin_lock_bh(&list_lock);
990 999
991 while (list) { 1000 while (list) {
992 struct foo *next = 1001 struct foo *next = list->next;
993 if (!timer_delete( !! 1002 if (!del_timer(&list->timer)) {
994 /* Give ti 1003 /* Give timer a chance to delete this */
995 spin_unloc 1004 spin_unlock_bh(&list_lock);
996 goto retry 1005 goto retry;
997 } 1006 }
998 kfree(list); 1007 kfree(list);
999 list = next; 1008 list = next;
1000 } 1009 }
1001 1010
1002 spin_unlock_bh(&list_lock 1011 spin_unlock_bh(&list_lock);
1003 1012
1004 1013
1005 Another common problem is deleting timers whi 1014 Another common problem is deleting timers which restart themselves (by
1006 calling add_timer() at the end of their timer !! 1015 calling :c:func:`add_timer()` at the end of their timer function).
1007 Because this is a fairly common case which is 1016 Because this is a fairly common case which is prone to races, you should
1008 use timer_delete_sync() (``include/linux/time !! 1017 use :c:func:`del_timer_sync()` (``include/linux/timer.h``) to
1009 !! 1018 handle this case. It returns the number of times the timer had to be
1010 Before freeing a timer, timer_shutdown() or t !! 1019 deleted before we finally stopped it from adding itself back in.
1011 called which will keep it from being rearmed. <<
1012 rearm the timer will be silently ignored by t <<
1013 <<
1014 1020
1015 Locking Speed 1021 Locking Speed
1016 ============= 1022 =============
1017 1023
1018 There are three main things to worry about wh 1024 There are three main things to worry about when considering speed of
1019 some code which does locking. First is concur 1025 some code which does locking. First is concurrency: how many things are
1020 going to be waiting while someone else is hol 1026 going to be waiting while someone else is holding a lock. Second is the
1021 time taken to actually acquire and release an 1027 time taken to actually acquire and release an uncontended lock. Third is
1022 using fewer, or smarter locks. I'm assuming t 1028 using fewer, or smarter locks. I'm assuming that the lock is used fairly
1023 often: otherwise, you wouldn't be concerned a 1029 often: otherwise, you wouldn't be concerned about efficiency.
1024 1030
1025 Concurrency depends on how long the lock is u 1031 Concurrency depends on how long the lock is usually held: you should
1026 hold the lock for as long as needed, but no l 1032 hold the lock for as long as needed, but no longer. In the cache
1027 example, we always create the object without 1033 example, we always create the object without the lock held, and then
1028 grab the lock only when we are ready to inser 1034 grab the lock only when we are ready to insert it in the list.
1029 1035
1030 Acquisition times depend on how much damage t 1036 Acquisition times depend on how much damage the lock operations do to
1031 the pipeline (pipeline stalls) and how likely 1037 the pipeline (pipeline stalls) and how likely it is that this CPU was
1032 the last one to grab the lock (ie. is the loc 1038 the last one to grab the lock (ie. is the lock cache-hot for this CPU):
1033 on a machine with more CPUs, this likelihood 1039 on a machine with more CPUs, this likelihood drops fast. Consider a
1034 700MHz Intel Pentium III: an instruction take 1040 700MHz Intel Pentium III: an instruction takes about 0.7ns, an atomic
1035 increment takes about 58ns, a lock which is c 1041 increment takes about 58ns, a lock which is cache-hot on this CPU takes
1036 160ns, and a cacheline transfer from another 1042 160ns, and a cacheline transfer from another CPU takes an additional 170
1037 to 360ns. (These figures from Paul McKenney's 1043 to 360ns. (These figures from Paul McKenney's `Linux Journal RCU
1038 article <http://www.linuxjournal.com/article. 1044 article <http://www.linuxjournal.com/article.php?sid=6993>`__).
1039 1045
1040 These two aims conflict: holding a lock for a 1046 These two aims conflict: holding a lock for a short time might be done
1041 by splitting locks into parts (such as in our 1047 by splitting locks into parts (such as in our final per-object-lock
1042 example), but this increases the number of lo 1048 example), but this increases the number of lock acquisitions, and the
1043 results are often slower than having a single 1049 results are often slower than having a single lock. This is another
1044 reason to advocate locking simplicity. 1050 reason to advocate locking simplicity.
1045 1051
1046 The third concern is addressed below: there a 1052 The third concern is addressed below: there are some methods to reduce
1047 the amount of locking which needs to be done. 1053 the amount of locking which needs to be done.
1048 1054
1049 Read/Write Lock Variants 1055 Read/Write Lock Variants
1050 ------------------------ 1056 ------------------------
1051 1057
1052 Both spinlocks and mutexes have read/write va 1058 Both spinlocks and mutexes have read/write variants: ``rwlock_t`` and
1053 :c:type:`struct rw_semaphore <rw_semaphore>`. 1059 :c:type:`struct rw_semaphore <rw_semaphore>`. These divide
1054 users into two classes: the readers and the w 1060 users into two classes: the readers and the writers. If you are only
1055 reading the data, you can get a read lock, bu 1061 reading the data, you can get a read lock, but to write to the data you
1056 need the write lock. Many people can hold a r 1062 need the write lock. Many people can hold a read lock, but a writer must
1057 be sole holder. 1063 be sole holder.
1058 1064
1059 If your code divides neatly along reader/writ 1065 If your code divides neatly along reader/writer lines (as our cache code
1060 does), and the lock is held by readers for si 1066 does), and the lock is held by readers for significant lengths of time,
1061 using these locks can help. They are slightly 1067 using these locks can help. They are slightly slower than the normal
1062 locks though, so in practice ``rwlock_t`` is 1068 locks though, so in practice ``rwlock_t`` is not usually worthwhile.
1063 1069
1064 Avoiding Locks: Read Copy Update 1070 Avoiding Locks: Read Copy Update
1065 -------------------------------- 1071 --------------------------------
1066 1072
1067 There is a special method of read/write locki 1073 There is a special method of read/write locking called Read Copy Update.
1068 Using RCU, the readers can avoid taking a loc 1074 Using RCU, the readers can avoid taking a lock altogether: as we expect
1069 our cache to be read more often than updated 1075 our cache to be read more often than updated (otherwise the cache is a
1070 waste of time), it is a candidate for this op 1076 waste of time), it is a candidate for this optimization.
1071 1077
1072 How do we get rid of read locks? Getting rid 1078 How do we get rid of read locks? Getting rid of read locks means that
1073 writers may be changing the list underneath t 1079 writers may be changing the list underneath the readers. That is
1074 actually quite simple: we can read a linked l 1080 actually quite simple: we can read a linked list while an element is
1075 being added if the writer adds the element ve 1081 being added if the writer adds the element very carefully. For example,
1076 adding ``new`` to a single linked list called 1082 adding ``new`` to a single linked list called ``list``::
1077 1083
1078 new->next = list->next; 1084 new->next = list->next;
1079 wmb(); 1085 wmb();
1080 list->next = new; 1086 list->next = new;
1081 1087
1082 1088
1083 The wmb() is a write memory barrier. It ensur !! 1089 The :c:func:`wmb()` is a write memory barrier. It ensures that the
1084 first operation (setting the new element's `` 1090 first operation (setting the new element's ``next`` pointer) is complete
1085 and will be seen by all CPUs, before the seco 1091 and will be seen by all CPUs, before the second operation is (putting
1086 the new element into the list). This is impor 1092 the new element into the list). This is important, since modern
1087 compilers and modern CPUs can both reorder in 1093 compilers and modern CPUs can both reorder instructions unless told
1088 otherwise: we want a reader to either not see 1094 otherwise: we want a reader to either not see the new element at all, or
1089 see the new element with the ``next`` pointer 1095 see the new element with the ``next`` pointer correctly pointing at the
1090 rest of the list. 1096 rest of the list.
1091 1097
1092 Fortunately, there is a function to do this f 1098 Fortunately, there is a function to do this for standard
1093 :c:type:`struct list_head <list_head>` lists: 1099 :c:type:`struct list_head <list_head>` lists:
1094 list_add_rcu() (``include/linux/list.h``). !! 1100 :c:func:`list_add_rcu()` (``include/linux/list.h``).
1095 1101
1096 Removing an element from the list is even sim 1102 Removing an element from the list is even simpler: we replace the
1097 pointer to the old element with a pointer to 1103 pointer to the old element with a pointer to its successor, and readers
1098 will either see it, or skip over it. 1104 will either see it, or skip over it.
1099 1105
1100 :: 1106 ::
1101 1107
1102 list->next = old->next; 1108 list->next = old->next;
1103 1109
1104 1110
1105 There is list_del_rcu() (``include/linux/list !! 1111 There is :c:func:`list_del_rcu()` (``include/linux/list.h``) which
1106 does this (the normal version poisons the old 1112 does this (the normal version poisons the old object, which we don't
1107 want). 1113 want).
1108 1114
1109 The reader must also be careful: some CPUs ca 1115 The reader must also be careful: some CPUs can look through the ``next``
1110 pointer to start reading the contents of the 1116 pointer to start reading the contents of the next element early, but
1111 don't realize that the pre-fetched contents i 1117 don't realize that the pre-fetched contents is wrong when the ``next``
1112 pointer changes underneath them. Once again, 1118 pointer changes underneath them. Once again, there is a
1113 list_for_each_entry_rcu() (``include/linux/li !! 1119 :c:func:`list_for_each_entry_rcu()` (``include/linux/list.h``)
1114 to help you. Of course, writers can just use 1120 to help you. Of course, writers can just use
1115 list_for_each_entry(), since there cannot be !! 1121 :c:func:`list_for_each_entry()`, since there cannot be two
1116 simultaneous writers. 1122 simultaneous writers.
1117 1123
1118 Our final dilemma is this: when can we actual 1124 Our final dilemma is this: when can we actually destroy the removed
1119 element? Remember, a reader might be stepping 1125 element? Remember, a reader might be stepping through this element in
1120 the list right now: if we free this element a 1126 the list right now: if we free this element and the ``next`` pointer
1121 changes, the reader will jump off into garbag 1127 changes, the reader will jump off into garbage and crash. We need to
1122 wait until we know that all the readers who w 1128 wait until we know that all the readers who were traversing the list
1123 when we deleted the element are finished. We 1129 when we deleted the element are finished. We use
1124 call_rcu() to register a callback which will !! 1130 :c:func:`call_rcu()` to register a callback which will actually
1125 destroy the object once all pre-existing read 1131 destroy the object once all pre-existing readers are finished.
1126 Alternatively, synchronize_rcu() may be used !! 1132 Alternatively, :c:func:`synchronize_rcu()` may be used to block
1127 until all pre-existing are finished. 1133 until all pre-existing are finished.
1128 1134
1129 But how does Read Copy Update know when the r 1135 But how does Read Copy Update know when the readers are finished? The
1130 method is this: firstly, the readers always t 1136 method is this: firstly, the readers always traverse the list inside
1131 rcu_read_lock()/rcu_read_unlock() pairs: !! 1137 :c:func:`rcu_read_lock()`/:c:func:`rcu_read_unlock()` pairs:
1132 these simply disable preemption so the reader 1138 these simply disable preemption so the reader won't go to sleep while
1133 reading the list. 1139 reading the list.
1134 1140
1135 RCU then waits until every other CPU has slep 1141 RCU then waits until every other CPU has slept at least once: since
1136 readers cannot sleep, we know that any reader 1142 readers cannot sleep, we know that any readers which were traversing the
1137 list during the deletion are finished, and th 1143 list during the deletion are finished, and the callback is triggered.
1138 The real Read Copy Update code is a little mo 1144 The real Read Copy Update code is a little more optimized than this, but
1139 this is the fundamental idea. 1145 this is the fundamental idea.
1140 1146
1141 :: 1147 ::
1142 1148
1143 --- cache.c.perobjectlock 2003-12-11 17 1149 --- cache.c.perobjectlock 2003-12-11 17:15:03.000000000 +1100
1144 +++ cache.c.rcupdate 2003-12-11 17:55: 1150 +++ cache.c.rcupdate 2003-12-11 17:55:14.000000000 +1100
1145 @@ -1,15 +1,18 @@ 1151 @@ -1,15 +1,18 @@
1146 #include <linux/list.h> 1152 #include <linux/list.h>
1147 #include <linux/slab.h> 1153 #include <linux/slab.h>
1148 #include <linux/string.h> 1154 #include <linux/string.h>
1149 +#include <linux/rcupdate.h> 1155 +#include <linux/rcupdate.h>
1150 #include <linux/mutex.h> 1156 #include <linux/mutex.h>
1151 #include <asm/errno.h> 1157 #include <asm/errno.h>
1152 1158
1153 struct object 1159 struct object
1154 { 1160 {
1155 - /* These two protected by cache_ 1161 - /* These two protected by cache_lock. */
1156 + /* This is protected by RCU */ 1162 + /* This is protected by RCU */
1157 struct list_head list; 1163 struct list_head list;
1158 int popularity; 1164 int popularity;
1159 1165
1160 + struct rcu_head rcu; 1166 + struct rcu_head rcu;
1161 + 1167 +
1162 atomic_t refcnt; 1168 atomic_t refcnt;
1163 1169
1164 /* Doesn't change once created. 1170 /* Doesn't change once created. */
1165 @@ -40,7 +43,7 @@ 1171 @@ -40,7 +43,7 @@
1166 { 1172 {
1167 struct object *i; 1173 struct object *i;
1168 1174
1169 - list_for_each_entry(i, &cache, l 1175 - list_for_each_entry(i, &cache, list) {
1170 + list_for_each_entry_rcu(i, &cach 1176 + list_for_each_entry_rcu(i, &cache, list) {
1171 if (i->id == id) { 1177 if (i->id == id) {
1172 i->popularity++; 1178 i->popularity++;
1173 return i; 1179 return i;
1174 @@ -49,19 +52,25 @@ 1180 @@ -49,19 +52,25 @@
1175 return NULL; 1181 return NULL;
1176 } 1182 }
1177 1183
1178 +/* Final discard done once we know no re 1184 +/* Final discard done once we know no readers are looking. */
1179 +static void cache_delete_rcu(void *arg) 1185 +static void cache_delete_rcu(void *arg)
1180 +{ 1186 +{
1181 + object_put(arg); 1187 + object_put(arg);
1182 +} 1188 +}
1183 + 1189 +
1184 /* Must be holding cache_lock */ 1190 /* Must be holding cache_lock */
1185 static void __cache_delete(struct object 1191 static void __cache_delete(struct object *obj)
1186 { 1192 {
1187 BUG_ON(!obj); 1193 BUG_ON(!obj);
1188 - list_del(&obj->list); 1194 - list_del(&obj->list);
1189 - object_put(obj); 1195 - object_put(obj);
1190 + list_del_rcu(&obj->list); 1196 + list_del_rcu(&obj->list);
1191 cache_num--; 1197 cache_num--;
1192 + call_rcu(&obj->rcu, cache_delete 1198 + call_rcu(&obj->rcu, cache_delete_rcu);
1193 } 1199 }
1194 1200
1195 /* Must be holding cache_lock */ 1201 /* Must be holding cache_lock */
1196 static void __cache_add(struct object *o 1202 static void __cache_add(struct object *obj)
1197 { 1203 {
1198 - list_add(&obj->list, &cache); 1204 - list_add(&obj->list, &cache);
1199 + list_add_rcu(&obj->list, &cache) 1205 + list_add_rcu(&obj->list, &cache);
1200 if (++cache_num > MAX_CACHE_SIZE 1206 if (++cache_num > MAX_CACHE_SIZE) {
1201 struct object *i, *outca 1207 struct object *i, *outcast = NULL;
1202 list_for_each_entry(i, & 1208 list_for_each_entry(i, &cache, list) {
1203 @@ -104,12 +114,11 @@ 1209 @@ -104,12 +114,11 @@
1204 struct object *cache_find(int id) 1210 struct object *cache_find(int id)
1205 { 1211 {
1206 struct object *obj; 1212 struct object *obj;
1207 - unsigned long flags; 1213 - unsigned long flags;
1208 1214
1209 - spin_lock_irqsave(&cache_lock, f 1215 - spin_lock_irqsave(&cache_lock, flags);
1210 + rcu_read_lock(); 1216 + rcu_read_lock();
1211 obj = __cache_find(id); 1217 obj = __cache_find(id);
1212 if (obj) 1218 if (obj)
1213 object_get(obj); 1219 object_get(obj);
1214 - spin_unlock_irqrestore(&cache_lo 1220 - spin_unlock_irqrestore(&cache_lock, flags);
1215 + rcu_read_unlock(); 1221 + rcu_read_unlock();
1216 return obj; 1222 return obj;
1217 } 1223 }
1218 1224
1219 Note that the reader will alter the popularit 1225 Note that the reader will alter the popularity member in
1220 __cache_find(), and now it doesn't hold a loc !! 1226 :c:func:`__cache_find()`, and now it doesn't hold a lock. One
1221 solution would be to make it an ``atomic_t``, 1227 solution would be to make it an ``atomic_t``, but for this usage, we
1222 don't really care about races: an approximate 1228 don't really care about races: an approximate result is good enough, so
1223 I didn't change it. 1229 I didn't change it.
1224 1230
1225 The result is that cache_find() requires no !! 1231 The result is that :c:func:`cache_find()` requires no
1226 synchronization with any other functions, so 1232 synchronization with any other functions, so is almost as fast on SMP as
1227 it would be on UP. 1233 it would be on UP.
1228 1234
1229 There is a further optimization possible here 1235 There is a further optimization possible here: remember our original
1230 cache code, where there were no reference cou 1236 cache code, where there were no reference counts and the caller simply
1231 held the lock whenever using the object? This 1237 held the lock whenever using the object? This is still possible: if you
1232 hold the lock, no one can delete the object, 1238 hold the lock, no one can delete the object, so you don't need to get
1233 and put the reference count. 1239 and put the reference count.
1234 1240
1235 Now, because the 'read lock' in RCU is simply 1241 Now, because the 'read lock' in RCU is simply disabling preemption, a
1236 caller which always has preemption disabled b 1242 caller which always has preemption disabled between calling
1237 cache_find() and object_put() does not !! 1243 :c:func:`cache_find()` and :c:func:`object_put()` does not
1238 need to actually get and put the reference co 1244 need to actually get and put the reference count: we could expose
1239 __cache_find() by making it non-static, and s !! 1245 :c:func:`__cache_find()` by making it non-static, and such
1240 callers could simply call that. 1246 callers could simply call that.
1241 1247
1242 The benefit here is that the reference count 1248 The benefit here is that the reference count is not written to: the
1243 object is not altered in any way, which is mu 1249 object is not altered in any way, which is much faster on SMP machines
1244 due to caching. 1250 due to caching.
1245 1251
1246 Per-CPU Data 1252 Per-CPU Data
1247 ------------ 1253 ------------
1248 1254
1249 Another technique for avoiding locking which 1255 Another technique for avoiding locking which is used fairly widely is to
1250 duplicate information for each CPU. For examp 1256 duplicate information for each CPU. For example, if you wanted to keep a
1251 count of a common condition, you could use a 1257 count of a common condition, you could use a spin lock and a single
1252 counter. Nice and simple. 1258 counter. Nice and simple.
1253 1259
1254 If that was too slow (it's usually not, but i 1260 If that was too slow (it's usually not, but if you've got a really big
1255 machine to test on and can show that it is), 1261 machine to test on and can show that it is), you could instead use a
1256 counter for each CPU, then none of them need 1262 counter for each CPU, then none of them need an exclusive lock. See
1257 DEFINE_PER_CPU(), get_cpu_var() and !! 1263 :c:func:`DEFINE_PER_CPU()`, :c:func:`get_cpu_var()` and
1258 put_cpu_var() (``include/linux/percpu.h``). !! 1264 :c:func:`put_cpu_var()` (``include/linux/percpu.h``).
1259 1265
1260 Of particular use for simple per-cpu counters 1266 Of particular use for simple per-cpu counters is the ``local_t`` type,
1261 and the cpu_local_inc() and related functions !! 1267 and the :c:func:`cpu_local_inc()` and related functions, which are
1262 more efficient than simple code on some archi 1268 more efficient than simple code on some architectures
1263 (``include/asm/local.h``). 1269 (``include/asm/local.h``).
1264 1270
1265 Note that there is no simple, reliable way of 1271 Note that there is no simple, reliable way of getting an exact value of
1266 such a counter, without introducing more lock 1272 such a counter, without introducing more locks. This is not a problem
1267 for some uses. 1273 for some uses.
1268 1274
1269 Data Which Mostly Used By An IRQ Handler 1275 Data Which Mostly Used By An IRQ Handler
1270 ---------------------------------------- 1276 ----------------------------------------
1271 1277
1272 If data is always accessed from within the sa 1278 If data is always accessed from within the same IRQ handler, you don't
1273 need a lock at all: the kernel already guaran 1279 need a lock at all: the kernel already guarantees that the irq handler
1274 will not run simultaneously on multiple CPUs. 1280 will not run simultaneously on multiple CPUs.
1275 1281
1276 Manfred Spraul points out that you can still 1282 Manfred Spraul points out that you can still do this, even if the data
1277 is very occasionally accessed in user context 1283 is very occasionally accessed in user context or softirqs/tasklets. The
1278 irq handler doesn't use a lock, and all other 1284 irq handler doesn't use a lock, and all other accesses are done as so::
1279 1285
1280 mutex_lock(&lock); !! 1286 spin_lock(&lock);
1281 disable_irq(irq); 1287 disable_irq(irq);
1282 ... 1288 ...
1283 enable_irq(irq); 1289 enable_irq(irq);
1284 mutex_unlock(&lock); !! 1290 spin_unlock(&lock);
1285 1291
1286 The disable_irq() prevents the irq handler fr !! 1292 The :c:func:`disable_irq()` prevents the irq handler from running
1287 (and waits for it to finish if it's currently 1293 (and waits for it to finish if it's currently running on other CPUs).
1288 The spinlock prevents any other accesses happ 1294 The spinlock prevents any other accesses happening at the same time.
1289 Naturally, this is slower than just a spin_lo !! 1295 Naturally, this is slower than just a :c:func:`spin_lock_irq()`
1290 call, so it only makes sense if this type of 1296 call, so it only makes sense if this type of access happens extremely
1291 rarely. 1297 rarely.
1292 1298
1293 What Functions Are Safe To Call From Interrup 1299 What Functions Are Safe To Call From Interrupts?
1294 ============================================= 1300 ================================================
1295 1301
1296 Many functions in the kernel sleep (ie. call 1302 Many functions in the kernel sleep (ie. call schedule()) directly or
1297 indirectly: you can never call them while hol 1303 indirectly: you can never call them while holding a spinlock, or with
1298 preemption disabled. This also means you need 1304 preemption disabled. This also means you need to be in user context:
1299 calling them from an interrupt is illegal. 1305 calling them from an interrupt is illegal.
1300 1306
1301 Some Functions Which Sleep 1307 Some Functions Which Sleep
1302 -------------------------- 1308 --------------------------
1303 1309
1304 The most common ones are listed below, but yo 1310 The most common ones are listed below, but you usually have to read the
1305 code to find out if other calls are safe. If 1311 code to find out if other calls are safe. If everyone else who calls it
1306 can sleep, you probably need to be able to sl 1312 can sleep, you probably need to be able to sleep, too. In particular,
1307 registration and deregistration functions usu 1313 registration and deregistration functions usually expect to be called
1308 from user context, and can sleep. 1314 from user context, and can sleep.
1309 1315
1310 - Accesses to userspace: 1316 - Accesses to userspace:
1311 1317
1312 - copy_from_user() !! 1318 - :c:func:`copy_from_user()`
1313 1319
1314 - copy_to_user() !! 1320 - :c:func:`copy_to_user()`
1315 1321
1316 - get_user() !! 1322 - :c:func:`get_user()`
1317 1323
1318 - put_user() !! 1324 - :c:func:`put_user()`
1319 1325
1320 - kmalloc(GP_KERNEL) <kmalloc>` !! 1326 - :c:func:`kmalloc(GFP_KERNEL) <kmalloc>`
1321 1327
1322 - mutex_lock_interruptible() and !! 1328 - :c:func:`mutex_lock_interruptible()` and
1323 mutex_lock() !! 1329 :c:func:`mutex_lock()`
1324 1330
1325 There is a mutex_trylock() which does not !! 1331 There is a :c:func:`mutex_trylock()` which does not sleep.
1326 Still, it must not be used inside interrup 1332 Still, it must not be used inside interrupt context since its
1327 implementation is not safe for that. mutex !! 1333 implementation is not safe for that. :c:func:`mutex_unlock()`
1328 will also never sleep. It cannot be used i 1334 will also never sleep. It cannot be used in interrupt context either
1329 since a mutex must be released by the same 1335 since a mutex must be released by the same task that acquired it.
1330 1336
1331 Some Functions Which Don't Sleep 1337 Some Functions Which Don't Sleep
1332 -------------------------------- 1338 --------------------------------
1333 1339
1334 Some functions are safe to call from any cont 1340 Some functions are safe to call from any context, or holding almost any
1335 lock. 1341 lock.
1336 1342
1337 - printk() !! 1343 - :c:func:`printk()`
1338 1344
1339 - kfree() !! 1345 - :c:func:`kfree()`
1340 1346
1341 - add_timer() and timer_delete() !! 1347 - :c:func:`add_timer()` and :c:func:`del_timer()`
1342 1348
1343 Mutex API reference 1349 Mutex API reference
1344 =================== 1350 ===================
1345 1351
1346 .. kernel-doc:: include/linux/mutex.h 1352 .. kernel-doc:: include/linux/mutex.h
1347 :internal: 1353 :internal:
1348 1354
1349 .. kernel-doc:: kernel/locking/mutex.c 1355 .. kernel-doc:: kernel/locking/mutex.c
1350 :export: 1356 :export:
1351 1357
1352 Futex API reference 1358 Futex API reference
1353 =================== 1359 ===================
1354 1360
1355 .. kernel-doc:: kernel/futex/core.c !! 1361 .. kernel-doc:: kernel/futex.c
1356 :internal: <<
1357 <<
1358 .. kernel-doc:: kernel/futex/futex.h <<
1359 :internal: <<
1360 <<
1361 .. kernel-doc:: kernel/futex/pi.c <<
1362 :internal: <<
1363 <<
1364 .. kernel-doc:: kernel/futex/requeue.c <<
1365 :internal: <<
1366 <<
1367 .. kernel-doc:: kernel/futex/waitwake.c <<
1368 :internal: 1362 :internal:
1369 1363
1370 Further reading 1364 Further reading
1371 =============== 1365 ===============
1372 1366
1373 - ``Documentation/locking/spinlocks.rst``: L 1367 - ``Documentation/locking/spinlocks.rst``: Linus Torvalds' spinlocking
1374 tutorial in the kernel sources. 1368 tutorial in the kernel sources.
1375 1369
1376 - Unix Systems for Modern Architectures: Sym 1370 - Unix Systems for Modern Architectures: Symmetric Multiprocessing and
1377 Caching for Kernel Programmers: 1371 Caching for Kernel Programmers:
1378 1372
1379 Curt Schimmel's very good introduction to 1373 Curt Schimmel's very good introduction to kernel level locking (not
1380 written for Linux, but nearly everything a 1374 written for Linux, but nearly everything applies). The book is
1381 expensive, but really worth every penny to 1375 expensive, but really worth every penny to understand SMP locking.
1382 [ISBN: 0201633388] 1376 [ISBN: 0201633388]
1383 1377
1384 Thanks 1378 Thanks
1385 ====== 1379 ======
1386 1380
1387 Thanks to Telsa Gwynne for DocBooking, neaten 1381 Thanks to Telsa Gwynne for DocBooking, neatening and adding style.
1388 1382
1389 Thanks to Martin Pool, Philipp Rumpf, Stephen 1383 Thanks to Martin Pool, Philipp Rumpf, Stephen Rothwell, Paul Mackerras,
1390 Ruedi Aschwanden, Alan Cox, Manfred Spraul, T 1384 Ruedi Aschwanden, Alan Cox, Manfred Spraul, Tim Waugh, Pete Zaitcev,
1391 James Morris, Robert Love, Paul McKenney, Joh 1385 James Morris, Robert Love, Paul McKenney, John Ashby for proofreading,
1392 correcting, flaming, commenting. 1386 correcting, flaming, commenting.
1393 1387
1394 Thanks to the cabal for having no influence o 1388 Thanks to the cabal for having no influence on this document.
1395 1389
1396 Glossary 1390 Glossary
1397 ======== 1391 ========
1398 1392
1399 preemption 1393 preemption
1400 Prior to 2.5, or when ``CONFIG_PREEMPT`` is 1394 Prior to 2.5, or when ``CONFIG_PREEMPT`` is unset, processes in user
1401 context inside the kernel would not preempt 1395 context inside the kernel would not preempt each other (ie. you had that
1402 CPU until you gave it up, except for interr 1396 CPU until you gave it up, except for interrupts). With the addition of
1403 ``CONFIG_PREEMPT`` in 2.5.4, this changed: 1397 ``CONFIG_PREEMPT`` in 2.5.4, this changed: when in user context, higher
1404 priority tasks can "cut in": spinlocks were 1398 priority tasks can "cut in": spinlocks were changed to disable
1405 preemption, even on UP. 1399 preemption, even on UP.
1406 1400
1407 bh 1401 bh
1408 Bottom Half: for historical reasons, functi 1402 Bottom Half: for historical reasons, functions with '_bh' in them often
1409 now refer to any software interrupt, e.g. s !! 1403 now refer to any software interrupt, e.g. :c:func:`spin_lock_bh()`
1410 blocks any software interrupt on the curren 1404 blocks any software interrupt on the current CPU. Bottom halves are
1411 deprecated, and will eventually be replaced 1405 deprecated, and will eventually be replaced by tasklets. Only one bottom
1412 half will be running at any time. 1406 half will be running at any time.
1413 1407
1414 Hardware Interrupt / Hardware IRQ 1408 Hardware Interrupt / Hardware IRQ
1415 Hardware interrupt request. in_hardirq() re !! 1409 Hardware interrupt request. :c:func:`in_irq()` returns true in a
1416 hardware interrupt handler. 1410 hardware interrupt handler.
1417 1411
1418 Interrupt Context 1412 Interrupt Context
1419 Not user context: processing a hardware irq 1413 Not user context: processing a hardware irq or software irq. Indicated
1420 by the in_interrupt() macro returning true. !! 1414 by the :c:func:`in_interrupt()` macro returning true.
1421 1415
1422 SMP 1416 SMP
1423 Symmetric Multi-Processor: kernels compiled 1417 Symmetric Multi-Processor: kernels compiled for multiple-CPU machines.
1424 (``CONFIG_SMP=y``). 1418 (``CONFIG_SMP=y``).
1425 1419
1426 Software Interrupt / softirq 1420 Software Interrupt / softirq
1427 Software interrupt handler. in_hardirq() re !! 1421 Software interrupt handler. :c:func:`in_irq()` returns false;
1428 in_softirq() returns true. Tasklets and sof !! 1422 :c:func:`in_softirq()` returns true. Tasklets and softirqs both
1429 fall into the category of 'software interru 1423 fall into the category of 'software interrupts'.
1430 1424
1431 Strictly speaking a softirq is one of up to 1425 Strictly speaking a softirq is one of up to 32 enumerated software
1432 interrupts which can run on multiple CPUs a 1426 interrupts which can run on multiple CPUs at once. Sometimes used to
1433 refer to tasklets as well (ie. all software 1427 refer to tasklets as well (ie. all software interrupts).
1434 1428
1435 tasklet 1429 tasklet
1436 A dynamically-registrable software interrup 1430 A dynamically-registrable software interrupt, which is guaranteed to
1437 only run on one CPU at a time. 1431 only run on one CPU at a time.
1438 1432
1439 timer 1433 timer
1440 A dynamically-registrable software interrup 1434 A dynamically-registrable software interrupt, which is run at (or close
1441 to) a given time. When running, it is just 1435 to) a given time. When running, it is just like a tasklet (in fact, they
1442 are called from the ``TIMER_SOFTIRQ``). 1436 are called from the ``TIMER_SOFTIRQ``).
1443 1437
1444 UP 1438 UP
1445 Uni-Processor: Non-SMP. (``CONFIG_SMP=n``). 1439 Uni-Processor: Non-SMP. (``CONFIG_SMP=n``).
1446 1440
1447 User Context 1441 User Context
1448 The kernel executing on behalf of a particu 1442 The kernel executing on behalf of a particular process (ie. a system
1449 call or trap) or kernel thread. You can tel 1443 call or trap) or kernel thread. You can tell which process with the
1450 ``current`` macro.) Not to be confused with 1444 ``current`` macro.) Not to be confused with userspace. Can be
1451 interrupted by software or hardware interru 1445 interrupted by software or hardware interrupts.
1452 1446
1453 Userspace 1447 Userspace
1454 A process executing its own code outside th 1448 A process executing its own code outside the kernel.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.