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