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#include <linux/kref.h>
 18#include <linux/ktime.h>
 19#include <linux/list.h>
 20#include <linux/spinlock.h>
 21#include <linux/fence.h>
 22
 23#include "uapi/sync.h"
 24
 25struct sync_timeline;
 26struct sync_file;
 27
 28/**
 29 * struct sync_timeline_ops - sync object implementation ops
 30 * @driver_name:	name of the implementation
 31 * @has_signaled:	returns:
 32 *			  1 if pt has signaled
 33 *			  0 if pt has not signaled
 34 *			 <0 on error
 35 * @timeline_value_str: fill str with the value of the sync_timeline's counter
 36 * @fence_value_str:	fill str with the value of the fence
 37 */
 38struct sync_timeline_ops {
 39	const char *driver_name;
 40
 41	/* required */
 42	int (*has_signaled)(struct fence *fence);
 43
 44	/* optional */
 45	void (*timeline_value_str)(struct sync_timeline *timeline, char *str,
 46				   int size);
 47
 48	/* optional */
 49	void (*fence_value_str)(struct fence *fence, char *str, int size);
 50};
 51
 52/**
 53 * struct sync_timeline - sync object
 54 * @kref:		reference count on fence.
 55 * @ops:		ops that define the implementation of the sync_timeline
 56 * @name:		name of the sync_timeline. Useful for debugging
 57 * @destroyed:		set when sync_timeline is destroyed
 58 * @child_list_head:	list of children sync_pts for this sync_timeline
 59 * @child_list_lock:	lock protecting @child_list_head, destroyed, and
 60 *			fence.status
 61 * @active_list_head:	list of active (unsignaled/errored) sync_pts
 62 * @sync_timeline_list:	membership in global sync_timeline_list
 63 */
 64struct sync_timeline {
 65	struct kref		kref;
 66	const struct sync_timeline_ops	*ops;
 67	char			name[32];
 68
 69	/* protected by child_list_lock */
 70	bool			destroyed;
 71	int			context, value;
 72
 73	struct list_head	child_list_head;
 74	spinlock_t		child_list_lock;
 75
 76	struct list_head	active_list_head;
 77
 78#ifdef CONFIG_DEBUG_FS
 79	struct list_head	sync_timeline_list;
 80#endif
 81};
 82
 83static inline struct sync_timeline *fence_parent(struct fence *fence)
 84{
 85	return container_of(fence->lock, struct sync_timeline,
 86			    child_list_lock);
 87}
 88
 89struct sync_file_cb {
 90	struct fence_cb cb;
 91	struct fence *fence;
 92	struct sync_file *sync_file;
 93};
 94
 95/**
 96 * struct sync_file - sync file to export to the userspace
 97 * @file:		file representing this fence
 98 * @kref:		reference count on fence.
 99 * @name:		name of sync_file.  Useful for debugging
100 * @sync_file_list:	membership in global file list
101 * @num_fences		number of sync_pts in the fence
102 * @wq:			wait queue for fence signaling
103 * @status:		0: signaled, >0:active, <0: error
104 * @cbs:		sync_pts callback information
105 */
106struct sync_file {
107	struct file		*file;
108	struct kref		kref;
109	char			name[32];
110#ifdef CONFIG_DEBUG_FS
111	struct list_head	sync_file_list;
112#endif
113	int num_fences;
114
115	wait_queue_head_t	wq;
116	atomic_t		status;
117
118	struct sync_file_cb	cbs[];
119};
120
121/*
122 * API for sync_timeline implementers
123 */
124
125/**
126 * sync_timeline_create() - creates a sync object
127 * @ops:	specifies the implementation ops for the object
128 * @size:	size to allocate for this obj
129 * @name:	sync_timeline name
130 *
131 * Creates a new sync_timeline which will use the implementation specified by
132 * @ops.  @size bytes will be allocated allowing for implementation specific
133 * data to be kept after the generic sync_timeline struct. Returns the
134 * sync_timeline object or NULL in case of error.
135 */
136struct sync_timeline *sync_timeline_create(const struct sync_timeline_ops *ops,
137					   int size, const char *name);
138
139/**
140 * sync_timeline_destroy() - destroys a sync object
141 * @obj:	sync_timeline to destroy
142 *
143 * A sync implementation should call this when the @obj is going away
144 * (i.e. module unload.)  @obj won't actually be freed until all its children
145 * fences are freed.
146 */
147void sync_timeline_destroy(struct sync_timeline *obj);
148
149/**
150 * sync_timeline_signal() - signal a status change on a sync_timeline
151 * @obj:	sync_timeline to signal
152 *
153 * A sync implementation should call this any time one of it's fences
154 * has signaled or has an error condition.
155 */
156void sync_timeline_signal(struct sync_timeline *obj);
157
158/**
159 * sync_pt_create() - creates a sync pt
160 * @parent:	fence's parent sync_timeline
161 * @size:	size to allocate for this pt
162 *
163 * Creates a new fence as a child of @parent.  @size bytes will be
164 * allocated allowing for implementation specific data to be kept after
165 * the generic sync_timeline struct. Returns the fence object or
166 * NULL in case of error.
167 */
168struct fence *sync_pt_create(struct sync_timeline *parent, int size);
169
170/**
171 * sync_fence_create() - creates a sync fence
172 * @name:	name of fence to create
173 * @fence:	fence to add to the sync_fence
174 *
175 * Creates a sync_file containg @fence. Once this is called, the sync_file
176 * takes ownership of @fence.
177 */
178struct sync_file *sync_file_create(const char *name, struct fence *fence);
179
180/*
181 * API for sync_file consumers
182 */
183
184/**
185 * sync_file_merge() - merge two sync_files
186 * @name:	name of new fence
187 * @a:		sync_file a
188 * @b:		sync_file b
189 *
190 * Creates a new sync_file which contains copies of all the fences in both
191 * @a and @b.  @a and @b remain valid, independent sync_file. Returns the
192 * new merged sync_file or NULL in case of error.
193 */
194struct sync_file *sync_file_merge(const char *name,
195				    struct sync_file *a, struct sync_file *b);
196
197/**
198 * sync_file_fdget() - get a sync_file from an fd
199 * @fd:		fd referencing a fence
200 *
201 * Ensures @fd references a valid sync_file, increments the refcount of the
202 * backing file. Returns the sync_file or NULL in case of error.
203 */
204struct sync_file *sync_file_fdget(int fd);
205
206/**
207 * sync_file_put() - puts a reference of a sync_file
208 * @sync_file:	sync_file to put
209 *
210 * Puts a reference on @sync_fence.  If this is the last reference, the
211 * sync_fil and all it's sync_pts will be freed
212 */
213void sync_file_put(struct sync_file *sync_file);
214
215/**
216 * sync_file_install() - installs a sync_file into a file descriptor
217 * @sync_file:	sync_file to install
218 * @fd:		file descriptor in which to install the fence
219 *
220 * Installs @sync_file into @fd.  @fd's should be acquired through
221 * get_unused_fd_flags(O_CLOEXEC).
222 */
223void sync_file_install(struct sync_file *sync_file, int fd);
224
225#ifdef CONFIG_DEBUG_FS
226
227void sync_timeline_debug_add(struct sync_timeline *obj);
228void sync_timeline_debug_remove(struct sync_timeline *obj);
229void sync_file_debug_add(struct sync_file *fence);
230void sync_file_debug_remove(struct sync_file *fence);
231void sync_dump(void);
232
233#else
234# define sync_timeline_debug_add(obj)
235# define sync_timeline_debug_remove(obj)
236# define sync_file_debug_add(fence)
237# define sync_file_debug_remove(fence)
238# define sync_dump()
239#endif
240
241#endif /* _LINUX_SYNC_H */