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 90 int hwspin_lock_bust(struct hwspinlock *hwlock, unsigned int id);
91 91
92 After verifying the owner of the hwspinlock, r 92 After verifying the owner of the hwspinlock, release a previously acquired
93 hwspinlock; returns 0 on success, or an approp 93 hwspinlock; returns 0 on success, or an appropriate error code on failure
94 (e.g. -EOPNOTSUPP if the bust operation is not 94 (e.g. -EOPNOTSUPP if the bust operation is not defined for the specific
95 hwspinlock). 95 hwspinlock).
96 96
97 Should be called from a process context (might 97 Should be called from a process context (might sleep).
98 98
99 :: 99 ::
100 100
101 int hwspin_lock_timeout(struct hwspinlock *h 101 int hwspin_lock_timeout(struct hwspinlock *hwlock, unsigned int timeout);
102 102
103 Lock a previously-assigned hwspinlock with a t 103 Lock a previously-assigned hwspinlock with a timeout limit (specified in
104 msecs). If the hwspinlock is already taken, th 104 msecs). If the hwspinlock is already taken, the function will busy loop
105 waiting for it to be released, but give up whe 105 waiting for it to be released, but give up when the timeout elapses.
106 Upon a successful return from this function, p 106 Upon a successful return from this function, preemption is disabled so
107 the caller must not sleep, and is advised to r 107 the caller must not sleep, and is advised to release the hwspinlock as
108 soon as possible, in order to minimize remote 108 soon as possible, in order to minimize remote cores polling on the
109 hardware interconnect. 109 hardware interconnect.
110 110
111 Returns 0 when successful and an appropriate e 111 Returns 0 when successful and an appropriate error code otherwise (most
112 notably -ETIMEDOUT if the hwspinlock is still 112 notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
113 The function will never sleep. 113 The function will never sleep.
114 114
115 :: 115 ::
116 116
117 int hwspin_lock_timeout_irq(struct hwspinloc 117 int hwspin_lock_timeout_irq(struct hwspinlock *hwlock, unsigned int timeout);
118 118
119 Lock a previously-assigned hwspinlock with a t 119 Lock a previously-assigned hwspinlock with a timeout limit (specified in
120 msecs). If the hwspinlock is already taken, th 120 msecs). If the hwspinlock is already taken, the function will busy loop
121 waiting for it to be released, but give up whe 121 waiting for it to be released, but give up when the timeout elapses.
122 Upon a successful return from this function, p 122 Upon a successful return from this function, preemption and the local
123 interrupts are disabled, so the caller must no 123 interrupts are disabled, so the caller must not sleep, and is advised to
124 release the hwspinlock as soon as possible. 124 release the hwspinlock as soon as possible.
125 125
126 Returns 0 when successful and an appropriate e 126 Returns 0 when successful and an appropriate error code otherwise (most
127 notably -ETIMEDOUT if the hwspinlock is still 127 notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
128 The function will never sleep. 128 The function will never sleep.
129 129
130 :: 130 ::
131 131
132 int hwspin_lock_timeout_irqsave(struct hwspi 132 int hwspin_lock_timeout_irqsave(struct hwspinlock *hwlock, unsigned int to,
133 unsigned lon 133 unsigned long *flags);
134 134
135 Lock a previously-assigned hwspinlock with a t 135 Lock a previously-assigned hwspinlock with a timeout limit (specified in
136 msecs). If the hwspinlock is already taken, th 136 msecs). If the hwspinlock is already taken, the function will busy loop
137 waiting for it to be released, but give up whe 137 waiting for it to be released, but give up when the timeout elapses.
138 Upon a successful return from this function, p 138 Upon a successful return from this function, preemption is disabled,
139 local interrupts are disabled and their previo 139 local interrupts are disabled and their previous state is saved at the
140 given flags placeholder. The caller must not s 140 given flags placeholder. The caller must not sleep, and is advised to
141 release the hwspinlock as soon as possible. 141 release the hwspinlock as soon as possible.
142 142
143 Returns 0 when successful and an appropriate e 143 Returns 0 when successful and an appropriate error code otherwise (most
144 notably -ETIMEDOUT if the hwspinlock is still 144 notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
145 145
146 The function will never sleep. 146 The function will never sleep.
147 147
148 :: 148 ::
149 149
150 int hwspin_lock_timeout_raw(struct hwspinloc 150 int hwspin_lock_timeout_raw(struct hwspinlock *hwlock, unsigned int timeout);
151 151
152 Lock a previously-assigned hwspinlock with a t 152 Lock a previously-assigned hwspinlock with a timeout limit (specified in
153 msecs). If the hwspinlock is already taken, th 153 msecs). If the hwspinlock is already taken, the function will busy loop
154 waiting for it to be released, but give up whe 154 waiting for it to be released, but give up when the timeout elapses.
155 155
156 Caution: User must protect the routine of gett 156 Caution: User must protect the routine of getting hardware lock with mutex
157 or spinlock to avoid dead-lock, that will let 157 or spinlock to avoid dead-lock, that will let user can do some time-consuming
158 or sleepable operations under the hardware loc 158 or sleepable operations under the hardware lock.
159 159
160 Returns 0 when successful and an appropriate e 160 Returns 0 when successful and an appropriate error code otherwise (most
161 notably -ETIMEDOUT if the hwspinlock is still 161 notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
162 162
163 The function will never sleep. 163 The function will never sleep.
164 164
165 :: 165 ::
166 166
167 int hwspin_lock_timeout_in_atomic(struct hws 167 int hwspin_lock_timeout_in_atomic(struct hwspinlock *hwlock, unsigned int to);
168 168
169 Lock a previously-assigned hwspinlock with a t 169 Lock a previously-assigned hwspinlock with a timeout limit (specified in
170 msecs). If the hwspinlock is already taken, th 170 msecs). If the hwspinlock is already taken, the function will busy loop
171 waiting for it to be released, but give up whe 171 waiting for it to be released, but give up when the timeout elapses.
172 172
173 This function shall be called only from an ato 173 This function shall be called only from an atomic context and the timeout
174 value shall not exceed a few msecs. 174 value shall not exceed a few msecs.
175 175
176 Returns 0 when successful and an appropriate e 176 Returns 0 when successful and an appropriate error code otherwise (most
177 notably -ETIMEDOUT if the hwspinlock is still 177 notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
178 178
179 The function will never sleep. 179 The function will never sleep.
180 180
181 :: 181 ::
182 182
183 int hwspin_trylock(struct hwspinlock *hwlock 183 int hwspin_trylock(struct hwspinlock *hwlock);
184 184
185 185
186 Attempt to lock a previously-assigned hwspinlo 186 Attempt to lock a previously-assigned hwspinlock, but immediately fail if
187 it is already taken. 187 it is already taken.
188 188
189 Upon a successful return from this function, p 189 Upon a successful return from this function, preemption is disabled so
190 caller must not sleep, and is advised to relea 190 caller must not sleep, and is advised to release the hwspinlock as soon as
191 possible, in order to minimize remote cores po 191 possible, in order to minimize remote cores polling on the hardware
192 interconnect. 192 interconnect.
193 193
194 Returns 0 on success and an appropriate error 194 Returns 0 on success and an appropriate error code otherwise (most
195 notably -EBUSY if the hwspinlock was already t 195 notably -EBUSY if the hwspinlock was already taken).
196 The function will never sleep. 196 The function will never sleep.
197 197
198 :: 198 ::
199 199
200 int hwspin_trylock_irq(struct hwspinlock *hw 200 int hwspin_trylock_irq(struct hwspinlock *hwlock);
201 201
202 202
203 Attempt to lock a previously-assigned hwspinlo 203 Attempt to lock a previously-assigned hwspinlock, but immediately fail if
204 it is already taken. 204 it is already taken.
205 205
206 Upon a successful return from this function, p 206 Upon a successful return from this function, preemption and the local
207 interrupts are disabled so caller must not sle 207 interrupts are disabled so caller must not sleep, and is advised to
208 release the hwspinlock as soon as possible. 208 release the hwspinlock as soon as possible.
209 209
210 Returns 0 on success and an appropriate error 210 Returns 0 on success and an appropriate error code otherwise (most
211 notably -EBUSY if the hwspinlock was already t 211 notably -EBUSY if the hwspinlock was already taken).
212 212
213 The function will never sleep. 213 The function will never sleep.
214 214
215 :: 215 ::
216 216
217 int hwspin_trylock_irqsave(struct hwspinlock 217 int hwspin_trylock_irqsave(struct hwspinlock *hwlock, unsigned long *flags);
218 218
219 Attempt to lock a previously-assigned hwspinlo 219 Attempt to lock a previously-assigned hwspinlock, but immediately fail if
220 it is already taken. 220 it is already taken.
221 221
222 Upon a successful return from this function, p 222 Upon a successful return from this function, preemption is disabled,
223 the local interrupts are disabled and their pr 223 the local interrupts are disabled and their previous state is saved
224 at the given flags placeholder. The caller mus 224 at the given flags placeholder. The caller must not sleep, and is advised
225 to release the hwspinlock as soon as possible. 225 to release the hwspinlock as soon as possible.
226 226
227 Returns 0 on success and an appropriate error 227 Returns 0 on success and an appropriate error code otherwise (most
228 notably -EBUSY if the hwspinlock was already t 228 notably -EBUSY if the hwspinlock was already taken).
229 The function will never sleep. 229 The function will never sleep.
230 230
231 :: 231 ::
232 232
233 int hwspin_trylock_raw(struct hwspinlock *hw 233 int hwspin_trylock_raw(struct hwspinlock *hwlock);
234 234
235 Attempt to lock a previously-assigned hwspinlo 235 Attempt to lock a previously-assigned hwspinlock, but immediately fail if
236 it is already taken. 236 it is already taken.
237 237
238 Caution: User must protect the routine of gett 238 Caution: User must protect the routine of getting hardware lock with mutex
239 or spinlock to avoid dead-lock, that will let 239 or spinlock to avoid dead-lock, that will let user can do some time-consuming
240 or sleepable operations under the hardware loc 240 or sleepable operations under the hardware lock.
241 241
242 Returns 0 on success and an appropriate error 242 Returns 0 on success and an appropriate error code otherwise (most
243 notably -EBUSY if the hwspinlock was already t 243 notably -EBUSY if the hwspinlock was already taken).
244 The function will never sleep. 244 The function will never sleep.
245 245
246 :: 246 ::
247 247
248 int hwspin_trylock_in_atomic(struct hwspinlo 248 int hwspin_trylock_in_atomic(struct hwspinlock *hwlock);
249 249
250 Attempt to lock a previously-assigned hwspinlo 250 Attempt to lock a previously-assigned hwspinlock, but immediately fail if
251 it is already taken. 251 it is already taken.
252 252
253 This function shall be called only from an ato 253 This function shall be called only from an atomic context.
254 254
255 Returns 0 on success and an appropriate error 255 Returns 0 on success and an appropriate error code otherwise (most
256 notably -EBUSY if the hwspinlock was already t 256 notably -EBUSY if the hwspinlock was already taken).
257 The function will never sleep. 257 The function will never sleep.
258 258
259 :: 259 ::
260 260
261 void hwspin_unlock(struct hwspinlock *hwlock 261 void hwspin_unlock(struct hwspinlock *hwlock);
262 262
263 Unlock a previously-locked hwspinlock. Always 263 Unlock a previously-locked hwspinlock. Always succeed, and can be called
264 from any context (the function never sleeps). 264 from any context (the function never sleeps).
265 265
266 .. note:: 266 .. note::
267 267
268 code should **never** unlock an hwspinlock w 268 code should **never** unlock an hwspinlock which is already unlocked
269 (there is no protection against this). 269 (there is no protection against this).
270 270
271 :: 271 ::
272 272
273 void hwspin_unlock_irq(struct hwspinlock *hw 273 void hwspin_unlock_irq(struct hwspinlock *hwlock);
274 274
275 Unlock a previously-locked hwspinlock and enab 275 Unlock a previously-locked hwspinlock and enable local interrupts.
276 The caller should **never** unlock an hwspinlo 276 The caller should **never** unlock an hwspinlock which is already unlocked.
277 277
278 Doing so is considered a bug (there is no prot 278 Doing so is considered a bug (there is no protection against this).
279 Upon a successful return from this function, p 279 Upon a successful return from this function, preemption and local
280 interrupts are enabled. This function will nev 280 interrupts are enabled. This function will never sleep.
281 281
282 :: 282 ::
283 283
284 void 284 void
285 hwspin_unlock_irqrestore(struct hwspinlock * 285 hwspin_unlock_irqrestore(struct hwspinlock *hwlock, unsigned long *flags);
286 286
287 Unlock a previously-locked hwspinlock. 287 Unlock a previously-locked hwspinlock.
288 288
289 The caller should **never** unlock an hwspinlo 289 The caller should **never** unlock an hwspinlock which is already unlocked.
290 Doing so is considered a bug (there is no prot 290 Doing so is considered a bug (there is no protection against this).
291 Upon a successful return from this function, p 291 Upon a successful return from this function, preemption is reenabled,
292 and the state of the local interrupts is resto 292 and the state of the local interrupts is restored to the state saved at
293 the given flags. This function will never slee 293 the given flags. This function will never sleep.
294 294
295 :: 295 ::
296 296
297 void hwspin_unlock_raw(struct hwspinlock *hw 297 void hwspin_unlock_raw(struct hwspinlock *hwlock);
298 298
299 Unlock a previously-locked hwspinlock. 299 Unlock a previously-locked hwspinlock.
300 300
301 The caller should **never** unlock an hwspinlo 301 The caller should **never** unlock an hwspinlock which is already unlocked.
302 Doing so is considered a bug (there is no prot 302 Doing so is considered a bug (there is no protection against this).
303 This function will never sleep. 303 This function will never sleep.
304 304
305 :: 305 ::
306 306
307 void hwspin_unlock_in_atomic(struct hwspinlo 307 void hwspin_unlock_in_atomic(struct hwspinlock *hwlock);
308 308
309 Unlock a previously-locked hwspinlock. 309 Unlock a previously-locked hwspinlock.
310 310
311 The caller should **never** unlock an hwspinlo 311 The caller should **never** unlock an hwspinlock which is already unlocked.
312 Doing so is considered a bug (there is no prot 312 Doing so is considered a bug (there is no protection against this).
313 This function will never sleep. 313 This function will never sleep.
314 314
315 :: 315 ::
316 316
317 int hwspin_lock_get_id(struct hwspinlock *hw 317 int hwspin_lock_get_id(struct hwspinlock *hwlock);
318 318
319 Retrieve id number of a given hwspinlock. This 319 Retrieve id number of a given hwspinlock. This is needed when an
320 hwspinlock is dynamically assigned: before it 320 hwspinlock is dynamically assigned: before it can be used to achieve
321 mutual exclusion with a remote cpu, the id num 321 mutual exclusion with a remote cpu, the id number should be communicated
322 to the remote task with which we want to synch 322 to the remote task with which we want to synchronize.
323 323
324 Returns the hwspinlock id number, or -EINVAL i 324 Returns the hwspinlock id number, or -EINVAL if hwlock is null.
325 325
326 Typical usage 326 Typical usage
327 ============= 327 =============
328 328
329 :: 329 ::
330 330
331 #include <linux/hwspinlock.h> 331 #include <linux/hwspinlock.h>
332 #include <linux/err.h> 332 #include <linux/err.h>
333 333
334 int hwspinlock_example1(void) 334 int hwspinlock_example1(void)
335 { 335 {
336 struct hwspinlock *hwlock; 336 struct hwspinlock *hwlock;
337 int ret; 337 int ret;
338 338
339 /* dynamically assign a hwspin 339 /* dynamically assign a hwspinlock */
340 hwlock = hwspin_lock_request() 340 hwlock = hwspin_lock_request();
341 if (!hwlock) 341 if (!hwlock)
342 ... 342 ...
343 343
344 id = hwspin_lock_get_id(hwlock 344 id = hwspin_lock_get_id(hwlock);
345 /* probably need to communicat 345 /* probably need to communicate id to a remote processor now */
346 346
347 /* take the lock, spin for 1 s 347 /* take the lock, spin for 1 sec if it's already taken */
348 ret = hwspin_lock_timeout(hwlo 348 ret = hwspin_lock_timeout(hwlock, 1000);
349 if (ret) 349 if (ret)
350 ... 350 ...
351 351
352 /* 352 /*
353 * we took the lock, do our thi 353 * we took the lock, do our thing now, but do NOT sleep
354 */ 354 */
355 355
356 /* release the lock */ 356 /* release the lock */
357 hwspin_unlock(hwlock); 357 hwspin_unlock(hwlock);
358 358
359 /* free the lock */ 359 /* free the lock */
360 ret = hwspin_lock_free(hwlock) 360 ret = hwspin_lock_free(hwlock);
361 if (ret) 361 if (ret)
362 ... 362 ...
363 363
364 return ret; 364 return ret;
365 } 365 }
366 366
367 int hwspinlock_example2(void) 367 int hwspinlock_example2(void)
368 { 368 {
369 struct hwspinlock *hwlock; 369 struct hwspinlock *hwlock;
370 int ret; 370 int ret;
371 371
372 /* 372 /*
373 * assign a specific hwspinlock 373 * assign a specific hwspinlock id - this should be called early
374 * by board init code. 374 * by board init code.
375 */ 375 */
376 hwlock = hwspin_lock_request_s 376 hwlock = hwspin_lock_request_specific(PREDEFINED_LOCK_ID);
377 if (!hwlock) 377 if (!hwlock)
378 ... 378 ...
379 379
380 /* try to take it, but don't s 380 /* try to take it, but don't spin on it */
381 ret = hwspin_trylock(hwlock); 381 ret = hwspin_trylock(hwlock);
382 if (!ret) { 382 if (!ret) {
383 pr_info("lock is alrea 383 pr_info("lock is already taken\n");
384 return -EBUSY; 384 return -EBUSY;
385 } 385 }
386 386
387 /* 387 /*
388 * we took the lock, do our thi 388 * we took the lock, do our thing now, but do NOT sleep
389 */ 389 */
390 390
391 /* release the lock */ 391 /* release the lock */
392 hwspin_unlock(hwlock); 392 hwspin_unlock(hwlock);
393 393
394 /* free the lock */ 394 /* free the lock */
395 ret = hwspin_lock_free(hwlock) 395 ret = hwspin_lock_free(hwlock);
396 if (ret) 396 if (ret)
397 ... 397 ...
398 398
399 return ret; 399 return ret;
400 } 400 }
401 401
402 402
403 API for implementors 403 API for implementors
404 ==================== 404 ====================
405 405
406 :: 406 ::
407 407
408 int hwspin_lock_register(struct hwspinlock_d 408 int hwspin_lock_register(struct hwspinlock_device *bank, struct device *dev,
409 const struct hwspinlock_ops *o 409 const struct hwspinlock_ops *ops, int base_id, int num_locks);
410 410
411 To be called from the underlying platform-spec 411 To be called from the underlying platform-specific implementation, in
412 order to register a new hwspinlock device (whi 412 order to register a new hwspinlock device (which is usually a bank of
413 numerous locks). Should be called from a proce 413 numerous locks). Should be called from a process context (this function
414 might sleep). 414 might sleep).
415 415
416 Returns 0 on success, or appropriate error cod 416 Returns 0 on success, or appropriate error code on failure.
417 417
418 :: 418 ::
419 419
420 int hwspin_lock_unregister(struct hwspinlock 420 int hwspin_lock_unregister(struct hwspinlock_device *bank);
421 421
422 To be called from the underlying vendor-specif 422 To be called from the underlying vendor-specific implementation, in order
423 to unregister an hwspinlock device (which is u 423 to unregister an hwspinlock device (which is usually a bank of numerous
424 locks). 424 locks).
425 425
426 Should be called from a process context (this 426 Should be called from a process context (this function might sleep).
427 427
428 Returns the address of hwspinlock on success, 428 Returns the address of hwspinlock on success, or NULL on error (e.g.
429 if the hwspinlock is still in use). 429 if the hwspinlock is still in use).
430 430
431 Important structs 431 Important structs
432 ================= 432 =================
433 433
434 struct hwspinlock_device is a device which usu 434 struct hwspinlock_device is a device which usually contains a bank
435 of hardware locks. It is registered by the und 435 of hardware locks. It is registered by the underlying hwspinlock
436 implementation using the hwspin_lock_register( 436 implementation using the hwspin_lock_register() API.
437 437
438 :: 438 ::
439 439
440 /** 440 /**
441 * struct hwspinlock_device - a device 441 * struct hwspinlock_device - a device which usually spans numerous hwspinlocks
442 * @dev: underlying device, will be use 442 * @dev: underlying device, will be used to invoke runtime PM api
443 * @ops: platform-specific hwspinlock h 443 * @ops: platform-specific hwspinlock handlers
444 * @base_id: id index of the first lock 444 * @base_id: id index of the first lock in this device
445 * @num_locks: number of locks in this 445 * @num_locks: number of locks in this device
446 * @lock: dynamically allocated array o 446 * @lock: dynamically allocated array of 'struct hwspinlock'
447 */ 447 */
448 struct hwspinlock_device { 448 struct hwspinlock_device {
449 struct device *dev; 449 struct device *dev;
450 const struct hwspinlock_ops *o 450 const struct hwspinlock_ops *ops;
451 int base_id; 451 int base_id;
452 int num_locks; 452 int num_locks;
453 struct hwspinlock lock[0]; 453 struct hwspinlock lock[0];
454 }; 454 };
455 455
456 struct hwspinlock_device contains an array of 456 struct hwspinlock_device contains an array of hwspinlock structs, each
457 of which represents a single hardware lock:: 457 of which represents a single hardware lock::
458 458
459 /** 459 /**
460 * struct hwspinlock - this struct repr 460 * struct hwspinlock - this struct represents a single hwspinlock instance
461 * @bank: the hwspinlock_device structu 461 * @bank: the hwspinlock_device structure which owns this lock
462 * @lock: initialized and used by hwspi 462 * @lock: initialized and used by hwspinlock core
463 * @priv: private data, owned by the un 463 * @priv: private data, owned by the underlying platform-specific hwspinlock drv
464 */ 464 */
465 struct hwspinlock { 465 struct hwspinlock {
466 struct hwspinlock_device *bank 466 struct hwspinlock_device *bank;
467 spinlock_t lock; 467 spinlock_t lock;
468 void *priv; 468 void *priv;
469 }; 469 };
470 470
471 When registering a bank of locks, the hwspinlo 471 When registering a bank of locks, the hwspinlock driver only needs to
472 set the priv members of the locks. The rest of 472 set the priv members of the locks. The rest of the members are set and
473 initialized by the hwspinlock core itself. 473 initialized by the hwspinlock core itself.
474 474
475 Implementation callbacks 475 Implementation callbacks
476 ======================== 476 ========================
477 477
478 There are three possible callbacks defined in 478 There are three possible callbacks defined in 'struct hwspinlock_ops'::
479 479
480 struct hwspinlock_ops { 480 struct hwspinlock_ops {
481 int (*trylock)(struct hwspinlo 481 int (*trylock)(struct hwspinlock *lock);
482 void (*unlock)(struct hwspinlo 482 void (*unlock)(struct hwspinlock *lock);
483 void (*relax)(struct hwspinloc 483 void (*relax)(struct hwspinlock *lock);
484 }; 484 };
485 485
486 The first two callbacks are mandatory: 486 The first two callbacks are mandatory:
487 487
488 The ->trylock() callback should make a single 488 The ->trylock() callback should make a single attempt to take the lock, and
489 return 0 on failure and 1 on success. This cal 489 return 0 on failure and 1 on success. This callback may **not** sleep.
490 490
491 The ->unlock() callback releases the lock. It 491 The ->unlock() callback releases the lock. It always succeed, and it, too,
492 may **not** sleep. 492 may **not** sleep.
493 493
494 The ->relax() callback is optional. It is call 494 The ->relax() callback is optional. It is called by hwspinlock core while
495 spinning on a lock, and can be used by the und 495 spinning on a lock, and can be used by the underlying implementation to force
496 a delay between two successive invocations of 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.