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  *
  66  * There are multiple uses for this, with sometimes slightly different rules in
  67  * how the fence slots are used.
  68  *
  69  * One use is to synchronize cross-driver access to a struct dma_buf, either for
  70  * dynamic buffer management or just to handle implicit synchronization between
  71  * different users of the buffer in userspace. See &dma_buf.resv for a more
  72  * in-depth discussion.
  73  *
  74  * The other major use is to manage access and locking within a driver in a
  75  * buffer based memory manager. struct ttm_buffer_object is the canonical
  76  * example here, since this is where reservation objects originated from. But
  77  * use in drivers is spreading and some drivers also manage struct
  78  * drm_gem_object with the same scheme.
  79  */
  80 struct dma_resv {
  81         /**
  82          * @lock:
  83          *
  84          * Update side lock. Don't use directly, instead use the wrapper
  85          * functions like dma_resv_lock() and dma_resv_unlock().
  86          *
  87          * Drivers which use the reservation object to manage memory dynamically
  88          * also use this lock to protect buffer object state like placement,
  89          * allocation policies or throughout command submission.
  90          */
  91         struct ww_mutex lock;
  92
  93         /**
  94          * @seq:
  95          *
  96          * Sequence count for managing RCU read-side synchronization, allows
  97          * read-only access to @fence_excl and @fence while ensuring we take a
  98          * consistent snapshot.
  99          */
 100         seqcount_ww_mutex_t seq;
 101
 102         /**
 103          * @fence_excl:
 104          *
 105          * The exclusive fence, if there is one currently.
 106          *
 107          * There are two ways to update this fence:
 108          *
 109          * - First by calling dma_resv_add_excl_fence(), which replaces all
 110          *   fences attached to the reservation object. To guarantee that no
 111          *   fences are lost, this new fence must signal only after all previous
 112          *   fences, both shared and exclusive, have signalled. In some cases it
 113          *   is convenient to achieve that by attaching a struct dma_fence_array
 114          *   with all the new and old fences.
 115          *
 116          * - Alternatively the fence can be set directly, which leaves the
 117          *   shared fences unchanged. To guarantee that no fences are lost, this
 118          *   new fence must signal only after the previous exclusive fence has
 119          *   signalled. Since the shared fences are staying intact, it is not
 120          *   necessary to maintain any ordering against those. If semantically
 121          *   only a new access is added without actually treating the previous
 122          *   one as a dependency the exclusive fences can be strung together
 123          *   using struct dma_fence_chain.
 124          *
 125          * Note that actual semantics of what an exclusive or shared fence mean
 126          * is defined by the user, for reservation objects shared across drivers
 127          * see &dma_buf.resv.
 128          */
 129         struct dma_fence __rcu *fence_excl;
 130
 131         /**
 132          * @fence:
 133          *
 134          * List of current shared fences.
 135          *
 136          * There are no ordering constraints of shared fences against the
 137          * exclusive fence slot. If a waiter needs to wait for all access, it
 138          * has to wait for both sets of fences to signal.
 139          *
 140          * A new fence is added by calling dma_resv_add_shared_fence(). Since
 141          * this often needs to be done past the point of no return in command
 142          * submission it cannot fail, and therefore sufficient slots need to be
 143          * reserved by calling dma_resv_reserve_shared().
 144          *
 145          * Note that actual semantics of what an exclusive or shared fence mean
 146          * is defined by the user, for reservation objects shared across drivers
 147          * see &dma_buf.resv.
 148          */
 149         struct dma_resv_list __rcu *fence;
 150 };
 151
 152 /**
 153  * struct dma_resv_iter - current position into the dma_resv fences
 154  *
 155  * Don't touch this directly in the driver, use the accessor function instead.
 156  */
 157 struct dma_resv_iter {
 158         /** @obj: The dma_resv object we iterate over */
 159         struct dma_resv *obj;
 160
 161         /** @all_fences: If all fences should be returned */
 162         bool all_fences;
 163
 164         /** @fence: the currently handled fence */
 165         struct dma_fence *fence;
 166
 167         /** @seq: sequence number to check for modifications */
 168         unsigned int seq;
 169
 170         /** @index: index into the shared fences */
 171         unsigned int index;
 172
 173         /** @fences: the shared fences; private, *MUST* not dereference  */
 174         struct dma_resv_list *fences;
 175
 176         /** @shared_count: number of shared fences */
 177         unsigned int shared_count;
 178
 179         /** @is_restarted: true if this is the first returned fence */
 180         bool is_restarted;
 181 };
 182
 183 struct dma_fence *dma_resv_iter_first_unlocked(struct dma_resv_iter *cursor);
 184 struct dma_fence *dma_resv_iter_next_unlocked(struct dma_resv_iter *cursor);
 185 struct dma_fence *dma_resv_iter_first(struct dma_resv_iter *cursor);
 186 struct dma_fence *dma_resv_iter_next(struct dma_resv_iter *cursor);
 187
 188 /**
 189  * dma_resv_iter_begin - initialize a dma_resv_iter object
 190  * @cursor: The dma_resv_iter object to initialize
 191  * @obj: The dma_resv object which we want to iterate over
 192  * @all_fences: If all fences should be returned or just the exclusive one
 193  */
 194 static inline void dma_resv_iter_begin(struct dma_resv_iter *cursor,
 195                                        struct dma_resv *obj,
 196                                        bool all_fences)
 197 {
 198         cursor->obj = obj;
 199         cursor->all_fences = all_fences;
 200         cursor->fence = NULL;
 201 }
 202
 203 /**
 204  * dma_resv_iter_end - cleanup a dma_resv_iter object
 205  * @cursor: the dma_resv_iter object which should be cleaned up
 206  *
 207  * Make sure that the reference to the fence in the cursor is properly
 208  * dropped.
 209  */
 210 static inline void dma_resv_iter_end(struct dma_resv_iter *cursor)
 211 {
 212         dma_fence_put(cursor->fence);
 213 }
 214
 215 /**
 216  * dma_resv_iter_is_exclusive - test if the current fence is the exclusive one
 217  * @cursor: the cursor of the current position
 218  *
 219  * Returns true if the currently returned fence is the exclusive one.
 220  */
 221 static inline bool dma_resv_iter_is_exclusive(struct dma_resv_iter *cursor)
 222 {
 223         return cursor->index == 0;
 224 }
 225
 226 /**
 227  * dma_resv_iter_is_restarted - test if this is the first fence after a restart
 228  * @cursor: the cursor with the current position
 229  *
 230  * Return true if this is the first fence in an iteration after a restart.
 231  */
 232 static inline bool dma_resv_iter_is_restarted(struct dma_resv_iter *cursor)
 233 {
 234         return cursor->is_restarted;
 235 }
 236
 237 /**
 238  * dma_resv_for_each_fence_unlocked - unlocked fence iterator
 239  * @cursor: a struct dma_resv_iter pointer
 240  * @fence: the current fence
 241  *
 242  * Iterate over the fences in a struct dma_resv object without holding the
 243  * &dma_resv.lock and using RCU instead. The cursor needs to be initialized
 244  * with dma_resv_iter_begin() and cleaned up with dma_resv_iter_end(). Inside
 245  * the iterator a reference to the dma_fence is held and the RCU lock dropped.
 246  * When the dma_resv is modified the iteration starts over again.
 247  */
 248 #define dma_resv_for_each_fence_unlocked(cursor, fence)                 \
 249         for (fence = dma_resv_iter_first_unlocked(cursor);              \
 250              fence; fence = dma_resv_iter_next_unlocked(cursor))
 251
 252 /**
 253  * dma_resv_for_each_fence - fence iterator
 254  * @cursor: a struct dma_resv_iter pointer
 255  * @obj: a dma_resv object pointer
 256  * @all_fences: true if all fences should be returned
 257  * @fence: the current fence
 258  *
 259  * Iterate over the fences in a struct dma_resv object while holding the
 260  * &dma_resv.lock. @all_fences controls if the shared fences are returned as
 261  * well. The cursor initialisation is part of the iterator and the fence stays
 262  * valid as long as the lock is held and so no extra reference to the fence is
 263  * taken.
 264  */
 265 #define dma_resv_for_each_fence(cursor, obj, all_fences, fence) \
 266         for (dma_resv_iter_begin(cursor, obj, all_fences),      \
 267              fence = dma_resv_iter_first(cursor); fence;        \
 268              fence = dma_resv_iter_next(cursor))
 269
 270 #define dma_resv_held(obj) lockdep_is_held(&(obj)->lock.base)
 271 #define dma_resv_assert_held(obj) lockdep_assert_held(&(obj)->lock.base)
 272
 273 #ifdef CONFIG_DEBUG_MUTEXES
 274 void dma_resv_reset_shared_max(struct dma_resv *obj);
 275 #else
 276 static inline void dma_resv_reset_shared_max(struct dma_resv *obj) {}
 277 #endif
 278
 279 /**
 280  * dma_resv_lock - lock the reservation object
 281  * @obj: the reservation object
 282  * @ctx: the locking context
 283  *
 284  * Locks the reservation object for exclusive access and modification. Note,
 285  * that the lock is only against other writers, readers will run concurrently
 286  * with a writer under RCU. The seqlock is used to notify readers if they
 287  * overlap with a writer.
 288  *
 289  * As the reservation object may be locked by multiple parties in an
 290  * undefined order, a #ww_acquire_ctx is passed to unwind if a cycle
 291  * is detected. See ww_mutex_lock() and ww_acquire_init(). A reservation
 292  * object may be locked by itself by passing NULL as @ctx.
 293  *
 294  * When a die situation is indicated by returning -EDEADLK all locks held by
 295  * @ctx must be unlocked and then dma_resv_lock_slow() called on @obj.
 296  *
 297  * Unlocked by calling dma_resv_unlock().
 298  *
 299  * See also dma_resv_lock_interruptible() for the interruptible variant.
 300  */
 301 static inline int dma_resv_lock(struct dma_resv *obj,
 302                                 struct ww_acquire_ctx *ctx)
 303 {
 304         return ww_mutex_lock(&obj->lock, ctx);
 305 }
 306
 307 /**
 308  * dma_resv_lock_interruptible - lock the reservation object
 309  * @obj: the reservation object
 310  * @ctx: the locking context
 311  *
 312  * Locks the reservation object interruptible for exclusive access and
 313  * modification. Note, that the lock is only against other writers, readers
 314  * will run concurrently with a writer under RCU. The seqlock is used to
 315  * notify readers if they overlap with a writer.
 316  *
 317  * As the reservation object may be locked by multiple parties in an
 318  * undefined order, a #ww_acquire_ctx is passed to unwind if a cycle
 319  * is detected. See ww_mutex_lock() and ww_acquire_init(). A reservation
 320  * object may be locked by itself by passing NULL as @ctx.
 321  *
 322  * When a die situation is indicated by returning -EDEADLK all locks held by
 323  * @ctx must be unlocked and then dma_resv_lock_slow_interruptible() called on
 324  * @obj.
 325  *
 326  * Unlocked by calling dma_resv_unlock().
 327  */
 328 static inline int dma_resv_lock_interruptible(struct dma_resv *obj,
 329                                               struct ww_acquire_ctx *ctx)
 330 {
 331         return ww_mutex_lock_interruptible(&obj->lock, ctx);
 332 }
 333
 334 /**
 335  * dma_resv_lock_slow - slowpath lock the reservation object
 336  * @obj: the reservation object
 337  * @ctx: the locking context
 338  *
 339  * Acquires the reservation object after a die case. This function
 340  * will sleep until the lock becomes available. See dma_resv_lock() as
 341  * well.
 342  *
 343  * See also dma_resv_lock_slow_interruptible() for the interruptible variant.
 344  */
 345 static inline void dma_resv_lock_slow(struct dma_resv *obj,
 346                                       struct ww_acquire_ctx *ctx)
 347 {
 348         ww_mutex_lock_slow(&obj->lock, ctx);
 349 }
 350
 351 /**
 352  * dma_resv_lock_slow_interruptible - slowpath lock the reservation
 353  * object, interruptible
 354  * @obj: the reservation object
 355  * @ctx: the locking context
 356  *
 357  * Acquires the reservation object interruptible after a die case. This function
 358  * will sleep until the lock becomes available. See
 359  * dma_resv_lock_interruptible() as well.
 360  */
 361 static inline int dma_resv_lock_slow_interruptible(struct dma_resv *obj,
 362                                                    struct ww_acquire_ctx *ctx)
 363 {
 364         return ww_mutex_lock_slow_interruptible(&obj->lock, ctx);
 365 }
 366
 367 /**
 368  * dma_resv_trylock - trylock the reservation object
 369  * @obj: the reservation object
 370  *
 371  * Tries to lock the reservation object for exclusive access and modification.
 372  * Note, that the lock is only against other writers, readers will run
 373  * concurrently with a writer under RCU. The seqlock is used to notify readers
 374  * if they overlap with a writer.
 375  *
 376  * Also note that since no context is provided, no deadlock protection is
 377  * possible, which is also not needed for a trylock.
 378  *
 379  * Returns true if the lock was acquired, false otherwise.
 380  */
 381 static inline bool __must_check dma_resv_trylock(struct dma_resv *obj)
 382 {
 383         return ww_mutex_trylock(&obj->lock, NULL);
 384 }
 385
 386 /**
 387  * dma_resv_is_locked - is the reservation object locked
 388  * @obj: the reservation object
 389  *
 390  * Returns true if the mutex is locked, false if unlocked.
 391  */
 392 static inline bool dma_resv_is_locked(struct dma_resv *obj)
 393 {
 394         return ww_mutex_is_locked(&obj->lock);
 395 }
 396
 397 /**
 398  * dma_resv_locking_ctx - returns the context used to lock the object
 399  * @obj: the reservation object
 400  *
 401  * Returns the context used to lock a reservation object or NULL if no context
 402  * was used or the object is not locked at all.
 403  *
 404  * WARNING: This interface is pretty horrible, but TTM needs it because it
 405  * doesn't pass the struct ww_acquire_ctx around in some very long callchains.
 406  * Everyone else just uses it to check whether they're holding a reservation or
 407  * not.
 408  */
 409 static inline struct ww_acquire_ctx *dma_resv_locking_ctx(struct dma_resv *obj)
 410 {
 411         return READ_ONCE(obj->lock.ctx);
 412 }
 413
 414 /**
 415  * dma_resv_unlock - unlock the reservation object
 416  * @obj: the reservation object
 417  *
 418  * Unlocks the reservation object following exclusive access.
 419  */
 420 static inline void dma_resv_unlock(struct dma_resv *obj)
 421 {
 422         dma_resv_reset_shared_max(obj);
 423         ww_mutex_unlock(&obj->lock);
 424 }
 425
 426 /**
 427  * dma_resv_excl_fence - return the object's exclusive fence
 428  * @obj: the reservation object
 429  *
 430  * Returns the exclusive fence (if any). Caller must either hold the objects
 431  * through dma_resv_lock() or the RCU read side lock through rcu_read_lock(),
 432  * or one of the variants of each
 433  *
 434  * RETURNS
 435  * The exclusive fence or NULL
 436  */
 437 static inline struct dma_fence *
 438 dma_resv_excl_fence(struct dma_resv *obj)
 439 {
 440         return rcu_dereference_check(obj->fence_excl, dma_resv_held(obj));
 441 }
 442
 443 /**
 444  * dma_resv_shared_list - get the reservation object's shared fence list
 445  * @obj: the reservation object
 446  *
 447  * Returns the shared fence list. Caller must either hold the objects
 448  * through dma_resv_lock() or the RCU read side lock through rcu_read_lock(),
 449  * or one of the variants of each
 450  */
 451 static inline struct dma_resv_list *dma_resv_shared_list(struct dma_resv *obj)
 452 {
 453         return rcu_dereference_check(obj->fence, dma_resv_held(obj));
 454 }
 455
 456 void dma_resv_init(struct dma_resv *obj);
 457 void dma_resv_fini(struct dma_resv *obj);
 458 int dma_resv_reserve_shared(struct dma_resv *obj, unsigned int num_fences);
 459 void dma_resv_add_shared_fence(struct dma_resv *obj, struct dma_fence *fence);
 460 void dma_resv_add_excl_fence(struct dma_resv *obj, struct dma_fence *fence);
 461 int dma_resv_get_fences(struct dma_resv *obj, struct dma_fence **pfence_excl,
 462                         unsigned *pshared_count, struct dma_fence ***pshared);
 463 int dma_resv_copy_fences(struct dma_resv *dst, struct dma_resv *src);
 464 long dma_resv_wait_timeout(struct dma_resv *obj, bool wait_all, bool intr,
 465                            unsigned long timeout);
 466 bool dma_resv_test_signaled(struct dma_resv *obj, bool test_all);
 467 void dma_resv_describe(struct dma_resv *obj, struct seq_file *seq);
 468
 469 #endif /* _LINUX_RESERVATION_H */