0001 .. Copyright 2004 Linus Torvalds
0002 .. Copyright 2004 Pavel Machek <pavel@ucw.cz>
0003 .. Copyright 2006 Bob Copeland <me@bobcopeland.com>
0004
0005 Sparse
0006 ======
0007
0008 Sparse is a semantic checker for C programs; it can be used to find a
0009 number of potential problems with kernel code. See
0010 https://lwn.net/Articles/689907/ for an overview of sparse; this document
0011 contains some kernel-specific sparse information.
0012 More information on sparse, mainly about its internals, can be found in
0013 its official pages at https://sparse.docs.kernel.org.
0014
0015
0016 Using sparse for typechecking
0017 -----------------------------
0018
0019 "__bitwise" is a type attribute, so you have to do something like this::
0020
0021 typedef int __bitwise pm_request_t;
0022
0023 enum pm_request {
0024 PM_SUSPEND = (__force pm_request_t) 1,
0025 PM_RESUME = (__force pm_request_t) 2
0026 };
0027
0028 which makes PM_SUSPEND and PM_RESUME "bitwise" integers (the "__force" is
0029 there because sparse will complain about casting to/from a bitwise type,
0030 but in this case we really _do_ want to force the conversion). And because
0031 the enum values are all the same type, now "enum pm_request" will be that
0032 type too.
0033
0034 And with gcc, all the "__bitwise"/"__force stuff" goes away, and it all
0035 ends up looking just like integers to gcc.
0036
0037 Quite frankly, you don't need the enum there. The above all really just
0038 boils down to one special "int __bitwise" type.
0039
0040 So the simpler way is to just do::
0041
0042 typedef int __bitwise pm_request_t;
0043
0044 #define PM_SUSPEND ((__force pm_request_t) 1)
0045 #define PM_RESUME ((__force pm_request_t) 2)
0046
0047 and you now have all the infrastructure needed for strict typechecking.
0048
0049 One small note: the constant integer "0" is special. You can use a
0050 constant zero as a bitwise integer type without sparse ever complaining.
0051 This is because "bitwise" (as the name implies) was designed for making
0052 sure that bitwise types don't get mixed up (little-endian vs big-endian
0053 vs cpu-endian vs whatever), and there the constant "0" really _is_
0054 special.
0055
0056 Using sparse for lock checking
0057 ------------------------------
0058
0059 The following macros are undefined for gcc and defined during a sparse
0060 run to use the "context" tracking feature of sparse, applied to
0061 locking. These annotations tell sparse when a lock is held, with
0062 regard to the annotated function's entry and exit.
0063
0064 __must_hold - The specified lock is held on function entry and exit.
0065
0066 __acquires - The specified lock is held on function exit, but not entry.
0067
0068 __releases - The specified lock is held on function entry, but not exit.
0069
0070 If the function enters and exits without the lock held, acquiring and
0071 releasing the lock inside the function in a balanced way, no
0072 annotation is needed. The three annotations above are for cases where
0073 sparse would otherwise report a context imbalance.
0074
0075 Getting sparse
0076 --------------
0077
0078 You can get tarballs of the latest released versions from:
0079 https://www.kernel.org/pub/software/devel/sparse/dist/
0080
0081 Alternatively, you can get snapshots of the latest development version
0082 of sparse using git to clone::
0083
0084 git://git.kernel.org/pub/scm/devel/sparse/sparse.git
0085
0086 Once you have it, just do::
0087
0088 make
0089 make install
0090
0091 as a regular user, and it will install sparse in your ~/bin directory.
0092
0093 Using sparse
0094 ------------
0095
0096 Do a kernel make with "make C=1" to run sparse on all the C files that get
0097 recompiled, or use "make C=2" to run sparse on the files whether they need to
0098 be recompiled or not. The latter is a fast way to check the whole tree if you
0099 have already built it.
0100
0101 The optional make variable CF can be used to pass arguments to sparse. The
0102 build system passes -Wbitwise to sparse automatically.
0103
0104 Note that sparse defines the __CHECKER__ preprocessor symbol.
