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