[PATCH] rwsem: Comments to explain the meaning of the rwsem's count field

[Tim Chen]

It takes me a while to understand how rwsem's count field mainifest
itself in different scenarios.  I'm adding comments to provide a quick
reference on the the rwsem's count field for each scenario where readers
and writers are contending/holding the lock.  Hopefully it will be useful
for future maintenance of the code and for people to get up to speed on
how the logic in the code works.

Signed-off-by: Tim Chen <tim.c.chen@xxxxxxxxxxxxxxx>
---
 kernel/locking/rwsem-xadd.c | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/kernel/locking/rwsem-xadd.c b/kernel/locking/rwsem-xadd.c
index 1d66e08..305c15f 100644
--- a/kernel/locking/rwsem-xadd.c
+++ b/kernel/locking/rwsem-xadd.c
@@ -12,6 +12,28 @@
 #include <linux/export.h>
 
 /*
+ * Meaning of the rw_semaphore's count field:
+ * (32 bit case illustrated, similar for 64 bit)
+ *
+ * (listed in decreasing order)
+ * 0x0000000X  X readers active, no writer waiting (X*ACTIVE_BIAS)
+ * 0x00000000  rwsem is unlocked, and no one is waiting for the lock
+ * 0xffff000X  X readers active, writer and/or reader waiting.
+ *	       (X*ACTIVE_BIAS + WAITING_BIAS)
+ * 0xffff0001  (1) one writer active, nobody queued. (ACTIVE_WRITE_BIAS)
+ *	       or
+ *	       (2) one reader active, writer(s) queued.
+ *		   (WAITING_BIAS + ACTIVE_BIAS)
+ * 0xffff0000  There are writers or readers queued but none active
+ *	       (WAITING_BIAS), a writer can try to grab the lock and
+ *	       take itself off wait list if awake.  Writer who has just
+ *	       completed its task seeing this count will try to
+ *	       wake people up from wait list.
+ * 0xfffe0001  Writer active, readers/writer queued
+ *	       (ACTIVE_WRITE_BIAS + WAITING_BIAS)
+ */
+
+/*
  * Initialize an rwsem:
  */
 void __init_rwsem(struct rw_semaphore *sem, const char *name,
-- 
1.7.11.7


--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/