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