]>
Commit | Line | Data |
---|---|---|
e941759c ML |
1 | /* |
2 | * Fence mechanism for dma-buf to allow for asynchronous dma access | |
3 | * | |
4 | * Copyright (C) 2012 Canonical Ltd | |
5 | * Copyright (C) 2012 Texas Instruments | |
6 | * | |
7 | * Authors: | |
8 | * Rob Clark <robdclark@gmail.com> | |
9 | * Maarten Lankhorst <maarten.lankhorst@canonical.com> | |
10 | * | |
11 | * This program is free software; you can redistribute it and/or modify it | |
12 | * under the terms of the GNU General Public License version 2 as published by | |
13 | * the Free Software Foundation. | |
14 | * | |
15 | * This program is distributed in the hope that it will be useful, but WITHOUT | |
16 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
17 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for | |
18 | * more details. | |
19 | */ | |
20 | ||
21 | #ifndef __LINUX_FENCE_H | |
22 | #define __LINUX_FENCE_H | |
23 | ||
24 | #include <linux/err.h> | |
25 | #include <linux/wait.h> | |
26 | #include <linux/list.h> | |
27 | #include <linux/bitops.h> | |
28 | #include <linux/kref.h> | |
29 | #include <linux/sched.h> | |
30 | #include <linux/printk.h> | |
3c3b177a | 31 | #include <linux/rcupdate.h> |
e941759c ML |
32 | |
33 | struct fence; | |
34 | struct fence_ops; | |
35 | struct fence_cb; | |
36 | ||
37 | /** | |
38 | * struct fence - software synchronization primitive | |
39 | * @refcount: refcount for this fence | |
40 | * @ops: fence_ops associated with this fence | |
3c3b177a | 41 | * @rcu: used for releasing fence with kfree_rcu |
e941759c ML |
42 | * @cb_list: list of all callbacks to call |
43 | * @lock: spin_lock_irqsave used for locking | |
44 | * @context: execution context this fence belongs to, returned by | |
45 | * fence_context_alloc() | |
46 | * @seqno: the sequence number of this fence inside the execution context, | |
47 | * can be compared to decide which fence would be signaled later. | |
48 | * @flags: A mask of FENCE_FLAG_* defined below | |
49 | * @timestamp: Timestamp when the fence was signaled. | |
50 | * @status: Optional, only valid if < 0, must be set before calling | |
51 | * fence_signal, indicates that the fence has completed with an error. | |
52 | * | |
53 | * the flags member must be manipulated and read using the appropriate | |
54 | * atomic ops (bit_*), so taking the spinlock will not be needed most | |
55 | * of the time. | |
56 | * | |
57 | * FENCE_FLAG_SIGNALED_BIT - fence is already signaled | |
58 | * FENCE_FLAG_ENABLE_SIGNAL_BIT - enable_signaling might have been called* | |
59 | * FENCE_FLAG_USER_BITS - start of the unused bits, can be used by the | |
60 | * implementer of the fence for its own purposes. Can be used in different | |
61 | * ways by different fence implementers, so do not rely on this. | |
62 | * | |
3590d50e | 63 | * Since atomic bitops are used, this is not guaranteed to be the case. |
e941759c ML |
64 | * Particularly, if the bit was set, but fence_signal was called right |
65 | * before this bit was set, it would have been able to set the | |
66 | * FENCE_FLAG_SIGNALED_BIT, before enable_signaling was called. | |
67 | * Adding a check for FENCE_FLAG_SIGNALED_BIT after setting | |
68 | * FENCE_FLAG_ENABLE_SIGNAL_BIT closes this race, and makes sure that | |
69 | * after fence_signal was called, any enable_signaling call will have either | |
70 | * been completed, or never called at all. | |
71 | */ | |
72 | struct fence { | |
73 | struct kref refcount; | |
74 | const struct fence_ops *ops; | |
3c3b177a | 75 | struct rcu_head rcu; |
e941759c ML |
76 | struct list_head cb_list; |
77 | spinlock_t *lock; | |
76bf0db5 CK |
78 | u64 context; |
79 | unsigned seqno; | |
e941759c ML |
80 | unsigned long flags; |
81 | ktime_t timestamp; | |
82 | int status; | |
83 | }; | |
84 | ||
85 | enum fence_flag_bits { | |
86 | FENCE_FLAG_SIGNALED_BIT, | |
87 | FENCE_FLAG_ENABLE_SIGNAL_BIT, | |
88 | FENCE_FLAG_USER_BITS, /* must always be last member */ | |
89 | }; | |
90 | ||
91 | typedef void (*fence_func_t)(struct fence *fence, struct fence_cb *cb); | |
92 | ||
93 | /** | |
94 | * struct fence_cb - callback for fence_add_callback | |
95 | * @node: used by fence_add_callback to append this struct to fence::cb_list | |
96 | * @func: fence_func_t to call | |
97 | * | |
98 | * This struct will be initialized by fence_add_callback, additional | |
99 | * data can be passed along by embedding fence_cb in another struct. | |
100 | */ | |
101 | struct fence_cb { | |
102 | struct list_head node; | |
103 | fence_func_t func; | |
104 | }; | |
105 | ||
106 | /** | |
107 | * struct fence_ops - operations implemented for fence | |
108 | * @get_driver_name: returns the driver name. | |
109 | * @get_timeline_name: return the name of the context this fence belongs to. | |
110 | * @enable_signaling: enable software signaling of fence. | |
111 | * @signaled: [optional] peek whether the fence is signaled, can be null. | |
112 | * @wait: custom wait implementation, or fence_default_wait. | |
113 | * @release: [optional] called on destruction of fence, can be null | |
114 | * @fill_driver_data: [optional] callback to fill in free-form debug info | |
115 | * Returns amount of bytes filled, or -errno. | |
116 | * @fence_value_str: [optional] fills in the value of the fence as a string | |
117 | * @timeline_value_str: [optional] fills in the current value of the timeline | |
118 | * as a string | |
119 | * | |
120 | * Notes on enable_signaling: | |
121 | * For fence implementations that have the capability for hw->hw | |
122 | * signaling, they can implement this op to enable the necessary | |
123 | * irqs, or insert commands into cmdstream, etc. This is called | |
124 | * in the first wait() or add_callback() path to let the fence | |
125 | * implementation know that there is another driver waiting on | |
126 | * the signal (ie. hw->sw case). | |
127 | * | |
128 | * This function can be called called from atomic context, but not | |
129 | * from irq context, so normal spinlocks can be used. | |
130 | * | |
131 | * A return value of false indicates the fence already passed, | |
f353d71f MI |
132 | * or some failure occurred that made it impossible to enable |
133 | * signaling. True indicates successful enabling. | |
e941759c ML |
134 | * |
135 | * fence->status may be set in enable_signaling, but only when false is | |
136 | * returned. | |
137 | * | |
138 | * Calling fence_signal before enable_signaling is called allows | |
139 | * for a tiny race window in which enable_signaling is called during, | |
140 | * before, or after fence_signal. To fight this, it is recommended | |
141 | * that before enable_signaling returns true an extra reference is | |
142 | * taken on the fence, to be released when the fence is signaled. | |
143 | * This will mean fence_signal will still be called twice, but | |
144 | * the second time will be a noop since it was already signaled. | |
145 | * | |
146 | * Notes on signaled: | |
147 | * May set fence->status if returning true. | |
148 | * | |
149 | * Notes on wait: | |
150 | * Must not be NULL, set to fence_default_wait for default implementation. | |
151 | * the fence_default_wait implementation should work for any fence, as long | |
152 | * as enable_signaling works correctly. | |
153 | * | |
154 | * Must return -ERESTARTSYS if the wait is intr = true and the wait was | |
155 | * interrupted, and remaining jiffies if fence has signaled, or 0 if wait | |
156 | * timed out. Can also return other error values on custom implementations, | |
157 | * which should be treated as if the fence is signaled. For example a hardware | |
158 | * lockup could be reported like that. | |
159 | * | |
160 | * Notes on release: | |
161 | * Can be NULL, this function allows additional commands to run on | |
162 | * destruction of the fence. Can be called from irq context. | |
163 | * If pointer is set to NULL, kfree will get called instead. | |
164 | */ | |
165 | ||
166 | struct fence_ops { | |
167 | const char * (*get_driver_name)(struct fence *fence); | |
168 | const char * (*get_timeline_name)(struct fence *fence); | |
169 | bool (*enable_signaling)(struct fence *fence); | |
170 | bool (*signaled)(struct fence *fence); | |
171 | signed long (*wait)(struct fence *fence, bool intr, signed long timeout); | |
172 | void (*release)(struct fence *fence); | |
173 | ||
174 | int (*fill_driver_data)(struct fence *fence, void *data, int size); | |
175 | void (*fence_value_str)(struct fence *fence, char *str, int size); | |
176 | void (*timeline_value_str)(struct fence *fence, char *str, int size); | |
177 | }; | |
178 | ||
179 | void fence_init(struct fence *fence, const struct fence_ops *ops, | |
76bf0db5 | 180 | spinlock_t *lock, u64 context, unsigned seqno); |
e941759c ML |
181 | |
182 | void fence_release(struct kref *kref); | |
183 | void fence_free(struct fence *fence); | |
184 | ||
4be05420 CW |
185 | /** |
186 | * fence_put - decreases refcount of the fence | |
187 | * @fence: [in] fence to reduce refcount of | |
188 | */ | |
189 | static inline void fence_put(struct fence *fence) | |
190 | { | |
191 | if (fence) | |
192 | kref_put(&fence->refcount, fence_release); | |
193 | } | |
194 | ||
e941759c ML |
195 | /** |
196 | * fence_get - increases refcount of the fence | |
197 | * @fence: [in] fence to increase refcount of | |
198 | * | |
199 | * Returns the same fence, with refcount increased by 1. | |
200 | */ | |
201 | static inline struct fence *fence_get(struct fence *fence) | |
202 | { | |
203 | if (fence) | |
204 | kref_get(&fence->refcount); | |
205 | return fence; | |
206 | } | |
207 | ||
3c3b177a ML |
208 | /** |
209 | * fence_get_rcu - get a fence from a reservation_object_list with rcu read lock | |
210 | * @fence: [in] fence to increase refcount of | |
211 | * | |
212 | * Function returns NULL if no refcount could be obtained, or the fence. | |
213 | */ | |
214 | static inline struct fence *fence_get_rcu(struct fence *fence) | |
215 | { | |
216 | if (kref_get_unless_zero(&fence->refcount)) | |
217 | return fence; | |
218 | else | |
219 | return NULL; | |
220 | } | |
221 | ||
e941759c | 222 | /** |
4be05420 CW |
223 | * fence_get_rcu_safe - acquire a reference to an RCU tracked fence |
224 | * @fence: [in] pointer to fence to increase refcount of | |
225 | * | |
226 | * Function returns NULL if no refcount could be obtained, or the fence. | |
227 | * This function handles acquiring a reference to a fence that may be | |
228 | * reallocated within the RCU grace period (such as with SLAB_DESTROY_BY_RCU), | |
229 | * so long as the caller is using RCU on the pointer to the fence. | |
230 | * | |
231 | * An alternative mechanism is to employ a seqlock to protect a bunch of | |
232 | * fences, such as used by struct reservation_object. When using a seqlock, | |
233 | * the seqlock must be taken before and checked after a reference to the | |
234 | * fence is acquired (as shown here). | |
235 | * | |
236 | * The caller is required to hold the RCU read lock. | |
e941759c | 237 | */ |
4be05420 | 238 | static inline struct fence *fence_get_rcu_safe(struct fence * __rcu *fencep) |
e941759c | 239 | { |
4be05420 CW |
240 | do { |
241 | struct fence *fence; | |
242 | ||
243 | fence = rcu_dereference(*fencep); | |
244 | if (!fence || !fence_get_rcu(fence)) | |
245 | return NULL; | |
246 | ||
247 | /* The atomic_inc_not_zero() inside fence_get_rcu() | |
248 | * provides a full memory barrier upon success (such as now). | |
249 | * This is paired with the write barrier from assigning | |
250 | * to the __rcu protected fence pointer so that if that | |
251 | * pointer still matches the current fence, we know we | |
252 | * have successfully acquire a reference to it. If it no | |
253 | * longer matches, we are holding a reference to some other | |
254 | * reallocated pointer. This is possible if the allocator | |
255 | * is using a freelist like SLAB_DESTROY_BY_RCU where the | |
256 | * fence remains valid for the RCU grace period, but it | |
257 | * may be reallocated. When using such allocators, we are | |
258 | * responsible for ensuring the reference we get is to | |
259 | * the right fence, as below. | |
260 | */ | |
261 | if (fence == rcu_access_pointer(*fencep)) | |
262 | return rcu_pointer_handoff(fence); | |
263 | ||
264 | fence_put(fence); | |
265 | } while (1); | |
e941759c ML |
266 | } |
267 | ||
268 | int fence_signal(struct fence *fence); | |
269 | int fence_signal_locked(struct fence *fence); | |
270 | signed long fence_default_wait(struct fence *fence, bool intr, signed long timeout); | |
271 | int fence_add_callback(struct fence *fence, struct fence_cb *cb, | |
272 | fence_func_t func); | |
273 | bool fence_remove_callback(struct fence *fence, struct fence_cb *cb); | |
274 | void fence_enable_sw_signaling(struct fence *fence); | |
275 | ||
276 | /** | |
277 | * fence_is_signaled_locked - Return an indication if the fence is signaled yet. | |
278 | * @fence: [in] the fence to check | |
279 | * | |
280 | * Returns true if the fence was already signaled, false if not. Since this | |
281 | * function doesn't enable signaling, it is not guaranteed to ever return | |
282 | * true if fence_add_callback, fence_wait or fence_enable_sw_signaling | |
283 | * haven't been called before. | |
284 | * | |
285 | * This function requires fence->lock to be held. | |
286 | */ | |
287 | static inline bool | |
288 | fence_is_signaled_locked(struct fence *fence) | |
289 | { | |
290 | if (test_bit(FENCE_FLAG_SIGNALED_BIT, &fence->flags)) | |
291 | return true; | |
292 | ||
293 | if (fence->ops->signaled && fence->ops->signaled(fence)) { | |
294 | fence_signal_locked(fence); | |
295 | return true; | |
296 | } | |
297 | ||
298 | return false; | |
299 | } | |
300 | ||
301 | /** | |
302 | * fence_is_signaled - Return an indication if the fence is signaled yet. | |
303 | * @fence: [in] the fence to check | |
304 | * | |
305 | * Returns true if the fence was already signaled, false if not. Since this | |
306 | * function doesn't enable signaling, it is not guaranteed to ever return | |
307 | * true if fence_add_callback, fence_wait or fence_enable_sw_signaling | |
308 | * haven't been called before. | |
309 | * | |
310 | * It's recommended for seqno fences to call fence_signal when the | |
311 | * operation is complete, it makes it possible to prevent issues from | |
312 | * wraparound between time of issue and time of use by checking the return | |
313 | * value of this function before calling hardware-specific wait instructions. | |
314 | */ | |
315 | static inline bool | |
316 | fence_is_signaled(struct fence *fence) | |
317 | { | |
318 | if (test_bit(FENCE_FLAG_SIGNALED_BIT, &fence->flags)) | |
319 | return true; | |
320 | ||
321 | if (fence->ops->signaled && fence->ops->signaled(fence)) { | |
322 | fence_signal(fence); | |
323 | return true; | |
324 | } | |
325 | ||
326 | return false; | |
327 | } | |
328 | ||
6c455ac1 CK |
329 | /** |
330 | * fence_is_later - return if f1 is chronologically later than f2 | |
331 | * @f1: [in] the first fence from the same context | |
332 | * @f2: [in] the second fence from the same context | |
333 | * | |
334 | * Returns true if f1 is chronologically later than f2. Both fences must be | |
335 | * from the same context, since a seqno is not re-used across contexts. | |
336 | */ | |
337 | static inline bool fence_is_later(struct fence *f1, struct fence *f2) | |
338 | { | |
339 | if (WARN_ON(f1->context != f2->context)) | |
340 | return false; | |
341 | ||
b47bcb93 | 342 | return (int)(f1->seqno - f2->seqno) > 0; |
6c455ac1 CK |
343 | } |
344 | ||
e941759c ML |
345 | /** |
346 | * fence_later - return the chronologically later fence | |
347 | * @f1: [in] the first fence from the same context | |
348 | * @f2: [in] the second fence from the same context | |
349 | * | |
350 | * Returns NULL if both fences are signaled, otherwise the fence that would be | |
351 | * signaled last. Both fences must be from the same context, since a seqno is | |
352 | * not re-used across contexts. | |
353 | */ | |
354 | static inline struct fence *fence_later(struct fence *f1, struct fence *f2) | |
355 | { | |
356 | if (WARN_ON(f1->context != f2->context)) | |
357 | return NULL; | |
358 | ||
359 | /* | |
360 | * can't check just FENCE_FLAG_SIGNALED_BIT here, it may never have been | |
361 | * set if enable_signaling wasn't called, and enabling that here is | |
362 | * overkill. | |
363 | */ | |
6c455ac1 | 364 | if (fence_is_later(f1, f2)) |
e941759c | 365 | return fence_is_signaled(f1) ? NULL : f1; |
6c455ac1 CK |
366 | else |
367 | return fence_is_signaled(f2) ? NULL : f2; | |
e941759c ML |
368 | } |
369 | ||
370 | signed long fence_wait_timeout(struct fence *, bool intr, signed long timeout); | |
a519435a CK |
371 | signed long fence_wait_any_timeout(struct fence **fences, uint32_t count, |
372 | bool intr, signed long timeout); | |
e941759c ML |
373 | |
374 | /** | |
375 | * fence_wait - sleep until the fence gets signaled | |
376 | * @fence: [in] the fence to wait on | |
377 | * @intr: [in] if true, do an interruptible wait | |
378 | * | |
379 | * This function will return -ERESTARTSYS if interrupted by a signal, | |
380 | * or 0 if the fence was signaled. Other error values may be | |
381 | * returned on custom implementations. | |
382 | * | |
383 | * Performs a synchronous wait on this fence. It is assumed the caller | |
384 | * directly or indirectly holds a reference to the fence, otherwise the | |
385 | * fence might be freed before return, resulting in undefined behavior. | |
386 | */ | |
387 | static inline signed long fence_wait(struct fence *fence, bool intr) | |
388 | { | |
389 | signed long ret; | |
390 | ||
391 | /* Since fence_wait_timeout cannot timeout with | |
392 | * MAX_SCHEDULE_TIMEOUT, only valid return values are | |
393 | * -ERESTARTSYS and MAX_SCHEDULE_TIMEOUT. | |
394 | */ | |
395 | ret = fence_wait_timeout(fence, intr, MAX_SCHEDULE_TIMEOUT); | |
396 | ||
397 | return ret < 0 ? ret : 0; | |
398 | } | |
399 | ||
76bf0db5 | 400 | u64 fence_context_alloc(unsigned num); |
e941759c ML |
401 | |
402 | #define FENCE_TRACE(f, fmt, args...) \ | |
403 | do { \ | |
404 | struct fence *__ff = (f); \ | |
97f2645f | 405 | if (IS_ENABLED(CONFIG_FENCE_TRACE)) \ |
76bf0db5 | 406 | pr_info("f %llu#%u: " fmt, \ |
e941759c ML |
407 | __ff->context, __ff->seqno, ##args); \ |
408 | } while (0) | |
409 | ||
410 | #define FENCE_WARN(f, fmt, args...) \ | |
411 | do { \ | |
412 | struct fence *__ff = (f); \ | |
76bf0db5 | 413 | pr_warn("f %llu#%u: " fmt, __ff->context, __ff->seqno, \ |
e941759c ML |
414 | ##args); \ |
415 | } while (0) | |
416 | ||
417 | #define FENCE_ERR(f, fmt, args...) \ | |
418 | do { \ | |
419 | struct fence *__ff = (f); \ | |
76bf0db5 | 420 | pr_err("f %llu#%u: " fmt, __ff->context, __ff->seqno, \ |
e941759c ML |
421 | ##args); \ |
422 | } while (0) | |
423 | ||
424 | #endif /* __LINUX_FENCE_H */ |