Root/
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) |
17 | - Ubuntu (>=10.04 Lucid Lynx) |
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 | |
27 | Information and tips about Coccinelle are also provided on the wiki |
28 | pages at http://cocci.ekstranet.diku.dk/wiki/doku.php |
29 | |
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 | |
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. |
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 | |
51 | Four modes are defined: patch, report, context, and org. The mode to |
52 | use is specified by setting the MODE variable with 'MODE=<mode>'. |
53 | |
54 | 'patch' proposes a fix, when possible. |
55 | |
56 | 'report' generates a list in the following format: |
57 | file:line:column-column: message |
58 | |
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 | |
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. |
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 |
80 | sub-directories of 'scripts/coccinelle' to the entire Linux kernel. |
81 | |
82 | For each semantic patch, a commit message is proposed. It gives a |
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 | |
90 | |
91 | Using Coccinelle with a single semantic patch |
92 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
93 | |
94 | The optional make variable COCCI can be used to check a single |
95 | semantic patch. In that case, the variable must be initialized with |
96 | the name of the semantic patch to apply. |
97 | |
98 | For instance: |
99 | |
100 | make coccicheck COCCI=<my_SP.cocci> MODE=patch |
101 | or |
102 | make coccicheck COCCI=<my_SP.cocci> MODE=report |
103 | |
104 | |
105 | Controlling Which Files are Processed by Coccinelle |
106 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
107 | By default the entire kernel source tree is checked. |
108 | |
109 | To apply Coccinelle to a specific directory, M= can be used. |
110 | For example, to check drivers/net/wireless/ one may write: |
111 | |
112 | make coccicheck M=drivers/net/wireless/ |
113 | |
114 | To apply Coccinelle on a file basis, instead of a directory basis, the |
115 | following command may be used: |
116 | |
117 | make C=1 CHECK="scripts/coccicheck" |
118 | |
119 | To check only newly edited code, use the value 2 for the C flag, i.e. |
120 | |
121 | make C=2 CHECK="scripts/coccicheck" |
122 | |
123 | This runs every semantic patch in scripts/coccinelle by default. The |
124 | COCCI variable may additionally be used to only apply a single |
125 | semantic patch as shown in the previous section. |
126 | |
127 | The "chain" mode is the default. You can select another one with the |
128 | MODE variable explained above. |
129 | |
130 | In this mode, there is no information about semantic patches |
131 | displayed, and no commit message proposed. |
132 | |
133 | |
134 | Proposing new semantic patches |
135 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
136 | |
137 | New semantic patches can be proposed and submitted by kernel |
138 | developers. For sake of clarity, they should be organized in the |
139 | sub-directories of 'scripts/coccinelle/'. |
140 | |
141 | |
142 | Detailed description of the 'report' mode |
143 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
144 | |
145 | 'report' generates a list in the following format: |
146 | file:line:column-column: message |
147 | |
148 | Example: |
149 | |
150 | Running |
151 | |
152 | make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci |
153 | |
154 | will execute the following part of the SmPL script. |
155 | |
156 | <smpl> |
157 | @r depends on !context && !patch && (org || report)@ |
158 | expression x; |
159 | position p; |
160 | @@ |
161 | |
162 | ERR_PTR@p(PTR_ERR(x)) |
163 | |
164 | @script:python depends on report@ |
165 | p << r.p; |
166 | x << r.x; |
167 | @@ |
168 | |
169 | msg="ERR_CAST can be used with %s" % (x) |
170 | coccilib.report.print_report(p[0], msg) |
171 | </smpl> |
172 | |
173 | This SmPL excerpt generates entries on the standard output, as |
174 | illustrated below: |
175 | |
176 | /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg |
177 | /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth |
178 | /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg |
179 | |
180 | |
181 | Detailed description of the 'patch' mode |
182 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
183 | |
184 | When the 'patch' mode is available, it proposes a fix for each problem |
185 | identified. |
186 | |
187 | Example: |
188 | |
189 | Running |
190 | make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci |
191 | |
192 | will execute the following part of the SmPL script. |
193 | |
194 | <smpl> |
195 | @ depends on !context && patch && !org && !report @ |
196 | expression x; |
197 | @@ |
198 | |
199 | - ERR_PTR(PTR_ERR(x)) |
200 | + ERR_CAST(x) |
201 | </smpl> |
202 | |
203 | This SmPL excerpt generates patch hunks on the standard output, as |
204 | illustrated below: |
205 | |
206 | diff -u -p a/crypto/ctr.c b/crypto/ctr.c |
207 | --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 |
208 | +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 |
209 | @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct |
210 | alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, |
211 | CRYPTO_ALG_TYPE_MASK); |
212 | if (IS_ERR(alg)) |
213 | - return ERR_PTR(PTR_ERR(alg)); |
214 | + return ERR_CAST(alg); |
215 | |
216 | /* Block size must be >= 4 bytes. */ |
217 | err = -EINVAL; |
218 | |
219 | Detailed description of the 'context' mode |
220 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
221 | |
222 | 'context' highlights lines of interest and their context |
223 | in a diff-like style. |
224 | |
225 | NOTE: The diff-like output generated is NOT an applicable patch. The |
226 | intent of the 'context' mode is to highlight the important lines |
227 | (annotated with minus, '-') and gives some surrounding context |
228 | lines around. This output can be used with the diff mode of |
229 | Emacs to review the code. |
230 | |
231 | Example: |
232 | |
233 | Running |
234 | make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci |
235 | |
236 | will execute the following part of the SmPL script. |
237 | |
238 | <smpl> |
239 | @ depends on context && !patch && !org && !report@ |
240 | expression x; |
241 | @@ |
242 | |
243 | * ERR_PTR(PTR_ERR(x)) |
244 | </smpl> |
245 | |
246 | This SmPL excerpt generates diff hunks on the standard output, as |
247 | illustrated below: |
248 | |
249 | diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing |
250 | --- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 |
251 | +++ /tmp/nothing |
252 | @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct |
253 | alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, |
254 | CRYPTO_ALG_TYPE_MASK); |
255 | if (IS_ERR(alg)) |
256 | - return ERR_PTR(PTR_ERR(alg)); |
257 | |
258 | /* Block size must be >= 4 bytes. */ |
259 | err = -EINVAL; |
260 | |
261 | Detailed description of the 'org' mode |
262 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
263 | |
264 | 'org' generates a report in the Org mode format of Emacs. |
265 | |
266 | Example: |
267 | |
268 | Running |
269 | make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci |
270 | |
271 | will execute the following part of the SmPL script. |
272 | |
273 | <smpl> |
274 | @r depends on !context && !patch && (org || report)@ |
275 | expression x; |
276 | position p; |
277 | @@ |
278 | |
279 | ERR_PTR@p(PTR_ERR(x)) |
280 | |
281 | @script:python depends on org@ |
282 | p << r.p; |
283 | x << r.x; |
284 | @@ |
285 | |
286 | msg="ERR_CAST can be used with %s" % (x) |
287 | msg_safe=msg.replace("[","@(").replace("]",")") |
288 | coccilib.org.print_todo(p[0], msg_safe) |
289 | </smpl> |
290 | |
291 | This SmPL excerpt generates Org entries on the standard output, as |
292 | illustrated below: |
293 | |
294 | * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] |
295 | * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] |
296 | * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]] |
297 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9