Documentation/coccinelle.txt

   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]]