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
  90
  91 Using Coccinelle with a single semantic patch
  92~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  93
  94The optional make variable COCCI can be used to check a single
  95semantic patch. In that case, the variable must be initialized with
  96the name of the semantic patch to apply.
  97
  98For instance:
  99
 100        make coccicheck COCCI=<my_SP.cocci> MODE=patch
 101or
 102        make coccicheck COCCI=<my_SP.cocci> MODE=report
 103
 104
 105 Using Coccinelle on (modified) files
 106~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 107
 108To apply Coccinelle on a file basis, instead of a directory basis, the
 109following command may be used:
 110
 111    make C=1 CHECK="scripts/coccicheck"
 112
 113To check only newly edited code, use the value 2 for the C flag, i.e.
 114
 115    make C=2 CHECK="scripts/coccicheck"
 116
 117This runs every semantic patch in scripts/coccinelle by default. The
 118COCCI variable may additionally be used to only apply a single
 119semantic patch as shown in the previous section.
 120
 121The "chain" mode is the default. You can select another one with the
 122MODE variable explained above.
 123
 124In this mode, there is no information about semantic patches
 125displayed, and no commit message proposed.
 126
 127
 128 Proposing new semantic patches
 129~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 130
 131New semantic patches can be proposed and submitted by kernel
 132developers. For sake of clarity, they should be organized in the
 133sub-directories of 'scripts/coccinelle/'.
 134
 135
 136 Detailed description of the 'report' mode
 137~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 138
 139'report' generates a list in the following format:
 140  file:line:column-column: message
 141
 142Example:
 143
 144Running
 145
 146        make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci
 147
 148will execute the following part of the SmPL script.
 149
 150<smpl>
 151@r depends on !context && !patch && (org || report)@
 152expression x;
 153position p;
 154@@
 155
 156 ERR_PTR@p(PTR_ERR(x))
 157
 158@script:python depends on report@
 159p << r.p;
 160x << r.x;
 161@@
 162
 163msg="ERR_CAST can be used with %s" % (x)
 164coccilib.report.print_report(p[0], msg)
 165</smpl>
 166
 167This SmPL excerpt generates entries on the standard output, as
 168illustrated below:
 169
 170/home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg
 171/home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth
 172/home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg
 173
 174
 175 Detailed description of the 'patch' mode
 176~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 177
 178When the 'patch' mode is available, it proposes a fix for each problem
 179identified.
 180
 181Example:
 182
 183Running
 184        make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci
 185
 186will execute the following part of the SmPL script.
 187
 188<smpl>
 189@ depends on !context && patch && !org && !report @
 190expression x;
 191@@
 192
 193- ERR_PTR(PTR_ERR(x))
 194+ ERR_CAST(x)
 195</smpl>
 196
 197This SmPL excerpt generates patch hunks on the standard output, as
 198illustrated below:
 199
 200diff -u -p a/crypto/ctr.c b/crypto/ctr.c
 201--- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200
 202+++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200
 203@@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct
 204        alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,
 205                                  CRYPTO_ALG_TYPE_MASK);
 206        if (IS_ERR(alg))
 207-               return ERR_PTR(PTR_ERR(alg));
 208+               return ERR_CAST(alg);
 209 
 210        /* Block size must be >= 4 bytes. */
 211        err = -EINVAL;
 212
 213 Detailed description of the 'context' mode
 214~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 215
 216'context' highlights lines of interest and their context
 217in a diff-like style.
 218
 219NOTE: The diff-like output generated is NOT an applicable patch. The
 220      intent of the 'context' mode is to highlight the important lines
 221      (annotated with minus, '-') and gives some surrounding context
 222      lines around. This output can be used with the diff mode of
 223      Emacs to review the code.
 224
 225Example:
 226
 227Running
 228        make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci
 229
 230will execute the following part of the SmPL script.
 231
 232<smpl>
 233@ depends on context && !patch && !org && !report@
 234expression x;
 235@@
 236
 237* ERR_PTR(PTR_ERR(x))
 238</smpl>
 239
 240This SmPL excerpt generates diff hunks on the standard output, as
 241illustrated below:
 242
 243diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing
 244--- /home/user/linux/crypto/ctr.c       2010-05-26 10:49:38.000000000 +0200
 245+++ /tmp/nothing
 246@@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct
 247        alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,
 248                                  CRYPTO_ALG_TYPE_MASK);
 249        if (IS_ERR(alg))
 250-               return ERR_PTR(PTR_ERR(alg));
 251 
 252        /* Block size must be >= 4 bytes. */
 253        err = -EINVAL;
 254
 255 Detailed description of the 'org' mode
 256~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 257
 258'org' generates a report in the Org mode format of Emacs.
 259
 260Example:
 261
 262Running
 263        make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci
 264
 265will execute the following part of the SmPL script.
 266
 267<smpl>
 268@r depends on !context && !patch && (org || report)@
 269expression x;
 270position p;
 271@@
 272
 273 ERR_PTR@p(PTR_ERR(x))
 274
 275@script:python depends on org@
 276p << r.p;
 277x << r.x;
 278@@
 279
 280msg="ERR_CAST can be used with %s" % (x)
 281msg_safe=msg.replace("[","@(").replace("]",")")
 282coccilib.org.print_todo(p[0], msg_safe)
 283</smpl>
 284
 285This SmPL excerpt generates Org entries on the standard output, as
 286illustrated below:
 287
 288* TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]]
 289* TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]]
 290* TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]]
 291
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.