1 /* SPDX-License-Identifier: GPL-2.0 */
10  * but with an additional state: read/shared, intent, exclusive/write
12  * The purpose of the intent state is to allow for greater concurrency on tree
17  * But by adding an intent state, which is exclusive with other intent locks but
23  *   six_lock_read(&foo->lock);
24  *   six_unlock_read(&foo->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);
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():
51  *   This allows locks to be dropped and the retaken iff the state they protect
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)) { ... }
71  *   read or intent state, six_lock_increment() can be used to bump the "lock
72  *   held in this state" counter, increasing the number of unlock calls that
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.
82  *   Since the intent state supercedes read, it's legal to increment the read
96  *   object that will change when the object is reused - i.e. logical key order.
104  * Wait list entry interface:
107  *   wait list entry. By embedding six_lock_waiter into another object, and by
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
122  *   have timestamps in strictly ascending order - this is so the timestamp can
137 	atomic_t		state;  member
171  * six_lock_init - initialize a six lock
183  * six_lock_seq - obtain current lock sequence number
191  * and state corresponding to what @lock protects is still valid.
195 	return lock->seq;  in six_lock_seq()
201  * six_trylock_type - attempt to take a six lock without blocking
213 		       struct six_lock_waiter *wait,
218  * six_lock_waiter - take a lock, with full waitlist interface
221  * @wait:	pointer to wait object, which will be added to lock's waitlist
232 				  struct six_lock_waiter *wait,  in six_lock_waiter()  argument
235 	return six_lock_ip_waiter(lock, type, wait, should_sleep_fn, p, _THIS_IP_);  in six_lock_waiter()
239  * six_lock_ip - take a six lock lock
253 	struct six_lock_waiter wait;  in six_lock_ip()  local
255 	return six_lock_ip_waiter(lock, type, &wait, should_sleep_fn, p, ip);  in six_lock_ip()
259  * six_lock_type - take a six lock lock
271 	struct six_lock_waiter wait;  in six_lock_type()  local
273 	return six_lock_ip_waiter(lock, type, &wait, should_sleep_fn, p, _THIS_IP_);  in six_lock_type()
280  * six_relock_type - attempt to re-take a lock that was held previously
297  * six_unlock_type - drop a six lock
305  * six_lock_read(&foo->lock);				read count 1
306  * six_lock_increment(&foo->lock, SIX_LOCK_read);	read count 2
307  * six_lock_unlock(&foo->lock, SIX_LOCK_read);		read count 1
308  * six_lock_unlock(&foo->lock, SIX_LOCK_read);		read count 0
327 			   struct six_lock_waiter *wait,		\
331 	return six_lock_ip_waiter(lock, SIX_LOCK_##type, wait, should_sleep_fn, p, ip);\