Based on kernel version 3.3. Page generated on 2012-03-23 21:25 EST.
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 Information and tips about Coccinelle are also provided on the wiki 28 pages at http://cocci.ekstranet.diku.dk/wiki/doku.php 29 30 Once you have it, run the following command: 31 32 ./configure 33 make 34 35 as a regular user, and install it with 36 37 sudo make install 38 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 42 correct. 43 44 Using Coccinelle on the Linux kernel 45 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 46 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. 50 51 Four modes are defined: patch, report, context, and org. The mode to 52 use is specified by setting the MODE variable with 'MODE=<mode>'. 53 54 'patch' proposes a fix, when possible. 55 56 'report' generates a list in the following format: 57 file:line:column-column: message 58 59 'context' highlights lines of interest and their context in a 60 diff-like style.Lines of interest are indicated with '-'. 61 62 'org' generates a report in the Org mode format of Emacs. 63 64 Note that not all semantic patches implement all modes. For easy use 65 of Coccinelle, the default mode is "chain" which tries the previous 66 modes in the order above until one succeeds. 67 68 To make a report for every semantic patch, run the following command: 69 70 make coccicheck MODE=report 71 72 NB: The 'report' mode is the default one. 73 74 To produce patches, run: 75 76 make coccicheck MODE=patch 77 78 79 The coccicheck target applies every semantic patch available in the 80 sub-directories of 'scripts/coccinelle' to the entire Linux kernel. 81 82 For each semantic patch, a commit message is proposed. It gives a 83 description of the problem being checked by the semantic patch, and 84 includes a reference to Coccinelle. 85 86 As any static code analyzer, Coccinelle produces false 87 positives. Thus, reports must be carefully checked, and patches 88 reviewed. 89 90 91 Using Coccinelle with a single semantic patch 92 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 93 94 The optional make variable COCCI can be used to check a single 95 semantic patch. In that case, the variable must be initialized with 96 the name of the semantic patch to apply. 97 98 For instance: 99 100 make coccicheck COCCI=<my_SP.cocci> MODE=patch 101 or 102 make coccicheck COCCI=<my_SP.cocci> MODE=report 103 104 105 Controlling Which Files are Processed by Coccinelle 106 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 107 By default the entire kernel source tree is checked. 108 109 To apply Coccinelle to a specific directory, M= can be used. 110 For example, to check drivers/net/wireless/ one may write: 111 112 make coccicheck M=drivers/net/wireless/ 113 114 To apply Coccinelle on a file basis, instead of a directory basis, the 115 following command may be used: 116 117 make C=1 CHECK="scripts/coccicheck" 118 119 To check only newly edited code, use the value 2 for the C flag, i.e. 120 121 make C=2 CHECK="scripts/coccicheck" 122 123 This runs every semantic patch in scripts/coccinelle by default. The 124 COCCI variable may additionally be used to only apply a single 125 semantic patch as shown in the previous section. 126 127 The "chain" mode is the default. You can select another one with the 128 MODE variable explained above. 129 130 In this mode, there is no information about semantic patches 131 displayed, and no commit message proposed. 132 133 134 Proposing new semantic patches 135 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 136 137 New semantic patches can be proposed and submitted by kernel 138 developers. For sake of clarity, they should be organized in the 139 sub-directories of 'scripts/coccinelle/'. 140 141 142 Detailed description of the 'report' mode 143 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 144 145 'report' generates a list in the following format: 146 file:line:column-column: message 147 148 Example: 149 150 Running 151 152 make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci 153 154 will execute the following part of the SmPL script. 155 156 <smpl> 157 @r depends on !context && !patch && (org || report)@ 158 expression x; 159 position p; 160 @@ 161 162 ERR_PTR@p(PTR_ERR(x)) 163 164 @script:python depends on report@ 165 p << r.p; 166 x << r.x; 167 @@ 168 169 msg="ERR_CAST can be used with %s" % (x) 170 coccilib.report.print_report(p[0], msg) 171 </smpl> 172 173 This SmPL excerpt generates entries on the standard output, as 174 illustrated below: 175 176 /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg 177 /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth 178 /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg 179 180 181 Detailed description of the 'patch' mode 182 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 183 184 When the 'patch' mode is available, it proposes a fix for each problem 185 identified. 186 187 Example: 188 189 Running 190 make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci 191 192 will execute the following part of the SmPL script. 193 194 <smpl> 195 @ depends on !context && patch && !org && !report @ 196 expression x; 197 @@ 198 199 - ERR_PTR(PTR_ERR(x)) 200 + ERR_CAST(x) 201 </smpl> 202 203 This SmPL excerpt generates patch hunks on the standard output, as 204 illustrated below: 205 206 diff -u -p a/crypto/ctr.c b/crypto/ctr.c 207 --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 208 +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 209 @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct 210 alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, 211 CRYPTO_ALG_TYPE_MASK); 212 if (IS_ERR(alg)) 213 - return ERR_PTR(PTR_ERR(alg)); 214 + return ERR_CAST(alg); 215 216 /* Block size must be >= 4 bytes. */ 217 err = -EINVAL; 218 219 Detailed description of the 'context' mode 220 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 221 222 'context' highlights lines of interest and their context 223 in a diff-like style. 224 225 NOTE: The diff-like output generated is NOT an applicable patch. The 226 intent of the 'context' mode is to highlight the important lines 227 (annotated with minus, '-') and gives some surrounding context 228 lines around. This output can be used with the diff mode of 229 Emacs to review the code. 230 231 Example: 232 233 Running 234 make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci 235 236 will execute the following part of the SmPL script. 237 238 <smpl> 239 @ depends on context && !patch && !org && !report@ 240 expression x; 241 @@ 242 243 * ERR_PTR(PTR_ERR(x)) 244 </smpl> 245 246 This SmPL excerpt generates diff hunks on the standard output, as 247 illustrated below: 248 249 diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing 250 --- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 251 +++ /tmp/nothing 252 @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct 253 alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, 254 CRYPTO_ALG_TYPE_MASK); 255 if (IS_ERR(alg)) 256 - return ERR_PTR(PTR_ERR(alg)); 257 258 /* Block size must be >= 4 bytes. */ 259 err = -EINVAL; 260 261 Detailed description of the 'org' mode 262 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 263 264 'org' generates a report in the Org mode format of Emacs. 265 266 Example: 267 268 Running 269 make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci 270 271 will execute the following part of the SmPL script. 272 273 <smpl> 274 @r depends on !context && !patch && (org || report)@ 275 expression x; 276 position p; 277 @@ 278 279 ERR_PTR@p(PTR_ERR(x)) 280 281 @script:python depends on org@ 282 p << r.p; 283 x << r.x; 284 @@ 285 286 msg="ERR_CAST can be used with %s" % (x) 287 msg_safe=msg.replace("[","@(").replace("]",")") 288 coccilib.org.print_todo(p[0], msg_safe) 289 </smpl> 290 291 This SmPL excerpt generates Org entries on the standard output, as 292 illustrated below: 293 294 * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] 295 * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] 296 * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]]