summaryrefslogtreecommitdiff
path: root/Documentation/sparse.txt
diff options
context:
space:
mode:
authorEd Cashin <ecashin@coraid.com>2012-12-17 16:03:25 -0800
committerLinus Torvalds <torvalds@linux-foundation.org>2012-12-17 17:15:23 -0800
commit6e9766317fd51a33a32c65d2b76a6bde3227bbbd (patch)
treee861925fb8752a7964ac18ba5a617f3296c30a46 /Documentation/sparse.txt
parent8529091e8e2ae25e0f4003086f619765ff255e4b (diff)
Documentation/sparse.txt: document context annotations for lock checking
The context feature of sparse is used with the Linux kernel sources to check for imbalanced uses of locks. Document the annotations defined in include/linux/compiler.h that tell sparse what to expect when a lock is held on function entry, exit, or both. Signed-off-by: Ed Cashin <ecashin@coraid.com> Reviewed-by: Josh Triplett <josh@joshtriplett.org> Acked-by: Christopher Li <sparse@chrisli.org> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Diffstat (limited to 'Documentation/sparse.txt')
-rw-r--r--Documentation/sparse.txt18
1 files changed, 18 insertions, 0 deletions
diff --git a/Documentation/sparse.txt b/Documentation/sparse.txt
index 4909d4116356..eceab1308a8c 100644
--- a/Documentation/sparse.txt
+++ b/Documentation/sparse.txt
@@ -49,6 +49,24 @@ be generated without __CHECK_ENDIAN__.
__bitwise - noisy stuff; in particular, __le*/__be* are that. We really
don't want to drown in noise unless we'd explicitly asked for it.
+Using sparse for lock checking
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following macros are undefined for gcc and defined during a sparse
+run to use the "context" tracking feature of sparse, applied to
+locking. These annotations tell sparse when a lock is held, with
+regard to the annotated function's entry and exit.
+
+__must_hold - The specified lock is held on function entry and exit.
+
+__acquires - The specified lock is held on function exit, but not entry.
+
+__releases - The specified lock is held on function entry, but not exit.
+
+If the function enters and exits without the lock held, acquiring and
+releasing the lock inside the function in a balanced way, no
+annotation is needed. The tree annotations above are for cases where
+sparse would otherwise report a context imbalance.
Getting sparse
~~~~~~~~~~~~~~