Branch data Line data Source code
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 : 0 : static inline struct hwspinlock *hwspin_lock_request_specific(unsigned int id)
103 : : {
104 [ # # # ]: 0 : 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 : 0 : int __hwspin_lock_timeout(struct hwspinlock *hwlock, unsigned int to,
114 : : int mode, unsigned long *flags)
115 : : {
116 : 0 : 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 : 0 : void __hwspin_unlock(struct hwspinlock *hwlock, int mode, unsigned long *flags)
127 : : {
128 : 0 : }
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 : 0 : static inline int hwspin_lock_timeout_irqsave(struct hwspinlock *hwlock,
282 : : unsigned int to, unsigned long *flags)
283 : : {
284 : 0 : 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 : 0 : int hwspin_lock_timeout_irq(struct hwspinlock *hwlock, unsigned int to)
306 : : {
307 : 0 : 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 : 0 : int hwspin_lock_timeout(struct hwspinlock *hwlock, unsigned int to)
376 : : {
377 : 0 : 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 : 0 : static inline void hwspin_unlock_irqrestore(struct hwspinlock *hwlock,
393 : : unsigned long *flags)
394 : : {
395 : 0 : __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 : 0 : static inline void hwspin_unlock_irq(struct hwspinlock *hwlock)
410 : : {
411 : 0 : __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 : 0 : static inline void hwspin_unlock(struct hwspinlock *hwlock)
456 : : {
457 : 0 : __hwspin_unlock(hwlock, 0, NULL);
458 : : }
459 : :
460 : : #endif /* __LINUX_HWSPINLOCK_H */
|
