Commit | Line | Data |
---|---|---|
7ad530bf EG |
1 | /* |
2 | * include/linux/sync.h | |
3 | * | |
4 | * Copyright (C) 2012 Google, Inc. | |
5 | * | |
6 | * This program is distributed in the hope that it will be useful, | |
7 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
8 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
9 | * GNU General Public License for more details. | |
10 | * | |
11 | */ | |
12 | ||
13 | #ifndef _LINUX_SYNC_H | |
14 | #define _LINUX_SYNC_H | |
15 | ||
16 | #include <linux/types.h> | |
01544170 | 17 | #include <linux/kref.h> |
97a84843 | 18 | #include <linux/ktime.h> |
7ad530bf EG |
19 | #include <linux/list.h> |
20 | #include <linux/spinlock.h> | |
21 | #include <linux/wait.h> | |
0f0d8406 | 22 | #include <linux/fence.h> |
7ad530bf | 23 | |
64907b94 CC |
24 | #include "uapi/sync.h" |
25 | ||
7ad530bf EG |
26 | struct sync_timeline; |
27 | struct sync_pt; | |
28 | struct sync_fence; | |
29 | ||
30 | /** | |
31 | * struct sync_timeline_ops - sync object implementation ops | |
4e20effa | 32 | * @driver_name: name of the implementation |
7ad530bf EG |
33 | * @dup: duplicate a sync_pt |
34 | * @has_signaled: returns: | |
35 | * 1 if pt has signaled | |
36 | * 0 if pt has not signaled | |
37 | * <0 on error | |
38 | * @compare: returns: | |
39 | * 1 if b will signal before a | |
40 | * 0 if a and b will signal at the same time | |
4e20effa | 41 | * -1 if a will signal before b |
7ad530bf EG |
42 | * @free_pt: called before sync_pt is freed |
43 | * @release_obj: called before sync_timeline is freed | |
4e20effa | 44 | * @fill_driver_data: write implementation specific driver data to data. |
79ba1525 EG |
45 | * should return an error if there is not enough room |
46 | * as specified by size. This information is returned | |
47 | * to userspace by SYNC_IOC_FENCE_INFO. | |
dbd52390 EG |
48 | * @timeline_value_str: fill str with the value of the sync_timeline's counter |
49 | * @pt_value_str: fill str with the value of the sync_pt | |
7ad530bf EG |
50 | */ |
51 | struct sync_timeline_ops { | |
52 | const char *driver_name; | |
53 | ||
54 | /* required */ | |
393f539c | 55 | struct sync_pt * (*dup)(struct sync_pt *pt); |
7ad530bf EG |
56 | |
57 | /* required */ | |
58 | int (*has_signaled)(struct sync_pt *pt); | |
59 | ||
60 | /* required */ | |
61 | int (*compare)(struct sync_pt *a, struct sync_pt *b); | |
62 | ||
63 | /* optional */ | |
64 | void (*free_pt)(struct sync_pt *sync_pt); | |
65 | ||
66 | /* optional */ | |
67 | void (*release_obj)(struct sync_timeline *sync_timeline); | |
af7582f2 | 68 | |
79ba1525 EG |
69 | /* optional */ |
70 | int (*fill_driver_data)(struct sync_pt *syncpt, void *data, int size); | |
dbd52390 EG |
71 | |
72 | /* optional */ | |
73 | void (*timeline_value_str)(struct sync_timeline *timeline, char *str, | |
74 | int size); | |
75 | ||
76 | /* optional */ | |
77 | void (*pt_value_str)(struct sync_pt *pt, char *str, int size); | |
7ad530bf EG |
78 | }; |
79 | ||
80 | /** | |
81 | * struct sync_timeline - sync object | |
c5b86b74 | 82 | * @kref: reference count on fence. |
4e20effa | 83 | * @ops: ops that define the implementation of the sync_timeline |
7ad530bf | 84 | * @name: name of the sync_timeline. Useful for debugging |
4e20effa | 85 | * @destroyed: set when sync_timeline is destroyed |
7ad530bf EG |
86 | * @child_list_head: list of children sync_pts for this sync_timeline |
87 | * @child_list_lock: lock protecting @child_list_head, destroyed, and | |
88 | * sync_pt.status | |
89 | * @active_list_head: list of active (unsignaled/errored) sync_pts | |
af7582f2 | 90 | * @sync_timeline_list: membership in global sync_timeline_list |
7ad530bf EG |
91 | */ |
92 | struct sync_timeline { | |
c5b86b74 | 93 | struct kref kref; |
7ad530bf EG |
94 | const struct sync_timeline_ops *ops; |
95 | char name[32]; | |
96 | ||
97 | /* protected by child_list_lock */ | |
98 | bool destroyed; | |
0f0d8406 | 99 | int context, value; |
7ad530bf EG |
100 | |
101 | struct list_head child_list_head; | |
102 | spinlock_t child_list_lock; | |
103 | ||
104 | struct list_head active_list_head; | |
af7582f2 | 105 | |
0f0d8406 | 106 | #ifdef CONFIG_DEBUG_FS |
af7582f2 | 107 | struct list_head sync_timeline_list; |
0f0d8406 | 108 | #endif |
7ad530bf EG |
109 | }; |
110 | ||
111 | /** | |
112 | * struct sync_pt - sync point | |
0f0d8406 | 113 | * @fence: base fence class |
7ad530bf EG |
114 | * @child_list: membership in sync_timeline.child_list_head |
115 | * @active_list: membership in sync_timeline.active_list_head | |
4e20effa | 116 | * @signaled_list: membership in temporary signaled_list on stack |
7ad530bf EG |
117 | * @fence: sync_fence to which the sync_pt belongs |
118 | * @pt_list: membership in sync_fence.pt_list_head | |
119 | * @status: 1: signaled, 0:active, <0: error | |
97a84843 | 120 | * @timestamp: time which sync_pt status transitioned from active to |
4e20effa | 121 | * signaled or error. |
7ad530bf EG |
122 | */ |
123 | struct sync_pt { | |
0f0d8406 | 124 | struct fence base; |
7ad530bf | 125 | |
0f0d8406 | 126 | struct list_head child_list; |
7ad530bf | 127 | struct list_head active_list; |
0f0d8406 | 128 | }; |
7ad530bf | 129 | |
0f0d8406 ML |
130 | static inline struct sync_timeline *sync_pt_parent(struct sync_pt *pt) |
131 | { | |
132 | return container_of(pt->base.lock, struct sync_timeline, | |
133 | child_list_lock); | |
134 | } | |
97a84843 | 135 | |
0f0d8406 ML |
136 | struct sync_fence_cb { |
137 | struct fence_cb cb; | |
138 | struct fence *sync_pt; | |
139 | struct sync_fence *fence; | |
7ad530bf EG |
140 | }; |
141 | ||
142 | /** | |
143 | * struct sync_fence - sync fence | |
144 | * @file: file representing this fence | |
4e20effa | 145 | * @kref: reference count on fence. |
7ad530bf | 146 | * @name: name of sync_fence. Useful for debugging |
4e20effa | 147 | * @pt_list_head: list of sync_pts in the fence. immutable once fence |
7ad530bf | 148 | * is created |
0f0d8406 | 149 | * @status: 0: signaled, >0:active, <0: error |
7ad530bf EG |
150 | * |
151 | * @wq: wait queue for fence signaling | |
af7582f2 | 152 | * @sync_fence_list: membership in global fence list |
7ad530bf EG |
153 | */ |
154 | struct sync_fence { | |
155 | struct file *file; | |
01544170 | 156 | struct kref kref; |
7ad530bf | 157 | char name[32]; |
0f0d8406 ML |
158 | #ifdef CONFIG_DEBUG_FS |
159 | struct list_head sync_fence_list; | |
160 | #endif | |
161 | int num_fences; | |
7ad530bf EG |
162 | |
163 | wait_queue_head_t wq; | |
0f0d8406 | 164 | atomic_t status; |
af7582f2 | 165 | |
0f0d8406 | 166 | struct sync_fence_cb cbs[]; |
7ad530bf EG |
167 | }; |
168 | ||
c0f61a4e EG |
169 | struct sync_fence_waiter; |
170 | typedef void (*sync_callback_t)(struct sync_fence *fence, | |
171 | struct sync_fence_waiter *waiter); | |
172 | ||
7ad530bf EG |
173 | /** |
174 | * struct sync_fence_waiter - metadata for asynchronous waiter on a fence | |
175 | * @waiter_list: membership in sync_fence.waiter_list_head | |
176 | * @callback: function pointer to call when fence signals | |
177 | * @callback_data: pointer to pass to @callback | |
178 | */ | |
179 | struct sync_fence_waiter { | |
0f0d8406 ML |
180 | wait_queue_t work; |
181 | sync_callback_t callback; | |
7ad530bf EG |
182 | }; |
183 | ||
c0f61a4e EG |
184 | static inline void sync_fence_waiter_init(struct sync_fence_waiter *waiter, |
185 | sync_callback_t callback) | |
186 | { | |
0f0d8406 | 187 | INIT_LIST_HEAD(&waiter->work.task_list); |
c0f61a4e EG |
188 | waiter->callback = callback; |
189 | } | |
190 | ||
7ad530bf EG |
191 | /* |
192 | * API for sync_timeline implementers | |
193 | */ | |
194 | ||
195 | /** | |
196 | * sync_timeline_create() - creates a sync object | |
4e20effa | 197 | * @ops: specifies the implementation ops for the object |
7ad530bf EG |
198 | * @size: size to allocate for this obj |
199 | * @name: sync_timeline name | |
200 | * | |
4e20effa MI |
201 | * Creates a new sync_timeline which will use the implementation specified by |
202 | * @ops. @size bytes will be allocated allowing for implementation specific | |
203 | * data to be kept after the generic sync_timeline struct. | |
7ad530bf EG |
204 | */ |
205 | struct sync_timeline *sync_timeline_create(const struct sync_timeline_ops *ops, | |
206 | int size, const char *name); | |
207 | ||
208 | /** | |
4e20effa | 209 | * sync_timeline_destroy() - destroys a sync object |
7ad530bf EG |
210 | * @obj: sync_timeline to destroy |
211 | * | |
4e20effa MI |
212 | * A sync implementation should call this when the @obj is going away |
213 | * (i.e. module unload.) @obj won't actually be freed until all its children | |
7ad530bf EG |
214 | * sync_pts are freed. |
215 | */ | |
216 | void sync_timeline_destroy(struct sync_timeline *obj); | |
217 | ||
218 | /** | |
219 | * sync_timeline_signal() - signal a status change on a sync_timeline | |
220 | * @obj: sync_timeline to signal | |
221 | * | |
4e20effa | 222 | * A sync implementation should call this any time one of it's sync_pts |
7ad530bf EG |
223 | * has signaled or has an error condition. |
224 | */ | |
225 | void sync_timeline_signal(struct sync_timeline *obj); | |
226 | ||
227 | /** | |
228 | * sync_pt_create() - creates a sync pt | |
229 | * @parent: sync_pt's parent sync_timeline | |
230 | * @size: size to allocate for this pt | |
231 | * | |
4e20effa MI |
232 | * Creates a new sync_pt as a child of @parent. @size bytes will be |
233 | * allocated allowing for implementation specific data to be kept after | |
7ad530bf EG |
234 | * the generic sync_timeline struct. |
235 | */ | |
236 | struct sync_pt *sync_pt_create(struct sync_timeline *parent, int size); | |
237 | ||
238 | /** | |
239 | * sync_pt_free() - frees a sync pt | |
240 | * @pt: sync_pt to free | |
241 | * | |
242 | * This should only be called on sync_pts which have been created but | |
243 | * not added to a fence. | |
244 | */ | |
245 | void sync_pt_free(struct sync_pt *pt); | |
246 | ||
247 | /** | |
248 | * sync_fence_create() - creates a sync fence | |
249 | * @name: name of fence to create | |
250 | * @pt: sync_pt to add to the fence | |
251 | * | |
252 | * Creates a fence containg @pt. Once this is called, the fence takes | |
253 | * ownership of @pt. | |
254 | */ | |
255 | struct sync_fence *sync_fence_create(const char *name, struct sync_pt *pt); | |
256 | ||
257 | /* | |
258 | * API for sync_fence consumers | |
259 | */ | |
260 | ||
261 | /** | |
262 | * sync_fence_merge() - merge two fences | |
263 | * @name: name of new fence | |
264 | * @a: fence a | |
265 | * @b: fence b | |
266 | * | |
267 | * Creates a new fence which contains copies of all the sync_pts in both | |
268 | * @a and @b. @a and @b remain valid, independent fences. | |
269 | */ | |
270 | struct sync_fence *sync_fence_merge(const char *name, | |
271 | struct sync_fence *a, struct sync_fence *b); | |
272 | ||
273 | /** | |
274 | * sync_fence_fdget() - get a fence from an fd | |
275 | * @fd: fd referencing a fence | |
276 | * | |
277 | * Ensures @fd references a valid fence, increments the refcount of the backing | |
278 | * file, and returns the fence. | |
279 | */ | |
280 | struct sync_fence *sync_fence_fdget(int fd); | |
281 | ||
282 | /** | |
4e20effa | 283 | * sync_fence_put() - puts a reference of a sync fence |
7ad530bf EG |
284 | * @fence: fence to put |
285 | * | |
286 | * Puts a reference on @fence. If this is the last reference, the fence and | |
287 | * all it's sync_pts will be freed | |
288 | */ | |
289 | void sync_fence_put(struct sync_fence *fence); | |
290 | ||
291 | /** | |
292 | * sync_fence_install() - installs a fence into a file descriptor | |
4e20effa | 293 | * @fence: fence to install |
7ad530bf EG |
294 | * @fd: file descriptor in which to install the fence |
295 | * | |
ae664752 HS |
296 | * Installs @fence into @fd. @fd's should be acquired through |
297 | * get_unused_fd_flags(O_CLOEXEC). | |
7ad530bf EG |
298 | */ |
299 | void sync_fence_install(struct sync_fence *fence, int fd); | |
300 | ||
301 | /** | |
302 | * sync_fence_wait_async() - registers and async wait on the fence | |
303 | * @fence: fence to wait on | |
c0f61a4e | 304 | * @waiter: waiter callback struck |
7ad530bf EG |
305 | * |
306 | * Returns 1 if @fence has already signaled. | |
307 | * | |
c0f61a4e EG |
308 | * Registers a callback to be called when @fence signals or has an error. |
309 | * @waiter should be initialized with sync_fence_waiter_init(). | |
7ad530bf EG |
310 | */ |
311 | int sync_fence_wait_async(struct sync_fence *fence, | |
c0f61a4e EG |
312 | struct sync_fence_waiter *waiter); |
313 | ||
314 | /** | |
315 | * sync_fence_cancel_async() - cancels an async wait | |
316 | * @fence: fence to wait on | |
317 | * @waiter: waiter callback struck | |
318 | * | |
319 | * returns 0 if waiter was removed from fence's async waiter list. | |
320 | * returns -ENOENT if waiter was not found on fence's async waiter list. | |
321 | * | |
322 | * Cancels a previously registered async wait. Will fail gracefully if | |
323 | * @waiter was never registered or if @fence has already signaled @waiter. | |
324 | */ | |
325 | int sync_fence_cancel_async(struct sync_fence *fence, | |
326 | struct sync_fence_waiter *waiter); | |
7ad530bf EG |
327 | |
328 | /** | |
329 | * sync_fence_wait() - wait on fence | |
330 | * @fence: fence to wait on | |
331 | * @tiemout: timeout in ms | |
332 | * | |
3b640f5d EG |
333 | * Wait for @fence to be signaled or have an error. Waits indefinitely |
334 | * if @timeout < 0 | |
7ad530bf EG |
335 | */ |
336 | int sync_fence_wait(struct sync_fence *fence, long timeout); | |
337 | ||
0f0d8406 ML |
338 | #ifdef CONFIG_DEBUG_FS |
339 | ||
340 | extern void sync_timeline_debug_add(struct sync_timeline *obj); | |
341 | extern void sync_timeline_debug_remove(struct sync_timeline *obj); | |
342 | extern void sync_fence_debug_add(struct sync_fence *fence); | |
343 | extern void sync_fence_debug_remove(struct sync_fence *fence); | |
344 | extern void sync_dump(void); | |
345 | ||
346 | #else | |
347 | # define sync_timeline_debug_add(obj) | |
348 | # define sync_timeline_debug_remove(obj) | |
349 | # define sync_fence_debug_add(fence) | |
350 | # define sync_fence_debug_remove(fence) | |
351 | # define sync_dump() | |
352 | #endif | |
353 | int sync_fence_wake_up_wq(wait_queue_t *curr, unsigned mode, | |
354 | int wake_flags, void *key); | |
355 | ||
7ad530bf | 356 | #endif /* _LINUX_SYNC_H */ |