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
14#include <asm/current.h>
15#include <linux/list.h>
16#include <linux/spinlock_types.h>
17#include <linux/lockdep.h>
18#include <linux/atomic.h>
19#include <asm/processor.h>
20#include <linux/osq_lock.h>
21#include <linux/debug_locks.h>
22#include <linux/cleanup.h>
23#include <linux/mutex_types.h>
24
25struct device;
26
27#ifdef CONFIG_DEBUG_LOCK_ALLOC
28# define __DEP_MAP_MUTEX_INITIALIZER(lockname)			\
29		, .dep_map = {					\
30			.name = #lockname,			\
31			.wait_type_inner = LD_WAIT_SLEEP,	\
32		}
33#else
34# define __DEP_MAP_MUTEX_INITIALIZER(lockname)
35#endif
36
37#ifdef CONFIG_DEBUG_MUTEXES
38
39# define __DEBUG_MUTEX_INITIALIZER(lockname)				\
40	, .magic = &lockname
41
42extern void mutex_destroy(struct mutex *lock);
43
44#else
45
46# define __DEBUG_MUTEX_INITIALIZER(lockname)
47
48static inline void mutex_destroy(struct mutex *lock) {}
49
50#endif
51
52#ifndef CONFIG_PREEMPT_RT
53/**
54 * mutex_init - initialize the mutex
55 * @mutex: the mutex to be initialized
56 *
57 * Initialize the mutex to unlocked state.
58 *
59 * It is not allowed to initialize an already locked mutex.
60 */
61#define mutex_init(mutex)						\
62do {									\
63	static struct lock_class_key __key;				\
64									\
65	__mutex_init((mutex), #mutex, &__key);				\
66} while (0)
67
68#define __MUTEX_INITIALIZER(lockname) \
69		{ .owner = ATOMIC_LONG_INIT(0) \
70		, .wait_lock = __RAW_SPIN_LOCK_UNLOCKED(lockname.wait_lock) \
71		, .wait_list = LIST_HEAD_INIT(lockname.wait_list) \
72		__DEBUG_MUTEX_INITIALIZER(lockname) \
73		__DEP_MAP_MUTEX_INITIALIZER(lockname) }
74
75#define DEFINE_MUTEX(mutexname) \
76	struct mutex mutexname = __MUTEX_INITIALIZER(mutexname)
77
78extern void __mutex_init(struct mutex *lock, const char *name,
79			 struct lock_class_key *key);
80
81/**
82 * mutex_is_locked - is the mutex locked
83 * @lock: the mutex to be queried
84 *
85 * Returns true if the mutex is locked, false if unlocked.
86 */
87extern bool mutex_is_locked(struct mutex *lock);
88
89#else /* !CONFIG_PREEMPT_RT */
90/*
91 * Preempt-RT variant based on rtmutexes.
92 */
93
94#define __MUTEX_INITIALIZER(mutexname)					\
95{									\
96	.rtmutex = __RT_MUTEX_BASE_INITIALIZER(mutexname.rtmutex)	\
97	__DEP_MAP_MUTEX_INITIALIZER(mutexname)				\
98}
99
100#define DEFINE_MUTEX(mutexname)						\
101	struct mutex mutexname = __MUTEX_INITIALIZER(mutexname)
102
103extern void __mutex_rt_init(struct mutex *lock, const char *name,
104			    struct lock_class_key *key);
105
106#define mutex_is_locked(l)	rt_mutex_base_is_locked(&(l)->rtmutex)
107
108#define __mutex_init(mutex, name, key)			\
109do {							\
110	rt_mutex_base_init(&(mutex)->rtmutex);		\
111	__mutex_rt_init((mutex), name, key);		\
112} while (0)
113
114#define mutex_init(mutex)				\
115do {							\
116	static struct lock_class_key __key;		\
117							\
118	__mutex_init((mutex), #mutex, &__key);		\
119} while (0)
120#endif /* CONFIG_PREEMPT_RT */
121
122#ifdef CONFIG_DEBUG_MUTEXES
123
124int __devm_mutex_init(struct device *dev, struct mutex *lock);
125
126#else
127
128static inline int __devm_mutex_init(struct device *dev, struct mutex *lock)
129{
130	/*
131	 * When CONFIG_DEBUG_MUTEXES is off mutex_destroy() is just a nop so
132	 * no really need to register it in the devm subsystem.
133	 */
134	return 0;
135}
136
137#endif
138
139#define devm_mutex_init(dev, mutex)			\
140({							\
141	typeof(mutex) mutex_ = (mutex);			\
142							\
143	mutex_init(mutex_);				\
144	__devm_mutex_init(dev, mutex_);			\
145})
146
147/*
148 * See kernel/locking/mutex.c for detailed documentation of these APIs.
149 * Also see Documentation/locking/mutex-design.rst.
150 */
151#ifdef CONFIG_DEBUG_LOCK_ALLOC
152extern void mutex_lock_nested(struct mutex *lock, unsigned int subclass);
153extern void _mutex_lock_nest_lock(struct mutex *lock, struct lockdep_map *nest_lock);
154
155extern int __must_check mutex_lock_interruptible_nested(struct mutex *lock,
156					unsigned int subclass);
157extern int __must_check mutex_lock_killable_nested(struct mutex *lock,
158					unsigned int subclass);
159extern void mutex_lock_io_nested(struct mutex *lock, unsigned int subclass);
160
161#define mutex_lock(lock) mutex_lock_nested(lock, 0)
162#define mutex_lock_interruptible(lock) mutex_lock_interruptible_nested(lock, 0)
163#define mutex_lock_killable(lock) mutex_lock_killable_nested(lock, 0)
164#define mutex_lock_io(lock) mutex_lock_io_nested(lock, 0)
165
166#define mutex_lock_nest_lock(lock, nest_lock)				\
167do {									\
168	typecheck(struct lockdep_map *, &(nest_lock)->dep_map);	\
169	_mutex_lock_nest_lock(lock, &(nest_lock)->dep_map);		\
170} while (0)
171
172#else
173extern void mutex_lock(struct mutex *lock);
174extern int __must_check mutex_lock_interruptible(struct mutex *lock);
175extern int __must_check mutex_lock_killable(struct mutex *lock);
176extern void mutex_lock_io(struct mutex *lock);
177
178# define mutex_lock_nested(lock, subclass) mutex_lock(lock)
179# define mutex_lock_interruptible_nested(lock, subclass) mutex_lock_interruptible(lock)
180# define mutex_lock_killable_nested(lock, subclass) mutex_lock_killable(lock)
181# define mutex_lock_nest_lock(lock, nest_lock) mutex_lock(lock)
182# define mutex_lock_io_nested(lock, subclass) mutex_lock_io(lock)
183#endif
184
185/*
186 * NOTE: mutex_trylock() follows the spin_trylock() convention,
187 *       not the down_trylock() convention!
188 *
189 * Returns 1 if the mutex has been acquired successfully, and 0 on contention.
190 */
191extern int mutex_trylock(struct mutex *lock);
192extern void mutex_unlock(struct mutex *lock);
193
194extern int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock);
195
196DEFINE_GUARD(mutex, struct mutex *, mutex_lock(_T), mutex_unlock(_T))
197DEFINE_GUARD_COND(mutex, _try, mutex_trylock(_T))
198DEFINE_GUARD_COND(mutex, _intr, mutex_lock_interruptible(_T) == 0)
199
200#endif /* __LINUX_MUTEX_H */
201