aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/kernel-locking.tmpl
diff options
context:
space:
mode:
authorMatthew Wilcox <matthew@wil.cx>2008-04-23 07:20:41 -0400
committerMatthew Wilcox <willy@linux.intel.com>2008-07-24 08:29:40 -0400
commit78305de2f99e9f43ab860dd95bb430b20e26c695 (patch)
tree18bd576b2f6c9dd3f91ed40188fa13690cf311bf /Documentation/DocBook/kernel-locking.tmpl
parent338b9bb3adac0d2c5a1e180491d9b001d624c402 (diff)
Remove mention of semaphores from kernel-locking
Since the consensus seems to be to eliminate semaphores where possible, we shouldn't be educating people about how to use them as locks. Use mutexes instead. Semaphores should be described in a separate document if we end up keeping them. Signed-off-by: Matthew Wilcox <willy@linux.intel.com> Acked-by: Rusty Russell <rusty@rustcorp.com.au>
Diffstat (limited to 'Documentation/DocBook/kernel-locking.tmpl')
-rw-r--r--Documentation/DocBook/kernel-locking.tmpl57
1 files changed, 24 insertions, 33 deletions
diff --git a/Documentation/DocBook/kernel-locking.tmpl b/Documentation/DocBook/kernel-locking.tmpl
index 2510763295d0..084f6ad7b7a0 100644
--- a/Documentation/DocBook/kernel-locking.tmpl
+++ b/Documentation/DocBook/kernel-locking.tmpl
@@ -219,10 +219,10 @@
219 </para> 219 </para>
220 220
221 <sect1 id="lock-intro"> 221 <sect1 id="lock-intro">
222 <title>Three Main Types of Kernel Locks: Spinlocks, Mutexes and Semaphores</title> 222 <title>Two Main Types of Kernel Locks: Spinlocks and Mutexes</title>
223 223
224 <para> 224 <para>
225 There are three main types of kernel locks. The fundamental type 225 There are two main types of kernel locks. The fundamental type
226 is the spinlock 226 is the spinlock
227 (<filename class="headerfile">include/asm/spinlock.h</filename>), 227 (<filename class="headerfile">include/asm/spinlock.h</filename>),
228 which is a very simple single-holder lock: if you can't get the 228 which is a very simple single-holder lock: if you can't get the
@@ -240,14 +240,6 @@
240 use a spinlock instead. 240 use a spinlock instead.
241 </para> 241 </para>
242 <para> 242 <para>
243 The third type is a semaphore
244 (<filename class="headerfile">include/linux/semaphore.h</filename>): it
245 can have more than one holder at any time (the number decided at
246 initialization time), although it is most commonly used as a
247 single-holder lock (a mutex). If you can't get a semaphore, your
248 task will be suspended and later on woken up - just like for mutexes.
249 </para>
250 <para>
251 Neither type of lock is recursive: see 243 Neither type of lock is recursive: see
252 <xref linkend="deadlock"/>. 244 <xref linkend="deadlock"/>.
253 </para> 245 </para>
@@ -278,7 +270,7 @@
278 </para> 270 </para>
279 271
280 <para> 272 <para>
281 Semaphores still exist, because they are required for 273 Mutexes still exist, because they are required for
282 synchronization between <firstterm linkend="gloss-usercontext">user 274 synchronization between <firstterm linkend="gloss-usercontext">user
283 contexts</firstterm>, as we will see below. 275 contexts</firstterm>, as we will see below.
284 </para> 276 </para>
@@ -289,18 +281,17 @@
289 281
290 <para> 282 <para>
291 If you have a data structure which is only ever accessed from 283 If you have a data structure which is only ever accessed from
292 user context, then you can use a simple semaphore 284 user context, then you can use a simple mutex
293 (<filename>linux/linux/semaphore.h</filename>) to protect it. This 285 (<filename>include/linux/mutex.h</filename>) to protect it. This
294 is the most trivial case: you initialize the semaphore to the number 286 is the most trivial case: you initialize the mutex. Then you can
295 of resources available (usually 1), and call 287 call <function>mutex_lock_interruptible()</function> to grab the mutex,
296 <function>down_interruptible()</function> to grab the semaphore, and 288 and <function>mutex_unlock()</function> to release it. There is also a
297 <function>up()</function> to release it. There is also a 289 <function>mutex_lock()</function>, which should be avoided, because it
298 <function>down()</function>, which should be avoided, because it
299 will not return if a signal is received. 290 will not return if a signal is received.
300 </para> 291 </para>
301 292
302 <para> 293 <para>
303 Example: <filename>linux/net/core/netfilter.c</filename> allows 294 Example: <filename>net/netfilter/nf_sockopt.c</filename> allows
304 registration of new <function>setsockopt()</function> and 295 registration of new <function>setsockopt()</function> and
305 <function>getsockopt()</function> calls, with 296 <function>getsockopt()</function> calls, with
306 <function>nf_register_sockopt()</function>. Registration and 297 <function>nf_register_sockopt()</function>. Registration and
@@ -515,7 +506,7 @@
515 <listitem> 506 <listitem>
516 <para> 507 <para>
517 If you are in a process context (any syscall) and want to 508 If you are in a process context (any syscall) and want to
518 lock other process out, use a semaphore. You can take a semaphore 509 lock other process out, use a mutex. You can take a mutex
519 and sleep (<function>copy_from_user*(</function> or 510 and sleep (<function>copy_from_user*(</function> or
520 <function>kmalloc(x,GFP_KERNEL)</function>). 511 <function>kmalloc(x,GFP_KERNEL)</function>).
521 </para> 512 </para>
@@ -662,7 +653,7 @@
662<entry>SLBH</entry> 653<entry>SLBH</entry>
663<entry>SLBH</entry> 654<entry>SLBH</entry>
664<entry>SLBH</entry> 655<entry>SLBH</entry>
665<entry>DI</entry> 656<entry>MLI</entry>
666<entry>None</entry> 657<entry>None</entry>
667</row> 658</row>
668 659
@@ -692,8 +683,8 @@
692<entry>spin_lock_bh</entry> 683<entry>spin_lock_bh</entry>
693</row> 684</row>
694<row> 685<row>
695<entry>DI</entry> 686<entry>MLI</entry>
696<entry>down_interruptible</entry> 687<entry>mutex_lock_interruptible</entry>
697</row> 688</row>
698 689
699</tbody> 690</tbody>
@@ -1310,7 +1301,7 @@ as Alan Cox says, <quote>Lock data, not code</quote>.
1310 <para> 1301 <para>
1311 There is a coding bug where a piece of code tries to grab a 1302 There is a coding bug where a piece of code tries to grab a
1312 spinlock twice: it will spin forever, waiting for the lock to 1303 spinlock twice: it will spin forever, waiting for the lock to
1313 be released (spinlocks, rwlocks and semaphores are not 1304 be released (spinlocks, rwlocks and mutexes are not
1314 recursive in Linux). This is trivial to diagnose: not a 1305 recursive in Linux). This is trivial to diagnose: not a
1315 stay-up-five-nights-talk-to-fluffy-code-bunnies kind of 1306 stay-up-five-nights-talk-to-fluffy-code-bunnies kind of
1316 problem. 1307 problem.
@@ -1335,7 +1326,7 @@ as Alan Cox says, <quote>Lock data, not code</quote>.
1335 1326
1336 <para> 1327 <para>
1337 This complete lockup is easy to diagnose: on SMP boxes the 1328 This complete lockup is easy to diagnose: on SMP boxes the
1338 watchdog timer or compiling with <symbol>DEBUG_SPINLOCKS</symbol> set 1329 watchdog timer or compiling with <symbol>DEBUG_SPINLOCK</symbol> set
1339 (<filename>include/linux/spinlock.h</filename>) will show this up 1330 (<filename>include/linux/spinlock.h</filename>) will show this up
1340 immediately when it happens. 1331 immediately when it happens.
1341 </para> 1332 </para>
@@ -1558,7 +1549,7 @@ the amount of locking which needs to be done.
1558 <title>Read/Write Lock Variants</title> 1549 <title>Read/Write Lock Variants</title>
1559 1550
1560 <para> 1551 <para>
1561 Both spinlocks and semaphores have read/write variants: 1552 Both spinlocks and mutexes have read/write variants:
1562 <type>rwlock_t</type> and <structname>struct rw_semaphore</structname>. 1553 <type>rwlock_t</type> and <structname>struct rw_semaphore</structname>.
1563 These divide users into two classes: the readers and the writers. If 1554 These divide users into two classes: the readers and the writers. If
1564 you are only reading the data, you can get a read lock, but to write to 1555 you are only reading the data, you can get a read lock, but to write to
@@ -1681,7 +1672,7 @@ the amount of locking which needs to be done.
1681 #include &lt;linux/slab.h&gt; 1672 #include &lt;linux/slab.h&gt;
1682 #include &lt;linux/string.h&gt; 1673 #include &lt;linux/string.h&gt;
1683+#include &lt;linux/rcupdate.h&gt; 1674+#include &lt;linux/rcupdate.h&gt;
1684 #include &lt;linux/semaphore.h&gt; 1675 #include &lt;linux/mutex.h&gt;
1685 #include &lt;asm/errno.h&gt; 1676 #include &lt;asm/errno.h&gt;
1686 1677
1687 struct object 1678 struct object
@@ -1913,7 +1904,7 @@ machines due to caching.
1913 </listitem> 1904 </listitem>
1914 <listitem> 1905 <listitem>
1915 <para> 1906 <para>
1916 <function> put_user()</function> 1907 <function>put_user()</function>
1917 </para> 1908 </para>
1918 </listitem> 1909 </listitem>
1919 </itemizedlist> 1910 </itemizedlist>
@@ -1927,13 +1918,13 @@ machines due to caching.
1927 1918
1928 <listitem> 1919 <listitem>
1929 <para> 1920 <para>
1930 <function>down_interruptible()</function> and 1921 <function>mutex_lock_interruptible()</function> and
1931 <function>down()</function> 1922 <function>mutex_lock()</function>
1932 </para> 1923 </para>
1933 <para> 1924 <para>
1934 There is a <function>down_trylock()</function> which can be 1925 There is a <function>mutex_trylock()</function> which can be
1935 used inside interrupt context, as it will not sleep. 1926 used inside interrupt context, as it will not sleep.
1936 <function>up()</function> will also never sleep. 1927 <function>mutex_unlock()</function> will also never sleep.
1937 </para> 1928 </para>
1938 </listitem> 1929 </listitem>
1939 </itemizedlist> 1930 </itemizedlist>
@@ -2023,7 +2014,7 @@ machines due to caching.
2023 <para> 2014 <para>
2024 Prior to 2.5, or when <symbol>CONFIG_PREEMPT</symbol> is 2015 Prior to 2.5, or when <symbol>CONFIG_PREEMPT</symbol> is
2025 unset, processes in user context inside the kernel would not 2016 unset, processes in user context inside the kernel would not
2026 preempt each other (ie. you had that CPU until you have it up, 2017 preempt each other (ie. you had that CPU until you gave it up,
2027 except for interrupts). With the addition of 2018 except for interrupts). With the addition of
2028 <symbol>CONFIG_PREEMPT</symbol> in 2.5.4, this changed: when 2019 <symbol>CONFIG_PREEMPT</symbol> in 2.5.4, this changed: when
2029 in user context, higher priority tasks can "cut in": spinlocks 2020 in user context, higher priority tasks can "cut in": spinlocks