Based on kernel version 4.8. Page generated on 2016-10-06 23:10 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 features and options 10 which are provided by Coccinelle version 1.0.0-rc11 and above. 11 Using earlier versions will fail as the option names used by 12 the Coccinelle files and coccicheck have been updated. 13 14 Coccinelle is available through the package manager 15 of many distributions, e.g. : 16 17 - Debian 18 - Fedora 19 - Ubuntu 20 - OpenSUSE 21 - Arch Linux 22 - NetBSD 23 - FreeBSD 24 25 26 You can get the latest version released from the Coccinelle homepage at 27 http://coccinelle.lip6.fr/ 28 29 Information and tips about Coccinelle are also provided on the wiki 30 pages at http://cocci.ekstranet.diku.dk/wiki/doku.php 31 32 Once you have it, run the following command: 33 34 ./configure 35 make 36 37 as a regular user, and install it with 38 39 sudo make install 40 41 Supplemental documentation 42 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 43 44 For supplemental documentation refer to the wiki: 45 46 https://bottest.wiki.kernel.org/coccicheck 47 48 The wiki documentation always refers to the linux-next version of the script. 49 50 Using Coccinelle on the Linux kernel 51 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 52 53 A Coccinelle-specific target is defined in the top level 54 Makefile. This target is named 'coccicheck' and calls the 'coccicheck' 55 front-end in the 'scripts' directory. 56 57 Four basic modes are defined: patch, report, context, and org. The mode to 58 use is specified by setting the MODE variable with 'MODE=<mode>'. 59 60 'patch' proposes a fix, when possible. 61 62 'report' generates a list in the following format: 63 file:line:column-column: message 64 65 'context' highlights lines of interest and their context in a 66 diff-like style.Lines of interest are indicated with '-'. 67 68 'org' generates a report in the Org mode format of Emacs. 69 70 Note that not all semantic patches implement all modes. For easy use 71 of Coccinelle, the default mode is "report". 72 73 Two other modes provide some common combinations of these modes. 74 75 'chain' tries the previous modes in the order above until one succeeds. 76 77 'rep+ctxt' runs successively the report mode and the context mode. 78 It should be used with the C option (described later) 79 which checks the code on a file basis. 80 81 Examples: 82 To make a report for every semantic patch, run the following command: 83 84 make coccicheck MODE=report 85 86 To produce patches, run: 87 88 make coccicheck MODE=patch 89 90 91 The coccicheck target applies every semantic patch available in the 92 sub-directories of 'scripts/coccinelle' to the entire Linux kernel. 93 94 For each semantic patch, a commit message is proposed. It gives a 95 description of the problem being checked by the semantic patch, and 96 includes a reference to Coccinelle. 97 98 As any static code analyzer, Coccinelle produces false 99 positives. Thus, reports must be carefully checked, and patches 100 reviewed. 101 102 To enable verbose messages set the V= variable, for example: 103 104 make coccicheck MODE=report V=1 105 106 Coccinelle parallelization 107 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 108 109 By default, coccicheck tries to run as parallel as possible. To change 110 the parallelism, set the J= variable. For example, to run across 4 CPUs: 111 112 make coccicheck MODE=report J=4 113 114 As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization, 115 if support for this is detected you will benefit from parmap parallelization. 116 117 When parmap is enabled coccicheck will enable dynamic load balancing by using 118 '--chunksize 1' argument, this ensures we keep feeding threads with work 119 one by one, so that we avoid the situation where most work gets done by only 120 a few threads. With dynamic load balancing, if a thread finishes early we keep 121 feeding it more work. 122 123 When parmap is enabled, if an error occurs in Coccinelle, this error 124 value is propagated back, the return value of the 'make coccicheck' 125 captures this return value. 126 127 Using Coccinelle with a single semantic patch 128 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 129 130 The optional make variable COCCI can be used to check a single 131 semantic patch. In that case, the variable must be initialized with 132 the name of the semantic patch to apply. 133 134 For instance: 135 136 make coccicheck COCCI=<my_SP.cocci> MODE=patch 137 or 138 make coccicheck COCCI=<my_SP.cocci> MODE=report 139 140 141 Controlling Which Files are Processed by Coccinelle 142 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 143 By default the entire kernel source tree is checked. 144 145 To apply Coccinelle to a specific directory, M= can be used. 146 For example, to check drivers/net/wireless/ one may write: 147 148 make coccicheck M=drivers/net/wireless/ 149 150 To apply Coccinelle on a file basis, instead of a directory basis, the 151 following command may be used: 152 153 make C=1 CHECK="scripts/coccicheck" 154 155 To check only newly edited code, use the value 2 for the C flag, i.e. 156 157 make C=2 CHECK="scripts/coccicheck" 158 159 In these modes, which works on a file basis, there is no information 160 about semantic patches displayed, and no commit message proposed. 161 162 This runs every semantic patch in scripts/coccinelle by default. The 163 COCCI variable may additionally be used to only apply a single 164 semantic patch as shown in the previous section. 165 166 The "report" mode is the default. You can select another one with the 167 MODE variable explained above. 168 169 Debugging Coccinelle SmPL patches 170 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 171 172 Using coccicheck is best as it provides in the spatch command line 173 include options matching the options used when we compile the kernel. 174 You can learn what these options are by using V=1, you could then 175 manually run Coccinelle with debug options added. 176 177 Alternatively you can debug running Coccinelle against SmPL patches 178 by asking for stderr to be redirected to stderr, by default stderr 179 is redirected to /dev/null, if you'd like to capture stderr you 180 can specify the DEBUG_FILE="file.txt" option to coccicheck. For 181 instance: 182 183 rm -f cocci.err 184 make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err 185 cat cocci.err 186 187 You can use SPFLAGS to add debugging flags, for instance you may want to 188 add both --profile --show-trying to SPFLAGS when debugging. For instance 189 you may want to use: 190 191 rm -f err.log 192 export COCCI=scripts/coccinelle/misc/irqf_oneshot.cocci 193 make coccicheck DEBUG_FILE="err.log" MODE=report SPFLAGS="--profile --show-trying" M=./drivers/mfd/arizona-irq.c 194 195 err.log will now have the profiling information, while stdout will 196 provide some progress information as Coccinelle moves forward with 197 work. 198 199 DEBUG_FILE support is only supported when using coccinelle >= 1.2. 200 201 .cocciconfig support 202 ~~~~~~~~~~~~~~~~~~~~~~ 203 204 Coccinelle supports reading .cocciconfig for default Coccinelle options that 205 should be used every time spatch is spawned, the order of precedence for 206 variables for .cocciconfig is as follows: 207 208 o Your current user's home directory is processed first 209 o Your directory from which spatch is called is processed next 210 o The directory provided with the --dir option is processed last, if used 211 212 Since coccicheck runs through make, it naturally runs from the kernel 213 proper dir, as such the second rule above would be implied for picking up a 214 .cocciconfig when using 'make coccicheck'. 215 216 'make coccicheck' also supports using M= targets.If you do not supply 217 any M= target, it is assumed you want to target the entire kernel. 218 The kernel coccicheck script has: 219 220 if [ "$KBUILD_EXTMOD" = "" ] ; then 221 OPTIONS="--dir $srctree $COCCIINCLUDE" 222 else 223 OPTIONS="--dir $KBUILD_EXTMOD $COCCIINCLUDE" 224 fi 225 226 KBUILD_EXTMOD is set when an explicit target with M= is used. For both cases 227 the spatch --dir argument is used, as such third rule applies when whether M= 228 is used or not, and when M= is used the target directory can have its own 229 .cocciconfig file. When M= is not passed as an argument to coccicheck the 230 target directory is the same as the directory from where spatch was called. 231 232 If not using the kernel's coccicheck target, keep the above precedence 233 order logic of .cocciconfig reading. If using the kernel's coccicheck target, 234 override any of the kernel's .coccicheck's settings using SPFLAGS. 235 236 We help Coccinelle when used against Linux with a set of sensible defaults 237 options for Linux with our own Linux .cocciconfig. This hints to coccinelle 238 git can be used for 'git grep' queries over coccigrep. A timeout of 200 239 seconds should suffice for now. 240 241 The options picked up by coccinelle when reading a .cocciconfig do not appear 242 as arguments to spatch processes running on your system, to confirm what 243 options will be used by Coccinelle run: 244 245 spatch --print-options-only 246 247 You can override with your own preferred index option by using SPFLAGS. Take 248 note that when there are conflicting options Coccinelle takes precedence for 249 the last options passed. Using .cocciconfig is possible to use idutils, however 250 given the order of precedence followed by Coccinelle, since the kernel now 251 carries its own .cocciconfig, you will need to use SPFLAGS to use idutils if 252 desired. See below section "Additional flags" for more details on how to use 253 idutils. 254 255 Additional flags 256 ~~~~~~~~~~~~~~~~~~ 257 258 Additional flags can be passed to spatch through the SPFLAGS 259 variable. This works as Coccinelle respects the last flags 260 given to it when options are in conflict. 261 262 make SPFLAGS=--use-glimpse coccicheck 263 264 Coccinelle supports idutils as well but requires coccinelle >= 1.0.6. 265 When no ID file is specified coccinelle assumes your ID database file 266 is in the file .id-utils.index on the top level of the kernel, coccinelle 267 carries a script scripts/idutils_index.sh which creates the database with 268 269 mkid -i C --output .id-utils.index 270 271 If you have another database filename you can also just symlink with this 272 name. 273 274 make SPFLAGS=--use-idutils coccicheck 275 276 Alternatively you can specify the database filename explicitly, for 277 instance: 278 279 make SPFLAGS="--use-idutils /full-path/to/ID" coccicheck 280 281 See spatch --help to learn more about spatch options. 282 283 Note that the '--use-glimpse' and '--use-idutils' options 284 require external tools for indexing the code. None of them is 285 thus active by default. However, by indexing the code with 286 one of these tools, and according to the cocci file used, 287 spatch could proceed the entire code base more quickly. 288 289 SmPL patch specific options 290 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 291 292 SmPL patches can have their own requirements for options passed 293 to Coccinelle. SmPL patch specific options can be provided by 294 providing them at the top of the SmPL patch, for instance: 295 296 // Options: --no-includes --include-headers 297 298 SmPL patch Coccinelle requirements 299 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 300 301 As Coccinelle features get added some more advanced SmPL patches 302 may require newer versions of Coccinelle. If an SmPL patch requires 303 at least a version of Coccinelle, this can be specified as follows, 304 as an example if requiring at least Coccinelle >= 1.0.5: 305 306 // Requires: 1.0.5 307 308 Proposing new semantic patches 309 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 310 311 New semantic patches can be proposed and submitted by kernel 312 developers. For sake of clarity, they should be organized in the 313 sub-directories of 'scripts/coccinelle/'. 314 315 316 Detailed description of the 'report' mode 317 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 318 319 'report' generates a list in the following format: 320 file:line:column-column: message 321 322 Example: 323 324 Running 325 326 make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci 327 328 will execute the following part of the SmPL script. 329 330 <smpl> 331 @r depends on !context && !patch && (org || report)@ 332 expression x; 333 position p; 334 @@ 335 336 ERR_PTR@p(PTR_ERR(x)) 337 338 @script:python depends on report@ 339 p << r.p; 340 x << r.x; 341 @@ 342 343 msg="ERR_CAST can be used with %s" % (x) 344 coccilib.report.print_report(p[0], msg) 345 </smpl> 346 347 This SmPL excerpt generates entries on the standard output, as 348 illustrated below: 349 350 /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg 351 /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth 352 /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg 353 354 355 Detailed description of the 'patch' mode 356 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 357 358 When the 'patch' mode is available, it proposes a fix for each problem 359 identified. 360 361 Example: 362 363 Running 364 make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci 365 366 will execute the following part of the SmPL script. 367 368 <smpl> 369 @ depends on !context && patch && !org && !report @ 370 expression x; 371 @@ 372 373 - ERR_PTR(PTR_ERR(x)) 374 + ERR_CAST(x) 375 </smpl> 376 377 This SmPL excerpt generates patch hunks on the standard output, as 378 illustrated below: 379 380 diff -u -p a/crypto/ctr.c b/crypto/ctr.c 381 --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 382 +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 383 @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct 384 alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, 385 CRYPTO_ALG_TYPE_MASK); 386 if (IS_ERR(alg)) 387 - return ERR_PTR(PTR_ERR(alg)); 388 + return ERR_CAST(alg); 389 390 /* Block size must be >= 4 bytes. */ 391 err = -EINVAL; 392 393 Detailed description of the 'context' mode 394 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 395 396 'context' highlights lines of interest and their context 397 in a diff-like style. 398 399 NOTE: The diff-like output generated is NOT an applicable patch. The 400 intent of the 'context' mode is to highlight the important lines 401 (annotated with minus, '-') and gives some surrounding context 402 lines around. This output can be used with the diff mode of 403 Emacs to review the code. 404 405 Example: 406 407 Running 408 make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci 409 410 will execute the following part of the SmPL script. 411 412 <smpl> 413 @ depends on context && !patch && !org && !report@ 414 expression x; 415 @@ 416 417 * ERR_PTR(PTR_ERR(x)) 418 </smpl> 419 420 This SmPL excerpt generates diff hunks on the standard output, as 421 illustrated below: 422 423 diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing 424 --- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 425 +++ /tmp/nothing 426 @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct 427 alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, 428 CRYPTO_ALG_TYPE_MASK); 429 if (IS_ERR(alg)) 430 - return ERR_PTR(PTR_ERR(alg)); 431 432 /* Block size must be >= 4 bytes. */ 433 err = -EINVAL; 434 435 Detailed description of the 'org' mode 436 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 437 438 'org' generates a report in the Org mode format of Emacs. 439 440 Example: 441 442 Running 443 make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci 444 445 will execute the following part of the SmPL script. 446 447 <smpl> 448 @r depends on !context && !patch && (org || report)@ 449 expression x; 450 position p; 451 @@ 452 453 ERR_PTR@p(PTR_ERR(x)) 454 455 @script:python depends on org@ 456 p << r.p; 457 x << r.x; 458 @@ 459 460 msg="ERR_CAST can be used with %s" % (x) 461 msg_safe=msg.replace("[","@(").replace("]",")") 462 coccilib.org.print_todo(p[0], msg_safe) 463 </smpl> 464 465 This SmPL excerpt generates Org entries on the standard output, as 466 illustrated below: 467 468 * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] 469 * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] 470 * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]]