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
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.
13
14Coccinelle is available through the package manager
15of many distributions, e.g. :
16
17 - Debian
18 - Fedora
19 - Ubuntu
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
29Information and tips about Coccinelle are also provided on the wiki
30pages at http://cocci.ekstranet.diku.dk/wiki/doku.php
31
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
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
48Four basic modes are defined: patch, report, context, and org. The mode to
49use is specified by setting the MODE variable with 'MODE=<mode>'.
50
51'patch' proposes a fix, when possible.
52
53'report' generates a list in the following format:
54  file:line:column-column: message
55
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
61Note that not all semantic patches implement all modes. For easy use
62of Coccinelle, the default mode is "report".
63
64Two other modes provide some common combinations of these modes.
65
66'chain' tries the previous modes in the order above until one succeeds.
67
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.
71
72Examples:
73	To make a report for every semantic patch, run the following command:
74
75		make coccicheck MODE=report
76
77	To produce patches, run:
78
79		make coccicheck MODE=patch
80
81
82The coccicheck target applies every semantic patch available in the
83sub-directories of 'scripts/coccinelle' to the entire Linux kernel.
84
85For each semantic patch, a commit message is proposed.  It gives a
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
93To enable verbose messages set the V= variable, for example:
94
95   make coccicheck MODE=report V=1
96
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
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
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:
123
124    make coccicheck M=drivers/net/wireless/
125
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
135In these modes, which works on a file basis, there is no information
136about semantic patches displayed, and no commit message proposed.
137
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
142The "report" mode is the default. You can select another one with the
143MODE variable explained above.
144
145 Additional flags
146~~~~~~~~~~~~~~~~~~
147
148Additional flags can be passed to spatch through the SPFLAGS
149variable.
150
151    make SPFLAGS=--use-glimpse coccicheck
152    make SPFLAGS=--use-idutils coccicheck
153
154See spatch --help to learn more about spatch options.
155
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
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
167sub-directories of 'scripts/coccinelle/'.
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
180	make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci
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
218	make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci
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
262	make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci
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
297	make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci
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]]
325