1 ===========================
2 Hardware Spinlock Framework
3 ===========================
4
5 Introduction
6 ============
7
8 Hardware spinlock modules provide hardware assistance for synchronization
9 and mutual exclusion between heterogeneous processors and those not operating
10 under a single, shared operating system.
11
12 For example, OMAP4 has dual Cortex-A9, dual Cortex-M3 and a C64x+ DSP,
13 each of which is running a different Operating System (the master, A9,
14 is usually running Linux and the slave processors, the M3 and the DSP,
15 are running some flavor of RTOS).
16
17 A generic hwspinlock framework allows platform-independent drivers to use
18 the hwspinlock device in order to access data structures that are shared
19 between remote processors, that otherwise have no alternative mechanism
20 to accomplish synchronization and mutual exclusion operations.
21
22 This is necessary, for example, for Inter-processor communications:
23 on OMAP4, cpu-intensive multimedia tasks are offloaded by the host to the
24 remote M3 and/or C64x+ slave processors (by an IPC subsystem called Syslink).
25
26 To achieve fast message-based communications, a minimal kernel support
27 is needed to deliver messages arriving from a remote processor to the
28 appropriate user process.
29
30 This communication is based on simple data structures that is shared between
31 the remote processors, and access to it is synchronized using the hwspinlock
32 module (remote processor directly places new messages in this shared data
33 structure).
34
35 A common hwspinlock interface makes it possible to have generic, platform-
36 independent, drivers.
37
38 User API
39 ========
40
41 ::
42
43 struct hwspinlock *hwspin_lock_request(void);
44
45 Dynamically assign an hwspinlock and return its address, or NULL
46 in case an unused hwspinlock isn't available. Users of this
47 API will usually want to communicate the lock's id to the remote core
48 before it can be used to achieve synchronization.
49
50 Should be called from a process context (might sleep).
51
52 ::
53
54 struct hwspinlock *hwspin_lock_request_specific(unsigned int id);
55
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
59 ids for predefined purposes.
60
61 Should be called from a process context (might sleep).
62
63 ::
64
65 int of_hwspin_lock_get_id(struct device_node *np, int index);
66
67 Retrieve the global lock id for an OF phandle-based specific lock.
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
70 be requested using the normal hwspin_lock_request_specific() API.
71
72 The function returns a lock id number on success, -EPROBE_DEFER if
73 the hwspinlock device is not yet registered with the core, or other
74 error values.
75
76 Should be called from a process context (might sleep).
77
78 ::
79
80 int hwspin_lock_free(struct hwspinlock *hwlock);
81
82 Free a previously-assigned hwspinlock; returns 0 on success, or an
83 appropriate error code on failure (e.g. -EINVAL if the hwspinlock
84 is already free).
85
86 Should be called from a process context (might sleep).
87
88 ::
89
90 int hwspin_lock_bust(struct hwspinlock *hwlock, unsigned int id);
91
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
94 (e.g. -EOPNOTSUPP if the bust operation is not defined for the specific
95 hwspinlock).
96
97 Should be called from a process context (might sleep).
98
99 ::
100
101 int hwspin_lock_timeout(struct hwspinlock *hwlock, unsigned int timeout);
102
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
105 waiting for it to be released, but give up when the timeout elapses.
106 Upon a successful return from this function, preemption is disabled so
107 the caller must not sleep, and is advised to release the hwspinlock as
108 soon as possible, in order to minimize remote cores polling on the
109 hardware interconnect.
110
111 Returns 0 when successful and an appropriate error code otherwise (most
112 notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
113 The function will never sleep.
114
115 ::
116
117 int hwspin_lock_timeout_irq(struct hwspinlock *hwlock, unsigned int timeout);
118
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
121 waiting for it to be released, but give up when the timeout elapses.
122 Upon a successful return from this function, preemption and the local
123 interrupts are disabled, so the caller must not sleep, and is advised to
124 release the hwspinlock as soon as possible.
125
126 Returns 0 when successful and an appropriate error code otherwise (most
127 notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
128 The function will never sleep.
129
130 ::
131
132 int hwspin_lock_timeout_irqsave(struct hwspinlock *hwlock, unsigned int to,
133 unsigned long *flags);
134
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
137 waiting for it to be released, but give up when the timeout elapses.
138 Upon a successful return from this function, preemption is disabled,
139 local interrupts are disabled and their previous state is saved at the
140 given flags placeholder. The caller must not sleep, and is advised to
141 release the hwspinlock as soon as possible.
142
143 Returns 0 when successful and an appropriate error code otherwise (most
144 notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
145
146 The function will never sleep.
147
148 ::
149
150 int hwspin_lock_timeout_raw(struct hwspinlock *hwlock, unsigned int timeout);
151
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
154 waiting for it to be released, but give up when the timeout elapses.
155
156 Caution: User must protect the routine of getting hardware lock with mutex
157 or spinlock to avoid dead-lock, that will let user can do some time-consuming
158 or sleepable operations under the hardware lock.
159
160 Returns 0 when successful and an appropriate error code otherwise (most
161 notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
162
163 The function will never sleep.
164
165 ::
166
167 int hwspin_lock_timeout_in_atomic(struct hwspinlock *hwlock, unsigned int to);
168
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
171 waiting for it to be released, but give up when the timeout elapses.
172
173 This function shall be called only from an atomic context and the timeout
174 value shall not exceed a few msecs.
175
176 Returns 0 when successful and an appropriate error code otherwise (most
177 notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
178
179 The function will never sleep.
180
181 ::
182
183 int hwspin_trylock(struct hwspinlock *hwlock);
184
185
186 Attempt to lock a previously-assigned hwspinlock, but immediately fail if
187 it is already taken.
188
189 Upon a successful return from this function, preemption is disabled so
190 caller must not sleep, and is advised to release the hwspinlock as soon as
191 possible, in order to minimize remote cores polling on the hardware
192 interconnect.
193
194 Returns 0 on success and an appropriate error code otherwise (most
195 notably -EBUSY if the hwspinlock was already taken).
196 The function will never sleep.
197
198 ::
199
200 int hwspin_trylock_irq(struct hwspinlock *hwlock);
201
202
203 Attempt to lock a previously-assigned hwspinlock, but immediately fail if
204 it is already taken.
205
206 Upon a successful return from this function, preemption and the local
207 interrupts are disabled so caller must not sleep, and is advised to
208 release the hwspinlock as soon as possible.
209
210 Returns 0 on success and an appropriate error code otherwise (most
211 notably -EBUSY if the hwspinlock was already taken).
212
213 The function will never sleep.
214
215 ::
216
217 int hwspin_trylock_irqsave(struct hwspinlock *hwlock, unsigned long *flags);
218
219 Attempt to lock a previously-assigned hwspinlock, but immediately fail if
220 it is already taken.
221
222 Upon a successful return from this function, preemption is disabled,
223 the local interrupts are disabled and their previous state is saved
224 at the given flags placeholder. The caller must not sleep, and is advised
225 to release the hwspinlock as soon as possible.
226
227 Returns 0 on success and an appropriate error code otherwise (most
228 notably -EBUSY if the hwspinlock was already taken).
229 The function will never sleep.
230
231 ::
232
233 int hwspin_trylock_raw(struct hwspinlock *hwlock);
234
235 Attempt to lock a previously-assigned hwspinlock, but immediately fail if
236 it is already taken.
237
238 Caution: User must protect the routine of getting hardware lock with mutex
239 or spinlock to avoid dead-lock, that will let user can do some time-consuming
240 or sleepable operations under the hardware lock.
241
242 Returns 0 on success and an appropriate error code otherwise (most
243 notably -EBUSY if the hwspinlock was already taken).
244 The function will never sleep.
245
246 ::
247
248 int hwspin_trylock_in_atomic(struct hwspinlock *hwlock);
249
250 Attempt to lock a previously-assigned hwspinlock, but immediately fail if
251 it is already taken.
252
253 This function shall be called only from an atomic context.
254
255 Returns 0 on success and an appropriate error code otherwise (most
256 notably -EBUSY if the hwspinlock was already taken).
257 The function will never sleep.
258
259 ::
260
261 void hwspin_unlock(struct hwspinlock *hwlock);
262
263 Unlock a previously-locked hwspinlock. Always succeed, and can be called
264 from any context (the function never sleeps).
265
266 .. note::
267
268 code should **never** unlock an hwspinlock which is already unlocked
269 (there is no protection against this).
270
271 ::
272
273 void hwspin_unlock_irq(struct hwspinlock *hwlock);
274
275 Unlock a previously-locked hwspinlock and enable local interrupts.
276 The caller should **never** unlock an hwspinlock which is already unlocked.
277
278 Doing so is considered a bug (there is no protection against this).
279 Upon a successful return from this function, preemption and local
280 interrupts are enabled. This function will never sleep.
281
282 ::
283
284 void
285 hwspin_unlock_irqrestore(struct hwspinlock *hwlock, unsigned long *flags);
286
287 Unlock a previously-locked hwspinlock.
288
289 The caller should **never** unlock an hwspinlock which is already unlocked.
290 Doing so is considered a bug (there is no protection against this).
291 Upon a successful return from this function, preemption is reenabled,
292 and the state of the local interrupts is restored to the state saved at
293 the given flags. This function will never sleep.
294
295 ::
296
297 void hwspin_unlock_raw(struct hwspinlock *hwlock);
298
299 Unlock a previously-locked hwspinlock.
300
301 The caller should **never** unlock an hwspinlock which is already unlocked.
302 Doing so is considered a bug (there is no protection against this).
303 This function will never sleep.
304
305 ::
306
307 void hwspin_unlock_in_atomic(struct hwspinlock *hwlock);
308
309 Unlock a previously-locked hwspinlock.
310
311 The caller should **never** unlock an hwspinlock which is already unlocked.
312 Doing so is considered a bug (there is no protection against this).
313 This function will never sleep.
314
315 ::
316
317 int hwspin_lock_get_id(struct hwspinlock *hwlock);
318
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
321 mutual exclusion with a remote cpu, the id number should be communicated
322 to the remote task with which we want to synchronize.
323
324 Returns the hwspinlock id number, or -EINVAL if hwlock is null.
325
326 Typical usage
327 =============
328
329 ::
330
331 #include <linux/hwspinlock.h>
332 #include <linux/err.h>
333
334 int hwspinlock_example1(void)
335 {
336 struct hwspinlock *hwlock;
337 int ret;
338
339 /* dynamically assign a hwspinlock */
340 hwlock = hwspin_lock_request();
341 if (!hwlock)
342 ...
343
344 id = hwspin_lock_get_id(hwlock);
345 /* probably need to communicate id to a remote processor now */
346
347 /* take the lock, spin for 1 sec if it's already taken */
348 ret = hwspin_lock_timeout(hwlock, 1000);
349 if (ret)
350 ...
351
352 /*
353 * we took the lock, do our thing now, but do NOT sleep
354 */
355
356 /* release the lock */
357 hwspin_unlock(hwlock);
358
359 /* free the lock */
360 ret = hwspin_lock_free(hwlock);
361 if (ret)
362 ...
363
364 return ret;
365 }
366
367 int hwspinlock_example2(void)
368 {
369 struct hwspinlock *hwlock;
370 int ret;
371
372 /*
373 * assign a specific hwspinlock id - this should be called early
374 * by board init code.
375 */
376 hwlock = hwspin_lock_request_specific(PREDEFINED_LOCK_ID);
377 if (!hwlock)
378 ...
379
380 /* try to take it, but don't spin on it */
381 ret = hwspin_trylock(hwlock);
382 if (!ret) {
383 pr_info("lock is already taken\n");
384 return -EBUSY;
385 }
386
387 /*
388 * we took the lock, do our thing now, but do NOT sleep
389 */
390
391 /* release the lock */
392 hwspin_unlock(hwlock);
393
394 /* free the lock */
395 ret = hwspin_lock_free(hwlock);
396 if (ret)
397 ...
398
399 return ret;
400 }
401
402
403 API for implementors
404 ====================
405
406 ::
407
408 int hwspin_lock_register(struct hwspinlock_device *bank, struct device *dev,
409 const struct hwspinlock_ops *ops, int base_id, int num_locks);
410
411 To be called from the underlying platform-specific implementation, in
412 order to register a new hwspinlock device (which is usually a bank of
413 numerous locks). Should be called from a process context (this function
414 might sleep).
415
416 Returns 0 on success, or appropriate error code on failure.
417
418 ::
419
420 int hwspin_lock_unregister(struct hwspinlock_device *bank);
421
422 To be called from the underlying vendor-specific implementation, in order
423 to unregister an hwspinlock device (which is usually a bank of numerous
424 locks).
425
426 Should be called from a process context (this function might sleep).
427
428 Returns the address of hwspinlock on success, or NULL on error (e.g.
429 if the hwspinlock is still in use).
430
431 Important structs
432 =================
433
434 struct hwspinlock_device is a device which usually contains a bank
435 of hardware locks. It is registered by the underlying hwspinlock
436 implementation using the hwspin_lock_register() API.
437
438 ::
439
440 /**
441 * struct hwspinlock_device - a device which usually spans numerous hwspinlocks
442 * @dev: underlying device, will be used to invoke runtime PM api
443 * @ops: platform-specific hwspinlock handlers
444 * @base_id: id index of the first lock in this device
445 * @num_locks: number of locks in this device
446 * @lock: dynamically allocated array of 'struct hwspinlock'
447 */
448 struct hwspinlock_device {
449 struct device *dev;
450 const struct hwspinlock_ops *ops;
451 int base_id;
452 int num_locks;
453 struct hwspinlock lock[0];
454 };
455
456 struct hwspinlock_device contains an array of hwspinlock structs, each
457 of which represents a single hardware lock::
458
459 /**
460 * struct hwspinlock - this struct represents a single hwspinlock instance
461 * @bank: the hwspinlock_device structure which owns this lock
462 * @lock: initialized and used by hwspinlock core
463 * @priv: private data, owned by the underlying platform-specific hwspinlock drv
464 */
465 struct hwspinlock {
466 struct hwspinlock_device *bank;
467 spinlock_t lock;
468 void *priv;
469 };
470
471 When registering a bank of locks, the hwspinlock driver only needs to
472 set the priv members of the locks. The rest of the members are set and
473 initialized by the hwspinlock core itself.
474
475 Implementation callbacks
476 ========================
477
478 There are three possible callbacks defined in 'struct hwspinlock_ops'::
479
480 struct hwspinlock_ops {
481 int (*trylock)(struct hwspinlock *lock);
482 void (*unlock)(struct hwspinlock *lock);
483 void (*relax)(struct hwspinlock *lock);
484 };
485
486 The first two callbacks are mandatory:
487
488 The ->trylock() callback should make a single attempt to take the lock, and
489 return 0 on failure and 1 on success. This callback may **not** sleep.
490
491 The ->unlock() callback releases the lock. It always succeed, and it, too,
492 may **not** sleep.
493
494 The ->relax() callback is optional. It is called by hwspinlock core while
495 spinning on a lock, and can be used by the underlying implementation to force
496 a delay between two successive invocations of ->trylock(). It may **not** sleep.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.