1 | /* SPDX-License-Identifier: GPL-2.0 */ |
2 | /* |
3 | * Hardware spinlock public header |
4 | * |
5 | * Copyright (C) 2010 Texas Instruments Incorporated - http://www.ti.com |
6 | * |
7 | * Contact: Ohad Ben-Cohen <ohad@wizery.com> |
8 | */ |
9 | |
10 | #ifndef __LINUX_HWSPINLOCK_H |
11 | #define __LINUX_HWSPINLOCK_H |
12 | |
13 | #include <linux/err.h> |
14 | #include <linux/sched.h> |
15 | |
16 | /* hwspinlock mode argument */ |
17 | #define HWLOCK_IRQSTATE 0x01 /* Disable interrupts, save state */ |
18 | #define HWLOCK_IRQ 0x02 /* Disable interrupts, don't save state */ |
19 | #define HWLOCK_RAW 0x03 |
20 | #define HWLOCK_IN_ATOMIC 0x04 /* Called while in atomic context */ |
21 | |
22 | struct device; |
23 | struct device_node; |
24 | struct hwspinlock; |
25 | struct hwspinlock_device; |
26 | struct hwspinlock_ops; |
27 | |
28 | /** |
29 | * struct hwspinlock_pdata - platform data for hwspinlock drivers |
30 | * @base_id: base id for this hwspinlock device |
31 | * |
32 | * hwspinlock devices provide system-wide hardware locks that are used |
33 | * by remote processors that have no other way to achieve synchronization. |
34 | * |
35 | * To achieve that, each physical lock must have a system-wide id number |
36 | * that is agreed upon, otherwise remote processors can't possibly assume |
37 | * they're using the same hardware lock. |
38 | * |
39 | * Usually boards have a single hwspinlock device, which provides several |
40 | * hwspinlocks, and in this case, they can be trivially numbered 0 to |
41 | * (num-of-locks - 1). |
42 | * |
43 | * In case boards have several hwspinlocks devices, a different base id |
44 | * should be used for each hwspinlock device (they can't all use 0 as |
45 | * a starting id!). |
46 | * |
47 | * This platform data structure should be used to provide the base id |
48 | * for each device (which is trivially 0 when only a single hwspinlock |
49 | * device exists). It can be shared between different platforms, hence |
50 | * its location. |
51 | */ |
52 | struct hwspinlock_pdata { |
53 | int base_id; |
54 | }; |
55 | |
56 | #ifdef CONFIG_HWSPINLOCK |
57 | |
58 | int hwspin_lock_register(struct hwspinlock_device *bank, struct device *dev, |
59 | const struct hwspinlock_ops *ops, int base_id, int num_locks); |
60 | int hwspin_lock_unregister(struct hwspinlock_device *bank); |
61 | struct hwspinlock *hwspin_lock_request(void); |
62 | struct hwspinlock *hwspin_lock_request_specific(unsigned int id); |
63 | int hwspin_lock_free(struct hwspinlock *hwlock); |
64 | int of_hwspin_lock_get_id(struct device_node *np, int index); |
65 | int hwspin_lock_get_id(struct hwspinlock *hwlock); |
66 | int __hwspin_lock_timeout(struct hwspinlock *, unsigned int, int, |
67 | unsigned long *); |
68 | int __hwspin_trylock(struct hwspinlock *, int, unsigned long *); |
69 | void __hwspin_unlock(struct hwspinlock *, int, unsigned long *); |
70 | int of_hwspin_lock_get_id_byname(struct device_node *np, const char *name); |
71 | int devm_hwspin_lock_free(struct device *dev, struct hwspinlock *hwlock); |
72 | struct hwspinlock *devm_hwspin_lock_request(struct device *dev); |
73 | struct hwspinlock *devm_hwspin_lock_request_specific(struct device *dev, |
74 | unsigned int id); |
75 | int devm_hwspin_lock_unregister(struct device *dev, |
76 | struct hwspinlock_device *bank); |
77 | int devm_hwspin_lock_register(struct device *dev, |
78 | struct hwspinlock_device *bank, |
79 | const struct hwspinlock_ops *ops, |
80 | int base_id, int num_locks); |
81 | |
82 | #else /* !CONFIG_HWSPINLOCK */ |
83 | |
84 | /* |
85 | * We don't want these functions to fail if CONFIG_HWSPINLOCK is not |
86 | * enabled. We prefer to silently succeed in this case, and let the |
87 | * code path get compiled away. This way, if CONFIG_HWSPINLOCK is not |
88 | * required on a given setup, users will still work. |
89 | * |
90 | * The only exception is hwspin_lock_register/hwspin_lock_unregister, with which |
91 | * we _do_ want users to fail (no point in registering hwspinlock instances if |
92 | * the framework is not available). |
93 | * |
94 | * Note: ERR_PTR(-ENODEV) will still be considered a success for NULL-checking |
95 | * users. Others, which care, can still check this with IS_ERR. |
96 | */ |
97 | static inline struct hwspinlock *hwspin_lock_request(void) |
98 | { |
99 | return ERR_PTR(-ENODEV); |
100 | } |
101 | |
102 | static inline struct hwspinlock *hwspin_lock_request_specific(unsigned int id) |
103 | { |
104 | return ERR_PTR(-ENODEV); |
105 | } |
106 | |
107 | static inline int hwspin_lock_free(struct hwspinlock *hwlock) |
108 | { |
109 | return 0; |
110 | } |
111 | |
112 | static inline |
113 | int __hwspin_lock_timeout(struct hwspinlock *hwlock, unsigned int to, |
114 | int mode, unsigned long *flags) |
115 | { |
116 | return 0; |
117 | } |
118 | |
119 | static inline |
120 | int __hwspin_trylock(struct hwspinlock *hwlock, int mode, unsigned long *flags) |
121 | { |
122 | return 0; |
123 | } |
124 | |
125 | static inline |
126 | void __hwspin_unlock(struct hwspinlock *hwlock, int mode, unsigned long *flags) |
127 | { |
128 | } |
129 | |
130 | static inline int of_hwspin_lock_get_id(struct device_node *np, int index) |
131 | { |
132 | return 0; |
133 | } |
134 | |
135 | static inline int hwspin_lock_get_id(struct hwspinlock *hwlock) |
136 | { |
137 | return 0; |
138 | } |
139 | |
140 | static inline |
141 | int of_hwspin_lock_get_id_byname(struct device_node *np, const char *name) |
142 | { |
143 | return 0; |
144 | } |
145 | |
146 | static inline |
147 | int devm_hwspin_lock_free(struct device *dev, struct hwspinlock *hwlock) |
148 | { |
149 | return 0; |
150 | } |
151 | |
152 | static inline struct hwspinlock *devm_hwspin_lock_request(struct device *dev) |
153 | { |
154 | return ERR_PTR(-ENODEV); |
155 | } |
156 | |
157 | static inline |
158 | struct hwspinlock *devm_hwspin_lock_request_specific(struct device *dev, |
159 | unsigned int id) |
160 | { |
161 | return ERR_PTR(-ENODEV); |
162 | } |
163 | |
164 | #endif /* !CONFIG_HWSPINLOCK */ |
165 | |
166 | /** |
167 | * hwspin_trylock_irqsave() - try to lock an hwspinlock, disable interrupts |
168 | * @hwlock: an hwspinlock which we want to trylock |
169 | * @flags: a pointer to where the caller's interrupt state will be saved at |
170 | * |
171 | * This function attempts to lock the underlying hwspinlock, and will |
172 | * immediately fail if the hwspinlock is already locked. |
173 | * |
174 | * Upon a successful return from this function, preemption and local |
175 | * interrupts are disabled (previous interrupts state is saved at @flags), |
176 | * so the caller must not sleep, and is advised to release the hwspinlock |
177 | * as soon as possible. |
178 | * |
179 | * Returns 0 if we successfully locked the hwspinlock, -EBUSY if |
180 | * the hwspinlock was already taken, and -EINVAL if @hwlock is invalid. |
181 | */ |
182 | static inline |
183 | int hwspin_trylock_irqsave(struct hwspinlock *hwlock, unsigned long *flags) |
184 | { |
185 | return __hwspin_trylock(hwlock, HWLOCK_IRQSTATE, flags); |
186 | } |
187 | |
188 | /** |
189 | * hwspin_trylock_irq() - try to lock an hwspinlock, disable interrupts |
190 | * @hwlock: an hwspinlock which we want to trylock |
191 | * |
192 | * This function attempts to lock the underlying hwspinlock, and will |
193 | * immediately fail if the hwspinlock is already locked. |
194 | * |
195 | * Upon a successful return from this function, preemption and local |
196 | * interrupts are disabled, so the caller must not sleep, and is advised |
197 | * to release the hwspinlock as soon as possible. |
198 | * |
199 | * Returns 0 if we successfully locked the hwspinlock, -EBUSY if |
200 | * the hwspinlock was already taken, and -EINVAL if @hwlock is invalid. |
201 | */ |
202 | static inline int hwspin_trylock_irq(struct hwspinlock *hwlock) |
203 | { |
204 | return __hwspin_trylock(hwlock, HWLOCK_IRQ, NULL); |
205 | } |
206 | |
207 | /** |
208 | * hwspin_trylock_raw() - attempt to lock a specific hwspinlock |
209 | * @hwlock: an hwspinlock which we want to trylock |
210 | * |
211 | * This function attempts to lock an hwspinlock, and will immediately fail |
212 | * if the hwspinlock is already taken. |
213 | * |
214 | * Caution: User must protect the routine of getting hardware lock with mutex |
215 | * or spinlock to avoid dead-lock, that will let user can do some time-consuming |
216 | * or sleepable operations under the hardware lock. |
217 | * |
218 | * Returns 0 if we successfully locked the hwspinlock, -EBUSY if |
219 | * the hwspinlock was already taken, and -EINVAL if @hwlock is invalid. |
220 | */ |
221 | static inline int hwspin_trylock_raw(struct hwspinlock *hwlock) |
222 | { |
223 | return __hwspin_trylock(hwlock, HWLOCK_RAW, NULL); |
224 | } |
225 | |
226 | /** |
227 | * hwspin_trylock_in_atomic() - attempt to lock a specific hwspinlock |
228 | * @hwlock: an hwspinlock which we want to trylock |
229 | * |
230 | * This function attempts to lock an hwspinlock, and will immediately fail |
231 | * if the hwspinlock is already taken. |
232 | * |
233 | * This function shall be called only from an atomic context. |
234 | * |
235 | * Returns 0 if we successfully locked the hwspinlock, -EBUSY if |
236 | * the hwspinlock was already taken, and -EINVAL if @hwlock is invalid. |
237 | */ |
238 | static inline int hwspin_trylock_in_atomic(struct hwspinlock *hwlock) |
239 | { |
240 | return __hwspin_trylock(hwlock, HWLOCK_IN_ATOMIC, NULL); |
241 | } |
242 | |
243 | /** |
244 | * hwspin_trylock() - attempt to lock a specific hwspinlock |
245 | * @hwlock: an hwspinlock which we want to trylock |
246 | * |
247 | * This function attempts to lock an hwspinlock, and will immediately fail |
248 | * if the hwspinlock is already taken. |
249 | * |
250 | * Upon a successful return from this function, preemption is disabled, |
251 | * so the caller must not sleep, and is advised to release the hwspinlock |
252 | * as soon as possible. This is required in order to minimize remote cores |
253 | * polling on the hardware interconnect. |
254 | * |
255 | * Returns 0 if we successfully locked the hwspinlock, -EBUSY if |
256 | * the hwspinlock was already taken, and -EINVAL if @hwlock is invalid. |
257 | */ |
258 | static inline int hwspin_trylock(struct hwspinlock *hwlock) |
259 | { |
260 | return __hwspin_trylock(hwlock, 0, NULL); |
261 | } |
262 | |
263 | /** |
264 | * hwspin_lock_timeout_irqsave() - lock hwspinlock, with timeout, disable irqs |
265 | * @hwlock: the hwspinlock to be locked |
266 | * @to: timeout value in msecs |
267 | * @flags: a pointer to where the caller's interrupt state will be saved at |
268 | * |
269 | * This function locks the underlying @hwlock. If the @hwlock |
270 | * is already taken, the function will busy loop waiting for it to |
271 | * be released, but give up when @timeout msecs have elapsed. |
272 | * |
273 | * Upon a successful return from this function, preemption and local interrupts |
274 | * are disabled (plus previous interrupt state is saved), so the caller must |
275 | * not sleep, and is advised to release the hwspinlock as soon as possible. |
276 | * |
277 | * Returns 0 when the @hwlock was successfully taken, and an appropriate |
278 | * error code otherwise (most notably an -ETIMEDOUT if the @hwlock is still |
279 | * busy after @timeout msecs). The function will never sleep. |
280 | */ |
281 | static inline int hwspin_lock_timeout_irqsave(struct hwspinlock *hwlock, |
282 | unsigned int to, unsigned long *flags) |
283 | { |
284 | return __hwspin_lock_timeout(hwlock, to, HWLOCK_IRQSTATE, flags); |
285 | } |
286 | |
287 | /** |
288 | * hwspin_lock_timeout_irq() - lock hwspinlock, with timeout, disable irqs |
289 | * @hwlock: the hwspinlock to be locked |
290 | * @to: timeout value in msecs |
291 | * |
292 | * This function locks the underlying @hwlock. If the @hwlock |
293 | * is already taken, the function will busy loop waiting for it to |
294 | * be released, but give up when @timeout msecs have elapsed. |
295 | * |
296 | * Upon a successful return from this function, preemption and local interrupts |
297 | * are disabled so the caller must not sleep, and is advised to release the |
298 | * hwspinlock as soon as possible. |
299 | * |
300 | * Returns 0 when the @hwlock was successfully taken, and an appropriate |
301 | * error code otherwise (most notably an -ETIMEDOUT if the @hwlock is still |
302 | * busy after @timeout msecs). The function will never sleep. |
303 | */ |
304 | static inline |
305 | int hwspin_lock_timeout_irq(struct hwspinlock *hwlock, unsigned int to) |
306 | { |
307 | return __hwspin_lock_timeout(hwlock, to, HWLOCK_IRQ, NULL); |
308 | } |
309 | |
310 | /** |
311 | * hwspin_lock_timeout_raw() - lock an hwspinlock with timeout limit |
312 | * @hwlock: the hwspinlock to be locked |
313 | * @to: timeout value in msecs |
314 | * |
315 | * This function locks the underlying @hwlock. If the @hwlock |
316 | * is already taken, the function will busy loop waiting for it to |
317 | * be released, but give up when @timeout msecs have elapsed. |
318 | * |
319 | * Caution: User must protect the routine of getting hardware lock with mutex |
320 | * or spinlock to avoid dead-lock, that will let user can do some time-consuming |
321 | * or sleepable operations under the hardware lock. |
322 | * |
323 | * Returns 0 when the @hwlock was successfully taken, and an appropriate |
324 | * error code otherwise (most notably an -ETIMEDOUT if the @hwlock is still |
325 | * busy after @timeout msecs). The function will never sleep. |
326 | */ |
327 | static inline |
328 | int hwspin_lock_timeout_raw(struct hwspinlock *hwlock, unsigned int to) |
329 | { |
330 | return __hwspin_lock_timeout(hwlock, to, HWLOCK_RAW, NULL); |
331 | } |
332 | |
333 | /** |
334 | * hwspin_lock_timeout_in_atomic() - lock an hwspinlock with timeout limit |
335 | * @hwlock: the hwspinlock to be locked |
336 | * @to: timeout value in msecs |
337 | * |
338 | * This function locks the underlying @hwlock. If the @hwlock |
339 | * is already taken, the function will busy loop waiting for it to |
340 | * be released, but give up when @timeout msecs have elapsed. |
341 | * |
342 | * This function shall be called only from an atomic context and the timeout |
343 | * value shall not exceed a few msecs. |
344 | * |
345 | * Returns 0 when the @hwlock was successfully taken, and an appropriate |
346 | * error code otherwise (most notably an -ETIMEDOUT if the @hwlock is still |
347 | * busy after @timeout msecs). The function will never sleep. |
348 | */ |
349 | static inline |
350 | int hwspin_lock_timeout_in_atomic(struct hwspinlock *hwlock, unsigned int to) |
351 | { |
352 | return __hwspin_lock_timeout(hwlock, to, HWLOCK_IN_ATOMIC, NULL); |
353 | } |
354 | |
355 | /** |
356 | * hwspin_lock_timeout() - lock an hwspinlock with timeout limit |
357 | * @hwlock: the hwspinlock to be locked |
358 | * @to: timeout value in msecs |
359 | * |
360 | * This function locks the underlying @hwlock. If the @hwlock |
361 | * is already taken, the function will busy loop waiting for it to |
362 | * be released, but give up when @timeout msecs have elapsed. |
363 | * |
364 | * Upon a successful return from this function, preemption is disabled |
365 | * so the caller must not sleep, and is advised to release the hwspinlock |
366 | * as soon as possible. |
367 | * This is required in order to minimize remote cores polling on the |
368 | * hardware interconnect. |
369 | * |
370 | * Returns 0 when the @hwlock was successfully taken, and an appropriate |
371 | * error code otherwise (most notably an -ETIMEDOUT if the @hwlock is still |
372 | * busy after @timeout msecs). The function will never sleep. |
373 | */ |
374 | static inline |
375 | int hwspin_lock_timeout(struct hwspinlock *hwlock, unsigned int to) |
376 | { |
377 | return __hwspin_lock_timeout(hwlock, to, 0, NULL); |
378 | } |
379 | |
380 | /** |
381 | * hwspin_unlock_irqrestore() - unlock hwspinlock, restore irq state |
382 | * @hwlock: a previously-acquired hwspinlock which we want to unlock |
383 | * @flags: previous caller's interrupt state to restore |
384 | * |
385 | * This function will unlock a specific hwspinlock, enable preemption and |
386 | * restore the previous state of the local interrupts. It should be used |
387 | * to undo, e.g., hwspin_trylock_irqsave(). |
388 | * |
389 | * @hwlock must be already locked before calling this function: it is a bug |
390 | * to call unlock on a @hwlock that is already unlocked. |
391 | */ |
392 | static inline void hwspin_unlock_irqrestore(struct hwspinlock *hwlock, |
393 | unsigned long *flags) |
394 | { |
395 | __hwspin_unlock(hwlock, HWLOCK_IRQSTATE, flags); |
396 | } |
397 | |
398 | /** |
399 | * hwspin_unlock_irq() - unlock hwspinlock, enable interrupts |
400 | * @hwlock: a previously-acquired hwspinlock which we want to unlock |
401 | * |
402 | * This function will unlock a specific hwspinlock, enable preemption and |
403 | * enable local interrupts. Should be used to undo hwspin_lock_irq(). |
404 | * |
405 | * @hwlock must be already locked (e.g. by hwspin_trylock_irq()) before |
406 | * calling this function: it is a bug to call unlock on a @hwlock that is |
407 | * already unlocked. |
408 | */ |
409 | static inline void hwspin_unlock_irq(struct hwspinlock *hwlock) |
410 | { |
411 | __hwspin_unlock(hwlock, HWLOCK_IRQ, NULL); |
412 | } |
413 | |
414 | /** |
415 | * hwspin_unlock_raw() - unlock hwspinlock |
416 | * @hwlock: a previously-acquired hwspinlock which we want to unlock |
417 | * |
418 | * This function will unlock a specific hwspinlock. |
419 | * |
420 | * @hwlock must be already locked (e.g. by hwspin_trylock()) before calling |
421 | * this function: it is a bug to call unlock on a @hwlock that is already |
422 | * unlocked. |
423 | */ |
424 | static inline void hwspin_unlock_raw(struct hwspinlock *hwlock) |
425 | { |
426 | __hwspin_unlock(hwlock, HWLOCK_RAW, NULL); |
427 | } |
428 | |
429 | /** |
430 | * hwspin_unlock_in_atomic() - unlock hwspinlock |
431 | * @hwlock: a previously-acquired hwspinlock which we want to unlock |
432 | * |
433 | * This function will unlock a specific hwspinlock. |
434 | * |
435 | * @hwlock must be already locked (e.g. by hwspin_trylock()) before calling |
436 | * this function: it is a bug to call unlock on a @hwlock that is already |
437 | * unlocked. |
438 | */ |
439 | static inline void hwspin_unlock_in_atomic(struct hwspinlock *hwlock) |
440 | { |
441 | __hwspin_unlock(hwlock, HWLOCK_IN_ATOMIC, NULL); |
442 | } |
443 | |
444 | /** |
445 | * hwspin_unlock() - unlock hwspinlock |
446 | * @hwlock: a previously-acquired hwspinlock which we want to unlock |
447 | * |
448 | * This function will unlock a specific hwspinlock and enable preemption |
449 | * back. |
450 | * |
451 | * @hwlock must be already locked (e.g. by hwspin_trylock()) before calling |
452 | * this function: it is a bug to call unlock on a @hwlock that is already |
453 | * unlocked. |
454 | */ |
455 | static inline void hwspin_unlock(struct hwspinlock *hwlock) |
456 | { |
457 | __hwspin_unlock(hwlock, 0, NULL); |
458 | } |
459 | |
460 | #endif /* __LINUX_HWSPINLOCK_H */ |
461 | |