Commit | Line | Data |
---|---|---|
e228b1e6 NP |
1 | Copyright 2010 Nicolas Palix <npalix@diku.dk> |
2 | Copyright 2010 Julia Lawall <julia@diku.dk> | |
3 | Copyright 2010 Gilles Muller <Gilles.Muller@lip6.fr> | |
4 | ||
5 | ||
6 | Getting Coccinelle | |
7 | ~~~~~~~~~~~~~~~~~~~~ | |
8 | ||
9 | The semantic patches included in the kernel use the 'virtual rule' | |
10 | feature which was introduced in Coccinelle version 0.1.11. | |
11 | ||
12 | Coccinelle (>=0.2.0) is available through the package manager | |
13 | of many distributions, e.g. : | |
14 | ||
15 | - Debian (>=squeeze) | |
16 | - Fedora (>=13) | |
fbe3290f | 17 | - Ubuntu (>=10.04 Lucid Lynx) |
e228b1e6 NP |
18 | - OpenSUSE |
19 | - Arch Linux | |
20 | - NetBSD | |
21 | - FreeBSD | |
22 | ||
23 | ||
24 | You can get the latest version released from the Coccinelle homepage at | |
25 | http://coccinelle.lip6.fr/ | |
26 | ||
32af0898 NP |
27 | Information and tips about Coccinelle are also provided on the wiki |
28 | pages at http://cocci.ekstranet.diku.dk/wiki/doku.php | |
29 | ||
e228b1e6 NP |
30 | Once you have it, run the following command: |
31 | ||
32 | ./configure | |
33 | make | |
34 | ||
35 | as a regular user, and install it with | |
36 | ||
37 | sudo make install | |
38 | ||
a1087ef6 JL |
39 | The semantic patches in the kernel will work best with Coccinelle version |
40 | 0.2.4 or later. Using earlier versions may incur some parse errors in the | |
41 | semantic patch code, but any results that are obtained should still be | |
42 | correct. | |
e228b1e6 NP |
43 | |
44 | Using Coccinelle on the Linux kernel | |
45 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
46 | ||
47 | A Coccinelle-specific target is defined in the top level | |
48 | Makefile. This target is named 'coccicheck' and calls the 'coccicheck' | |
49 | front-end in the 'scripts' directory. | |
50 | ||
32af0898 | 51 | Four modes are defined: patch, report, context, and org. The mode to |
e228b1e6 NP |
52 | use is specified by setting the MODE variable with 'MODE=<mode>'. |
53 | ||
32af0898 NP |
54 | 'patch' proposes a fix, when possible. |
55 | ||
e228b1e6 NP |
56 | 'report' generates a list in the following format: |
57 | file:line:column-column: message | |
58 | ||
e228b1e6 NP |
59 | 'context' highlights lines of interest and their context in a |
60 | diff-like style.Lines of interest are indicated with '-'. | |
61 | ||
62 | 'org' generates a report in the Org mode format of Emacs. | |
63 | ||
32af0898 NP |
64 | Note that not all semantic patches implement all modes. For easy use |
65 | of Coccinelle, the default mode is "chain" which tries the previous | |
66 | modes in the order above until one succeeds. | |
e228b1e6 NP |
67 | |
68 | To make a report for every semantic patch, run the following command: | |
69 | ||
70 | make coccicheck MODE=report | |
71 | ||
72 | NB: The 'report' mode is the default one. | |
73 | ||
74 | To produce patches, run: | |
75 | ||
76 | make coccicheck MODE=patch | |
77 | ||
78 | ||
79 | The coccicheck target applies every semantic patch available in the | |
32af0898 | 80 | sub-directories of 'scripts/coccinelle' to the entire Linux kernel. |
e228b1e6 | 81 | |
32af0898 | 82 | For each semantic patch, a commit message is proposed. It gives a |
e228b1e6 NP |
83 | description of the problem being checked by the semantic patch, and |
84 | includes a reference to Coccinelle. | |
85 | ||
86 | As any static code analyzer, Coccinelle produces false | |
87 | positives. Thus, reports must be carefully checked, and patches | |
88 | reviewed. | |
89 | ||
26e56720 BS |
90 | To enable verbose messages set the V= variable, for example: |
91 | ||
92 | make coccicheck MODE=report V=1 | |
93 | ||
e228b1e6 NP |
94 | |
95 | Using Coccinelle with a single semantic patch | |
96 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
97 | ||
98 | The optional make variable COCCI can be used to check a single | |
99 | semantic patch. In that case, the variable must be initialized with | |
100 | the name of the semantic patch to apply. | |
101 | ||
102 | For instance: | |
103 | ||
104 | make coccicheck COCCI=<my_SP.cocci> MODE=patch | |
105 | or | |
106 | make coccicheck COCCI=<my_SP.cocci> MODE=report | |
107 | ||
108 | ||
f95ab209 GD |
109 | Controlling Which Files are Processed by Coccinelle |
110 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
111 | By default the entire kernel source tree is checked. | |
112 | ||
113 | To apply Coccinelle to a specific directory, M= can be used. | |
114 | For example, to check drivers/net/wireless/ one may write: | |
32af0898 | 115 | |
f95ab209 | 116 | make coccicheck M=drivers/net/wireless/ |
ed621cc4 | 117 | |
32af0898 NP |
118 | To apply Coccinelle on a file basis, instead of a directory basis, the |
119 | following command may be used: | |
120 | ||
121 | make C=1 CHECK="scripts/coccicheck" | |
122 | ||
123 | To check only newly edited code, use the value 2 for the C flag, i.e. | |
124 | ||
125 | make C=2 CHECK="scripts/coccicheck" | |
126 | ||
127 | This runs every semantic patch in scripts/coccinelle by default. The | |
128 | COCCI variable may additionally be used to only apply a single | |
129 | semantic patch as shown in the previous section. | |
130 | ||
131 | The "chain" mode is the default. You can select another one with the | |
132 | MODE variable explained above. | |
133 | ||
134 | In this mode, there is no information about semantic patches | |
135 | displayed, and no commit message proposed. | |
136 | ||
ed621cc4 NP |
137 | Additional flags |
138 | ~~~~~~~~~~~~~~~~~~ | |
139 | ||
140 | Additional flags can be passed to spatch through the SPFLAGS | |
141 | variable. | |
142 | ||
143 | make SPFLAGS=--use_glimpse coccicheck | |
144 | ||
145 | See spatch --help to learn more about spatch options. | |
32af0898 | 146 | |
e228b1e6 NP |
147 | Proposing new semantic patches |
148 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
149 | ||
150 | New semantic patches can be proposed and submitted by kernel | |
151 | developers. For sake of clarity, they should be organized in the | |
32af0898 | 152 | sub-directories of 'scripts/coccinelle/'. |
e228b1e6 NP |
153 | |
154 | ||
155 | Detailed description of the 'report' mode | |
156 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
157 | ||
158 | 'report' generates a list in the following format: | |
159 | file:line:column-column: message | |
160 | ||
161 | Example: | |
162 | ||
163 | Running | |
164 | ||
9dcf7990 | 165 | make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 NP |
166 | |
167 | will execute the following part of the SmPL script. | |
168 | ||
169 | <smpl> | |
170 | @r depends on !context && !patch && (org || report)@ | |
171 | expression x; | |
172 | position p; | |
173 | @@ | |
174 | ||
175 | ERR_PTR@p(PTR_ERR(x)) | |
176 | ||
177 | @script:python depends on report@ | |
178 | p << r.p; | |
179 | x << r.x; | |
180 | @@ | |
181 | ||
182 | msg="ERR_CAST can be used with %s" % (x) | |
183 | coccilib.report.print_report(p[0], msg) | |
184 | </smpl> | |
185 | ||
186 | This SmPL excerpt generates entries on the standard output, as | |
187 | illustrated below: | |
188 | ||
189 | /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg | |
190 | /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth | |
191 | /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg | |
192 | ||
193 | ||
194 | Detailed description of the 'patch' mode | |
195 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
196 | ||
197 | When the 'patch' mode is available, it proposes a fix for each problem | |
198 | identified. | |
199 | ||
200 | Example: | |
201 | ||
202 | Running | |
9dcf7990 | 203 | make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 NP |
204 | |
205 | will execute the following part of the SmPL script. | |
206 | ||
207 | <smpl> | |
208 | @ depends on !context && patch && !org && !report @ | |
209 | expression x; | |
210 | @@ | |
211 | ||
212 | - ERR_PTR(PTR_ERR(x)) | |
213 | + ERR_CAST(x) | |
214 | </smpl> | |
215 | ||
216 | This SmPL excerpt generates patch hunks on the standard output, as | |
217 | illustrated below: | |
218 | ||
219 | diff -u -p a/crypto/ctr.c b/crypto/ctr.c | |
220 | --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 | |
221 | +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 | |
222 | @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct | |
223 | alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, | |
224 | CRYPTO_ALG_TYPE_MASK); | |
225 | if (IS_ERR(alg)) | |
226 | - return ERR_PTR(PTR_ERR(alg)); | |
227 | + return ERR_CAST(alg); | |
228 | ||
229 | /* Block size must be >= 4 bytes. */ | |
230 | err = -EINVAL; | |
231 | ||
232 | Detailed description of the 'context' mode | |
233 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
234 | ||
235 | 'context' highlights lines of interest and their context | |
236 | in a diff-like style. | |
237 | ||
238 | NOTE: The diff-like output generated is NOT an applicable patch. The | |
239 | intent of the 'context' mode is to highlight the important lines | |
240 | (annotated with minus, '-') and gives some surrounding context | |
241 | lines around. This output can be used with the diff mode of | |
242 | Emacs to review the code. | |
243 | ||
244 | Example: | |
245 | ||
246 | Running | |
9dcf7990 | 247 | make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 NP |
248 | |
249 | will execute the following part of the SmPL script. | |
250 | ||
251 | <smpl> | |
252 | @ depends on context && !patch && !org && !report@ | |
253 | expression x; | |
254 | @@ | |
255 | ||
256 | * ERR_PTR(PTR_ERR(x)) | |
257 | </smpl> | |
258 | ||
259 | This SmPL excerpt generates diff hunks on the standard output, as | |
260 | illustrated below: | |
261 | ||
262 | diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing | |
263 | --- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 | |
264 | +++ /tmp/nothing | |
265 | @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct | |
266 | alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, | |
267 | CRYPTO_ALG_TYPE_MASK); | |
268 | if (IS_ERR(alg)) | |
269 | - return ERR_PTR(PTR_ERR(alg)); | |
270 | ||
271 | /* Block size must be >= 4 bytes. */ | |
272 | err = -EINVAL; | |
273 | ||
274 | Detailed description of the 'org' mode | |
275 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
276 | ||
277 | 'org' generates a report in the Org mode format of Emacs. | |
278 | ||
279 | Example: | |
280 | ||
281 | Running | |
9dcf7990 | 282 | make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 NP |
283 | |
284 | will execute the following part of the SmPL script. | |
285 | ||
286 | <smpl> | |
287 | @r depends on !context && !patch && (org || report)@ | |
288 | expression x; | |
289 | position p; | |
290 | @@ | |
291 | ||
292 | ERR_PTR@p(PTR_ERR(x)) | |
293 | ||
294 | @script:python depends on org@ | |
295 | p << r.p; | |
296 | x << r.x; | |
297 | @@ | |
298 | ||
299 | msg="ERR_CAST can be used with %s" % (x) | |
300 | msg_safe=msg.replace("[","@(").replace("]",")") | |
301 | coccilib.org.print_todo(p[0], msg_safe) | |
302 | </smpl> | |
303 | ||
304 | This SmPL excerpt generates Org entries on the standard output, as | |
305 | illustrated below: | |
306 | ||
307 | * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] | |
308 | * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] | |
309 | * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]] |