include/linux/reservation.h

   1 /*
   2  * Header file for reservations for dma-buf and ttm
   3  *
   4  * Copyright(C) 2011 Linaro Limited. All rights reserved.
   5  * Copyright (C) 2012-2013 Canonical Ltd
   6  * Copyright (C) 2012 Texas Instruments
   7  *
   8  * Authors:
   9  * Rob Clark <robdclark@gmail.com>
  10  * Maarten Lankhorst <maarten.lankhorst@canonical.com>
  11  * Thomas Hellstrom <thellstrom-at-vmware-dot-com>
  12  *
  13  * Based on bo.c which bears the following copyright notice,
  14  * but is dual licensed:
  15  *
  16  * Copyright (c) 2006-2009 VMware, Inc., Palo Alto, CA., USA
  17  * All Rights Reserved.
  18  *
  19  * Permission is hereby granted, free of charge, to any person obtaining a
  20  * copy of this software and associated documentation files (the
  21  * "Software"), to deal in the Software without restriction, including
  22  * without limitation the rights to use, copy, modify, merge, publish,
  23  * distribute, sub license, and/or sell copies of the Software, and to
  24  * permit persons to whom the Software is furnished to do so, subject to
  25  * the following conditions:
  26  *
  27  * The above copyright notice and this permission notice (including the
  28  * next paragraph) shall be included in all copies or substantial portions
  29  * of the Software.
  30  *
  31  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  32  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  33  * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
  34  * THE COPYRIGHT HOLDERS, AUTHORS AND/OR ITS SUPPLIERS BE LIABLE FOR ANY CLAIM,
  35  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
  36  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
  37  * USE OR OTHER DEALINGS IN THE SOFTWARE.
  38  */
  39 #ifndef _LINUX_RESERVATION_H
  40 #define _LINUX_RESERVATION_H
  41
  42 #include <linux/ww_mutex.h>
  43 #include <linux/dma-fence.h>
  44 #include <linux/slab.h>
  45 #include <linux/seqlock.h>
  46 #include <linux/rcupdate.h>
  47
  48 extern struct ww_class reservation_ww_class;
  49 extern struct lock_class_key reservation_seqcount_class;
  50 extern const char reservation_seqcount_string[];
  51
  52 /**
  53  * struct reservation_object_list - a list of shared fences
  54  * @rcu: for internal use
  55  * @shared_count: table of shared fences
  56  * @shared_max: for growing shared fence table
  57  * @shared: shared fence table
  58  */
  59 struct reservation_object_list {
  60         struct rcu_head rcu;
  61         u32 shared_count, shared_max;
  62         struct dma_fence __rcu *shared[];
  63 };
  64
  65 /**
  66  * struct reservation_object - a reservation object manages fences for a buffer
  67  * @lock: update side lock
  68  * @seq: sequence count for managing RCU read-side synchronization
  69  * @fence_excl: the exclusive fence, if there is one currently
  70  * @fence: list of current shared fences
  71  */
  72 struct reservation_object {
  73         struct ww_mutex lock;
  74         seqcount_t seq;
  75
  76         struct dma_fence __rcu *fence_excl;
  77         struct reservation_object_list __rcu *fence;
  78 };
  79
  80 #define reservation_object_held(obj) lockdep_is_held(&(obj)->lock.base)
  81 #define reservation_object_assert_held(obj) \
  82         lockdep_assert_held(&(obj)->lock.base)
  83
  84 /**
  85  * reservation_object_init - initialize a reservation object
  86  * @obj: the reservation object
  87  */
  88 static inline void
  89 reservation_object_init(struct reservation_object *obj)
  90 {
  91         ww_mutex_init(&obj->lock, &reservation_ww_class);
  92
  93         __seqcount_init(&obj->seq, reservation_seqcount_string, &reservation_seqcount_class);
  94         RCU_INIT_POINTER(obj->fence, NULL);
  95         RCU_INIT_POINTER(obj->fence_excl, NULL);
  96 }
  97
  98 /**
  99  * reservation_object_fini - destroys a reservation object
 100  * @obj: the reservation object
 101  */
 102 static inline void
 103 reservation_object_fini(struct reservation_object *obj)
 104 {
 105         int i;
 106         struct reservation_object_list *fobj;
 107         struct dma_fence *excl;
 108
 109         /*
 110          * This object should be dead and all references must have
 111          * been released to it, so no need to be protected with rcu.
 112          */
 113         excl = rcu_dereference_protected(obj->fence_excl, 1);
 114         if (excl)
 115                 dma_fence_put(excl);
 116
 117         fobj = rcu_dereference_protected(obj->fence, 1);
 118         if (fobj) {
 119                 for (i = 0; i < fobj->shared_count; ++i)
 120                         dma_fence_put(rcu_dereference_protected(fobj->shared[i], 1));
 121
 122                 kfree(fobj);
 123         }
 124
 125         ww_mutex_destroy(&obj->lock);
 126 }
 127
 128 /**
 129  * reservation_object_get_list - get the reservation object's
 130  * shared fence list, with update-side lock held
 131  * @obj: the reservation object
 132  *
 133  * Returns the shared fence list.  Does NOT take references to
 134  * the fence.  The obj->lock must be held.
 135  */
 136 static inline struct reservation_object_list *
 137 reservation_object_get_list(struct reservation_object *obj)
 138 {
 139         return rcu_dereference_protected(obj->fence,
 140                                          reservation_object_held(obj));
 141 }
 142
 143 /**
 144  * reservation_object_lock - lock the reservation object
 145  * @obj: the reservation object
 146  * @ctx: the locking context
 147  *
 148  * Locks the reservation object for exclusive access and modification. Note,
 149  * that the lock is only against other writers, readers will run concurrently
 150  * with a writer under RCU. The seqlock is used to notify readers if they
 151  * overlap with a writer.
 152  *
 153  * As the reservation object may be locked by multiple parties in an
 154  * undefined order, a #ww_acquire_ctx is passed to unwind if a cycle
 155  * is detected. See ww_mutex_lock() and ww_acquire_init(). A reservation
 156  * object may be locked by itself by passing NULL as @ctx.
 157  */
 158 static inline int
 159 reservation_object_lock(struct reservation_object *obj,
 160                         struct ww_acquire_ctx *ctx)
 161 {
 162         return ww_mutex_lock(&obj->lock, ctx);
 163 }
 164
 165 /**
 166  * reservation_object_lock_interruptible - lock the reservation object
 167  * @obj: the reservation object
 168  * @ctx: the locking context
 169  *
 170  * Locks the reservation object interruptible for exclusive access and
 171  * modification. Note, that the lock is only against other writers, readers
 172  * will run concurrently with a writer under RCU. The seqlock is used to
 173  * notify readers if they overlap with a writer.
 174  *
 175  * As the reservation object may be locked by multiple parties in an
 176  * undefined order, a #ww_acquire_ctx is passed to unwind if a cycle
 177  * is detected. See ww_mutex_lock() and ww_acquire_init(). A reservation
 178  * object may be locked by itself by passing NULL as @ctx.
 179  */
 180 static inline int
 181 reservation_object_lock_interruptible(struct reservation_object *obj,
 182                                       struct ww_acquire_ctx *ctx)
 183 {
 184         return ww_mutex_lock_interruptible(&obj->lock, ctx);
 185 }
 186
 187
 188 /**
 189  * reservation_object_trylock - trylock the reservation object
 190  * @obj: the reservation object
 191  *
 192  * Tries to lock the reservation object for exclusive access and modification.
 193  * Note, that the lock is only against other writers, readers will run
 194  * concurrently with a writer under RCU. The seqlock is used to notify readers
 195  * if they overlap with a writer.
 196  *
 197  * Also note that since no context is provided, no deadlock protection is
 198  * possible.
 199  *
 200  * Returns true if the lock was acquired, false otherwise.
 201  */
 202 static inline bool __must_check
 203 reservation_object_trylock(struct reservation_object *obj)
 204 {
 205         return ww_mutex_trylock(&obj->lock);
 206 }
 207
 208 /**
 209  * reservation_object_unlock - unlock the reservation object
 210  * @obj: the reservation object
 211  *
 212  * Unlocks the reservation object following exclusive access.
 213  */
 214 static inline void
 215 reservation_object_unlock(struct reservation_object *obj)
 216 {
 217 #ifdef CONFIG_DEBUG_MUTEXES
 218         /* Test shared fence slot reservation */
 219         if (obj->fence)
 220                 obj->fence->shared_max = obj->fence->shared_count;
 221 #endif
 222         ww_mutex_unlock(&obj->lock);
 223 }
 224
 225 /**
 226  * reservation_object_get_excl - get the reservation object's
 227  * exclusive fence, with update-side lock held
 228  * @obj: the reservation object
 229  *
 230  * Returns the exclusive fence (if any).  Does NOT take a
 231  * reference. Writers must hold obj->lock, readers may only
 232  * hold a RCU read side lock.
 233  *
 234  * RETURNS
 235  * The exclusive fence or NULL
 236  */
 237 static inline struct dma_fence *
 238 reservation_object_get_excl(struct reservation_object *obj)
 239 {
 240         return rcu_dereference_protected(obj->fence_excl,
 241                                          reservation_object_held(obj));
 242 }
 243
 244 /**
 245  * reservation_object_get_excl_rcu - get the reservation object's
 246  * exclusive fence, without lock held.
 247  * @obj: the reservation object
 248  *
 249  * If there is an exclusive fence, this atomically increments it's
 250  * reference count and returns it.
 251  *
 252  * RETURNS
 253  * The exclusive fence or NULL if none
 254  */
 255 static inline struct dma_fence *
 256 reservation_object_get_excl_rcu(struct reservation_object *obj)
 257 {
 258         struct dma_fence *fence;
 259
 260         if (!rcu_access_pointer(obj->fence_excl))
 261                 return NULL;
 262
 263         rcu_read_lock();
 264         fence = dma_fence_get_rcu_safe(&obj->fence_excl);
 265         rcu_read_unlock();
 266
 267         return fence;
 268 }
 269
 270 int reservation_object_reserve_shared(struct reservation_object *obj,
 271                                       unsigned int num_fences);
 272 void reservation_object_add_shared_fence(struct reservation_object *obj,
 273                                          struct dma_fence *fence);
 274
 275 void reservation_object_add_excl_fence(struct reservation_object *obj,
 276                                        struct dma_fence *fence);
 277
 278 int reservation_object_get_fences_rcu(struct reservation_object *obj,
 279                                       struct dma_fence **pfence_excl,
 280                                       unsigned *pshared_count,
 281                                       struct dma_fence ***pshared);
 282
 283 int reservation_object_copy_fences(struct reservation_object *dst,
 284                                    struct reservation_object *src);
 285
 286 long reservation_object_wait_timeout_rcu(struct reservation_object *obj,
 287                                          bool wait_all, bool intr,
 288                                          unsigned long timeout);
 289
 290 bool reservation_object_test_signaled_rcu(struct reservation_object *obj,
 291                                           bool test_all);
 292
 293 #endif /* _LINUX_RESERVATION_H */