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>
9 The semantic patches included in the kernel use the 'virtual rule'
10 feature which was introduced in Coccinelle version 0.1.11.
12 Coccinelle (>=0.2.0) is available through the package manager
13 of many distributions, e.g. :
17 - Ubuntu (>=10.04 Lucid Lynx)
24 You can get the latest version released from the Coccinelle homepage at
25 http://coccinelle.lip6.fr/
27 Information and tips about Coccinelle are also provided on the wiki
28 pages at http://cocci.ekstranet.diku.dk/wiki/doku.php
30 Once you have it, run the following command:
35 as a regular user, and install it with
39 The semantic patches in the kernel will work best with Coccinelle version
40 0.2.4 or later. Using earlier versions may incur some parse errors in the
41 semantic patch code, but any results that are obtained should still be
44 Using Coccinelle on the Linux kernel
45 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
47 A Coccinelle-specific target is defined in the top level
48 Makefile. This target is named 'coccicheck' and calls the 'coccicheck'
49 front-end in the 'scripts' directory.
51 Four basic modes are defined: patch, report, context, and org. The mode to
52 use is specified by setting the MODE variable with 'MODE=<mode>'.
54 'patch' proposes a fix, when possible.
56 'report' generates a list in the following format:
57 file:line:column-column: message
59 'context' highlights lines of interest and their context in a
60 diff-like style.Lines of interest are indicated with '-'.
62 'org' generates a report in the Org mode format of Emacs.
64 Note that not all semantic patches implement all modes. For easy use
65 of Coccinelle, the default mode is "report".
67 Two other modes provide some common combinations of these modes.
69 'chain' tries the previous modes in the order above until one succeeds.
71 'rep+ctxt' runs successively the report mode and the context mode.
72 It should be used with the C option (described later)
73 which checks the code on a file basis.
76 To make a report for every semantic patch, run the following command:
78 make coccicheck MODE=report
80 To produce patches, run:
82 make coccicheck MODE=patch
85 The coccicheck target applies every semantic patch available in the
86 sub-directories of 'scripts/coccinelle' to the entire Linux kernel.
88 For each semantic patch, a commit message is proposed. It gives a
89 description of the problem being checked by the semantic patch, and
90 includes a reference to Coccinelle.
92 As any static code analyzer, Coccinelle produces false
93 positives. Thus, reports must be carefully checked, and patches
96 To enable verbose messages set the V= variable, for example:
98 make coccicheck MODE=report V=1
100 By default, coccicheck tries to run as parallel as possible. To change
101 the parallelism, set the J= variable. For example, to run across 4 CPUs:
103 make coccicheck MODE=report J=4
106 Using Coccinelle with a single semantic patch
107 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
109 The optional make variable COCCI can be used to check a single
110 semantic patch. In that case, the variable must be initialized with
111 the name of the semantic patch to apply.
115 make coccicheck COCCI=<my_SP.cocci> MODE=patch
117 make coccicheck COCCI=<my_SP.cocci> MODE=report
120 Controlling Which Files are Processed by Coccinelle
121 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
122 By default the entire kernel source tree is checked.
124 To apply Coccinelle to a specific directory, M= can be used.
125 For example, to check drivers/net/wireless/ one may write:
127 make coccicheck M=drivers/net/wireless/
129 To apply Coccinelle on a file basis, instead of a directory basis, the
130 following command may be used:
132 make C=1 CHECK="scripts/coccicheck"
134 To check only newly edited code, use the value 2 for the C flag, i.e.
136 make C=2 CHECK="scripts/coccicheck"
138 In these modes, which works on a file basis, there is no information
139 about semantic patches displayed, and no commit message proposed.
141 This runs every semantic patch in scripts/coccinelle by default. The
142 COCCI variable may additionally be used to only apply a single
143 semantic patch as shown in the previous section.
145 The "report" mode is the default. You can select another one with the
146 MODE variable explained above.
151 Additional flags can be passed to spatch through the SPFLAGS
154 make SPFLAGS=--use-glimpse coccicheck
155 make SPFLAGS=--use-idutils coccicheck
157 See spatch --help to learn more about spatch options.
159 Note that the '--use-glimpse' and '--use-idutils' options
160 require external tools for indexing the code. None of them is
161 thus active by default. However, by indexing the code with
162 one of these tools, and according to the cocci file used,
163 spatch could proceed the entire code base more quickly.
165 Proposing new semantic patches
166 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
168 New semantic patches can be proposed and submitted by kernel
169 developers. For sake of clarity, they should be organized in the
170 sub-directories of 'scripts/coccinelle/'.
173 Detailed description of the 'report' mode
174 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
176 'report' generates a list in the following format:
177 file:line:column-column: message
183 make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci
185 will execute the following part of the SmPL script.
188 @r depends on !context && !patch && (org || report)@
193 ERR_PTR@p(PTR_ERR(x))
195 @script:python depends on report@
200 msg="ERR_CAST can be used with %s" % (x)
201 coccilib.report.print_report(p[0], msg)
204 This SmPL excerpt generates entries on the standard output, as
207 /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg
208 /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth
209 /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg
212 Detailed description of the 'patch' mode
213 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
215 When the 'patch' mode is available, it proposes a fix for each problem
221 make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci
223 will execute the following part of the SmPL script.
226 @ depends on !context && patch && !org && !report @
230 - ERR_PTR(PTR_ERR(x))
234 This SmPL excerpt generates patch hunks on the standard output, as
237 diff -u -p a/crypto/ctr.c b/crypto/ctr.c
238 --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200
239 +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200
240 @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct
241 alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,
242 CRYPTO_ALG_TYPE_MASK);
244 - return ERR_PTR(PTR_ERR(alg));
245 + return ERR_CAST(alg);
247 /* Block size must be >= 4 bytes. */
250 Detailed description of the 'context' mode
251 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
253 'context' highlights lines of interest and their context
254 in a diff-like style.
256 NOTE: The diff-like output generated is NOT an applicable patch. The
257 intent of the 'context' mode is to highlight the important lines
258 (annotated with minus, '-') and gives some surrounding context
259 lines around. This output can be used with the diff mode of
260 Emacs to review the code.
265 make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci
267 will execute the following part of the SmPL script.
270 @ depends on context && !patch && !org && !report@
274 * ERR_PTR(PTR_ERR(x))
277 This SmPL excerpt generates diff hunks on the standard output, as
280 diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing
281 --- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200
283 @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct
284 alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,
285 CRYPTO_ALG_TYPE_MASK);
287 - return ERR_PTR(PTR_ERR(alg));
289 /* Block size must be >= 4 bytes. */
292 Detailed description of the 'org' mode
293 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
295 'org' generates a report in the Org mode format of Emacs.
300 make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci
302 will execute the following part of the SmPL script.
305 @r depends on !context && !patch && (org || report)@
310 ERR_PTR@p(PTR_ERR(x))
312 @script:python depends on org@
317 msg="ERR_CAST can be used with %s" % (x)
318 msg_safe=msg.replace("[","@(").replace("]",")")
319 coccilib.org.print_todo(p[0], msg_safe)
322 This SmPL excerpt generates Org entries on the standard output, as
325 * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]]
326 * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]]
327 * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]]