sync.h revision 7ad530bf2499c702a6dcbb279cf78b76845ed584
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> 17#ifdef __KERNEL__ 18 19#include <linux/list.h> 20#include <linux/spinlock.h> 21#include <linux/wait.h> 22 23struct sync_timeline; 24struct sync_pt; 25struct sync_fence; 26 27/** 28 * struct sync_timeline_ops - sync object implementation ops 29 * @driver_name: name of the implentation 30 * @dup: duplicate a sync_pt 31 * @has_signaled: returns: 32 * 1 if pt has signaled 33 * 0 if pt has not signaled 34 * <0 on error 35 * @compare: returns: 36 * 1 if b will signal before a 37 * 0 if a and b will signal at the same time 38 * -1 if a will signabl before b 39 * @free_pt: called before sync_pt is freed 40 * @release_obj: called before sync_timeline is freed 41 */ 42struct sync_timeline_ops { 43 const char *driver_name; 44 45 /* required */ 46 struct sync_pt *(*dup)(struct sync_pt *pt); 47 48 /* required */ 49 int (*has_signaled)(struct sync_pt *pt); 50 51 /* required */ 52 int (*compare)(struct sync_pt *a, struct sync_pt *b); 53 54 /* optional */ 55 void (*free_pt)(struct sync_pt *sync_pt); 56 57 /* optional */ 58 void (*release_obj)(struct sync_timeline *sync_timeline); 59}; 60 61/** 62 * struct sync_timeline - sync object 63 * @ops: ops that define the implementaiton of the sync_timeline 64 * @name: name of the sync_timeline. Useful for debugging 65 * @destoryed: set when sync_timeline is destroyed 66 * @child_list_head: list of children sync_pts for this sync_timeline 67 * @child_list_lock: lock protecting @child_list_head, destroyed, and 68 * sync_pt.status 69 * @active_list_head: list of active (unsignaled/errored) sync_pts 70 */ 71struct sync_timeline { 72 const struct sync_timeline_ops *ops; 73 char name[32]; 74 75 /* protected by child_list_lock */ 76 bool destroyed; 77 78 struct list_head child_list_head; 79 spinlock_t child_list_lock; 80 81 struct list_head active_list_head; 82 spinlock_t active_list_lock; 83}; 84 85/** 86 * struct sync_pt - sync point 87 * @parent: sync_timeline to which this sync_pt belongs 88 * @child_list: membership in sync_timeline.child_list_head 89 * @active_list: membership in sync_timeline.active_list_head 90 * @fence: sync_fence to which the sync_pt belongs 91 * @pt_list: membership in sync_fence.pt_list_head 92 * @status: 1: signaled, 0:active, <0: error 93 */ 94struct sync_pt { 95 struct sync_timeline *parent; 96 struct list_head child_list; 97 98 struct list_head active_list; 99 100 struct sync_fence *fence; 101 struct list_head pt_list; 102 103 /* protected by parent->active_list_lock */ 104 int status; 105}; 106 107/** 108 * struct sync_fence - sync fence 109 * @file: file representing this fence 110 * @name: name of sync_fence. Useful for debugging 111 * @pt_list_head: list of sync_pts in ths fence. immutable once fence 112 * is created 113 * @waiter_list_head: list of asynchronous waiters on this fence 114 * @waiter_list_lock: lock protecting @waiter_list_head and @status 115 * @status: 1: signaled, 0:active, <0: error 116 * 117 * @wq: wait queue for fence signaling 118 */ 119struct sync_fence { 120 struct file *file; 121 char name[32]; 122 123 /* this list is immutable once the fence is created */ 124 struct list_head pt_list_head; 125 126 struct list_head waiter_list_head; 127 spinlock_t waiter_list_lock; /* also protects status */ 128 int status; 129 130 wait_queue_head_t wq; 131}; 132 133/** 134 * struct sync_fence_waiter - metadata for asynchronous waiter on a fence 135 * @waiter_list: membership in sync_fence.waiter_list_head 136 * @callback: function pointer to call when fence signals 137 * @callback_data: pointer to pass to @callback 138 */ 139struct sync_fence_waiter { 140 struct list_head waiter_list; 141 142 void (*callback)(struct sync_fence *fence, void *data); 143 void *callback_data; 144}; 145 146/* 147 * API for sync_timeline implementers 148 */ 149 150/** 151 * sync_timeline_create() - creates a sync object 152 * @ops: specifies the implemention ops for the object 153 * @size: size to allocate for this obj 154 * @name: sync_timeline name 155 * 156 * Creates a new sync_timeline which will use the implemetation specified by 157 * @ops. @size bytes will be allocated allowing for implemntation specific 158 * data to be kept after the generic sync_timeline stuct. 159 */ 160struct sync_timeline *sync_timeline_create(const struct sync_timeline_ops *ops, 161 int size, const char *name); 162 163/** 164 * sync_timeline_destory() - destorys a sync object 165 * @obj: sync_timeline to destroy 166 * 167 * A sync implemntation should call this when the @obj is going away 168 * (i.e. module unload.) @obj won't actually be freed until all its childern 169 * sync_pts are freed. 170 */ 171void sync_timeline_destroy(struct sync_timeline *obj); 172 173/** 174 * sync_timeline_signal() - signal a status change on a sync_timeline 175 * @obj: sync_timeline to signal 176 * 177 * A sync implemntation should call this any time one of it's sync_pts 178 * has signaled or has an error condition. 179 */ 180void sync_timeline_signal(struct sync_timeline *obj); 181 182/** 183 * sync_pt_create() - creates a sync pt 184 * @parent: sync_pt's parent sync_timeline 185 * @size: size to allocate for this pt 186 * 187 * Creates a new sync_pt as a chiled of @parent. @size bytes will be 188 * allocated allowing for implemntation specific data to be kept after 189 * the generic sync_timeline struct. 190 */ 191struct sync_pt *sync_pt_create(struct sync_timeline *parent, int size); 192 193/** 194 * sync_pt_free() - frees a sync pt 195 * @pt: sync_pt to free 196 * 197 * This should only be called on sync_pts which have been created but 198 * not added to a fence. 199 */ 200void sync_pt_free(struct sync_pt *pt); 201 202/** 203 * sync_fence_create() - creates a sync fence 204 * @name: name of fence to create 205 * @pt: sync_pt to add to the fence 206 * 207 * Creates a fence containg @pt. Once this is called, the fence takes 208 * ownership of @pt. 209 */ 210struct sync_fence *sync_fence_create(const char *name, struct sync_pt *pt); 211 212/* 213 * API for sync_fence consumers 214 */ 215 216/** 217 * sync_fence_merge() - merge two fences 218 * @name: name of new fence 219 * @a: fence a 220 * @b: fence b 221 * 222 * Creates a new fence which contains copies of all the sync_pts in both 223 * @a and @b. @a and @b remain valid, independent fences. 224 */ 225struct sync_fence *sync_fence_merge(const char *name, 226 struct sync_fence *a, struct sync_fence *b); 227 228/** 229 * sync_fence_fdget() - get a fence from an fd 230 * @fd: fd referencing a fence 231 * 232 * Ensures @fd references a valid fence, increments the refcount of the backing 233 * file, and returns the fence. 234 */ 235struct sync_fence *sync_fence_fdget(int fd); 236 237/** 238 * sync_fence_put() - puts a refernnce of a sync fence 239 * @fence: fence to put 240 * 241 * Puts a reference on @fence. If this is the last reference, the fence and 242 * all it's sync_pts will be freed 243 */ 244void sync_fence_put(struct sync_fence *fence); 245 246/** 247 * sync_fence_install() - installs a fence into a file descriptor 248 * @fence: fence to instal 249 * @fd: file descriptor in which to install the fence 250 * 251 * Installs @fence into @fd. @fd's should be acquired through get_unused_fd(). 252 */ 253void sync_fence_install(struct sync_fence *fence, int fd); 254 255/** 256 * sync_fence_wait_async() - registers and async wait on the fence 257 * @fence: fence to wait on 258 * @callback: callback 259 * @callback_data data to pass to the callback 260 * 261 * Returns 1 if @fence has already signaled. 262 * 263 * Registers a callback to be called when @fence signals or has an error 264 */ 265int sync_fence_wait_async(struct sync_fence *fence, 266 void (*callback)(struct sync_fence *, void *data), 267 void *callback_data); 268 269/** 270 * sync_fence_wait() - wait on fence 271 * @fence: fence to wait on 272 * @tiemout: timeout in ms 273 * 274 * Wait for @fence to be signaled or have an error. Waits indefintly 275 * if @timeout = 0 276 */ 277int sync_fence_wait(struct sync_fence *fence, long timeout); 278 279/* useful for sync driver's debug print handlers */ 280const char *sync_status_str(int status); 281 282#endif /* __KERNEL__ */ 283 284/** 285 * struct sync_merge_data - data passed to merge ioctl 286 * @fd2: file descriptor of second fence 287 * @name: name of new fence 288 * @fence: returns the fd of the new fence to userspace 289 */ 290struct sync_merge_data { 291 __s32 fd2; /* fd of second fence */ 292 char name[32]; /* name of new fence */ 293 __s32 fence; /* fd on newly created fence */ 294}; 295 296#define SYNC_IOC_MAGIC '>' 297 298/** 299 * DOC: SYNC_IOC_WAIT - wait for a fence to signal 300 * 301 * pass timeout in milliseconds. 302 */ 303#define SYNC_IOC_WAIT _IOW(SYNC_IOC_MAGIC, 0, __u32) 304 305/** 306 * DOC: SYNC_IOC_MERGE - merge two fences 307 * 308 * Takes a struct sync_merge_data. Creates a new fence containing copies of 309 * the sync_pts in both the calling fd and sync_merge_data.fd2. Returns the 310 * new fence's fd in sync_merge_data.fence 311 */ 312#define SYNC_IOC_MERGE _IOWR(SYNC_IOC_MAGIC, 1, struct sync_merge_data) 313 314#endif /* _LINUX_SYNC_H */ 315