Commit | Line | Data |
---|---|---|
387b1468 MCC |
1 | =============== |
2 | Locking lessons | |
3 | =============== | |
4 | ||
fb0bbb92 | 5 | Lesson 1: Spin locks |
387b1468 | 6 | ==================== |
1da177e4 | 7 | |
387b1468 | 8 | The most basic primitive for locking is spinlock:: |
1da177e4 | 9 | |
387b1468 | 10 | static DEFINE_SPINLOCK(xxx_lock); |
1da177e4 LT |
11 | |
12 | unsigned long flags; | |
13 | ||
14 | spin_lock_irqsave(&xxx_lock, flags); | |
15 | ... critical section here .. | |
16 | spin_unlock_irqrestore(&xxx_lock, flags); | |
17 | ||
fb0bbb92 | 18 | The above is always safe. It will disable interrupts _locally_, but the |
1da177e4 LT |
19 | spinlock itself will guarantee the global lock, so it will guarantee that |
20 | there is only one thread-of-control within the region(s) protected by that | |
05801817 MK |
21 | lock. This works well even under UP also, so the code does _not_ need to |
22 | worry about UP vs SMP issues: the spinlocks work correctly under both. | |
fb0bbb92 WAS |
23 | |
24 | NOTE! Implications of spin_locks for memory are further described in: | |
1da177e4 | 25 | |
fb0bbb92 | 26 | Documentation/memory-barriers.txt |
387b1468 | 27 | |
4bfdebd6 | 28 | (5) ACQUIRE operations. |
387b1468 | 29 | |
4bfdebd6 | 30 | (6) RELEASE operations. |
1da177e4 LT |
31 | |
32 | The above is usually pretty simple (you usually need and want only one | |
33 | spinlock for most things - using more than one spinlock can make things a | |
34 | lot more complex and even slower and is usually worth it only for | |
387b1468 | 35 | sequences that you **know** need to be split up: avoid it at all cost if you |
05801817 | 36 | aren't sure). |
1da177e4 LT |
37 | |
38 | This is really the only really hard part about spinlocks: once you start | |
39 | using spinlocks they tend to expand to areas you might not have noticed | |
40 | before, because you have to make sure the spinlocks correctly protect the | |
387b1468 | 41 | shared data structures **everywhere** they are used. The spinlocks are most |
fb0bbb92 WAS |
42 | easily added to places that are completely independent of other code (for |
43 | example, internal driver data structures that nobody else ever touches). | |
44 | ||
387b1468 | 45 | NOTE! The spin-lock is safe only when you **also** use the lock itself |
fb0bbb92 WAS |
46 | to do locking across CPU's, which implies that EVERYTHING that |
47 | touches a shared variable has to agree about the spinlock they want | |
48 | to use. | |
1da177e4 LT |
49 | |
50 | ---- | |
51 | ||
52 | Lesson 2: reader-writer spinlocks. | |
387b1468 | 53 | ================================== |
1da177e4 LT |
54 | |
55 | If your data accesses have a very natural pattern where you usually tend | |
56 | to mostly read from the shared variables, the reader-writer locks | |
fb0bbb92 | 57 | (rw_lock) versions of the spinlocks are sometimes useful. They allow multiple |
1da177e4 | 58 | readers to be in the same critical region at once, but if somebody wants |
fb0bbb92 | 59 | to change the variables it has to get an exclusive write lock. |
1da177e4 | 60 | |
fb0bbb92 WAS |
61 | NOTE! reader-writer locks require more atomic memory operations than |
62 | simple spinlocks. Unless the reader critical section is long, you | |
63 | are better off just using spinlocks. | |
1da177e4 | 64 | |
387b1468 | 65 | The routines look the same as above:: |
fb0bbb92 | 66 | |
d04fa5a3 | 67 | rwlock_t xxx_lock = __RW_LOCK_UNLOCKED(xxx_lock); |
1da177e4 LT |
68 | |
69 | unsigned long flags; | |
70 | ||
71 | read_lock_irqsave(&xxx_lock, flags); | |
72 | .. critical section that only reads the info ... | |
73 | read_unlock_irqrestore(&xxx_lock, flags); | |
74 | ||
75 | write_lock_irqsave(&xxx_lock, flags); | |
76 | .. read and write exclusive access to the info ... | |
77 | write_unlock_irqrestore(&xxx_lock, flags); | |
78 | ||
fb0bbb92 WAS |
79 | The above kind of lock may be useful for complex data structures like |
80 | linked lists, especially searching for entries without changing the list | |
81 | itself. The read lock allows many concurrent readers. Anything that | |
387b1468 | 82 | **changes** the list will have to get the write lock. |
fb0bbb92 WAS |
83 | |
84 | NOTE! RCU is better for list traversal, but requires careful | |
bff9e34c | 85 | attention to design detail (see Documentation/RCU/listRCU.rst). |
1da177e4 | 86 | |
fb0bbb92 | 87 | Also, you cannot "upgrade" a read-lock to a write-lock, so if you at _any_ |
1da177e4 | 88 | time need to do any changes (even if you don't do it every time), you have |
fb0bbb92 WAS |
89 | to get the write-lock at the very beginning. |
90 | ||
91 | NOTE! We are working hard to remove reader-writer spinlocks in most | |
92 | cases, so please don't add a new one without consensus. (Instead, see | |
bff9e34c | 93 | Documentation/RCU/rcu.rst for complete information.) |
1da177e4 LT |
94 | |
95 | ---- | |
96 | ||
97 | Lesson 3: spinlocks revisited. | |
387b1468 | 98 | ============================== |
1da177e4 LT |
99 | |
100 | The single spin-lock primitives above are by no means the only ones. They | |
101 | are the most safe ones, and the ones that work under all circumstances, | |
387b1468 | 102 | but partly **because** they are safe they are also fairly slow. They are slower |
05801817 MK |
103 | than they'd need to be, because they do have to disable interrupts |
104 | (which is just a single instruction on a x86, but it's an expensive one - | |
105 | and on other architectures it can be worse). | |
1da177e4 LT |
106 | |
107 | If you have a case where you have to protect a data structure across | |
108 | several CPU's and you want to use spinlocks you can potentially use | |
109 | cheaper versions of the spinlocks. IFF you know that the spinlocks are | |
387b1468 | 110 | never used in interrupt handlers, you can use the non-irq versions:: |
1da177e4 LT |
111 | |
112 | spin_lock(&lock); | |
113 | ... | |
114 | spin_unlock(&lock); | |
115 | ||
116 | (and the equivalent read-write versions too, of course). The spinlock will | |
214e0aed | 117 | guarantee the same kind of exclusive access, and it will be much faster. |
1da177e4 | 118 | This is useful if you know that the data in question is only ever |
214e0aed | 119 | manipulated from a "process context", ie no interrupts involved. |
1da177e4 LT |
120 | |
121 | The reasons you mustn't use these versions if you have interrupts that | |
387b1468 | 122 | play with the spinlock is that you can get deadlocks:: |
1da177e4 LT |
123 | |
124 | spin_lock(&lock); | |
125 | ... | |
126 | <- interrupt comes in: | |
127 | spin_lock(&lock); | |
128 | ||
129 | where an interrupt tries to lock an already locked variable. This is ok if | |
130 | the other interrupt happens on another CPU, but it is _not_ ok if the | |
131 | interrupt happens on the same CPU that already holds the lock, because the | |
132 | lock will obviously never be released (because the interrupt is waiting | |
133 | for the lock, and the lock-holder is interrupted by the interrupt and will | |
214e0aed | 134 | not continue until the interrupt has been processed). |
1da177e4 LT |
135 | |
136 | (This is also the reason why the irq-versions of the spinlocks only need | |
137 | to disable the _local_ interrupts - it's ok to use spinlocks in interrupts | |
138 | on other CPU's, because an interrupt on another CPU doesn't interrupt the | |
139 | CPU that holds the lock, so the lock-holder can continue and eventually | |
214e0aed | 140 | releases the lock). |
1da177e4 | 141 | |
1da177e4 LT |
142 | Linus |
143 | ||
fb0bbb92 WAS |
144 | ---- |
145 | ||
146 | Reference information: | |
387b1468 | 147 | ====================== |
fb0bbb92 WAS |
148 | |
149 | For dynamic initialization, use spin_lock_init() or rwlock_init() as | |
387b1468 | 150 | appropriate:: |
fb0bbb92 WAS |
151 | |
152 | spinlock_t xxx_lock; | |
153 | rwlock_t xxx_rw_lock; | |
154 | ||
155 | static int __init xxx_init(void) | |
156 | { | |
157 | spin_lock_init(&xxx_lock); | |
158 | rwlock_init(&xxx_rw_lock); | |
159 | ... | |
160 | } | |
161 | ||
162 | module_init(xxx_init); | |
163 | ||
164 | For static initialization, use DEFINE_SPINLOCK() / DEFINE_RWLOCK() or | |
165 | __SPIN_LOCK_UNLOCKED() / __RW_LOCK_UNLOCKED() as appropriate. |