diff options
Diffstat (limited to 'Documentation/sparse.txt')
| -rw-r--r-- | Documentation/sparse.txt | 46 |
1 files changed, 38 insertions, 8 deletions
diff --git a/Documentation/sparse.txt b/Documentation/sparse.txt index f9c99c9a54f..eceab1308a8 100644 --- a/Documentation/sparse.txt +++ b/Documentation/sparse.txt @@ -1,5 +1,5 @@ Copyright 2004 Linus Torvalds -Copyright 2004 Pavel Machek <pavel@suse.cz> +Copyright 2004 Pavel Machek <pavel@ucw.cz> Copyright 2006 Bob Copeland <me@bobcopeland.com> Using sparse for typechecking @@ -42,14 +42,44 @@ sure that bitwise types don't get mixed up (little-endian vs big-endian vs cpu-endian vs whatever), and there the constant "0" really _is_ special. +__bitwise__ - to be used for relatively compact stuff (gfp_t, etc.) that +is mostly warning-free and is supposed to stay that way. Warnings will +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 ~~~~~~~~~~~~~~ -With git, you can just get it from +You can get latest released versions from the Sparse homepage at +https://sparse.wiki.kernel.org/index.php/Main_Page + +Alternatively, you can get snapshots of the latest development version +of sparse using git to clone.. - rsync://rsync.kernel.org/pub/scm/devel/sparse/sparse.git + git://git.kernel.org/pub/scm/devel/sparse/sparse.git -and DaveJ has tar-balls at +DaveJ has hourly generated tarballs of the git tree available at.. http://www.codemonkey.org.uk/projects/git-snapshots/sparse/ @@ -69,10 +99,10 @@ recompiled, or use "make C=2" to run sparse on the files whether they need to be recompiled or not. The latter is a fast way to check the whole tree if you have already built it. -The optional make variable CHECKFLAGS can be used to pass arguments to sparse. -The build system passes -Wbitwise to sparse automatically. To perform -endianness checks, you may define __CHECK_ENDIAN__: +The optional make variable CF can be used to pass arguments to sparse. The +build system passes -Wbitwise to sparse automatically. To perform endianness +checks, you may define __CHECK_ENDIAN__: - make C=2 CHECKFLAGS="-D__CHECK_ENDIAN__" + make C=2 CF="-D__CHECK_ENDIAN__" These checks are disabled by default as they generate a host of warnings. |