diff options
Diffstat (limited to 'Documentation/sparse.txt')
| -rw-r--r-- | Documentation/sparse.txt | 66 |
1 files changed, 51 insertions, 15 deletions
diff --git a/Documentation/sparse.txt b/Documentation/sparse.txt index 3f1c5464b1c..eceab1308a8 100644 --- a/Documentation/sparse.txt +++ b/Documentation/sparse.txt @@ -1,5 +1,6 @@ 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -41,23 +42,46 @@ 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. -Use +__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__. - make C=[12] CF=-Wbitwise +__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. -or you don't get any checking at all. +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. -Where to get sparse -~~~~~~~~~~~~~~~~~~~ +__must_hold - The specified lock is held on function entry and exit. -With git, you can just get it from +__acquires - The specified lock is held on function exit, but not entry. - rsync://rsync.kernel.org/pub/scm/devel/sparse/sparse.git +__releases - The specified lock is held on function entry, but not exit. -and DaveJ has tar-balls at +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. - http://www.codemonkey.org.uk/projects/git-snapshots/sparse/ +Getting sparse +~~~~~~~~~~~~~~ + +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.. + + git://git.kernel.org/pub/scm/devel/sparse/sparse.git + +DaveJ has hourly generated tarballs of the git tree available at.. + + http://www.codemonkey.org.uk/projects/git-snapshots/sparse/ Once you have it, just do @@ -65,8 +89,20 @@ Once you have it, just do make make install -as your regular user, and it will install sparse in your ~/bin directory. -After that, doing a kernel make with "make C=1" will run sparse on all the -C files that get recompiled, or with "make C=2" will run sparse on the -files whether they need to be recompiled or not (ie the latter is fast way -to check the whole tree if you have already built it). +as a regular user, and it will install sparse in your ~/bin directory. + +Using sparse +~~~~~~~~~~~~ + +Do a kernel make with "make C=1" to run sparse on all the C files that get +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 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 CF="-D__CHECK_ENDIAN__" + +These checks are disabled by default as they generate a host of warnings. |