Root/
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]] |
259 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9