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 | ||
39 | ||
40 | Using Coccinelle on the Linux kernel | |
41 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
42 | ||
43 | A Coccinelle-specific target is defined in the top level | |
44 | Makefile. This target is named 'coccicheck' and calls the 'coccicheck' | |
45 | front-end in the 'scripts' directory. | |
46 | ||
32af0898 | 47 | Four modes are defined: patch, report, context, and org. The mode to |
e228b1e6 NP |
48 | use is specified by setting the MODE variable with 'MODE=<mode>'. |
49 | ||
32af0898 NP |
50 | 'patch' proposes a fix, when possible. |
51 | ||
e228b1e6 NP |
52 | 'report' generates a list in the following format: |
53 | file:line:column-column: message | |
54 | ||
e228b1e6 NP |
55 | 'context' highlights lines of interest and their context in a |
56 | diff-like style.Lines of interest are indicated with '-'. | |
57 | ||
58 | 'org' generates a report in the Org mode format of Emacs. | |
59 | ||
32af0898 NP |
60 | Note that not all semantic patches implement all modes. For easy use |
61 | of Coccinelle, the default mode is "chain" which tries the previous | |
62 | modes in the order above until one succeeds. | |
e228b1e6 NP |
63 | |
64 | To make a report for every semantic patch, run the following command: | |
65 | ||
66 | make coccicheck MODE=report | |
67 | ||
68 | NB: The 'report' mode is the default one. | |
69 | ||
70 | To produce patches, run: | |
71 | ||
72 | make coccicheck MODE=patch | |
73 | ||
74 | ||
75 | The coccicheck target applies every semantic patch available in the | |
32af0898 | 76 | sub-directories of 'scripts/coccinelle' to the entire Linux kernel. |
e228b1e6 | 77 | |
32af0898 | 78 | For each semantic patch, a commit message is proposed. It gives a |
e228b1e6 NP |
79 | description of the problem being checked by the semantic patch, and |
80 | includes a reference to Coccinelle. | |
81 | ||
82 | As any static code analyzer, Coccinelle produces false | |
83 | positives. Thus, reports must be carefully checked, and patches | |
84 | reviewed. | |
85 | ||
86 | ||
87 | Using Coccinelle with a single semantic patch | |
88 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
89 | ||
90 | The optional make variable COCCI can be used to check a single | |
91 | semantic patch. In that case, the variable must be initialized with | |
92 | the name of the semantic patch to apply. | |
93 | ||
94 | For instance: | |
95 | ||
96 | make coccicheck COCCI=<my_SP.cocci> MODE=patch | |
97 | or | |
98 | make coccicheck COCCI=<my_SP.cocci> MODE=report | |
99 | ||
100 | ||
32af0898 NP |
101 | Using Coccinelle on (modified) files |
102 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
103 | ||
104 | To apply Coccinelle on a file basis, instead of a directory basis, the | |
105 | following command may be used: | |
106 | ||
107 | make C=1 CHECK="scripts/coccicheck" | |
108 | ||
109 | To check only newly edited code, use the value 2 for the C flag, i.e. | |
110 | ||
111 | make C=2 CHECK="scripts/coccicheck" | |
112 | ||
113 | This runs every semantic patch in scripts/coccinelle by default. The | |
114 | COCCI variable may additionally be used to only apply a single | |
115 | semantic patch as shown in the previous section. | |
116 | ||
117 | The "chain" mode is the default. You can select another one with the | |
118 | MODE variable explained above. | |
119 | ||
120 | In this mode, there is no information about semantic patches | |
121 | displayed, and no commit message proposed. | |
122 | ||
123 | ||
e228b1e6 NP |
124 | Proposing new semantic patches |
125 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
126 | ||
127 | New semantic patches can be proposed and submitted by kernel | |
128 | developers. For sake of clarity, they should be organized in the | |
32af0898 | 129 | sub-directories of 'scripts/coccinelle/'. |
e228b1e6 NP |
130 | |
131 | ||
132 | Detailed description of the 'report' mode | |
133 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
134 | ||
135 | 'report' generates a list in the following format: | |
136 | file:line:column-column: message | |
137 | ||
138 | Example: | |
139 | ||
140 | Running | |
141 | ||
9dcf7990 | 142 | make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 NP |
143 | |
144 | will execute the following part of the SmPL script. | |
145 | ||
146 | <smpl> | |
147 | @r depends on !context && !patch && (org || report)@ | |
148 | expression x; | |
149 | position p; | |
150 | @@ | |
151 | ||
152 | ERR_PTR@p(PTR_ERR(x)) | |
153 | ||
154 | @script:python depends on report@ | |
155 | p << r.p; | |
156 | x << r.x; | |
157 | @@ | |
158 | ||
159 | msg="ERR_CAST can be used with %s" % (x) | |
160 | coccilib.report.print_report(p[0], msg) | |
161 | </smpl> | |
162 | ||
163 | This SmPL excerpt generates entries on the standard output, as | |
164 | illustrated below: | |
165 | ||
166 | /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg | |
167 | /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth | |
168 | /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg | |
169 | ||
170 | ||
171 | Detailed description of the 'patch' mode | |
172 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
173 | ||
174 | When the 'patch' mode is available, it proposes a fix for each problem | |
175 | identified. | |
176 | ||
177 | Example: | |
178 | ||
179 | Running | |
9dcf7990 | 180 | make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 NP |
181 | |
182 | will execute the following part of the SmPL script. | |
183 | ||
184 | <smpl> | |
185 | @ depends on !context && patch && !org && !report @ | |
186 | expression x; | |
187 | @@ | |
188 | ||
189 | - ERR_PTR(PTR_ERR(x)) | |
190 | + ERR_CAST(x) | |
191 | </smpl> | |
192 | ||
193 | This SmPL excerpt generates patch hunks on the standard output, as | |
194 | illustrated below: | |
195 | ||
196 | diff -u -p a/crypto/ctr.c b/crypto/ctr.c | |
197 | --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 | |
198 | +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 | |
199 | @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct | |
200 | alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, | |
201 | CRYPTO_ALG_TYPE_MASK); | |
202 | if (IS_ERR(alg)) | |
203 | - return ERR_PTR(PTR_ERR(alg)); | |
204 | + return ERR_CAST(alg); | |
205 | ||
206 | /* Block size must be >= 4 bytes. */ | |
207 | err = -EINVAL; | |
208 | ||
209 | Detailed description of the 'context' mode | |
210 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
211 | ||
212 | 'context' highlights lines of interest and their context | |
213 | in a diff-like style. | |
214 | ||
215 | NOTE: The diff-like output generated is NOT an applicable patch. The | |
216 | intent of the 'context' mode is to highlight the important lines | |
217 | (annotated with minus, '-') and gives some surrounding context | |
218 | lines around. This output can be used with the diff mode of | |
219 | Emacs to review the code. | |
220 | ||
221 | Example: | |
222 | ||
223 | Running | |
9dcf7990 | 224 | make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 NP |
225 | |
226 | will execute the following part of the SmPL script. | |
227 | ||
228 | <smpl> | |
229 | @ depends on context && !patch && !org && !report@ | |
230 | expression x; | |
231 | @@ | |
232 | ||
233 | * ERR_PTR(PTR_ERR(x)) | |
234 | </smpl> | |
235 | ||
236 | This SmPL excerpt generates diff hunks on the standard output, as | |
237 | illustrated below: | |
238 | ||
239 | diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing | |
240 | --- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 | |
241 | +++ /tmp/nothing | |
242 | @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct | |
243 | alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, | |
244 | CRYPTO_ALG_TYPE_MASK); | |
245 | if (IS_ERR(alg)) | |
246 | - return ERR_PTR(PTR_ERR(alg)); | |
247 | ||
248 | /* Block size must be >= 4 bytes. */ | |
249 | err = -EINVAL; | |
250 | ||
251 | Detailed description of the 'org' mode | |
252 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
253 | ||
254 | 'org' generates a report in the Org mode format of Emacs. | |
255 | ||
256 | Example: | |
257 | ||
258 | Running | |
9dcf7990 | 259 | make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 NP |
260 | |
261 | will execute the following part of the SmPL script. | |
262 | ||
263 | <smpl> | |
264 | @r depends on !context && !patch && (org || report)@ | |
265 | expression x; | |
266 | position p; | |
267 | @@ | |
268 | ||
269 | ERR_PTR@p(PTR_ERR(x)) | |
270 | ||
271 | @script:python depends on org@ | |
272 | p << r.p; | |
273 | x << r.x; | |
274 | @@ | |
275 | ||
276 | msg="ERR_CAST can be used with %s" % (x) | |
277 | msg_safe=msg.replace("[","@(").replace("]",")") | |
278 | coccilib.org.print_todo(p[0], msg_safe) | |
279 | </smpl> | |
280 | ||
281 | This SmPL excerpt generates Org entries on the standard output, as | |
282 | illustrated below: | |
283 | ||
284 | * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] | |
285 | * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] | |
286 | * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]] |