include/drm/ttm/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/wait.h>
  53 #include <linux/atomic.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  * @kill_takers: Boolean whether to kill takers of the lock.
  67  * @signal: Signal to send when kill_takers is true.
  68  */
  69
  70 struct ttm_lock {
  71         struct ttm_base_object base;
  72         wait_queue_head_t queue;
  73         spinlock_t lock;
  74         int32_t rw;
  75         uint32_t flags;
  76         bool kill_takers;
  77         int signal;
  78         struct ttm_object_file *vt_holder;
  79 };
  80
  81
  82 /**
  83  * ttm_lock_init
  84  *
  85  * @lock: Pointer to a struct ttm_lock
  86  * Initializes the lock.
  87  */
  88 extern void ttm_lock_init(struct ttm_lock *lock);
  89
  90 /**
  91  * ttm_read_unlock
  92  *
  93  * @lock: Pointer to a struct ttm_lock
  94  *
  95  * Releases a read lock.
  96  */
  97 extern void ttm_read_unlock(struct ttm_lock *lock);
  98
  99 /**
 100  * ttm_read_lock
 101  *
 102  * @lock: Pointer to a struct ttm_lock
 103  * @interruptible: Interruptible sleeping while waiting for a lock.
 104  *
 105  * Takes the lock in read mode.
 106  * Returns:
 107  * -ERESTARTSYS If interrupted by a signal and interruptible is true.
 108  */
 109 extern int ttm_read_lock(struct ttm_lock *lock, bool interruptible);
 110
 111 /**
 112  * ttm_read_trylock
 113  *
 114  * @lock: Pointer to a struct ttm_lock
 115  * @interruptible: Interruptible sleeping while waiting for a lock.
 116  *
 117  * Tries to take the lock in read mode. If the lock is already held
 118  * in write mode, the function will return -EBUSY. If the lock is held
 119  * in vt or suspend mode, the function will sleep until these modes
 120  * are unlocked.
 121  *
 122  * Returns:
 123  * -EBUSY The lock was already held in write mode.
 124  * -ERESTARTSYS If interrupted by a signal and interruptible is true.
 125  */
 126 extern int ttm_read_trylock(struct ttm_lock *lock, bool interruptible);
 127
 128 /**
 129  * ttm_write_unlock
 130  *
 131  * @lock: Pointer to a struct ttm_lock
 132  *
 133  * Releases a write lock.
 134  */
 135 extern void ttm_write_unlock(struct ttm_lock *lock);
 136
 137 /**
 138  * ttm_write_lock
 139  *
 140  * @lock: Pointer to a struct ttm_lock
 141  * @interruptible: Interruptible sleeping while waiting for a lock.
 142  *
 143  * Takes the lock in write mode.
 144  * Returns:
 145  * -ERESTARTSYS If interrupted by a signal and interruptible is true.
 146  */
 147 extern int ttm_write_lock(struct ttm_lock *lock, bool interruptible);
 148
 149 /**
 150  * ttm_lock_downgrade
 151  *
 152  * @lock: Pointer to a struct ttm_lock
 153  *
 154  * Downgrades a write lock to a read lock.
 155  */
 156 extern void ttm_lock_downgrade(struct ttm_lock *lock);
 157
 158 /**
 159  * ttm_suspend_lock
 160  *
 161  * @lock: Pointer to a struct ttm_lock
 162  *
 163  * Takes the lock in suspend mode. Excludes read and write mode.
 164  */
 165 extern void ttm_suspend_lock(struct ttm_lock *lock);
 166
 167 /**
 168  * ttm_suspend_unlock
 169  *
 170  * @lock: Pointer to a struct ttm_lock
 171  *
 172  * Releases a suspend lock
 173  */
 174 extern void ttm_suspend_unlock(struct ttm_lock *lock);
 175
 176 /**
 177  * ttm_vt_lock
 178  *
 179  * @lock: Pointer to a struct ttm_lock
 180  * @interruptible: Interruptible sleeping while waiting for a lock.
 181  * @tfile: Pointer to a struct ttm_object_file to register the lock with.
 182  *
 183  * Takes the lock in vt mode.
 184  * Returns:
 185  * -ERESTARTSYS If interrupted by a signal and interruptible is true.
 186  * -ENOMEM: Out of memory when locking.
 187  */
 188 extern int ttm_vt_lock(struct ttm_lock *lock, bool interruptible,
 189                        struct ttm_object_file *tfile);
 190
 191 /**
 192  * ttm_vt_unlock
 193  *
 194  * @lock: Pointer to a struct ttm_lock
 195  *
 196  * Releases a vt lock.
 197  * Returns:
 198  * -EINVAL If the lock was not held.
 199  */
 200 extern int ttm_vt_unlock(struct ttm_lock *lock);
 201
 202 /**
 203  * ttm_write_unlock
 204  *
 205  * @lock: Pointer to a struct ttm_lock
 206  *
 207  * Releases a write lock.
 208  */
 209 extern void ttm_write_unlock(struct ttm_lock *lock);
 210
 211 /**
 212  * ttm_write_lock
 213  *
 214  * @lock: Pointer to a struct ttm_lock
 215  * @interruptible: Interruptible sleeping while waiting for a lock.
 216  *
 217  * Takes the lock in write mode.
 218  * Returns:
 219  * -ERESTARTSYS If interrupted by a signal and interruptible is true.
 220  */
 221 extern int ttm_write_lock(struct ttm_lock *lock, bool interruptible);
 222
 223 /**
 224  * ttm_lock_set_kill
 225  *
 226  * @lock: Pointer to a struct ttm_lock
 227  * @val: Boolean whether to kill processes taking the lock.
 228  * @signal: Signal to send to the process taking the lock.
 229  *
 230  * The kill-when-taking-lock functionality is used to kill processes that keep
 231  * on using the TTM functionality when its resources has been taken down, for
 232  * example when the X server exits. A typical sequence would look like this:
 233  * - X server takes lock in write mode.
 234  * - ttm_lock_set_kill() is called with @val set to true.
 235  * - As part of X server exit, TTM resources are taken down.
 236  * - X server releases the lock on file release.
 237  * - Another dri client wants to render, takes the lock and is killed.
 238  *
 239  */
 240 static inline void ttm_lock_set_kill(struct ttm_lock *lock, bool val,
 241                                      int signal)
 242 {
 243         lock->kill_takers = val;
 244         if (val)
 245                 lock->signal = signal;
 246 }
 247
 248 #endif