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
21struct device;
22struct device_node;
23struct hwspinlock;
24struct hwspinlock_device;
25struct 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 */
51struct hwspinlock_pdata {
52 int base_id;
53};
54
55#ifdef CONFIG_HWSPINLOCK
56
57int hwspin_lock_register(struct hwspinlock_device *bank, struct device *dev,
58 const struct hwspinlock_ops *ops, int base_id, int num_locks);
59int hwspin_lock_unregister(struct hwspinlock_device *bank);
60struct hwspinlock *hwspin_lock_request(void);
61struct hwspinlock *hwspin_lock_request_specific(unsigned int id);
62int hwspin_lock_free(struct hwspinlock *hwlock);
63int of_hwspin_lock_get_id(struct device_node *np, int index);
64int hwspin_lock_get_id(struct hwspinlock *hwlock);
65int __hwspin_lock_timeout(struct hwspinlock *, unsigned int, int,
66 unsigned long *);
67int __hwspin_trylock(struct hwspinlock *, int, unsigned long *);
68void __hwspin_unlock(struct hwspinlock *, int, unsigned long *);
69int of_hwspin_lock_get_id_byname(struct device_node *np, const char *name);
70int devm_hwspin_lock_free(struct device *dev, struct hwspinlock *hwlock);
71struct hwspinlock *devm_hwspin_lock_request(struct device *dev);
72struct hwspinlock *devm_hwspin_lock_request_specific(struct device *dev,
73 unsigned int id);
74int devm_hwspin_lock_unregister(struct device *dev,
75 struct hwspinlock_device *bank);
76int 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 */
96static inline struct hwspinlock *hwspin_lock_request(void)
97{
98 return ERR_PTR(-ENODEV);
99}
100
101static inline struct hwspinlock *hwspin_lock_request_specific(unsigned int id)
102{
103 return ERR_PTR(-ENODEV);
104}
105
106static inline int hwspin_lock_free(struct hwspinlock *hwlock)
107{
108 return 0;
109}
110
111static inline
112int __hwspin_lock_timeout(struct hwspinlock *hwlock, unsigned int to,
113 int mode, unsigned long *flags)
114{
115 return 0;
116}
117
118static inline
119int __hwspin_trylock(struct hwspinlock *hwlock, int mode, unsigned long *flags)
120{
121 return 0;
122}
123
124static inline
125void __hwspin_unlock(struct hwspinlock *hwlock, int mode, unsigned long *flags)
126{
127}
128
129static inline int of_hwspin_lock_get_id(struct device_node *np, int index)
130{
131 return 0;
132}
133
134static inline int hwspin_lock_get_id(struct hwspinlock *hwlock)
135{
136 return 0;
137}
138
139static inline
140int of_hwspin_lock_get_id_byname(struct device_node *np, const char *name)
141{
142 return 0;
143}
144
145static inline
146int devm_hwspin_lock_free(struct device *dev, struct hwspinlock *hwlock)
147{
148 return 0;
149}
150
151static inline struct hwspinlock *devm_hwspin_lock_request(struct device *dev)
152{
153 return ERR_PTR(-ENODEV);
154}
155
156static inline
157struct 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 */
181static inline
182int 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 */
201static 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 */
220static 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 */
240static 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 */
263static 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 */
286static inline
287int 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 */
309static inline
310int 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 */
334static inline
335int 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 */
352static 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 */
369static 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 */
384static 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 */
400static inline void hwspin_unlock(struct hwspinlock *hwlock)
401{
402 __hwspin_unlock(hwlock, 0, NULL);
403}
404
405#endif /* __LINUX_HWSPINLOCK_H */
406