drivers/staging/gma500/psb_ttm_fence_api.h

   1 /**************************************************************************
   2  *
   3  * Copyright (c) 2006-2008 Tungsten Graphics, Inc., Cedar Park, TX., USA
   4  * All Rights Reserved.
   5  * Copyright (c) 2009 VMware, Inc., Palo Alto, CA., USA
   6  * All Rights Reserved.
   7  *
   8  * This program is free software; you can redistribute it and/or modify it
   9  * under the terms and conditions of the GNU General Public License,
  10  * version 2, as published by the Free Software Foundation.
  11  *
  12  * This program is distributed in the hope it will be useful, but WITHOUT
  13  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  14  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  15  * more details.
  16  *
  17  * You should have received a copy of the GNU General Public License along with
  18  * this program; if not, write to the Free Software Foundation, Inc.,
  19  * 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  **************************************************************************/
  22 /*
  23  * Authors: Thomas Hellstrom <thomas-at-tungstengraphics-dot-com>
  24  */
  25 #ifndef _TTM_FENCE_API_H_
  26 #define _TTM_FENCE_API_H_
  27
  28 #include <linux/list.h>
  29 #include <linux/kref.h>
  30
  31 #define TTM_FENCE_FLAG_EMIT (1 << 0)
  32 #define TTM_FENCE_TYPE_EXE  (1 << 0)
  33
  34 struct ttm_fence_device;
  35
  36 /**
  37  * struct ttm_fence_info
  38  *
  39  * @fence_class:    The fence class.
  40  * @fence_type:     Bitfield indicating types for this fence.
  41  * @signaled_types: Bitfield indicating which types are signaled.
  42  * @error:          Last error reported from the device.
  43  *
  44  * Used as output from the ttm_fence_get_info
  45  */
  46
  47 struct ttm_fence_info {
  48         uint32_t signaled_types;
  49         uint32_t error;
  50 };
  51
  52 /**
  53  * struct ttm_fence_object
  54  *
  55  * @fdev:            Pointer to the fence device struct.
  56  * @kref:            Holds the reference count of this fence object.
  57  * @ring:            List head used for the circular list of not-completely
  58  *                   signaled fences.
  59  * @info:            Data for fast retrieval using the ttm_fence_get_info()
  60  * function.
  61  * @timeout_jiffies: Absolute jiffies value indicating when this fence
  62  *                   object times out and, if waited on, calls ttm_fence_lockup
  63  *                   to check for and resolve a GPU lockup.
  64  * @sequence:        Fence sequence number.
  65  * @waiting_types:   Types currently waited on.
  66  * @destroy:         Called to free the fence object, when its refcount has
  67  *                   reached zero. If NULL, kfree is used.
  68  *
  69  * This struct is provided in the driver interface so that drivers can
  70  * derive from it and create their own fence implementation. All members
  71  * are private to the fence implementation and the fence driver callbacks.
  72  * Otherwise a driver may access the derived object using container_of().
  73  */
  74
  75 struct ttm_fence_object {
  76         struct ttm_fence_device *fdev;
  77         struct kref kref;
  78         uint32_t fence_class;
  79         uint32_t fence_type;
  80
  81         /*
  82          * The below fields are protected by the fence class
  83          * manager spinlock.
  84          */
  85
  86         struct list_head ring;
  87         struct ttm_fence_info info;
  88         unsigned long timeout_jiffies;
  89         uint32_t sequence;
  90         uint32_t waiting_types;
  91         void (*destroy) (struct ttm_fence_object *);
  92 };
  93
  94 /**
  95  * ttm_fence_object_init
  96  *
  97  * @fdev: Pointer to a struct ttm_fence_device.
  98  * @fence_class: Fence class for this fence.
  99  * @type: Fence type for this fence.
 100  * @create_flags: Flags indicating varios actions at init time. At this point
 101  * there's only TTM_FENCE_FLAG_EMIT, which triggers a sequence emission to
 102  * the command stream.
 103  * @destroy: Destroy function. If NULL, kfree() is used.
 104  * @fence: The struct ttm_fence_object to initialize.
 105  *
 106  * Initialize a pre-allocated fence object. This function, together with the
 107  * destroy function makes it possible to derive driver-specific fence objects.
 108  */
 109
 110 extern int
 111 ttm_fence_object_init(struct ttm_fence_device *fdev,
 112                       uint32_t fence_class,
 113                       uint32_t type,
 114                       uint32_t create_flags,
 115                       void (*destroy) (struct ttm_fence_object *fence),
 116                       struct ttm_fence_object *fence);
 117
 118 /**
 119  * ttm_fence_object_create
 120  *
 121  * @fdev: Pointer to a struct ttm_fence_device.
 122  * @fence_class: Fence class for this fence.
 123  * @type: Fence type for this fence.
 124  * @create_flags: Flags indicating varios actions at init time. At this point
 125  * there's only TTM_FENCE_FLAG_EMIT, which triggers a sequence emission to
 126  * the command stream.
 127  * @c_fence: On successful termination, *(@c_fence) will point to the created
 128  * fence object.
 129  *
 130  * Create and initialize a struct ttm_fence_object. The destroy function will
 131  * be set to kfree().
 132  */
 133
 134 extern int
 135 ttm_fence_object_create(struct ttm_fence_device *fdev,
 136                         uint32_t fence_class,
 137                         uint32_t type,
 138                         uint32_t create_flags,
 139                         struct ttm_fence_object **c_fence);
 140
 141 /**
 142  * ttm_fence_object_wait
 143  *
 144  * @fence: The fence object to wait on.
 145  * @lazy: Allow sleeps to reduce the cpu-usage if polling.
 146  * @interruptible: Sleep interruptible when waiting.
 147  * @type_mask: Wait for the given type_mask to signal.
 148  *
 149  * Wait for a fence to signal the given type_mask. The function will
 150  * perform a fence_flush using type_mask. (See ttm_fence_object_flush).
 151  *
 152  * Returns
 153  * -ERESTART if interrupted by a signal.
 154  * May return driver-specific error codes if timed-out.
 155  */
 156
 157 extern int
 158 ttm_fence_object_wait(struct ttm_fence_object *fence,
 159                       bool lazy, bool interruptible, uint32_t type_mask);
 160
 161 /**
 162  * ttm_fence_object_flush
 163  *
 164  * @fence: The fence object to flush.
 165  * @flush_mask: Fence types to flush.
 166  *
 167  * Make sure that the given fence eventually signals the
 168  * types indicated by @flush_mask. Note that this may or may not
 169  * map to a CPU or GPU flush.
 170  */
 171
 172 extern int
 173 ttm_fence_object_flush(struct ttm_fence_object *fence, uint32_t flush_mask);
 174
 175 /**
 176  * ttm_fence_get_info
 177  *
 178  * @fence: The fence object.
 179  *
 180  * Copy the info block from the fence while holding relevant locks.
 181  */
 182
 183 struct ttm_fence_info ttm_fence_get_info(struct ttm_fence_object *fence);
 184
 185 /**
 186  * ttm_fence_object_ref
 187  *
 188  * @fence: The fence object.
 189  *
 190  * Return a ref-counted pointer to the fence object indicated by @fence.
 191  */
 192
 193 static inline struct ttm_fence_object *ttm_fence_object_ref(struct
 194                                                             ttm_fence_object
 195                                                             *fence)
 196 {
 197         kref_get(&fence->kref);
 198         return fence;
 199 }
 200
 201 /**
 202  * ttm_fence_object_unref
 203  *
 204  * @p_fence: Pointer to a ref-counted pinter to a struct ttm_fence_object.
 205  *
 206  * Unreference the fence object pointed to by *(@p_fence), clearing
 207  * *(p_fence).
 208  */
 209
 210 extern void ttm_fence_object_unref(struct ttm_fence_object **p_fence);
 211
 212 /**
 213  * ttm_fence_object_signaled
 214  *
 215  * @fence: Pointer to the struct ttm_fence_object.
 216  * @mask: Type mask to check whether signaled.
 217  *
 218  * This function checks (without waiting) whether the fence object
 219  * pointed to by @fence has signaled the types indicated by @mask,
 220  * and returns 1 if true, 0 if false. This function does NOT perform
 221  * an implicit fence flush.
 222  */
 223
 224 extern bool
 225 ttm_fence_object_signaled(struct ttm_fence_object *fence, uint32_t mask);
 226
 227 /**
 228  * ttm_fence_class
 229  *
 230  * @fence: Pointer to the struct ttm_fence_object.
 231  *
 232  * Convenience function that returns the fence class of a
 233  * struct ttm_fence_object.
 234  */
 235
 236 static inline uint32_t ttm_fence_class(const struct ttm_fence_object *fence)
 237 {
 238         return fence->fence_class;
 239 }
 240
 241 /**
 242  * ttm_fence_types
 243  *
 244  * @fence: Pointer to the struct ttm_fence_object.
 245  *
 246  * Convenience function that returns the fence types of a
 247  * struct ttm_fence_object.
 248  */
 249
 250 static inline uint32_t ttm_fence_types(const struct ttm_fence_object *fence)
 251 {
 252         return fence->fence_type;
 253 }
 254
 255 /*
 256  * The functions below are wrappers to the above functions, with
 257  * similar names but with sync_obj omitted. These wrappers are intended
 258  * to be plugged directly into the buffer object driver's sync object
 259  * API, if the driver chooses to use ttm_fence_objects as buffer object
 260  * sync objects. In the prototypes below, a sync_obj is cast to a
 261  * struct ttm_fence_object, whereas a sync_arg is cast to an
 262  * uint32_t representing a fence_type argument.
 263  */
 264
 265 extern bool ttm_fence_sync_obj_signaled(void *sync_obj, void *sync_arg);
 266 extern int ttm_fence_sync_obj_wait(void *sync_obj, void *sync_arg,
 267                                    bool lazy, bool interruptible);
 268 extern int ttm_fence_sync_obj_flush(void *sync_obj, void *sync_arg);
 269 extern void ttm_fence_sync_obj_unref(void **sync_obj);
 270 extern void *ttm_fence_sync_obj_ref(void *sync_obj);
 271
 272 #endif