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 (include/asm/spinlock.h), 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 - (include/linux/semaphore.h): 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