X-Git-Url: http://ftp.safe.ca/?a=blobdiff_plain;ds=sidebyside;f=Documentation%2FDocBook%2Fkernel-locking.tmpl;h=084f6ad7b7a0a4729b85aea3cc5c3e6eb6557689;hb=b0c83ae1de01880075955c7224e751440688ec74;hp=77c42f40be5d66ecb0b2235ef3dd1300301eafa8;hpb=e9b62693ae0a1e13ccc97a6792d9a7770c8d1b5b;p=safe%2Fjmp%2Flinux-2.6
diff --git a/Documentation/DocBook/kernel-locking.tmpl b/Documentation/DocBook/kernel-locking.tmpl
index 77c42f4..084f6ad 100644
--- a/Documentation/DocBook/kernel-locking.tmpl
+++ b/Documentation/DocBook/kernel-locking.tmpl
@@ -219,10 +219,10 @@
- Three Main Types of Kernel Locks: Spinlocks, Mutexes and Semaphores
+ Two Main Types of Kernel Locks: Spinlocks and Mutexes
- There are three main types of kernel locks. The fundamental type
+ There are two main types of kernel locks. The fundamental type
is the spinlock
(),
which is a very simple single-holder lock: if you can't get the
@@ -240,14 +240,6 @@
use a spinlock instead.
- The third type is a semaphore
- (): it
- can have more than one holder at any time (the number decided at
- initialization time), although it is most commonly used as a
- single-holder lock (a mutex). If you can't get a semaphore, your
- task will be suspended and later on woken up - just like for mutexes.
-
-
Neither type of lock is recursive: see
.
@@ -278,7 +270,7 @@
- Semaphores still exist, because they are required for
+ Mutexes still exist, because they are required for
synchronization between user
contexts, as we will see below.
@@ -289,18 +281,17 @@
If you have a data structure which is only ever accessed from
- user context, then you can use a simple semaphore
- (linux/linux/semaphore.h) to protect it. This
- is the most trivial case: you initialize the semaphore to the number
- of resources available (usually 1), and call
- down_interruptible() to grab the semaphore, and
- up() to release it. There is also a
- down(), which should be avoided, because it
+ user context, then you can use a simple mutex
+ (include/linux/mutex.h) to protect it. This
+ is the most trivial case: you initialize the mutex. Then you can
+ call mutex_lock_interruptible() to grab the mutex,
+ and mutex_unlock() to release it. There is also a
+ mutex_lock(), which should be avoided, because it
will not return if a signal is received.
- Example: linux/net/core/netfilter.c allows
+ Example: net/netfilter/nf_sockopt.c allows
registration of new setsockopt() and
getsockopt() calls, with
nf_register_sockopt(). Registration and
@@ -515,7 +506,7 @@
If you are in a process context (any syscall) and want to
- lock other process out, use a semaphore. You can take a semaphore
+ lock other process out, use a mutex. You can take a mutex
and sleep (copy_from_user*( or
kmalloc(x,GFP_KERNEL)).
@@ -662,7 +653,7 @@
SLBH
SLBH
SLBH
-DI
+MLI
None
@@ -692,8 +683,8 @@
spin_lock_bh
-DI
-down_interruptible
+MLI
+mutex_lock_interruptible
@@ -703,6 +694,31 @@
+
+ The trylock Functions
+
+ There are functions that try to acquire a lock only once and immediately
+ return a value telling about success or failure to acquire the lock.
+ They can be used if you need no access to the data protected with the lock
+ when some other thread is holding the lock. You should acquire the lock
+ later if you then need access to the data protected with the lock.
+
+
+
+ spin_trylock() does not spin but returns non-zero if
+ it acquires the spinlock on the first try or 0 if not. This function can
+ be used in all contexts like spin_lock: you must have
+ disabled the contexts that might interrupt you and acquire the spin lock.
+
+
+
+ mutex_trylock() does not suspend your task
+ but returns non-zero if it could lock the mutex on the first try
+ or 0 if not. This function cannot be safely used in hardware or software
+ interrupt contexts despite not sleeping.
+
+
+
Common Examples
@@ -1285,7 +1301,7 @@ as Alan Cox says, Lock data, not code
.
There is a coding bug where a piece of code tries to grab a
spinlock twice: it will spin forever, waiting for the lock to
- be released (spinlocks, rwlocks and semaphores are not
+ be released (spinlocks, rwlocks and mutexes are not
recursive in Linux). This is trivial to diagnose: not a
stay-up-five-nights-talk-to-fluffy-code-bunnies kind of
problem.
@@ -1310,7 +1326,7 @@ as Alan Cox says, Lock data, not code
.
This complete lockup is easy to diagnose: on SMP boxes the
- watchdog timer or compiling with DEBUG_SPINLOCKS set
+ watchdog timer or compiling with DEBUG_SPINLOCK set
(include/linux/spinlock.h) will show this up
immediately when it happens.
@@ -1533,7 +1549,7 @@ the amount of locking which needs to be done.
Read/Write Lock Variants
- Both spinlocks and semaphores have read/write variants:
+ Both spinlocks and mutexes have read/write variants:
rwlock_t and struct rw_semaphore.
These divide users into two classes: the readers and the writers. If
you are only reading the data, you can get a read lock, but to write to
@@ -1656,7 +1672,7 @@ the amount of locking which needs to be done.
#include <linux/slab.h>
#include <linux/string.h>
+#include <linux/rcupdate.h>
- #include <linux/semaphore.h>
+ #include <linux/mutex.h>
#include <asm/errno.h>
struct object
@@ -1888,7 +1904,7 @@ machines due to caching.
- put_user()
+ put_user()
@@ -1902,13 +1918,13 @@ machines due to caching.
- down_interruptible() and
- down()
+ mutex_lock_interruptible() and
+ mutex_lock()
- There is a down_trylock() which can be
+ There is a mutex_trylock() which can be
used inside interrupt context, as it will not sleep.
- up() will also never sleep.
+ mutex_unlock() will also never sleep.
@@ -1998,7 +2014,7 @@ machines due to caching.
Prior to 2.5, or when CONFIG_PREEMPT is
unset, processes in user context inside the kernel would not
- preempt each other (ie. you had that CPU until you have it up,
+ preempt each other (ie. you had that CPU until you gave it up,
except for interrupts). With the addition of
CONFIG_PREEMPT in 2.5.4, this changed: when
in user context, higher priority tasks can "cut in": spinlocks