1 ===========================
2 Hardware Spinlock Framework
3 ===========================
4
5 Introduction
6 ============
7
8 Hardware spinlock modules provide hardware ass
9 and mutual exclusion between heterogeneous pro
10 under a single, shared operating system.
11
12 For example, OMAP4 has dual Cortex-A9, dual Co
13 each of which is running a different Operating
14 is usually running Linux and the slave process
15 are running some flavor of RTOS).
16
17 A generic hwspinlock framework allows platform
18 the hwspinlock device in order to access data
19 between remote processors, that otherwise have
20 to accomplish synchronization and mutual exclu
21
22 This is necessary, for example, for Inter-proc
23 on OMAP4, cpu-intensive multimedia tasks are o
24 remote M3 and/or C64x+ slave processors (by an
25
26 To achieve fast message-based communications,
27 is needed to deliver messages arriving from a
28 appropriate user process.
29
30 This communication is based on simple data str
31 the remote processors, and access to it is syn
32 module (remote processor directly places new m
33 structure).
34
35 A common hwspinlock interface makes it possibl
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 it
46 in case an unused hwspinlock isn't available.
47 API will usually want to communicate the lock'
48 before it can be used to achieve synchronizati
49
50 Should be called from a process context (might
51
52 ::
53
54 struct hwspinlock *hwspin_lock_request_speci
55
56 Assign a specific hwspinlock id and return its
57 if that hwspinlock is already in use. Usually
58 be calling this function in order to reserve s
59 ids for predefined purposes.
60
61 Should be called from a process context (might
62
63 ::
64
65 int of_hwspin_lock_get_id(struct device_node
66
67 Retrieve the global lock id for an OF phandle-
68 This function provides a means for DT users of
69 to get the global lock id of a specific hwspin
70 be requested using the normal hwspin_lock_requ
71
72 The function returns a lock id number on succe
73 the hwspinlock device is not yet registered wi
74 error values.
75
76 Should be called from a process context (might
77
78 ::
79
80 int hwspin_lock_free(struct hwspinlock *hwlo
81
82 Free a previously-assigned hwspinlock; returns
83 appropriate error code on failure (e.g. -EINVA
84 is already free).
85
86 Should be called from a process context (might
87
88 ::
89
90 int hwspin_lock_bust(struct hwspinlock *hwlo
91
92 After verifying the owner of the hwspinlock, r
93 hwspinlock; returns 0 on success, or an approp
94 (e.g. -EOPNOTSUPP if the bust operation is not
95 hwspinlock).
96
97 Should be called from a process context (might
98
99 ::
100
101 int hwspin_lock_timeout(struct hwspinlock *h
102
103 Lock a previously-assigned hwspinlock with a t
104 msecs). If the hwspinlock is already taken, th
105 waiting for it to be released, but give up whe
106 Upon a successful return from this function, p
107 the caller must not sleep, and is advised to r
108 soon as possible, in order to minimize remote
109 hardware interconnect.
110
111 Returns 0 when successful and an appropriate e
112 notably -ETIMEDOUT if the hwspinlock is still
113 The function will never sleep.
114
115 ::
116
117 int hwspin_lock_timeout_irq(struct hwspinloc
118
119 Lock a previously-assigned hwspinlock with a t
120 msecs). If the hwspinlock is already taken, th
121 waiting for it to be released, but give up whe
122 Upon a successful return from this function, p
123 interrupts are disabled, so the caller must no
124 release the hwspinlock as soon as possible.
125
126 Returns 0 when successful and an appropriate e
127 notably -ETIMEDOUT if the hwspinlock is still
128 The function will never sleep.
129
130 ::
131
132 int hwspin_lock_timeout_irqsave(struct hwspi
133 unsigned lon
134
135 Lock a previously-assigned hwspinlock with a t
136 msecs). If the hwspinlock is already taken, th
137 waiting for it to be released, but give up whe
138 Upon a successful return from this function, p
139 local interrupts are disabled and their previo
140 given flags placeholder. The caller must not s
141 release the hwspinlock as soon as possible.
142
143 Returns 0 when successful and an appropriate e
144 notably -ETIMEDOUT if the hwspinlock is still
145
146 The function will never sleep.
147
148 ::
149
150 int hwspin_lock_timeout_raw(struct hwspinloc
151
152 Lock a previously-assigned hwspinlock with a t
153 msecs). If the hwspinlock is already taken, th
154 waiting for it to be released, but give up whe
155
156 Caution: User must protect the routine of gett
157 or spinlock to avoid dead-lock, that will let
158 or sleepable operations under the hardware loc
159
160 Returns 0 when successful and an appropriate e
161 notably -ETIMEDOUT if the hwspinlock is still
162
163 The function will never sleep.
164
165 ::
166
167 int hwspin_lock_timeout_in_atomic(struct hws
168
169 Lock a previously-assigned hwspinlock with a t
170 msecs). If the hwspinlock is already taken, th
171 waiting for it to be released, but give up whe
172
173 This function shall be called only from an ato
174 value shall not exceed a few msecs.
175
176 Returns 0 when successful and an appropriate e
177 notably -ETIMEDOUT if the hwspinlock is still
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 hwspinlo
187 it is already taken.
188
189 Upon a successful return from this function, p
190 caller must not sleep, and is advised to relea
191 possible, in order to minimize remote cores po
192 interconnect.
193
194 Returns 0 on success and an appropriate error
195 notably -EBUSY if the hwspinlock was already t
196 The function will never sleep.
197
198 ::
199
200 int hwspin_trylock_irq(struct hwspinlock *hw
201
202
203 Attempt to lock a previously-assigned hwspinlo
204 it is already taken.
205
206 Upon a successful return from this function, p
207 interrupts are disabled so caller must not sle
208 release the hwspinlock as soon as possible.
209
210 Returns 0 on success and an appropriate error
211 notably -EBUSY if the hwspinlock was already t
212
213 The function will never sleep.
214
215 ::
216
217 int hwspin_trylock_irqsave(struct hwspinlock
218
219 Attempt to lock a previously-assigned hwspinlo
220 it is already taken.
221
222 Upon a successful return from this function, p
223 the local interrupts are disabled and their pr
224 at the given flags placeholder. The caller mus
225 to release the hwspinlock as soon as possible.
226
227 Returns 0 on success and an appropriate error
228 notably -EBUSY if the hwspinlock was already t
229 The function will never sleep.
230
231 ::
232
233 int hwspin_trylock_raw(struct hwspinlock *hw
234
235 Attempt to lock a previously-assigned hwspinlo
236 it is already taken.
237
238 Caution: User must protect the routine of gett
239 or spinlock to avoid dead-lock, that will let
240 or sleepable operations under the hardware loc
241
242 Returns 0 on success and an appropriate error
243 notably -EBUSY if the hwspinlock was already t
244 The function will never sleep.
245
246 ::
247
248 int hwspin_trylock_in_atomic(struct hwspinlo
249
250 Attempt to lock a previously-assigned hwspinlo
251 it is already taken.
252
253 This function shall be called only from an ato
254
255 Returns 0 on success and an appropriate error
256 notably -EBUSY if the hwspinlock was already t
257 The function will never sleep.
258
259 ::
260
261 void hwspin_unlock(struct hwspinlock *hwlock
262
263 Unlock a previously-locked hwspinlock. Always
264 from any context (the function never sleeps).
265
266 .. note::
267
268 code should **never** unlock an hwspinlock w
269 (there is no protection against this).
270
271 ::
272
273 void hwspin_unlock_irq(struct hwspinlock *hw
274
275 Unlock a previously-locked hwspinlock and enab
276 The caller should **never** unlock an hwspinlo
277
278 Doing so is considered a bug (there is no prot
279 Upon a successful return from this function, p
280 interrupts are enabled. This function will nev
281
282 ::
283
284 void
285 hwspin_unlock_irqrestore(struct hwspinlock *
286
287 Unlock a previously-locked hwspinlock.
288
289 The caller should **never** unlock an hwspinlo
290 Doing so is considered a bug (there is no prot
291 Upon a successful return from this function, p
292 and the state of the local interrupts is resto
293 the given flags. This function will never slee
294
295 ::
296
297 void hwspin_unlock_raw(struct hwspinlock *hw
298
299 Unlock a previously-locked hwspinlock.
300
301 The caller should **never** unlock an hwspinlo
302 Doing so is considered a bug (there is no prot
303 This function will never sleep.
304
305 ::
306
307 void hwspin_unlock_in_atomic(struct hwspinlo
308
309 Unlock a previously-locked hwspinlock.
310
311 The caller should **never** unlock an hwspinlo
312 Doing so is considered a bug (there is no prot
313 This function will never sleep.
314
315 ::
316
317 int hwspin_lock_get_id(struct hwspinlock *hw
318
319 Retrieve id number of a given hwspinlock. This
320 hwspinlock is dynamically assigned: before it
321 mutual exclusion with a remote cpu, the id num
322 to the remote task with which we want to synch
323
324 Returns the hwspinlock id number, or -EINVAL i
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 hwspin
340 hwlock = hwspin_lock_request()
341 if (!hwlock)
342 ...
343
344 id = hwspin_lock_get_id(hwlock
345 /* probably need to communicat
346
347 /* take the lock, spin for 1 s
348 ret = hwspin_lock_timeout(hwlo
349 if (ret)
350 ...
351
352 /*
353 * we took the lock, do our thi
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
374 * by board init code.
375 */
376 hwlock = hwspin_lock_request_s
377 if (!hwlock)
378 ...
379
380 /* try to take it, but don't s
381 ret = hwspin_trylock(hwlock);
382 if (!ret) {
383 pr_info("lock is alrea
384 return -EBUSY;
385 }
386
387 /*
388 * we took the lock, do our thi
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_d
409 const struct hwspinlock_ops *o
410
411 To be called from the underlying platform-spec
412 order to register a new hwspinlock device (whi
413 numerous locks). Should be called from a proce
414 might sleep).
415
416 Returns 0 on success, or appropriate error cod
417
418 ::
419
420 int hwspin_lock_unregister(struct hwspinlock
421
422 To be called from the underlying vendor-specif
423 to unregister an hwspinlock device (which is u
424 locks).
425
426 Should be called from a process context (this
427
428 Returns the address of hwspinlock on success,
429 if the hwspinlock is still in use).
430
431 Important structs
432 =================
433
434 struct hwspinlock_device is a device which usu
435 of hardware locks. It is registered by the und
436 implementation using the hwspin_lock_register(
437
438 ::
439
440 /**
441 * struct hwspinlock_device - a device
442 * @dev: underlying device, will be use
443 * @ops: platform-specific hwspinlock h
444 * @base_id: id index of the first lock
445 * @num_locks: number of locks in this
446 * @lock: dynamically allocated array o
447 */
448 struct hwspinlock_device {
449 struct device *dev;
450 const struct hwspinlock_ops *o
451 int base_id;
452 int num_locks;
453 struct hwspinlock lock[0];
454 };
455
456 struct hwspinlock_device contains an array of
457 of which represents a single hardware lock::
458
459 /**
460 * struct hwspinlock - this struct repr
461 * @bank: the hwspinlock_device structu
462 * @lock: initialized and used by hwspi
463 * @priv: private data, owned by the un
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 hwspinlo
472 set the priv members of the locks. The rest of
473 initialized by the hwspinlock core itself.
474
475 Implementation callbacks
476 ========================
477
478 There are three possible callbacks defined in
479
480 struct hwspinlock_ops {
481 int (*trylock)(struct hwspinlo
482 void (*unlock)(struct hwspinlo
483 void (*relax)(struct hwspinloc
484 };
485
486 The first two callbacks are mandatory:
487
488 The ->trylock() callback should make a single
489 return 0 on failure and 1 on success. This cal
490
491 The ->unlock() callback releases the lock. It
492 may **not** sleep.
493
494 The ->relax() callback is optional. It is call
495 spinning on a lock, and can be used by the und
496 a delay between two successive invocations of
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.