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