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.
 150
 151     make SPFLAGS=--use-glimpse coccicheck
 152     make SPFLAGS=--use-idutils coccicheck
 153
 154 See spatch --help to learn more about spatch options.
 155
 156 Note that the '--use-glimpse' and '--use-idutils' options
 157 require external tools for indexing the code. None of them is
 158 thus active by default. However, by indexing the code with
 159 one of these tools, and according to the cocci file used,
 160 spatch could proceed the entire code base more quickly.
 161
 162  Proposing new semantic patches
 163 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 164
 165 New semantic patches can be proposed and submitted by kernel
 166 developers. For sake of clarity, they should be organized in the
 167 sub-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
 176 Example:
 177
 178 Running
 179
 180         make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci
 181
 182 will execute the following part of the SmPL script.
 183
 184 <smpl>
 185 @r depends on !context && !patch && (org || report)@
 186 expression x;
 187 position p;
 188 @@
 189
 190  ERR_PTR@p(PTR_ERR(x))
 191
 192 @script:python depends on report@
 193 p << r.p;
 194 x << r.x;
 195 @@
 196
 197 msg="ERR_CAST can be used with %s" % (x)
 198 coccilib.report.print_report(p[0], msg)
 199 </smpl>
 200
 201 This SmPL excerpt generates entries on the standard output, as
 202 illustrated 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
 212 When the 'patch' mode is available, it proposes a fix for each problem
 213 identified.
 214
 215 Example:
 216
 217 Running
 218         make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci
 219
 220 will execute the following part of the SmPL script.
 221
 222 <smpl>
 223 @ depends on !context && patch && !org && !report @
 224 expression x;
 225 @@
 226
 227 - ERR_PTR(PTR_ERR(x))
 228 + ERR_CAST(x)
 229 </smpl>
 230
 231 This SmPL excerpt generates patch hunks on the standard output, as
 232 illustrated below:
 233
 234 diff -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
 251 in a diff-like style.
 252
 253 NOTE: 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
 259 Example:
 260
 261 Running
 262         make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci
 263
 264 will execute the following part of the SmPL script.
 265
 266 <smpl>
 267 @ depends on context && !patch && !org && !report@
 268 expression x;
 269 @@
 270
 271 * ERR_PTR(PTR_ERR(x))
 272 </smpl>
 273
 274 This SmPL excerpt generates diff hunks on the standard output, as
 275 illustrated below:
 276
 277 diff -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
 294 Example:
 295
 296 Running
 297         make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci
 298
 299 will execute the following part of the SmPL script.
 300
 301 <smpl>
 302 @r depends on !context && !patch && (org || report)@
 303 expression x;
 304 position p;
 305 @@
 306
 307  ERR_PTR@p(PTR_ERR(x))
 308
 309 @script:python depends on org@
 310 p << r.p;
 311 x << r.x;
 312 @@
 313
 314 msg="ERR_CAST can be used with %s" % (x)
 315 msg_safe=msg.replace("[","@(").replace("]",")")
 316 coccilib.org.print_todo(p[0], msg_safe)
 317 </smpl>
 318
 319 This SmPL excerpt generates Org entries on the standard output, as
 320 illustrated 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]]