Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/cjb/mmc
[linux-2.6.git] / Documentation / coccinelle.txt
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>
4
5
6  Getting Coccinelle
7 ~~~~~~~~~~~~~~~~~~~~
8
9 The semantic patches included in the kernel use the 'virtual rule'
10 feature which was introduced in Coccinelle version 0.1.11.
11
12 Coccinelle (>=0.2.0) is available through the package manager
13 of many distributions, e.g. :
14
15  - Debian (>=squeeze)
16  - Fedora (>=13)
17  - Ubuntu (>=10.04 Lucid Lynx)
18  - OpenSUSE
19  - Arch Linux
20  - NetBSD
21  - FreeBSD
22
23
24 You can get the latest version released from the Coccinelle homepage at
25 http://coccinelle.lip6.fr/
26
27 Once you have it, run the following command:
28
29         ./configure
30         make
31
32 as a regular user, and install it with
33
34         sudo make install
35
36
37  Using Coccinelle on the Linux kernel
38 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
39
40 A Coccinelle-specific target is defined in the top level
41 Makefile. This target is named 'coccicheck' and calls the 'coccicheck'
42 front-end in the 'scripts' directory.
43
44 Four modes are defined: report, patch, context, and org. The mode to
45 use 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
53 diff-like style.Lines of interest are indicated with '-'.
54
55 'org' generates a report in the Org mode format of Emacs.
56
57 Note that not all semantic patches implement all modes.
58
59 To make a report for every semantic patch, run the following command:
60
61         make coccicheck MODE=report
62
63 NB: The 'report' mode is the default one.
64
65 To produce patches, run:
66
67         make coccicheck MODE=patch
68
69
70 The coccicheck target applies every semantic patch available in the
71 subdirectories of 'scripts/coccinelle' to the entire Linux kernel.
72
73 For each semantic patch, a changelog message is proposed.  It gives a
74 description of the problem being checked by the semantic patch, and
75 includes a reference to Coccinelle.
76
77 As any static code analyzer, Coccinelle produces false
78 positives. Thus, reports must be carefully checked, and patches
79 reviewed.
80
81
82  Using Coccinelle with a single semantic patch
83 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
84
85 The optional make variable COCCI can be used to check a single
86 semantic patch. In that case, the variable must be initialized with
87 the name of the semantic patch to apply.
88
89 For instance:
90
91         make coccicheck COCCI=<my_SP.cocci> MODE=patch
92 or
93         make coccicheck COCCI=<my_SP.cocci> MODE=report
94
95
96  Proposing new semantic patches
97 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98
99 New semantic patches can be proposed and submitted by kernel
100 developers. For sake of clarity, they should be organized in the
101 subdirectories 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
110 Example:
111
112 Running
113
114         make coccicheck MODE=report COCCI=scripts/coccinelle/err_cast.cocci
115
116 will execute the following part of the SmPL script.
117
118 <smpl>
119 @r depends on !context && !patch && (org || report)@
120 expression x;
121 position p;
122 @@
123
124  ERR_PTR@p(PTR_ERR(x))
125
126 @script:python depends on report@
127 p << r.p;
128 x << r.x;
129 @@
130
131 msg="ERR_CAST can be used with %s" % (x)
132 coccilib.report.print_report(p[0], msg)
133 </smpl>
134
135 This SmPL excerpt generates entries on the standard output, as
136 illustrated 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
146 When the 'patch' mode is available, it proposes a fix for each problem
147 identified.
148
149 Example:
150
151 Running
152         make coccicheck MODE=patch COCCI=scripts/coccinelle/err_cast.cocci
153
154 will execute the following part of the SmPL script.
155
156 <smpl>
157 @ depends on !context && patch && !org && !report @
158 expression x;
159 @@
160
161 - ERR_PTR(PTR_ERR(x))
162 + ERR_CAST(x)
163 </smpl>
164
165 This SmPL excerpt generates patch hunks on the standard output, as
166 illustrated below:
167
168 diff -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
185 in a diff-like style.
186
187 NOTE: 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
193 Example:
194
195 Running
196         make coccicheck MODE=context COCCI=scripts/coccinelle/err_cast.cocci
197
198 will execute the following part of the SmPL script.
199
200 <smpl>
201 @ depends on context && !patch && !org && !report@
202 expression x;
203 @@
204
205 * ERR_PTR(PTR_ERR(x))
206 </smpl>
207
208 This SmPL excerpt generates diff hunks on the standard output, as
209 illustrated below:
210
211 diff -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
228 Example:
229
230 Running
231         make coccicheck MODE=org COCCI=scripts/coccinelle/err_cast.cocci
232
233 will execute the following part of the SmPL script.
234
235 <smpl>
236 @r depends on !context && !patch && (org || report)@
237 expression x;
238 position p;
239 @@
240
241  ERR_PTR@p(PTR_ERR(x))
242
243 @script:python depends on org@
244 p << r.p;
245 x << r.x;
246 @@
247
248 msg="ERR_CAST can be used with %s" % (x)
249 msg_safe=msg.replace("[","@(").replace("]",")")
250 coccilib.org.print_todo(p[0], msg_safe)
251 </smpl>
252
253 This SmPL excerpt generates Org entries on the standard output, as
254 illustrated 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]]