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