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