drivers/gpu/drm/vmwgfx/ttm_lock.h

   1 /**************************************************************************
   2  *
   3  * Copyright (c) 2007-2009 VMware, Inc., Palo Alto, CA., USA
   4  * All Rights Reserved.
   5  *
   6  * Permission is hereby granted, free of charge, to any person obtaining a
   7  * copy of this software and associated documentation files (the
   8  * "Software"), to deal in the Software without restriction, including
   9  * without limitation the rights to use, copy, modify, merge, publish,
  10  * distribute, sub license, and/or sell copies of the Software, and to
  11  * permit persons to whom the Software is furnished to do so, subject to
  12  * the following conditions:
  13  *
  14  * The above copyright notice and this permission notice (including the
  15  * next paragraph) shall be included in all copies or substantial portions
  16  * of the Software.
  17  *
  18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  19  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  20  * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
  21  * THE COPYRIGHT HOLDERS, AUTHORS AND/OR ITS SUPPLIERS BE LIABLE FOR ANY CLAIM,
  22  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
  23  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
  24  * USE OR OTHER DEALINGS IN THE SOFTWARE.
  25  *
  26  **************************************************************************/
  27 /*
  28  * Authors: Thomas Hellstrom <thellstrom-at-vmware-dot-com>
  29  */
  30
  31 /** @file ttm_lock.h
  32  * This file implements a simple replacement for the buffer manager use
  33  * of the DRM heavyweight hardware lock.
  34  * The lock is a read-write lock. Taking it in read mode and write mode
  35  * is relatively fast, and intended for in-kernel use only.
  36  *
  37  * The vt mode is used only when there is a need to block all
  38  * user-space processes from validating buffers.
  39  * It's allowed to leave kernel space with the vt lock held.
  40  * If a user-space process dies while having the vt-lock,
  41  * it will be released during the file descriptor release. The vt lock
  42  * excludes write lock and read lock.
  43  *
  44  * The suspend mode is used to lock out all TTM users when preparing for
  45  * and executing suspend operations.
  46  *
  47  */
  48
  49 #ifndef _TTM_LOCK_H_
  50 #define _TTM_LOCK_H_
  51
  52 #include <linux/atomic.h>
  53 #include <linux/wait.h>
  54
  55 #include "ttm_object.h"
  56
  57 /**
  58  * struct ttm_lock
  59  *
  60  * @base: ttm base object used solely to release the lock if the client
  61  * holding the lock dies.
  62  * @queue: Queue for processes waiting for lock change-of-status.
  63  * @lock: Spinlock protecting some lock members.
  64  * @rw: Read-write lock counter. Protected by @lock.
  65  * @flags: Lock state. Protected by @lock.
  66  */
  67
  68 struct ttm_lock {
  69         struct ttm_base_object base;
  70         wait_queue_head_t queue;
  71         spinlock_t lock;
  72         int32_t rw;
  73         uint32_t flags;
  74 };
  75
  76
  77 /**
  78  * ttm_lock_init
  79  *
  80  * @lock: Pointer to a struct ttm_lock
  81  * Initializes the lock.
  82  */
  83 extern void ttm_lock_init(struct ttm_lock *lock);
  84
  85 /**
  86  * ttm_read_unlock
  87  *
  88  * @lock: Pointer to a struct ttm_lock
  89  *
  90  * Releases a read lock.
  91  */
  92 extern void ttm_read_unlock(struct ttm_lock *lock);
  93
  94 /**
  95  * ttm_read_lock
  96  *
  97  * @lock: Pointer to a struct ttm_lock
  98  * @interruptible: Interruptible sleeping while waiting for a lock.
  99  *
 100  * Takes the lock in read mode.
 101  * Returns:
 102  * -ERESTARTSYS If interrupted by a signal and interruptible is true.
 103  */
 104 extern int ttm_read_lock(struct ttm_lock *lock, bool interruptible);
 105
 106 /**
 107  * ttm_read_trylock
 108  *
 109  * @lock: Pointer to a struct ttm_lock
 110  * @interruptible: Interruptible sleeping while waiting for a lock.
 111  *
 112  * Tries to take the lock in read mode. If the lock is already held
 113  * in write mode, the function will return -EBUSY. If the lock is held
 114  * in vt or suspend mode, the function will sleep until these modes
 115  * are unlocked.
 116  *
 117  * Returns:
 118  * -EBUSY The lock was already held in write mode.
 119  * -ERESTARTSYS If interrupted by a signal and interruptible is true.
 120  */
 121 extern int ttm_read_trylock(struct ttm_lock *lock, bool interruptible);
 122
 123 /**
 124  * ttm_write_unlock
 125  *
 126  * @lock: Pointer to a struct ttm_lock
 127  *
 128  * Releases a write lock.
 129  */
 130 extern void ttm_write_unlock(struct ttm_lock *lock);
 131
 132 /**
 133  * ttm_write_lock
 134  *
 135  * @lock: Pointer to a struct ttm_lock
 136  * @interruptible: Interruptible sleeping while waiting for a lock.
 137  *
 138  * Takes the lock in write mode.
 139  * Returns:
 140  * -ERESTARTSYS If interrupted by a signal and interruptible is true.
 141  */
 142 extern int ttm_write_lock(struct ttm_lock *lock, bool interruptible);
 143
 144 /**
 145  * ttm_lock_downgrade
 146  *
 147  * @lock: Pointer to a struct ttm_lock
 148  *
 149  * Downgrades a write lock to a read lock.
 150  */
 151 extern void ttm_lock_downgrade(struct ttm_lock *lock);
 152
 153 /**
 154  * ttm_suspend_lock
 155  *
 156  * @lock: Pointer to a struct ttm_lock
 157  *
 158  * Takes the lock in suspend mode. Excludes read and write mode.
 159  */
 160 extern void ttm_suspend_lock(struct ttm_lock *lock);
 161
 162 /**
 163  * ttm_suspend_unlock
 164  *
 165  * @lock: Pointer to a struct ttm_lock
 166  *
 167  * Releases a suspend lock
 168  */
 169 extern void ttm_suspend_unlock(struct ttm_lock *lock);
 170
 171 /**
 172  * ttm_vt_lock
 173  *
 174  * @lock: Pointer to a struct ttm_lock
 175  * @interruptible: Interruptible sleeping while waiting for a lock.
 176  * @tfile: Pointer to a struct ttm_object_file to register the lock with.
 177  *
 178  * Takes the lock in vt mode.
 179  * Returns:
 180  * -ERESTARTSYS If interrupted by a signal and interruptible is true.
 181  * -ENOMEM: Out of memory when locking.
 182  */
 183 extern int ttm_vt_lock(struct ttm_lock *lock, bool interruptible,
 184                        struct ttm_object_file *tfile);
 185
 186 /**
 187  * ttm_vt_unlock
 188  *
 189  * @lock: Pointer to a struct ttm_lock
 190  *
 191  * Releases a vt lock.
 192  * Returns:
 193  * -EINVAL If the lock was not held.
 194  */
 195 extern int ttm_vt_unlock(struct ttm_lock *lock);
 196
 197 /**
 198  * ttm_write_unlock
 199  *
 200  * @lock: Pointer to a struct ttm_lock
 201  *
 202  * Releases a write lock.
 203  */
 204 extern void ttm_write_unlock(struct ttm_lock *lock);
 205
 206 /**
 207  * ttm_write_lock
 208  *
 209  * @lock: Pointer to a struct ttm_lock
 210  * @interruptible: Interruptible sleeping while waiting for a lock.
 211  *
 212  * Takes the lock in write mode.
 213  * Returns:
 214  * -ERESTARTSYS If interrupted by a signal and interruptible is true.
 215  */
 216 extern int ttm_write_lock(struct ttm_lock *lock, bool interruptible);
 217
 218 #endif