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