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