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