Commit | Line | Data |
---|---|---|
e228b1e6 NP |
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) | |
fbe3290f | 17 | - Ubuntu (>=10.04 Lucid Lynx) |
e228b1e6 NP |
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]] |