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