Branch data Line data Source code
1 : : /*
2 : : * Mutexes: blocking mutual exclusion locks
3 : : *
4 : : * started by Ingo Molnar:
5 : : *
6 : : * Copyright (C) 2004, 2005, 2006 Red Hat, Inc., Ingo Molnar <mingo@redhat.com>
7 : : *
8 : : * This file contains the main data structure and API definitions.
9 : : */
10 : : #ifndef __LINUX_MUTEX_H
11 : : #define __LINUX_MUTEX_H
12 : :
13 : : #include <asm/current.h>
14 : : #include <linux/list.h>
15 : : #include <linux/spinlock_types.h>
16 : : #include <linux/linkage.h>
17 : : #include <linux/lockdep.h>
18 : : #include <linux/atomic.h>
19 : : #include <asm/processor.h>
20 : :
21 : : /*
22 : : * Simple, straightforward mutexes with strict semantics:
23 : : *
24 : : * - only one task can hold the mutex at a time
25 : : * - only the owner can unlock the mutex
26 : : * - multiple unlocks are not permitted
27 : : * - recursive locking is not permitted
28 : : * - a mutex object must be initialized via the API
29 : : * - a mutex object must not be initialized via memset or copying
30 : : * - task may not exit with mutex held
31 : : * - memory areas where held locks reside must not be freed
32 : : * - held mutexes must not be reinitialized
33 : : * - mutexes may not be used in hardware or software interrupt
34 : : * contexts such as tasklets and timers
35 : : *
36 : : * These semantics are fully enforced when DEBUG_MUTEXES is
37 : : * enabled. Furthermore, besides enforcing the above rules, the mutex
38 : : * debugging code also implements a number of additional features
39 : : * that make lock debugging easier and faster:
40 : : *
41 : : * - uses symbolic names of mutexes, whenever they are printed in debug output
42 : : * - point-of-acquire tracking, symbolic lookup of function names
43 : : * - list of all locks held in the system, printout of them
44 : : * - owner tracking
45 : : * - detects self-recursing locks and prints out all relevant info
46 : : * - detects multi-task circular deadlocks and prints out all affected
47 : : * locks and tasks (and only those tasks)
48 : : */
49 : : struct mutex {
50 : : /* 1: unlocked, 0: locked, negative: locked, possible waiters */
51 : : atomic_t count;
52 : : spinlock_t wait_lock;
53 : : struct list_head wait_list;
54 : : #if defined(CONFIG_DEBUG_MUTEXES) || defined(CONFIG_SMP)
55 : : struct task_struct *owner;
56 : : #endif
57 : : #ifdef CONFIG_MUTEX_SPIN_ON_OWNER
58 : : void *spin_mlock; /* Spinner MCS lock */
59 : : #endif
60 : : #ifdef CONFIG_DEBUG_MUTEXES
61 : : const char *name;
62 : : void *magic;
63 : : #endif
64 : : #ifdef CONFIG_DEBUG_LOCK_ALLOC
65 : : struct lockdep_map dep_map;
66 : : #endif
67 : : };
68 : :
69 : : /*
70 : : * This is the control structure for tasks blocked on mutex,
71 : : * which resides on the blocked task's kernel stack:
72 : : */
73 : : struct mutex_waiter {
74 : : struct list_head list;
75 : : struct task_struct *task;
76 : : #ifdef CONFIG_DEBUG_MUTEXES
77 : : void *magic;
78 : : #endif
79 : : };
80 : :
81 : : #ifdef CONFIG_DEBUG_MUTEXES
82 : : # include <linux/mutex-debug.h>
83 : : #else
84 : : # define __DEBUG_MUTEX_INITIALIZER(lockname)
85 : : /**
86 : : * mutex_init - initialize the mutex
87 : : * @mutex: the mutex to be initialized
88 : : *
89 : : * Initialize the mutex to unlocked state.
90 : : *
91 : : * It is not allowed to initialize an already locked mutex.
92 : : */
93 : : # define mutex_init(mutex) \
94 : : do { \
95 : : static struct lock_class_key __key; \
96 : : \
97 : : __mutex_init((mutex), #mutex, &__key); \
98 : : } while (0)
99 : : static inline void mutex_destroy(struct mutex *lock) {}
100 : : #endif
101 : :
102 : : #ifdef CONFIG_DEBUG_LOCK_ALLOC
103 : : # define __DEP_MAP_MUTEX_INITIALIZER(lockname) \
104 : : , .dep_map = { .name = #lockname }
105 : : #else
106 : : # define __DEP_MAP_MUTEX_INITIALIZER(lockname)
107 : : #endif
108 : :
109 : : #define __MUTEX_INITIALIZER(lockname) \
110 : : { .count = ATOMIC_INIT(1) \
111 : : , .wait_lock = __SPIN_LOCK_UNLOCKED(lockname.wait_lock) \
112 : : , .wait_list = LIST_HEAD_INIT(lockname.wait_list) \
113 : : __DEBUG_MUTEX_INITIALIZER(lockname) \
114 : : __DEP_MAP_MUTEX_INITIALIZER(lockname) }
115 : :
116 : : #define DEFINE_MUTEX(mutexname) \
117 : : struct mutex mutexname = __MUTEX_INITIALIZER(mutexname)
118 : :
119 : : extern void __mutex_init(struct mutex *lock, const char *name,
120 : : struct lock_class_key *key);
121 : :
122 : : /**
123 : : * mutex_is_locked - is the mutex locked
124 : : * @lock: the mutex to be queried
125 : : *
126 : : * Returns 1 if the mutex is locked, 0 if unlocked.
127 : : */
128 : : static inline int mutex_is_locked(struct mutex *lock)
129 : : {
130 : 1477283 : return atomic_read(&lock->count) != 1;
131 : : }
132 : :
133 : : /*
134 : : * See kernel/locking/mutex.c for detailed documentation of these APIs.
135 : : * Also see Documentation/mutex-design.txt.
136 : : */
137 : : #ifdef CONFIG_DEBUG_LOCK_ALLOC
138 : : extern void mutex_lock_nested(struct mutex *lock, unsigned int subclass);
139 : : extern void _mutex_lock_nest_lock(struct mutex *lock, struct lockdep_map *nest_lock);
140 : :
141 : : extern int __must_check mutex_lock_interruptible_nested(struct mutex *lock,
142 : : unsigned int subclass);
143 : : extern int __must_check mutex_lock_killable_nested(struct mutex *lock,
144 : : unsigned int subclass);
145 : :
146 : : #define mutex_lock(lock) mutex_lock_nested(lock, 0)
147 : : #define mutex_lock_interruptible(lock) mutex_lock_interruptible_nested(lock, 0)
148 : : #define mutex_lock_killable(lock) mutex_lock_killable_nested(lock, 0)
149 : :
150 : : #define mutex_lock_nest_lock(lock, nest_lock) \
151 : : do { \
152 : : typecheck(struct lockdep_map *, &(nest_lock)->dep_map); \
153 : : _mutex_lock_nest_lock(lock, &(nest_lock)->dep_map); \
154 : : } while (0)
155 : :
156 : : #else
157 : : extern void mutex_lock(struct mutex *lock);
158 : : extern int __must_check mutex_lock_interruptible(struct mutex *lock);
159 : : extern int __must_check mutex_lock_killable(struct mutex *lock);
160 : :
161 : : # define mutex_lock_nested(lock, subclass) mutex_lock(lock)
162 : : # define mutex_lock_interruptible_nested(lock, subclass) mutex_lock_interruptible(lock)
163 : : # define mutex_lock_killable_nested(lock, subclass) mutex_lock_killable(lock)
164 : : # define mutex_lock_nest_lock(lock, nest_lock) mutex_lock(lock)
165 : : #endif
166 : :
167 : : /*
168 : : * NOTE: mutex_trylock() follows the spin_trylock() convention,
169 : : * not the down_trylock() convention!
170 : : *
171 : : * Returns 1 if the mutex has been acquired successfully, and 0 on contention.
172 : : */
173 : : extern int mutex_trylock(struct mutex *lock);
174 : : extern void mutex_unlock(struct mutex *lock);
175 : :
176 : : extern int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock);
177 : :
178 : : #ifndef arch_mutex_cpu_relax
179 : : # define arch_mutex_cpu_relax() cpu_relax()
180 : : #endif
181 : :
182 : : #endif
|
