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_get_excl - get the reservation object's
  86  * exclusive fence, with update-side lock held
  87  * @obj: the reservation object
  88  *
  89  * Returns the exclusive fence (if any).  Does NOT take a
  90  * reference. Writers must hold obj->lock, readers may only
  91  * hold a RCU read side lock.
  92  *
  93  * RETURNS
  94  * The exclusive fence or NULL
  95  */
  96 static inline struct dma_fence *
  97 reservation_object_get_excl(struct reservation_object *obj)
  98 {
  99         return rcu_dereference_protected(obj->fence_excl,
 100                                          reservation_object_held(obj));
 101 }
 102
 103 /**
 104  * reservation_object_get_list - get the reservation object's
 105  * shared fence list, with update-side lock held
 106  * @obj: the reservation object
 107  *
 108  * Returns the shared fence list.  Does NOT take references to
 109  * the fence.  The obj->lock must be held.
 110  */
 111 static inline struct reservation_object_list *
 112 reservation_object_get_list(struct reservation_object *obj)
 113 {
 114         return rcu_dereference_protected(obj->fence,
 115                                          reservation_object_held(obj));
 116 }
 117
 118 /**
 119  * reservation_object_fences - read consistent fence pointers
 120  * @obj: reservation object where we get the fences from
 121  * @excl: pointer for the exclusive fence
 122  * @list: pointer for the shared fence list
 123  *
 124  * Make sure we have a consisten exclusive fence and shared fence list.
 125  * Must be called with rcu read side lock held.
 126  */
 127 static inline void
 128 reservation_object_fences(struct reservation_object *obj,
 129                           struct dma_fence **excl,
 130                           struct reservation_object_list **list,
 131                           u32 *shared_count)
 132 {
 133         unsigned int seq;
 134
 135         do {
 136                 seq = read_seqcount_begin(&obj->seq);
 137                 *excl = rcu_dereference(obj->fence_excl);
 138                 *list = rcu_dereference(obj->fence);
 139                 *shared_count = *list ? (*list)->shared_count : 0;
 140         } while (read_seqcount_retry(&obj->seq, seq));
 141 }
 142
 143 /**
 144  * reservation_object_get_excl_rcu - get the reservation object's
 145  * exclusive fence, without lock held.
 146  * @obj: the reservation object
 147  *
 148  * If there is an exclusive fence, this atomically increments it's
 149  * reference count and returns it.
 150  *
 151  * RETURNS
 152  * The exclusive fence or NULL if none
 153  */
 154 static inline struct dma_fence *
 155 reservation_object_get_excl_rcu(struct reservation_object *obj)
 156 {
 157         struct dma_fence *fence;
 158
 159         if (!rcu_access_pointer(obj->fence_excl))
 160                 return NULL;
 161
 162         rcu_read_lock();
 163         fence = dma_fence_get_rcu_safe(&obj->fence_excl);
 164         rcu_read_unlock();
 165
 166         return fence;
 167 }
 168
 169 /**
 170  * reservation_object_lock - lock the reservation object
 171  * @obj: the reservation object
 172  * @ctx: the locking context
 173  *
 174  * Locks the reservation object for exclusive access and modification. Note,
 175  * that the lock is only against other writers, readers will run concurrently
 176  * with a writer under RCU. The seqlock is used to notify readers if they
 177  * overlap with a writer.
 178  *
 179  * As the reservation object may be locked by multiple parties in an
 180  * undefined order, a #ww_acquire_ctx is passed to unwind if a cycle
 181  * is detected. See ww_mutex_lock() and ww_acquire_init(). A reservation
 182  * object may be locked by itself by passing NULL as @ctx.
 183  */
 184 static inline int
 185 reservation_object_lock(struct reservation_object *obj,
 186                         struct ww_acquire_ctx *ctx)
 187 {
 188         return ww_mutex_lock(&obj->lock, ctx);
 189 }
 190
 191 /**
 192  * reservation_object_lock_interruptible - lock the reservation object
 193  * @obj: the reservation object
 194  * @ctx: the locking context
 195  *
 196  * Locks the reservation object interruptible for exclusive access and
 197  * modification. Note, that the lock is only against other writers, readers
 198  * will run concurrently with a writer under RCU. The seqlock is used to
 199  * notify readers if they overlap with a writer.
 200  *
 201  * As the reservation object may be locked by multiple parties in an
 202  * undefined order, a #ww_acquire_ctx is passed to unwind if a cycle
 203  * is detected. See ww_mutex_lock() and ww_acquire_init(). A reservation
 204  * object may be locked by itself by passing NULL as @ctx.
 205  */
 206 static inline int
 207 reservation_object_lock_interruptible(struct reservation_object *obj,
 208                                       struct ww_acquire_ctx *ctx)
 209 {
 210         return ww_mutex_lock_interruptible(&obj->lock, ctx);
 211 }
 212
 213 /**
 214  * reservation_object_lock_slow - slowpath lock the reservation object
 215  * @obj: the reservation object
 216  * @ctx: the locking context
 217  *
 218  * Acquires the reservation object after a die case. This function
 219  * will sleep until the lock becomes available. See reservation_object_lock() as
 220  * well.
 221  */
 222 static inline void
 223 reservation_object_lock_slow(struct reservation_object *obj,
 224                              struct ww_acquire_ctx *ctx)
 225 {
 226         ww_mutex_lock_slow(&obj->lock, ctx);
 227 }
 228
 229 /**
 230  * reservation_object_lock_slow_interruptible - slowpath lock the reservation
 231  * object, interruptible
 232  * @obj: the reservation object
 233  * @ctx: the locking context
 234  *
 235  * Acquires the reservation object interruptible after a die case. This function
 236  * will sleep until the lock becomes available. See
 237  * reservation_object_lock_interruptible() as well.
 238  */
 239 static inline int
 240 reservation_object_lock_slow_interruptible(struct reservation_object *obj,
 241                                            struct ww_acquire_ctx *ctx)
 242 {
 243         return ww_mutex_lock_slow_interruptible(&obj->lock, ctx);
 244 }
 245
 246 /**
 247  * reservation_object_trylock - trylock the reservation object
 248  * @obj: the reservation object
 249  *
 250  * Tries to lock the reservation object for exclusive access and modification.
 251  * Note, that the lock is only against other writers, readers will run
 252  * concurrently with a writer under RCU. The seqlock is used to notify readers
 253  * if they overlap with a writer.
 254  *
 255  * Also note that since no context is provided, no deadlock protection is
 256  * possible.
 257  *
 258  * Returns true if the lock was acquired, false otherwise.
 259  */
 260 static inline bool __must_check
 261 reservation_object_trylock(struct reservation_object *obj)
 262 {
 263         return ww_mutex_trylock(&obj->lock);
 264 }
 265
 266 /**
 267  * reservation_object_is_locked - is the reservation object locked
 268  * @obj: the reservation object
 269  *
 270  * Returns true if the mutex is locked, false if unlocked.
 271  */
 272 static inline bool
 273 reservation_object_is_locked(struct reservation_object *obj)
 274 {
 275         return ww_mutex_is_locked(&obj->lock);
 276 }
 277
 278 /**
 279  * reservation_object_locking_ctx - returns the context used to lock the object
 280  * @obj: the reservation object
 281  *
 282  * Returns the context used to lock a reservation object or NULL if no context
 283  * was used or the object is not locked at all.
 284  */
 285 static inline struct ww_acquire_ctx *
 286 reservation_object_locking_ctx(struct reservation_object *obj)
 287 {
 288         return READ_ONCE(obj->lock.ctx);
 289 }
 290
 291 /**
 292  * reservation_object_unlock - unlock the reservation object
 293  * @obj: the reservation object
 294  *
 295  * Unlocks the reservation object following exclusive access.
 296  */
 297 static inline void
 298 reservation_object_unlock(struct reservation_object *obj)
 299 {
 300 #ifdef CONFIG_DEBUG_MUTEXES
 301         /* Test shared fence slot reservation */
 302         if (rcu_access_pointer(obj->fence)) {
 303                 struct reservation_object_list *fence =
 304                         reservation_object_get_list(obj);
 305
 306                 fence->shared_max = fence->shared_count;
 307         }
 308 #endif
 309         ww_mutex_unlock(&obj->lock);
 310 }
 311
 312 void reservation_object_init(struct reservation_object *obj);
 313 void reservation_object_fini(struct reservation_object *obj);
 314 int reservation_object_reserve_shared(struct reservation_object *obj,
 315                                       unsigned int num_fences);
 316 void reservation_object_add_shared_fence(struct reservation_object *obj,
 317                                          struct dma_fence *fence);
 318
 319 void reservation_object_add_excl_fence(struct reservation_object *obj,
 320                                        struct dma_fence *fence);
 321
 322 int reservation_object_get_fences_rcu(struct reservation_object *obj,
 323                                       struct dma_fence **pfence_excl,
 324                                       unsigned *pshared_count,
 325                                       struct dma_fence ***pshared);
 326
 327 int reservation_object_copy_fences(struct reservation_object *dst,
 328                                    struct reservation_object *src);
 329
 330 long reservation_object_wait_timeout_rcu(struct reservation_object *obj,
 331                                          bool wait_all, bool intr,
 332                                          unsigned long timeout);
 333
 334 bool reservation_object_test_signaled_rcu(struct reservation_object *obj,
 335                                           bool test_all);
 336
 337 #endif /* _LINUX_RESERVATION_H */