[RFC-patch] Doc/lockdep-design: explain display of {state-bits}

[RFC-patch] Doc/lockdep-design: explain display of {state-bits}

[Jim Cromie]

Please offer corrections / wording improvements as appropriate.
In particular, the ".+-? " table could be more illuminating - I lack the
knowledge to make the right inferences..

(or just take it, and run with it ;-)

Signed-off-by:  Jim Cromie <jim.cromie@gmail.com>

--- doc-touches/Documentation/lockdep-design.txt~	2006-09-14 11:49:47.000000000 -0600
+++ doc-touches/Documentation/lockdep-design.txt	2006-09-15 12:46:34.000000000 -0600
@@ -36,6 +36,28 @@
 
 - 'ever used'                                       [ == !unused        ]
 
+When mutex rules are violated, these 4 state bits are presented in the
+mutex error messages, inside curlies.  A contrived example:
+
+   modprobe/2287 is trying to acquire lock:
+    (&sio_locks[i].lock){--..}, at: [<c02867fd>] mutex_lock+0x21/0x24
+
+   but task is already holding lock:
+    (&sio_locks[i].lock){--..}, at: [<c02867fd>] mutex_lock+0x21/0x24
+
+
+The bit position indicates hardirq, softirq, hardirq-read,
+softirq-read respectively, and the character displayed in each
+indicates:
+
+   '.'	 used
+   '+'  used in irqs
+   '-'  enabled in irqs
+   '?'  used and enabled (bits 3,4)
+
+Unused mutexes cannot be part of the cause of an error.
+
+
 Single-lock state rules:
 ------------------------