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