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 | Using Coccinelle on (modified) files |
106 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
107 | |
108 | To apply Coccinelle on a file basis, instead of a directory basis, the |
109 | following command may be used: |
110 | |
111 | make C=1 CHECK="scripts/coccicheck" |
112 | |
113 | To check only newly edited code, use the value 2 for the C flag, i.e. |
114 | |
115 | make C=2 CHECK="scripts/coccicheck" |
116 | |
117 | This runs every semantic patch in scripts/coccinelle by default. The |
118 | COCCI variable may additionally be used to only apply a single |
119 | semantic patch as shown in the previous section. |
120 | |
121 | The "chain" mode is the default. You can select another one with the |
122 | MODE variable explained above. |
123 | |
124 | In this mode, there is no information about semantic patches |
125 | displayed, and no commit message proposed. |
126 | |
127 | |
128 | Proposing new semantic patches |
129 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
130 | |
131 | New semantic patches can be proposed and submitted by kernel |
132 | developers. For sake of clarity, they should be organized in the |
133 | sub-directories of 'scripts/coccinelle/'. |
134 | |
135 | |
136 | Detailed description of the 'report' mode |
137 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
138 | |
139 | 'report' generates a list in the following format: |
140 | file:line:column-column: message |
141 | |
142 | Example: |
143 | |
144 | Running |
145 | |
146 | make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci |
147 | |
148 | will execute the following part of the SmPL script. |
149 | |
150 | <smpl> |
151 | @r depends on !context && !patch && (org || report)@ |
152 | expression x; |
153 | position p; |
154 | @@ |
155 | |
156 | ERR_PTR@p(PTR_ERR(x)) |
157 | |
158 | @script:python depends on report@ |
159 | p << r.p; |
160 | x << r.x; |
161 | @@ |
162 | |
163 | msg="ERR_CAST can be used with %s" % (x) |
164 | coccilib.report.print_report(p[0], msg) |
165 | </smpl> |
166 | |
167 | This SmPL excerpt generates entries on the standard output, as |
168 | illustrated below: |
169 | |
170 | /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg |
171 | /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth |
172 | /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg |
173 | |
174 | |
175 | Detailed description of the 'patch' mode |
176 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
177 | |
178 | When the 'patch' mode is available, it proposes a fix for each problem |
179 | identified. |
180 | |
181 | Example: |
182 | |
183 | Running |
184 | make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci |
185 | |
186 | will execute the following part of the SmPL script. |
187 | |
188 | <smpl> |
189 | @ depends on !context && patch && !org && !report @ |
190 | expression x; |
191 | @@ |
192 | |
193 | - ERR_PTR(PTR_ERR(x)) |
194 | + ERR_CAST(x) |
195 | </smpl> |
196 | |
197 | This SmPL excerpt generates patch hunks on the standard output, as |
198 | illustrated below: |
199 | |
200 | diff -u -p a/crypto/ctr.c b/crypto/ctr.c |
201 | --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 |
202 | +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 |
203 | @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct |
204 | alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, |
205 | CRYPTO_ALG_TYPE_MASK); |
206 | if (IS_ERR(alg)) |
207 | - return ERR_PTR(PTR_ERR(alg)); |
208 | + return ERR_CAST(alg); |
209 | |
210 | /* Block size must be >= 4 bytes. */ |
211 | err = -EINVAL; |
212 | |
213 | Detailed description of the 'context' mode |
214 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
215 | |
216 | 'context' highlights lines of interest and their context |
217 | in a diff-like style. |
218 | |
219 | NOTE: The diff-like output generated is NOT an applicable patch. The |
220 | intent of the 'context' mode is to highlight the important lines |
221 | (annotated with minus, '-') and gives some surrounding context |
222 | lines around. This output can be used with the diff mode of |
223 | Emacs to review the code. |
224 | |
225 | Example: |
226 | |
227 | Running |
228 | make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci |
229 | |
230 | will execute the following part of the SmPL script. |
231 | |
232 | <smpl> |
233 | @ depends on context && !patch && !org && !report@ |
234 | expression x; |
235 | @@ |
236 | |
237 | * ERR_PTR(PTR_ERR(x)) |
238 | </smpl> |
239 | |
240 | This SmPL excerpt generates diff hunks on the standard output, as |
241 | illustrated below: |
242 | |
243 | diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing |
244 | --- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 |
245 | +++ /tmp/nothing |
246 | @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct |
247 | alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, |
248 | CRYPTO_ALG_TYPE_MASK); |
249 | if (IS_ERR(alg)) |
250 | - return ERR_PTR(PTR_ERR(alg)); |
251 | |
252 | /* Block size must be >= 4 bytes. */ |
253 | err = -EINVAL; |
254 | |
255 | Detailed description of the 'org' mode |
256 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
257 | |
258 | 'org' generates a report in the Org mode format of Emacs. |
259 | |
260 | Example: |
261 | |
262 | Running |
263 | make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci |
264 | |
265 | will execute the following part of the SmPL script. |
266 | |
267 | <smpl> |
268 | @r depends on !context && !patch && (org || report)@ |
269 | expression x; |
270 | position p; |
271 | @@ |
272 | |
273 | ERR_PTR@p(PTR_ERR(x)) |
274 | |
275 | @script:python depends on org@ |
276 | p << r.p; |
277 | x << r.x; |
278 | @@ |
279 | |
280 | msg="ERR_CAST can be used with %s" % (x) |
281 | msg_safe=msg.replace("[","@(").replace("]",")") |
282 | coccilib.org.print_todo(p[0], msg_safe) |
283 | </smpl> |
284 | |
285 | This SmPL excerpt generates Org entries on the standard output, as |
286 | illustrated below: |
287 | |
288 | * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] |
289 | * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] |
290 | * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]] |
291 |
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