Documentation/locking/hwspinlock.rst

17 A generic hwspinlock framework allows platform-independent drivers to use
18 the hwspinlock device in order to access data structures that are shared
31 the remote processors, and access to it is synchronized using the hwspinlock
35 A common hwspinlock interface makes it possible to have generic, platform-
43   struct hwspinlock *hwspin_lock_request(void);
45 Dynamically assign an hwspinlock and return its address, or NULL
46 in case an unused hwspinlock isn't available. Users of this
54   struct hwspinlock *hwspin_lock_request_specific(unsigned int id);
56 Assign a specific hwspinlock id and return its address, or NULL
57 if that hwspinlock is already in use. Usually board code will
58 be calling this function in order to reserve specific hwspinlock
68 This function provides a means for DT users of a hwspinlock module
69 to get the global lock id of a specific hwspinlock, so that it can
73 the hwspinlock device is not yet registered with the core, or other
80   int hwspin_lock_free(struct hwspinlock *hwlock);
82 Free a previously-assigned hwspinlock; returns 0 on success, or an
83 appropriate error code on failure (e.g. -EINVAL if the hwspinlock
90   int hwspin_lock_bust(struct hwspinlock *hwlock, unsigned int id);
92 After verifying the owner of the hwspinlock, release a previously acquired
93 hwspinlock; returns 0 on success, or an appropriate error code on failure
95 hwspinlock).
101   int hwspin_lock_timeout(struct hwspinlock *hwlock, unsigned int timeout);
103 Lock a previously-assigned hwspinlock with a timeout limit (specified in
104 msecs). If the hwspinlock is already taken, the function will busy loop
107 the caller must not sleep, and is advised to release the hwspinlock as
112 notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
117   int hwspin_lock_timeout_irq(struct hwspinlock *hwlock, unsigned int timeout);
119 Lock a previously-assigned hwspinlock with a timeout limit (specified in
120 msecs). If the hwspinlock is already taken, the function will busy loop
124 release the hwspinlock as soon as possible.
127 notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
132   int hwspin_lock_timeout_irqsave(struct hwspinlock *hwlock, unsigned int to,
135 Lock a previously-assigned hwspinlock with a timeout limit (specified in
136 msecs). If the hwspinlock is already taken, the function will busy loop
141 release the hwspinlock as soon as possible.
144 notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
150   int hwspin_lock_timeout_raw(struct hwspinlock *hwlock, unsigned int timeout);
152 Lock a previously-assigned hwspinlock with a timeout limit (specified in
153 msecs). If the hwspinlock is already taken, the function will busy loop
161 notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
167   int hwspin_lock_timeout_in_atomic(struct hwspinlock *hwlock, unsigned int to);
169 Lock a previously-assigned hwspinlock with a timeout limit (specified in
170 msecs). If the hwspinlock is already taken, the function will busy loop
177 notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
183   int hwspin_trylock(struct hwspinlock *hwlock);
186 Attempt to lock a previously-assigned hwspinlock, but immediately fail if
190 caller must not sleep, and is advised to release the hwspinlock as soon as
195 notably -EBUSY if the hwspinlock was already taken).
200   int hwspin_trylock_irq(struct hwspinlock *hwlock);
203 Attempt to lock a previously-assigned hwspinlock, but immediately fail if
208 release the hwspinlock as soon as possible.
211 notably -EBUSY if the hwspinlock was already taken).
217   int hwspin_trylock_irqsave(struct hwspinlock *hwlock, unsigned long *flags);
219 Attempt to lock a previously-assigned hwspinlock, but immediately fail if
225 to release the hwspinlock as soon as possible.
228 notably -EBUSY if the hwspinlock was already taken).
233   int hwspin_trylock_raw(struct hwspinlock *hwlock);
235 Attempt to lock a previously-assigned hwspinlock, but immediately fail if
243 notably -EBUSY if the hwspinlock was already taken).
248   int hwspin_trylock_in_atomic(struct hwspinlock *hwlock);
250 Attempt to lock a previously-assigned hwspinlock, but immediately fail if
256 notably -EBUSY if the hwspinlock was already taken).
261   void hwspin_unlock(struct hwspinlock *hwlock);
263 Unlock a previously-locked hwspinlock. Always succeed, and can be called
268   code should **never** unlock an hwspinlock which is already unlocked
273   void hwspin_unlock_irq(struct hwspinlock *hwlock);
275 Unlock a previously-locked hwspinlock and enable local interrupts.
276 The caller should **never** unlock an hwspinlock which is already unlocked.
285   hwspin_unlock_irqrestore(struct hwspinlock *hwlock, unsigned long *flags);
287 Unlock a previously-locked hwspinlock.
289 The caller should **never** unlock an hwspinlock which is already unlocked.
297   void hwspin_unlock_raw(struct hwspinlock *hwlock);
299 Unlock a previously-locked hwspinlock.
301 The caller should **never** unlock an hwspinlock which is already unlocked.
307   void hwspin_unlock_in_atomic(struct hwspinlock *hwlock);
309 Unlock a previously-locked hwspinlock.
311 The caller should **never** unlock an hwspinlock which is already unlocked.
317   int hwspin_lock_get_id(struct hwspinlock *hwlock);
319 Retrieve id number of a given hwspinlock. This is needed when an
320 hwspinlock is dynamically assigned: before it can be used to achieve
324 Returns the hwspinlock id number, or -EINVAL if hwlock is null.
331 	#include <linux/hwspinlock.h>
336 		struct hwspinlock *hwlock;
339 		/* dynamically assign a hwspinlock */
369 		struct hwspinlock *hwlock;
373 		* assign a specific hwspinlock id - this should be called early
412 order to register a new hwspinlock device (which is usually a bank of
423 to unregister an hwspinlock device (which is usually a bank of numerous
428 Returns the address of hwspinlock on success, or NULL on error (e.g.
429 if the hwspinlock is still in use).
435 of hardware locks. It is registered by the underlying hwspinlock
443 	* @ops: platform-specific hwspinlock handlers
446 	* @lock: dynamically allocated array of 'struct hwspinlock'
453 		struct hwspinlock lock[0];
456 struct hwspinlock_device contains an array of hwspinlock structs, each
460 	* struct hwspinlock - this struct represents a single hwspinlock instance
462 	* @lock: initialized and used by hwspinlock core
463 	* @priv: private data, owned by the underlying platform-specific hwspinlock drv
465 	struct hwspinlock {
471 When registering a bank of locks, the hwspinlock driver only needs to
473 initialized by the hwspinlock core itself.
481 		int (*trylock)(struct hwspinlock *lock);
482 		void (*unlock)(struct hwspinlock *lock);
483 		void (*relax)(struct hwspinlock *lock);
494 The ->relax() callback is optional. It is called by hwspinlock core while