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 90 91 Using Coccinelle with a single semantic patch 92~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 93 94The optional make variable COCCI can be used to check a single 95semantic patch. In that case, the variable must be initialized with 96the name of the semantic patch to apply. 97 98For instance: 99 100 make coccicheck COCCI=<my_SP.cocci> MODE=patch 101or 102 make coccicheck COCCI=<my_SP.cocci> MODE=report 103 104 105 Controlling Which Files are Processed by Coccinelle 106~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 107By default the entire kernel source tree is checked. 108 109To apply Coccinelle to a specific directory, M= can be used. 110For example, to check drivers/net/wireless/ one may write: 111 112 make coccicheck M=drivers/net/wireless/ 113 114To apply Coccinelle on a file basis, instead of a directory basis, the 115following command may be used: 116 117 make C=1 CHECK="scripts/coccicheck" 118 119To check only newly edited code, use the value 2 for the C flag, i.e. 120 121 make C=2 CHECK="scripts/coccicheck" 122 123This runs every semantic patch in scripts/coccinelle by default. The 124COCCI variable may additionally be used to only apply a single 125semantic patch as shown in the previous section. 126 127The "chain" mode is the default. You can select another one with the 128MODE variable explained above. 129 130In this mode, there is no information about semantic patches 131displayed, and no commit message proposed. 132 133 134 Proposing new semantic patches 135~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 136 137New semantic patches can be proposed and submitted by kernel 138developers. For sake of clarity, they should be organized in the 139sub-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 148Example: 149 150Running 151 152 make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci 153 154will execute the following part of the SmPL script. 155 156<smpl> 157@r depends on !context && !patch && (org || report)@ 158expression x; 159position p; 160@@ 161 162 ERR_PTR@p(PTR_ERR(x)) 163 164@script:python depends on report@ 165p << r.p; 166x << r.x; 167@@ 168 169msg="ERR_CAST can be used with %s" % (x) 170coccilib.report.print_report(p[0], msg) 171</smpl> 172 173This SmPL excerpt generates entries on the standard output, as 174illustrated 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 184When the 'patch' mode is available, it proposes a fix for each problem 185identified. 186 187Example: 188 189Running 190 make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci 191 192will execute the following part of the SmPL script. 193 194<smpl> 195@ depends on !context && patch && !org && !report @ 196expression x; 197@@ 198 199- ERR_PTR(PTR_ERR(x)) 200+ ERR_CAST(x) 201</smpl> 202 203This SmPL excerpt generates patch hunks on the standard output, as 204illustrated below: 205 206diff -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 223in a diff-like style. 224 225NOTE: 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 231Example: 232 233Running 234 make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci 235 236will execute the following part of the SmPL script. 237 238<smpl> 239@ depends on context && !patch && !org && !report@ 240expression x; 241@@ 242 243* ERR_PTR(PTR_ERR(x)) 244</smpl> 245 246This SmPL excerpt generates diff hunks on the standard output, as 247illustrated below: 248 249diff -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 266Example: 267 268Running 269 make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci 270 271will execute the following part of the SmPL script. 272 273<smpl> 274@r depends on !context && !patch && (org || report)@ 275expression x; 276position p; 277@@ 278 279 ERR_PTR@p(PTR_ERR(x)) 280 281@script:python depends on org@ 282p << r.p; 283x << r.x; 284@@ 285 286msg="ERR_CAST can be used with %s" % (x) 287msg_safe=msg.replace("[","@(").replace("]",")") 288coccilib.org.print_todo(p[0], msg_safe) 289</smpl> 290 291This SmPL excerpt generates Org entries on the standard output, as 292illustrated 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]] 297