mutex.h 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229
  1. /* SPDX-License-Identifier: GPL-2.0 */
  2. /*
  3. * Mutexes: blocking mutual exclusion locks
  4. *
  5. * started by Ingo Molnar:
  6. *
  7. * Copyright (C) 2004, 2005, 2006 Red Hat, Inc., Ingo Molnar <mingo@redhat.com>
  8. *
  9. * This file contains the main data structure and API definitions.
  10. */
  11. #ifndef __LINUX_MUTEX_H
  12. #define __LINUX_MUTEX_H
  13. #include <asm/current.h>
  14. #include <linux/list.h>
  15. #include <linux/spinlock_types.h>
  16. #include <linux/lockdep.h>
  17. #include <linux/atomic.h>
  18. #include <asm/processor.h>
  19. #include <linux/osq_lock.h>
  20. #include <linux/debug_locks.h>
  21. #include <linux/android_vendor.h>
  22. struct ww_acquire_ctx;
  23. /*
  24. * Simple, straightforward mutexes with strict semantics:
  25. *
  26. * - only one task can hold the mutex at a time
  27. * - only the owner can unlock the mutex
  28. * - multiple unlocks are not permitted
  29. * - recursive locking is not permitted
  30. * - a mutex object must be initialized via the API
  31. * - a mutex object must not be initialized via memset or copying
  32. * - task may not exit with mutex held
  33. * - memory areas where held locks reside must not be freed
  34. * - held mutexes must not be reinitialized
  35. * - mutexes may not be used in hardware or software interrupt
  36. * contexts such as tasklets and timers
  37. *
  38. * These semantics are fully enforced when DEBUG_MUTEXES is
  39. * enabled. Furthermore, besides enforcing the above rules, the mutex
  40. * debugging code also implements a number of additional features
  41. * that make lock debugging easier and faster:
  42. *
  43. * - uses symbolic names of mutexes, whenever they are printed in debug output
  44. * - point-of-acquire tracking, symbolic lookup of function names
  45. * - list of all locks held in the system, printout of them
  46. * - owner tracking
  47. * - detects self-recursing locks and prints out all relevant info
  48. * - detects multi-task circular deadlocks and prints out all affected
  49. * locks and tasks (and only those tasks)
  50. */
  51. struct mutex {
  52. atomic_long_t owner;
  53. spinlock_t wait_lock;
  54. #ifdef CONFIG_MUTEX_SPIN_ON_OWNER
  55. struct optimistic_spin_queue osq; /* Spinner MCS lock */
  56. #endif
  57. struct list_head wait_list;
  58. #ifdef CONFIG_DEBUG_MUTEXES
  59. void *magic;
  60. #endif
  61. #ifdef CONFIG_DEBUG_LOCK_ALLOC
  62. struct lockdep_map dep_map;
  63. #endif
  64. ANDROID_OEM_DATA_ARRAY(1, 2);
  65. };
  66. struct ww_class;
  67. struct ww_acquire_ctx;
  68. struct ww_mutex {
  69. struct mutex base;
  70. struct ww_acquire_ctx *ctx;
  71. #ifdef CONFIG_DEBUG_MUTEXES
  72. struct ww_class *ww_class;
  73. #endif
  74. };
  75. /*
  76. * This is the control structure for tasks blocked on mutex,
  77. * which resides on the blocked task's kernel stack:
  78. */
  79. struct mutex_waiter {
  80. struct list_head list;
  81. struct task_struct *task;
  82. struct ww_acquire_ctx *ww_ctx;
  83. #ifdef CONFIG_DEBUG_MUTEXES
  84. void *magic;
  85. #endif
  86. };
  87. #ifdef CONFIG_DEBUG_MUTEXES
  88. #define __DEBUG_MUTEX_INITIALIZER(lockname) \
  89. , .magic = &lockname
  90. extern void mutex_destroy(struct mutex *lock);
  91. #else
  92. # define __DEBUG_MUTEX_INITIALIZER(lockname)
  93. static inline void mutex_destroy(struct mutex *lock) {}
  94. #endif
  95. /**
  96. * mutex_init - initialize the mutex
  97. * @mutex: the mutex to be initialized
  98. *
  99. * Initialize the mutex to unlocked state.
  100. *
  101. * It is not allowed to initialize an already locked mutex.
  102. */
  103. #define mutex_init(mutex) \
  104. do { \
  105. static struct lock_class_key __key; \
  106. \
  107. __mutex_init((mutex), #mutex, &__key); \
  108. } while (0)
  109. #ifdef CONFIG_DEBUG_LOCK_ALLOC
  110. # define __DEP_MAP_MUTEX_INITIALIZER(lockname) \
  111. , .dep_map = { \
  112. .name = #lockname, \
  113. .wait_type_inner = LD_WAIT_SLEEP, \
  114. }
  115. #else
  116. # define __DEP_MAP_MUTEX_INITIALIZER(lockname)
  117. #endif
  118. #define __MUTEX_INITIALIZER(lockname) \
  119. { .owner = ATOMIC_LONG_INIT(0) \
  120. , .wait_lock = __SPIN_LOCK_UNLOCKED(lockname.wait_lock) \
  121. , .wait_list = LIST_HEAD_INIT(lockname.wait_list) \
  122. __DEBUG_MUTEX_INITIALIZER(lockname) \
  123. __DEP_MAP_MUTEX_INITIALIZER(lockname) }
  124. #define DEFINE_MUTEX(mutexname) \
  125. struct mutex mutexname = __MUTEX_INITIALIZER(mutexname)
  126. extern void __mutex_init(struct mutex *lock, const char *name,
  127. struct lock_class_key *key);
  128. /**
  129. * mutex_is_locked - is the mutex locked
  130. * @lock: the mutex to be queried
  131. *
  132. * Returns true if the mutex is locked, false if unlocked.
  133. */
  134. extern bool mutex_is_locked(struct mutex *lock);
  135. /*
  136. * See kernel/locking/mutex.c for detailed documentation of these APIs.
  137. * Also see Documentation/locking/mutex-design.rst.
  138. */
  139. #ifdef CONFIG_DEBUG_LOCK_ALLOC
  140. extern void mutex_lock_nested(struct mutex *lock, unsigned int subclass);
  141. extern void _mutex_lock_nest_lock(struct mutex *lock, struct lockdep_map *nest_lock);
  142. extern int __must_check mutex_lock_interruptible_nested(struct mutex *lock,
  143. unsigned int subclass);
  144. extern int __must_check mutex_lock_killable_nested(struct mutex *lock,
  145. unsigned int subclass);
  146. extern void mutex_lock_io_nested(struct mutex *lock, unsigned int subclass);
  147. #define mutex_lock(lock) mutex_lock_nested(lock, 0)
  148. #define mutex_lock_interruptible(lock) mutex_lock_interruptible_nested(lock, 0)
  149. #define mutex_lock_killable(lock) mutex_lock_killable_nested(lock, 0)
  150. #define mutex_lock_io(lock) mutex_lock_io_nested(lock, 0)
  151. #define mutex_lock_nest_lock(lock, nest_lock) \
  152. do { \
  153. typecheck(struct lockdep_map *, &(nest_lock)->dep_map); \
  154. _mutex_lock_nest_lock(lock, &(nest_lock)->dep_map); \
  155. } while (0)
  156. #else
  157. extern void mutex_lock(struct mutex *lock);
  158. extern int __must_check mutex_lock_interruptible(struct mutex *lock);
  159. extern int __must_check mutex_lock_killable(struct mutex *lock);
  160. extern void mutex_lock_io(struct mutex *lock);
  161. # define mutex_lock_nested(lock, subclass) mutex_lock(lock)
  162. # define mutex_lock_interruptible_nested(lock, subclass) mutex_lock_interruptible(lock)
  163. # define mutex_lock_killable_nested(lock, subclass) mutex_lock_killable(lock)
  164. # define mutex_lock_nest_lock(lock, nest_lock) mutex_lock(lock)
  165. # define mutex_lock_io_nested(lock, subclass) mutex_lock_io(lock)
  166. #endif
  167. /*
  168. * NOTE: mutex_trylock() follows the spin_trylock() convention,
  169. * not the down_trylock() convention!
  170. *
  171. * Returns 1 if the mutex has been acquired successfully, and 0 on contention.
  172. */
  173. extern int mutex_trylock(struct mutex *lock);
  174. extern void mutex_unlock(struct mutex *lock);
  175. extern int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock);
  176. /*
  177. * These values are chosen such that FAIL and SUCCESS match the
  178. * values of the regular mutex_trylock().
  179. */
  180. enum mutex_trylock_recursive_enum {
  181. MUTEX_TRYLOCK_FAILED = 0,
  182. MUTEX_TRYLOCK_SUCCESS = 1,
  183. MUTEX_TRYLOCK_RECURSIVE,
  184. };
  185. /**
  186. * mutex_trylock_recursive - trylock variant that allows recursive locking
  187. * @lock: mutex to be locked
  188. *
  189. * This function should not be used, _ever_. It is purely for hysterical GEM
  190. * raisins, and once those are gone this will be removed.
  191. *
  192. * Returns:
  193. * - MUTEX_TRYLOCK_FAILED - trylock failed,
  194. * - MUTEX_TRYLOCK_SUCCESS - lock acquired,
  195. * - MUTEX_TRYLOCK_RECURSIVE - we already owned the lock.
  196. */
  197. extern /* __deprecated */ __must_check enum mutex_trylock_recursive_enum
  198. mutex_trylock_recursive(struct mutex *lock);
  199. #endif /* __LINUX_MUTEX_H */