Commit | Line | Data |
---|---|---|
1da177e4 | 1 | Copyright 2004 Linus Torvalds |
a2531293 | 2 | Copyright 2004 Pavel Machek <pavel@ucw.cz> |
e8331951 | 3 | Copyright 2006 Bob Copeland <me@bobcopeland.com> |
1da177e4 LT |
4 | |
5 | Using sparse for typechecking | |
6 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7 | ||
8 | "__bitwise" is a type attribute, so you have to do something like this: | |
9 | ||
10 | typedef int __bitwise pm_request_t; | |
11 | ||
12 | enum pm_request { | |
13 | PM_SUSPEND = (__force pm_request_t) 1, | |
14 | PM_RESUME = (__force pm_request_t) 2 | |
15 | }; | |
16 | ||
17 | which makes PM_SUSPEND and PM_RESUME "bitwise" integers (the "__force" is | |
18 | there because sparse will complain about casting to/from a bitwise type, | |
19 | but in this case we really _do_ want to force the conversion). And because | |
20 | the enum values are all the same type, now "enum pm_request" will be that | |
21 | type too. | |
22 | ||
23 | And with gcc, all the __bitwise/__force stuff goes away, and it all ends | |
24 | up looking just like integers to gcc. | |
25 | ||
26 | Quite frankly, you don't need the enum there. The above all really just | |
27 | boils down to one special "int __bitwise" type. | |
28 | ||
29 | So the simpler way is to just do | |
30 | ||
31 | typedef int __bitwise pm_request_t; | |
32 | ||
33 | #define PM_SUSPEND ((__force pm_request_t) 1) | |
34 | #define PM_RESUME ((__force pm_request_t) 2) | |
35 | ||
36 | and you now have all the infrastructure needed for strict typechecking. | |
37 | ||
38 | One small note: the constant integer "0" is special. You can use a | |
39 | constant zero as a bitwise integer type without sparse ever complaining. | |
40 | This is because "bitwise" (as the name implies) was designed for making | |
41 | sure that bitwise types don't get mixed up (little-endian vs big-endian | |
42 | vs cpu-endian vs whatever), and there the constant "0" really _is_ | |
43 | special. | |
44 | ||
20375bf8 SR |
45 | __bitwise__ - to be used for relatively compact stuff (gfp_t, etc.) that |
46 | is mostly warning-free and is supposed to stay that way. Warnings will | |
47 | be generated without __CHECK_ENDIAN__. | |
48 | ||
49 | __bitwise - noisy stuff; in particular, __le*/__be* are that. We really | |
50 | don't want to drown in noise unless we'd explicitly asked for it. | |
51 | ||
6e976631 EC |
52 | Using sparse for lock checking |
53 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
54 | ||
55 | The following macros are undefined for gcc and defined during a sparse | |
56 | run to use the "context" tracking feature of sparse, applied to | |
57 | locking. These annotations tell sparse when a lock is held, with | |
58 | regard to the annotated function's entry and exit. | |
59 | ||
60 | __must_hold - The specified lock is held on function entry and exit. | |
61 | ||
62 | __acquires - The specified lock is held on function exit, but not entry. | |
63 | ||
64 | __releases - The specified lock is held on function entry, but not exit. | |
65 | ||
66 | If the function enters and exits without the lock held, acquiring and | |
67 | releasing the lock inside the function in a balanced way, no | |
68 | annotation is needed. The tree annotations above are for cases where | |
69 | sparse would otherwise report a context imbalance. | |
20375bf8 | 70 | |
e8331951 BC |
71 | Getting sparse |
72 | ~~~~~~~~~~~~~~ | |
1da177e4 | 73 | |
a55028ff | 74 | You can get latest released versions from the Sparse homepage at |
05be7a86 | 75 | https://sparse.wiki.kernel.org/index.php/Main_Page |
1da177e4 | 76 | |
a55028ff DJ |
77 | Alternatively, you can get snapshots of the latest development version |
78 | of sparse using git to clone.. | |
1da177e4 | 79 | |
05be7a86 | 80 | git://git.kernel.org/pub/scm/devel/sparse/sparse.git |
a55028ff DJ |
81 | |
82 | DaveJ has hourly generated tarballs of the git tree available at.. | |
1da177e4 | 83 | |
e8331951 | 84 | http://www.codemonkey.org.uk/projects/git-snapshots/sparse/ |
1da177e4 LT |
85 | |
86 | ||
87 | Once you have it, just do | |
88 | ||
89 | make | |
90 | make install | |
91 | ||
e8331951 BC |
92 | as a regular user, and it will install sparse in your ~/bin directory. |
93 | ||
94 | Using sparse | |
95 | ~~~~~~~~~~~~ | |
96 | ||
97 | Do a kernel make with "make C=1" to run sparse on all the C files that get | |
98 | recompiled, or use "make C=2" to run sparse on the files whether they need to | |
99 | be recompiled or not. The latter is a fast way to check the whole tree if you | |
100 | have already built it. | |
101 | ||
a887a07d GU |
102 | The optional make variable CF can be used to pass arguments to sparse. The |
103 | build system passes -Wbitwise to sparse automatically. To perform endianness | |
104 | checks, you may define __CHECK_ENDIAN__: | |
e8331951 | 105 | |
a887a07d | 106 | make C=2 CF="-D__CHECK_ENDIAN__" |
e8331951 BC |
107 | |
108 | These checks are disabled by default as they generate a host of warnings. |