blob: 4a276ea7001c660a8f0dcbe7ff968abcff22a102 [file] [log] [blame]
Nicolas Palixe228b1e2010-06-06 17:15:02 +02001Copyright 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
9The semantic patches included in the kernel use the 'virtual rule'
10feature which was introduced in Coccinelle version 0.1.11.
11
12Coccinelle (>=0.2.0) is available through the package manager
13of many distributions, e.g. :
14
15 - Debian (>=squeeze)
16 - Fedora (>=13)
Kulikov Vasiliyfbe32902010-06-29 16:31:16 +040017 - Ubuntu (>=10.04 Lucid Lynx)
Nicolas Palixe228b1e2010-06-06 17:15:02 +020018 - OpenSUSE
19 - Arch Linux
20 - NetBSD
21 - FreeBSD
22
23
24You can get the latest version released from the Coccinelle homepage at
25http://coccinelle.lip6.fr/
26
Nicolas Palix32af0892010-10-13 00:49:07 +020027Information and tips about Coccinelle are also provided on the wiki
28pages at http://cocci.ekstranet.diku.dk/wiki/doku.php
29
Nicolas Palixe228b1e2010-06-06 17:15:02 +020030Once you have it, run the following command:
31
32 ./configure
33 make
34
35as a regular user, and install it with
36
37 sudo make install
38
39
40 Using Coccinelle on the Linux kernel
41~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
42
43A Coccinelle-specific target is defined in the top level
44Makefile. This target is named 'coccicheck' and calls the 'coccicheck'
45front-end in the 'scripts' directory.
46
Nicolas Palix32af0892010-10-13 00:49:07 +020047Four modes are defined: patch, report, context, and org. The mode to
Nicolas Palixe228b1e2010-06-06 17:15:02 +020048use is specified by setting the MODE variable with 'MODE=<mode>'.
49
Nicolas Palix32af0892010-10-13 00:49:07 +020050'patch' proposes a fix, when possible.
51
Nicolas Palixe228b1e2010-06-06 17:15:02 +020052'report' generates a list in the following format:
53 file:line:column-column: message
54
Nicolas Palixe228b1e2010-06-06 17:15:02 +020055'context' highlights lines of interest and their context in a
56diff-like style.Lines of interest are indicated with '-'.
57
58'org' generates a report in the Org mode format of Emacs.
59
Nicolas Palix32af0892010-10-13 00:49:07 +020060Note that not all semantic patches implement all modes. For easy use
61of Coccinelle, the default mode is "chain" which tries the previous
62modes in the order above until one succeeds.
Nicolas Palixe228b1e2010-06-06 17:15:02 +020063
64To make a report for every semantic patch, run the following command:
65
66 make coccicheck MODE=report
67
68NB: The 'report' mode is the default one.
69
70To produce patches, run:
71
72 make coccicheck MODE=patch
73
74
75The coccicheck target applies every semantic patch available in the
Nicolas Palix32af0892010-10-13 00:49:07 +020076sub-directories of 'scripts/coccinelle' to the entire Linux kernel.
Nicolas Palixe228b1e2010-06-06 17:15:02 +020077
Nicolas Palix32af0892010-10-13 00:49:07 +020078For each semantic patch, a commit message is proposed. It gives a
Nicolas Palixe228b1e2010-06-06 17:15:02 +020079description of the problem being checked by the semantic patch, and
80includes a reference to Coccinelle.
81
82As any static code analyzer, Coccinelle produces false
83positives. Thus, reports must be carefully checked, and patches
84reviewed.
85
86
87 Using Coccinelle with a single semantic patch
88~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
89
90The optional make variable COCCI can be used to check a single
91semantic patch. In that case, the variable must be initialized with
92the name of the semantic patch to apply.
93
94For instance:
95
96 make coccicheck COCCI=<my_SP.cocci> MODE=patch
97or
98 make coccicheck COCCI=<my_SP.cocci> MODE=report
99
100
Nicolas Palix32af0892010-10-13 00:49:07 +0200101 Using Coccinelle on (modified) files
102~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
103
104To apply Coccinelle on a file basis, instead of a directory basis, the
105following command may be used:
106
107 make C=1 CHECK="scripts/coccicheck"
108
109To check only newly edited code, use the value 2 for the C flag, i.e.
110
111 make C=2 CHECK="scripts/coccicheck"
112
113This runs every semantic patch in scripts/coccinelle by default. The
114COCCI variable may additionally be used to only apply a single
115semantic patch as shown in the previous section.
116
117The "chain" mode is the default. You can select another one with the
118MODE variable explained above.
119
120In this mode, there is no information about semantic patches
121displayed, and no commit message proposed.
122
123
Nicolas Palixe228b1e2010-06-06 17:15:02 +0200124 Proposing new semantic patches
125~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126
127New semantic patches can be proposed and submitted by kernel
128developers. For sake of clarity, they should be organized in the
Nicolas Palix32af0892010-10-13 00:49:07 +0200129sub-directories of 'scripts/coccinelle/'.
Nicolas Palixe228b1e2010-06-06 17:15:02 +0200130
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
138Example:
139
140Running
141
Nicolas Palix9dcf7992010-10-24 23:37:33 +0200142 make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci
Nicolas Palixe228b1e2010-06-06 17:15:02 +0200143
144will execute the following part of the SmPL script.
145
146<smpl>
147@r depends on !context && !patch && (org || report)@
148expression x;
149position p;
150@@
151
152 ERR_PTR@p(PTR_ERR(x))
153
154@script:python depends on report@
155p << r.p;
156x << r.x;
157@@
158
159msg="ERR_CAST can be used with %s" % (x)
160coccilib.report.print_report(p[0], msg)
161</smpl>
162
163This SmPL excerpt generates entries on the standard output, as
164illustrated 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
174When the 'patch' mode is available, it proposes a fix for each problem
175identified.
176
177Example:
178
179Running
Nicolas Palix9dcf7992010-10-24 23:37:33 +0200180 make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci
Nicolas Palixe228b1e2010-06-06 17:15:02 +0200181
182will execute the following part of the SmPL script.
183
184<smpl>
185@ depends on !context && patch && !org && !report @
186expression x;
187@@
188
189- ERR_PTR(PTR_ERR(x))
190+ ERR_CAST(x)
191</smpl>
192
193This SmPL excerpt generates patch hunks on the standard output, as
194illustrated below:
195
196diff -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
213in a diff-like style.
214
215NOTE: 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
221Example:
222
223Running
Nicolas Palix9dcf7992010-10-24 23:37:33 +0200224 make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci
Nicolas Palixe228b1e2010-06-06 17:15:02 +0200225
226will execute the following part of the SmPL script.
227
228<smpl>
229@ depends on context && !patch && !org && !report@
230expression x;
231@@
232
233* ERR_PTR(PTR_ERR(x))
234</smpl>
235
236This SmPL excerpt generates diff hunks on the standard output, as
237illustrated below:
238
239diff -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
256Example:
257
258Running
Nicolas Palix9dcf7992010-10-24 23:37:33 +0200259 make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci
Nicolas Palixe228b1e2010-06-06 17:15:02 +0200260
261will execute the following part of the SmPL script.
262
263<smpl>
264@r depends on !context && !patch && (org || report)@
265expression x;
266position p;
267@@
268
269 ERR_PTR@p(PTR_ERR(x))
270
271@script:python depends on org@
272p << r.p;
273x << r.x;
274@@
275
276msg="ERR_CAST can be used with %s" % (x)
277msg_safe=msg.replace("[","@(").replace("]",")")
278coccilib.org.print_todo(p[0], msg_safe)
279</smpl>
280
281This SmPL excerpt generates Org entries on the standard output, as
282illustrated 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]]