include/linux/dma-resv.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
  50 /**
  51  * struct dma_resv_list - a list of shared fences
  52  * @rcu: for internal use
  53  * @shared_count: table of shared fences
  54  * @shared_max: for growing shared fence table
  55  * @shared: shared fence table
  56  */
  57 struct dma_resv_list {
  58         struct rcu_head rcu;
  59         u32 shared_count, shared_max;
  60         struct dma_fence __rcu *shared[];
  61 };
  62
  63 /**
  64  * struct dma_resv - a reservation object manages fences for a buffer
  65  * @lock: update side lock
  66  * @seq: sequence count for managing RCU read-side synchronization
  67  * @fence_excl: the exclusive fence, if there is one currently
  68  * @fence: list of current shared fences
  69  */
  70 struct dma_resv {
  71         struct ww_mutex lock;
  72
  73         struct dma_fence __rcu *fence_excl;
  74         struct dma_resv_list __rcu *fence;
  75 };
  76
  77 #define dma_resv_held(obj) lockdep_is_held(&(obj)->lock.base)
  78 #define dma_resv_assert_held(obj) lockdep_assert_held(&(obj)->lock.base)
  79
  80 /**
  81  * dma_resv_get_excl - get the reservation object's
  82  * exclusive fence, with update-side lock held
  83  * @obj: the reservation object
  84  *
  85  * Returns the exclusive fence (if any).  Does NOT take a
  86  * reference. Writers must hold obj->lock, readers may only
  87  * hold a RCU read side lock.
  88  *
  89  * RETURNS
  90  * The exclusive fence or NULL
  91  */
  92 static inline struct dma_fence *dma_resv_get_excl(struct dma_resv *obj)
  93 {
  94         return rcu_dereference_protected(obj->fence_excl,
  95                                          dma_resv_held(obj));
  96 }
  97
  98 /**
  99  * dma_resv_get_list - get the reservation object's
 100  * shared fence list, with update-side lock held
 101  * @obj: the reservation object
 102  *
 103  * Returns the shared fence list.  Does NOT take references to
 104  * the fence.  The obj->lock must be held.
 105  */
 106 static inline struct dma_resv_list *dma_resv_get_list(struct dma_resv *obj)
 107 {
 108         return rcu_dereference_protected(obj->fence,
 109                                          dma_resv_held(obj));
 110 }
 111
 112 /**
 113  * dma_resv_fences - read consistent fence pointers
 114  * @obj: reservation object where we get the fences from
 115  * @excl: pointer for the exclusive fence
 116  * @list: pointer for the shared fence list
 117  *
 118  * Make sure we have a consisten exclusive fence and shared fence list.
 119  * Must be called with rcu read side lock held.
 120  */
 121 static inline void dma_resv_fences(struct dma_resv *obj,
 122                                    struct dma_fence **excl,
 123                                    struct dma_resv_list **list,
 124                                    u32 *shared_count)
 125 {
 126         do {
 127                 *excl = rcu_dereference(obj->fence_excl);
 128                 *list = rcu_dereference(obj->fence);
 129                 *shared_count = *list ? (*list)->shared_count : 0;
 130                 smp_rmb(); /* See dma_resv_add_excl_fence */
 131         } while (rcu_access_pointer(obj->fence_excl) != *excl);
 132 }
 133
 134 /**
 135  * dma_resv_get_excl_rcu - get the reservation object's
 136  * exclusive fence, without lock held.
 137  * @obj: the reservation object
 138  *
 139  * If there is an exclusive fence, this atomically increments it's
 140  * reference count and returns it.
 141  *
 142  * RETURNS
 143  * The exclusive fence or NULL if none
 144  */
 145 static inline struct dma_fence *dma_resv_get_excl_rcu(struct dma_resv *obj)
 146 {
 147         struct dma_fence *fence;
 148
 149         if (!rcu_access_pointer(obj->fence_excl))
 150                 return NULL;
 151
 152         rcu_read_lock();
 153         fence = dma_fence_get_rcu_safe(&obj->fence_excl);
 154         rcu_read_unlock();
 155
 156         return fence;
 157 }
 158
 159 /**
 160  * dma_resv_lock - lock the reservation object
 161  * @obj: the reservation object
 162  * @ctx: the locking context
 163  *
 164  * Locks the reservation object for exclusive access and modification. Note,
 165  * that the lock is only against other writers, readers will run concurrently
 166  * with a writer under RCU. The seqlock is used to notify readers if they
 167  * overlap with a writer.
 168  *
 169  * As the reservation object may be locked by multiple parties in an
 170  * undefined order, a #ww_acquire_ctx is passed to unwind if a cycle
 171  * is detected. See ww_mutex_lock() and ww_acquire_init(). A reservation
 172  * object may be locked by itself by passing NULL as @ctx.
 173  */
 174 static inline int dma_resv_lock(struct dma_resv *obj,
 175                                 struct ww_acquire_ctx *ctx)
 176 {
 177         return ww_mutex_lock(&obj->lock, ctx);
 178 }
 179
 180 /**
 181  * dma_resv_lock_interruptible - lock the reservation object
 182  * @obj: the reservation object
 183  * @ctx: the locking context
 184  *
 185  * Locks the reservation object interruptible for exclusive access and
 186  * modification. Note, that the lock is only against other writers, readers
 187  * will run concurrently with a writer under RCU. The seqlock is used to
 188  * notify readers if they overlap with a writer.
 189  *
 190  * As the reservation object may be locked by multiple parties in an
 191  * undefined order, a #ww_acquire_ctx is passed to unwind if a cycle
 192  * is detected. See ww_mutex_lock() and ww_acquire_init(). A reservation
 193  * object may be locked by itself by passing NULL as @ctx.
 194  */
 195 static inline int dma_resv_lock_interruptible(struct dma_resv *obj,
 196                                               struct ww_acquire_ctx *ctx)
 197 {
 198         return ww_mutex_lock_interruptible(&obj->lock, ctx);
 199 }
 200
 201 /**
 202  * dma_resv_lock_slow - slowpath lock the reservation object
 203  * @obj: the reservation object
 204  * @ctx: the locking context
 205  *
 206  * Acquires the reservation object after a die case. This function
 207  * will sleep until the lock becomes available. See dma_resv_lock() as
 208  * well.
 209  */
 210 static inline void dma_resv_lock_slow(struct dma_resv *obj,
 211                                       struct ww_acquire_ctx *ctx)
 212 {
 213         ww_mutex_lock_slow(&obj->lock, ctx);
 214 }
 215
 216 /**
 217  * dma_resv_lock_slow_interruptible - slowpath lock the reservation
 218  * object, interruptible
 219  * @obj: the reservation object
 220  * @ctx: the locking context
 221  *
 222  * Acquires the reservation object interruptible after a die case. This function
 223  * will sleep until the lock becomes available. See
 224  * dma_resv_lock_interruptible() as well.
 225  */
 226 static inline int dma_resv_lock_slow_interruptible(struct dma_resv *obj,
 227                                                    struct ww_acquire_ctx *ctx)
 228 {
 229         return ww_mutex_lock_slow_interruptible(&obj->lock, ctx);
 230 }
 231
 232 /**
 233  * dma_resv_trylock - trylock the reservation object
 234  * @obj: the reservation object
 235  *
 236  * Tries to lock the reservation object for exclusive access and modification.
 237  * Note, that the lock is only against other writers, readers will run
 238  * concurrently with a writer under RCU. The seqlock is used to notify readers
 239  * if they overlap with a writer.
 240  *
 241  * Also note that since no context is provided, no deadlock protection is
 242  * possible.
 243  *
 244  * Returns true if the lock was acquired, false otherwise.
 245  */
 246 static inline bool __must_check dma_resv_trylock(struct dma_resv *obj)
 247 {
 248         return ww_mutex_trylock(&obj->lock);
 249 }
 250
 251 /**
 252  * dma_resv_is_locked - is the reservation object locked
 253  * @obj: the reservation object
 254  *
 255  * Returns true if the mutex is locked, false if unlocked.
 256  */
 257 static inline bool dma_resv_is_locked(struct dma_resv *obj)
 258 {
 259         return ww_mutex_is_locked(&obj->lock);
 260 }
 261
 262 /**
 263  * dma_resv_locking_ctx - returns the context used to lock the object
 264  * @obj: the reservation object
 265  *
 266  * Returns the context used to lock a reservation object or NULL if no context
 267  * was used or the object is not locked at all.
 268  */
 269 static inline struct ww_acquire_ctx *dma_resv_locking_ctx(struct dma_resv *obj)
 270 {
 271         return READ_ONCE(obj->lock.ctx);
 272 }
 273
 274 /**
 275  * dma_resv_unlock - unlock the reservation object
 276  * @obj: the reservation object
 277  *
 278  * Unlocks the reservation object following exclusive access.
 279  */
 280 static inline void dma_resv_unlock(struct dma_resv *obj)
 281 {
 282 #ifdef CONFIG_DEBUG_MUTEXES
 283         /* Test shared fence slot reservation */
 284         if (rcu_access_pointer(obj->fence)) {
 285                 struct dma_resv_list *fence = dma_resv_get_list(obj);
 286
 287                 fence->shared_max = fence->shared_count;
 288         }
 289 #endif
 290         ww_mutex_unlock(&obj->lock);
 291 }
 292
 293 void dma_resv_init(struct dma_resv *obj);
 294 void dma_resv_fini(struct dma_resv *obj);
 295 int dma_resv_reserve_shared(struct dma_resv *obj, unsigned int num_fences);
 296 void dma_resv_add_shared_fence(struct dma_resv *obj, struct dma_fence *fence);
 297
 298 void dma_resv_add_excl_fence(struct dma_resv *obj, struct dma_fence *fence);
 299
 300 int dma_resv_get_fences_rcu(struct dma_resv *obj,
 301                             struct dma_fence **pfence_excl,
 302                             unsigned *pshared_count,
 303                             struct dma_fence ***pshared);
 304
 305 int dma_resv_copy_fences(struct dma_resv *dst, struct dma_resv *src);
 306
 307 long dma_resv_wait_timeout_rcu(struct dma_resv *obj, bool wait_all, bool intr,
 308                                unsigned long timeout);
 309
 310 bool dma_resv_test_signaled_rcu(struct dma_resv *obj, bool test_all);
 311
 312 #endif /* _LINUX_RESERVATION_H */