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 GD |
116 | make coccicheck M=drivers/net/wireless/ |
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 | ||
137 | ||
e228b1e6 NP |
138 | Proposing new semantic patches |
139 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
140 | ||
141 | New semantic patches can be proposed and submitted by kernel | |
142 | developers. For sake of clarity, they should be organized in the | |
32af0898 | 143 | sub-directories of 'scripts/coccinelle/'. |
e228b1e6 NP |
144 | |
145 | ||
146 | Detailed description of the 'report' mode | |
147 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
148 | ||
149 | 'report' generates a list in the following format: | |
150 | file:line:column-column: message | |
151 | ||
152 | Example: | |
153 | ||
154 | Running | |
155 | ||
9dcf7990 | 156 | make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 NP |
157 | |
158 | will execute the following part of the SmPL script. | |
159 | ||
160 | <smpl> | |
161 | @r depends on !context && !patch && (org || report)@ | |
162 | expression x; | |
163 | position p; | |
164 | @@ | |
165 | ||
166 | ERR_PTR@p(PTR_ERR(x)) | |
167 | ||
168 | @script:python depends on report@ | |
169 | p << r.p; | |
170 | x << r.x; | |
171 | @@ | |
172 | ||
173 | msg="ERR_CAST can be used with %s" % (x) | |
174 | coccilib.report.print_report(p[0], msg) | |
175 | </smpl> | |
176 | ||
177 | This SmPL excerpt generates entries on the standard output, as | |
178 | illustrated below: | |
179 | ||
180 | /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg | |
181 | /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth | |
182 | /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg | |
183 | ||
184 | ||
185 | Detailed description of the 'patch' mode | |
186 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
187 | ||
188 | When the 'patch' mode is available, it proposes a fix for each problem | |
189 | identified. | |
190 | ||
191 | Example: | |
192 | ||
193 | Running | |
9dcf7990 | 194 | make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 NP |
195 | |
196 | will execute the following part of the SmPL script. | |
197 | ||
198 | <smpl> | |
199 | @ depends on !context && patch && !org && !report @ | |
200 | expression x; | |
201 | @@ | |
202 | ||
203 | - ERR_PTR(PTR_ERR(x)) | |
204 | + ERR_CAST(x) | |
205 | </smpl> | |
206 | ||
207 | This SmPL excerpt generates patch hunks on the standard output, as | |
208 | illustrated below: | |
209 | ||
210 | diff -u -p a/crypto/ctr.c b/crypto/ctr.c | |
211 | --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 | |
212 | +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 | |
213 | @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct | |
214 | alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, | |
215 | CRYPTO_ALG_TYPE_MASK); | |
216 | if (IS_ERR(alg)) | |
217 | - return ERR_PTR(PTR_ERR(alg)); | |
218 | + return ERR_CAST(alg); | |
219 | ||
220 | /* Block size must be >= 4 bytes. */ | |
221 | err = -EINVAL; | |
222 | ||
223 | Detailed description of the 'context' mode | |
224 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
225 | ||
226 | 'context' highlights lines of interest and their context | |
227 | in a diff-like style. | |
228 | ||
229 | NOTE: The diff-like output generated is NOT an applicable patch. The | |
230 | intent of the 'context' mode is to highlight the important lines | |
231 | (annotated with minus, '-') and gives some surrounding context | |
232 | lines around. This output can be used with the diff mode of | |
233 | Emacs to review the code. | |
234 | ||
235 | Example: | |
236 | ||
237 | Running | |
9dcf7990 | 238 | make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 NP |
239 | |
240 | will execute the following part of the SmPL script. | |
241 | ||
242 | <smpl> | |
243 | @ depends on context && !patch && !org && !report@ | |
244 | expression x; | |
245 | @@ | |
246 | ||
247 | * ERR_PTR(PTR_ERR(x)) | |
248 | </smpl> | |
249 | ||
250 | This SmPL excerpt generates diff hunks on the standard output, as | |
251 | illustrated below: | |
252 | ||
253 | diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing | |
254 | --- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 | |
255 | +++ /tmp/nothing | |
256 | @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct | |
257 | alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, | |
258 | CRYPTO_ALG_TYPE_MASK); | |
259 | if (IS_ERR(alg)) | |
260 | - return ERR_PTR(PTR_ERR(alg)); | |
261 | ||
262 | /* Block size must be >= 4 bytes. */ | |
263 | err = -EINVAL; | |
264 | ||
265 | Detailed description of the 'org' mode | |
266 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
267 | ||
268 | 'org' generates a report in the Org mode format of Emacs. | |
269 | ||
270 | Example: | |
271 | ||
272 | Running | |
9dcf7990 | 273 | make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 NP |
274 | |
275 | will execute the following part of the SmPL script. | |
276 | ||
277 | <smpl> | |
278 | @r depends on !context && !patch && (org || report)@ | |
279 | expression x; | |
280 | position p; | |
281 | @@ | |
282 | ||
283 | ERR_PTR@p(PTR_ERR(x)) | |
284 | ||
285 | @script:python depends on org@ | |
286 | p << r.p; | |
287 | x << r.x; | |
288 | @@ | |
289 | ||
290 | msg="ERR_CAST can be used with %s" % (x) | |
291 | msg_safe=msg.replace("[","@(").replace("]",")") | |
292 | coccilib.org.print_todo(p[0], msg_safe) | |
293 | </smpl> | |
294 | ||
295 | This SmPL excerpt generates Org entries on the standard output, as | |
296 | illustrated below: | |
297 | ||
298 | * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] | |
299 | * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] | |
300 | * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]] |