1 /* SPDX-License-Identifier: GPL-2.0 */
14  * write lock without deadlocking, so an operation that updates multiple nodes
23  *   six_lock_read(&foo->lock);
24  *   six_unlock_read(&foo->lock);
26  * An intent lock must be held before taking a write lock:
27  *   six_lock_intent(&foo->lock);
28  *   six_lock_write(&foo->lock);
29  *   six_unlock_write(&foo->lock);
30  *   six_unlock_intent(&foo->lock);
40  * There are also interfaces that take the lock type as an enum:
42  *   six_lock_type(&foo->lock, SIX_LOCK_read);
43  *   six_trylock_convert(&foo->lock, SIX_LOCK_read, SIX_LOCK_intent)
44  *   six_lock_type(&foo->lock, SIX_LOCK_write);
45  *   six_unlock_type(&foo->lock, SIX_LOCK_write);
46  *   six_unlock_type(&foo->lock, SIX_LOCK_intent);
48  * Lock sequence numbers - unlock(), relock():
50  *   Locks embed sequences numbers, which are incremented on write lock/unlock.
56  *     six_lock_read(&foo->lock);
57  *     u32 seq = six_lock_seq(&foo->lock);
58  *     six_unlock_read(&foo->lock);
62  *     if (six_relock_read(&foo->lock, seq)) { ... }
64  *   If the relock operation succeeds, it is as if the lock was never unlocked.
70  *   layer that tracks held locks. If a lock is known to already be held in the
71  *   read or intent state, six_lock_increment() can be used to bump the "lock
76  *     six_lock_read(&foo->lock);
77  *     six_lock_increment(&foo->lock, SIX_LOCK_read);
78  *     six_unlock_read(&foo->lock);
79  *     six_unlock_read(&foo->lock);
80  *   foo->lock is now fully unlocked.
83  *   counter when holding an intent lock, but not the reverse.
85  *   A lock may only be held once for write: six_lock_increment(.., SIX_LOCK_write)
95  *   a cache and may reused, and lock ordering is based on a property of the
96  *   object that will change when the object is reused - i.e. logical key order.
98  *   If looking up an object in the cache may race with object reuse, and lock
100  *   correct lock order for that object and cause a deadlock. should_sleep_fn
108  *   traversing lock waitlists, it is then possible for an upper layer to
116  *   six_lock_waiter() will add the wait object to the waitlist re-trying taking
117  *   the lock, and before calling should_sleep_fn, and the wait object will not
118  *   be removed from the waitlist until either the lock has been successfully
122  *   have timestamps in strictly ascending order - this is so the timestamp can
123  *   be used as a cursor for lock graph traverse.
157 typedef int (*six_lock_should_sleep_fn)(struct six_lock *lock, void *);
159 void six_lock_exit(struct six_lock *lock);
165 void __six_lock_init(struct six_lock *lock, const char *name,
169  * six_lock_init - initialize a six lock
170  * @lock:	lock to initialize
173 #define six_lock_init(lock, flags)					\  argument
177 	__six_lock_init((lock), #lock, &__key, flags);			\
181  * six_lock_seq - obtain current lock sequence number
182  * @lock:	six_lock to obtain sequence number for
184  * @lock should be held for read or intent, and not write
186  * By saving the lock sequence number, we can unlock @lock and then (typically
189  * and state corresponding to what @lock protects is still valid.
191 static inline u32 six_lock_seq(const struct six_lock *lock)  in six_lock_seq()  argument
193 	return lock->seq;  in six_lock_seq()
196 bool six_trylock_ip(struct six_lock *lock, enum six_lock_type type, unsigned long ip);
199  * six_trylock_type - attempt to take a six lock without blocking
200  * @lock:	lock to take
205 static inline bool six_trylock_type(struct six_lock *lock, enum six_lock_type type)  in six_trylock_type()  argument
207 	return six_trylock_ip(lock, type, _THIS_IP_);  in six_trylock_type()
210 int six_lock_ip_waiter(struct six_lock *lock, enum six_lock_type type,
216  * six_lock_waiter - take a lock, with full waitlist interface
217  * @lock:	lock to take
219  * @wait:	pointer to wait object, which will be added to lock's waitlist
229 static inline int six_lock_waiter(struct six_lock *lock, enum six_lock_type type,  in six_lock_waiter()  argument
233 	return six_lock_ip_waiter(lock, type, wait, should_sleep_fn, p, _THIS_IP_);  in six_lock_waiter()
237  * six_lock_ip - take a six lock lock
238  * @lock:	lock to take
247 static inline int six_lock_ip(struct six_lock *lock, enum six_lock_type type,  in six_lock_ip()  argument
253 	return six_lock_ip_waiter(lock, type, &wait, should_sleep_fn, p, ip);  in six_lock_ip()
257  * six_lock_type - take a six lock lock
258  * @lock:	lock to take
266 static inline int six_lock_type(struct six_lock *lock, enum six_lock_type type,  in six_lock_type()  argument
271 	return six_lock_ip_waiter(lock, type, &wait, should_sleep_fn, p, _THIS_IP_);  in six_lock_type()
274 bool six_relock_ip(struct six_lock *lock, enum six_lock_type type,
278  * six_relock_type - attempt to re-take a lock that was held previously
279  * @lock:	lock to take
281  * @seq:	lock sequence number obtained from six_lock_seq() while lock was
286 static inline bool six_relock_type(struct six_lock *lock, enum six_lock_type type,  in six_relock_type()  argument
289 	return six_relock_ip(lock, type, seq, _THIS_IP_);  in six_relock_type()
292 void six_unlock_ip(struct six_lock *lock, enum six_lock_type type, unsigned long ip);
295  * six_unlock_type - drop a six lock
296  * @lock:	lock to unlock
299  * When a lock is held multiple times (because six_lock_incement()) was used),
300  * this decrements the 'lock held' counter by one.
303  * six_lock_read(&foo->lock);				read count 1
304  * six_lock_increment(&foo->lock, SIX_LOCK_read);	read count 2
305  * six_lock_unlock(&foo->lock, SIX_LOCK_read);		read count 1
306  * six_lock_unlock(&foo->lock, SIX_LOCK_read);		read count 0
308 static inline void six_unlock_type(struct six_lock *lock, enum six_lock_type type)  in six_unlock_type()  argument
310 	six_unlock_ip(lock, type, _THIS_IP_);  in six_unlock_type()
314 static inline bool six_trylock_ip_##type(struct six_lock *lock, unsigned long ip)\
316 	return six_trylock_ip(lock, SIX_LOCK_##type, ip);		\
319 static inline bool six_trylock_##type(struct six_lock *lock)		\
321 	return six_trylock_ip(lock, SIX_LOCK_##type, _THIS_IP_);	\
324 static inline int six_lock_ip_waiter_##type(struct six_lock *lock,	\
329 	return six_lock_ip_waiter(lock, SIX_LOCK_##type, wait, should_sleep_fn, p, ip);\
332 static inline int six_lock_ip_##type(struct six_lock *lock,		\
336 	return six_lock_ip(lock, SIX_LOCK_##type, should_sleep_fn, p, ip);\
339 static inline bool six_relock_ip_##type(struct six_lock *lock, u32 seq, unsigned long ip)\
341 	return six_relock_ip(lock, SIX_LOCK_##type, seq, ip);		\
344 static inline bool six_relock_##type(struct six_lock *lock, u32 seq)	\
346 	return six_relock_ip(lock, SIX_LOCK_##type, seq, _THIS_IP_);	\
349 static inline int six_lock_##type(struct six_lock *lock,		\
352 	return six_lock_ip_##type(lock, fn, p, _THIS_IP_);		\
355 static inline void six_unlock_ip_##type(struct six_lock *lock, unsigned long ip)	\
357 	six_unlock_ip(lock, SIX_LOCK_##type, ip);			\
360 static inline void six_unlock_##type(struct six_lock *lock)		\
362 	six_unlock_ip(lock, SIX_LOCK_##type, _THIS_IP_);		\