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