]>
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 | ||
78a95b9b | 51 | Four basic 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 | 64 | Note that not all semantic patches implement all modes. For easy use |
78a95b9b | 65 | of Coccinelle, the default mode is "report". |
e228b1e6 | 66 | |
78a95b9b | 67 | Two other modes provide some common combinations of these modes. |
e228b1e6 | 68 | |
78a95b9b | 69 | 'chain' tries the previous modes in the order above until one succeeds. |
e228b1e6 | 70 | |
78a95b9b NP |
71 | 'rep+ctxt' runs successively the report mode and the context mode. |
72 | It should be used with the C option (described later) | |
73 | which checks the code on a file basis. | |
e228b1e6 | 74 | |
78a95b9b NP |
75 | Examples: |
76 | To make a report for every semantic patch, run the following command: | |
e228b1e6 | 77 | |
78a95b9b NP |
78 | make coccicheck MODE=report |
79 | ||
80 | To produce patches, run: | |
81 | ||
82 | make coccicheck MODE=patch | |
e228b1e6 NP |
83 | |
84 | ||
85 | The coccicheck target applies every semantic patch available in the | |
32af0898 | 86 | sub-directories of 'scripts/coccinelle' to the entire Linux kernel. |
e228b1e6 | 87 | |
32af0898 | 88 | For each semantic patch, a commit message is proposed. It gives a |
e228b1e6 NP |
89 | description of the problem being checked by the semantic patch, and |
90 | includes a reference to Coccinelle. | |
91 | ||
92 | As any static code analyzer, Coccinelle produces false | |
93 | positives. Thus, reports must be carefully checked, and patches | |
94 | reviewed. | |
95 | ||
26e56720 BS |
96 | To enable verbose messages set the V= variable, for example: |
97 | ||
98 | make coccicheck MODE=report V=1 | |
99 | ||
90d06a46 KC |
100 | By default, coccicheck tries to run as parallel as possible. To change |
101 | the parallelism, set the J= variable. For example, to run across 4 CPUs: | |
102 | ||
103 | make coccicheck MODE=report J=4 | |
104 | ||
e228b1e6 NP |
105 | |
106 | Using Coccinelle with a single semantic patch | |
107 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
108 | ||
109 | The optional make variable COCCI can be used to check a single | |
110 | semantic patch. In that case, the variable must be initialized with | |
111 | the name of the semantic patch to apply. | |
112 | ||
113 | For instance: | |
114 | ||
115 | make coccicheck COCCI=<my_SP.cocci> MODE=patch | |
116 | or | |
117 | make coccicheck COCCI=<my_SP.cocci> MODE=report | |
118 | ||
119 | ||
f95ab209 GD |
120 | Controlling Which Files are Processed by Coccinelle |
121 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
122 | By default the entire kernel source tree is checked. | |
123 | ||
124 | To apply Coccinelle to a specific directory, M= can be used. | |
125 | For example, to check drivers/net/wireless/ one may write: | |
32af0898 | 126 | |
f95ab209 | 127 | make coccicheck M=drivers/net/wireless/ |
ed621cc4 | 128 | |
32af0898 NP |
129 | To apply Coccinelle on a file basis, instead of a directory basis, the |
130 | following command may be used: | |
131 | ||
132 | make C=1 CHECK="scripts/coccicheck" | |
133 | ||
134 | To check only newly edited code, use the value 2 for the C flag, i.e. | |
135 | ||
136 | make C=2 CHECK="scripts/coccicheck" | |
137 | ||
78a95b9b NP |
138 | In these modes, which works on a file basis, there is no information |
139 | about semantic patches displayed, and no commit message proposed. | |
140 | ||
32af0898 NP |
141 | This runs every semantic patch in scripts/coccinelle by default. The |
142 | COCCI variable may additionally be used to only apply a single | |
143 | semantic patch as shown in the previous section. | |
144 | ||
78a95b9b | 145 | The "report" mode is the default. You can select another one with the |
32af0898 NP |
146 | MODE variable explained above. |
147 | ||
ed621cc4 NP |
148 | Additional flags |
149 | ~~~~~~~~~~~~~~~~~~ | |
150 | ||
151 | Additional flags can be passed to spatch through the SPFLAGS | |
152 | variable. | |
153 | ||
78a95b9b NP |
154 | make SPFLAGS=--use-glimpse coccicheck |
155 | make SPFLAGS=--use-idutils coccicheck | |
ed621cc4 NP |
156 | |
157 | See spatch --help to learn more about spatch options. | |
32af0898 | 158 | |
78a95b9b NP |
159 | Note that the '--use-glimpse' and '--use-idutils' options |
160 | require external tools for indexing the code. None of them is | |
161 | thus active by default. However, by indexing the code with | |
162 | one of these tools, and according to the cocci file used, | |
163 | spatch could proceed the entire code base more quickly. | |
164 | ||
e228b1e6 NP |
165 | Proposing new semantic patches |
166 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
167 | ||
168 | New semantic patches can be proposed and submitted by kernel | |
169 | developers. For sake of clarity, they should be organized in the | |
32af0898 | 170 | sub-directories of 'scripts/coccinelle/'. |
e228b1e6 NP |
171 | |
172 | ||
173 | Detailed description of the 'report' mode | |
174 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
175 | ||
176 | 'report' generates a list in the following format: | |
177 | file:line:column-column: message | |
178 | ||
179 | Example: | |
180 | ||
181 | Running | |
182 | ||
9dcf7990 | 183 | make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 NP |
184 | |
185 | will execute the following part of the SmPL script. | |
186 | ||
187 | <smpl> | |
188 | @r depends on !context && !patch && (org || report)@ | |
189 | expression x; | |
190 | position p; | |
191 | @@ | |
192 | ||
193 | ERR_PTR@p(PTR_ERR(x)) | |
194 | ||
195 | @script:python depends on report@ | |
196 | p << r.p; | |
197 | x << r.x; | |
198 | @@ | |
199 | ||
200 | msg="ERR_CAST can be used with %s" % (x) | |
201 | coccilib.report.print_report(p[0], msg) | |
202 | </smpl> | |
203 | ||
204 | This SmPL excerpt generates entries on the standard output, as | |
205 | illustrated below: | |
206 | ||
207 | /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg | |
208 | /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth | |
209 | /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg | |
210 | ||
211 | ||
212 | Detailed description of the 'patch' mode | |
213 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
214 | ||
215 | When the 'patch' mode is available, it proposes a fix for each problem | |
216 | identified. | |
217 | ||
218 | Example: | |
219 | ||
220 | Running | |
9dcf7990 | 221 | make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 NP |
222 | |
223 | will execute the following part of the SmPL script. | |
224 | ||
225 | <smpl> | |
226 | @ depends on !context && patch && !org && !report @ | |
227 | expression x; | |
228 | @@ | |
229 | ||
230 | - ERR_PTR(PTR_ERR(x)) | |
231 | + ERR_CAST(x) | |
232 | </smpl> | |
233 | ||
234 | This SmPL excerpt generates patch hunks on the standard output, as | |
235 | illustrated below: | |
236 | ||
237 | diff -u -p a/crypto/ctr.c b/crypto/ctr.c | |
238 | --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 | |
239 | +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 | |
240 | @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct | |
241 | alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, | |
242 | CRYPTO_ALG_TYPE_MASK); | |
243 | if (IS_ERR(alg)) | |
244 | - return ERR_PTR(PTR_ERR(alg)); | |
245 | + return ERR_CAST(alg); | |
246 | ||
247 | /* Block size must be >= 4 bytes. */ | |
248 | err = -EINVAL; | |
249 | ||
250 | Detailed description of the 'context' mode | |
251 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
252 | ||
253 | 'context' highlights lines of interest and their context | |
254 | in a diff-like style. | |
255 | ||
256 | NOTE: The diff-like output generated is NOT an applicable patch. The | |
257 | intent of the 'context' mode is to highlight the important lines | |
258 | (annotated with minus, '-') and gives some surrounding context | |
259 | lines around. This output can be used with the diff mode of | |
260 | Emacs to review the code. | |
261 | ||
262 | Example: | |
263 | ||
264 | Running | |
9dcf7990 | 265 | make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 NP |
266 | |
267 | will execute the following part of the SmPL script. | |
268 | ||
269 | <smpl> | |
270 | @ depends on context && !patch && !org && !report@ | |
271 | expression x; | |
272 | @@ | |
273 | ||
274 | * ERR_PTR(PTR_ERR(x)) | |
275 | </smpl> | |
276 | ||
277 | This SmPL excerpt generates diff hunks on the standard output, as | |
278 | illustrated below: | |
279 | ||
280 | diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing | |
281 | --- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 | |
282 | +++ /tmp/nothing | |
283 | @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct | |
284 | alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, | |
285 | CRYPTO_ALG_TYPE_MASK); | |
286 | if (IS_ERR(alg)) | |
287 | - return ERR_PTR(PTR_ERR(alg)); | |
288 | ||
289 | /* Block size must be >= 4 bytes. */ | |
290 | err = -EINVAL; | |
291 | ||
292 | Detailed description of the 'org' mode | |
293 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
294 | ||
295 | 'org' generates a report in the Org mode format of Emacs. | |
296 | ||
297 | Example: | |
298 | ||
299 | Running | |
9dcf7990 | 300 | make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 NP |
301 | |
302 | will execute the following part of the SmPL script. | |
303 | ||
304 | <smpl> | |
305 | @r depends on !context && !patch && (org || report)@ | |
306 | expression x; | |
307 | position p; | |
308 | @@ | |
309 | ||
310 | ERR_PTR@p(PTR_ERR(x)) | |
311 | ||
312 | @script:python depends on org@ | |
313 | p << r.p; | |
314 | x << r.x; | |
315 | @@ | |
316 | ||
317 | msg="ERR_CAST can be used with %s" % (x) | |
318 | msg_safe=msg.replace("[","@(").replace("]",")") | |
319 | coccilib.org.print_todo(p[0], msg_safe) | |
320 | </smpl> | |
321 | ||
322 | This SmPL excerpt generates Org entries on the standard output, as | |
323 | illustrated below: | |
324 | ||
325 | * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] | |
326 | * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] | |
327 | * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]] |