drivers/staging/android/sync.h

   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
  25 struct sync_timeline;
  26 struct 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  */
  38 struct 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  */
  64 struct 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
  83 static 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
  89 struct 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  */
 106 struct 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  */
 136 struct 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  */
 147 void 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  */
 156 void 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  */
 168 struct 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  */
 178 struct 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  */
 194 struct 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  */
 204 struct 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  */
 213 void 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  */
 223 void sync_file_install(struct sync_file *sync_file, int fd);
 224
 225 #ifdef CONFIG_DEBUG_FS
 226
 227 void sync_timeline_debug_add(struct sync_timeline *obj);
 228 void sync_timeline_debug_remove(struct sync_timeline *obj);
 229 void sync_file_debug_add(struct sync_file *fence);
 230 void sync_file_debug_remove(struct sync_file *fence);
 231 void 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 */