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