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 features and options
  10which are provided by Coccinelle version 1.0.0-rc11 and above.
  11Using earlier versions will fail as the option names used by
  12the Coccinelle files and coccicheck have been updated.
  13
  14Coccinelle is available through the package manager
  15of many distributions, e.g. :
  16
  17 - Debian
  18 - Fedora
  19 - Ubuntu
  20 - OpenSUSE
  21 - Arch Linux
  22 - NetBSD
  23 - FreeBSD
  24
  25
  26You can get the latest version released from the Coccinelle homepage at
  27http://coccinelle.lip6.fr/
  28
  29Information and tips about Coccinelle are also provided on the wiki
  30pages at http://cocci.ekstranet.diku.dk/wiki/doku.php
  31
  32Once you have it, run the following command:
  33
  34        ./configure
  35        make
  36
  37as a regular user, and install it with
  38
  39        sudo make install
  40
  41 Using Coccinelle on the Linux kernel
  42~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  43
  44A Coccinelle-specific target is defined in the top level
  45Makefile. This target is named 'coccicheck' and calls the 'coccicheck'
  46front-end in the 'scripts' directory.
  47
  48Four basic modes are defined: patch, report, context, and org. The mode to
  49use 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
  57diff-like style.Lines of interest are indicated with '-'.
  58
  59'org' generates a report in the Org mode format of Emacs.
  60
  61Note that not all semantic patches implement all modes. For easy use
  62of Coccinelle, the default mode is "report".
  63
  64Two 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
  72Examples:
  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
  82The coccicheck target applies every semantic patch available in the
  83sub-directories of 'scripts/coccinelle' to the entire Linux kernel.
  84
  85For each semantic patch, a commit message is proposed.  It gives a
  86description of the problem being checked by the semantic patch, and
  87includes a reference to Coccinelle.
  88
  89As any static code analyzer, Coccinelle produces false
  90positives. Thus, reports must be carefully checked, and patches
  91reviewed.
  92
  93To enable verbose messages set the V= variable, for example:
  94
  95   make coccicheck MODE=report V=1
  96
  97By default, coccicheck tries to run as parallel as possible. To change
  98the 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
 106The optional make variable COCCI can be used to check a single
 107semantic patch. In that case, the variable must be initialized with
 108the name of the semantic patch to apply.
 109
 110For instance:
 111
 112        make coccicheck COCCI=<my_SP.cocci> MODE=patch
 113or
 114        make coccicheck COCCI=<my_SP.cocci> MODE=report
 115
 116
 117 Controlling Which Files are Processed by Coccinelle
 118~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 119By default the entire kernel source tree is checked.
 120
 121To apply Coccinelle to a specific directory, M= can be used.
 122For example, to check drivers/net/wireless/ one may write:
 123
 124    make coccicheck M=drivers/net/wireless/
 125
 126To apply Coccinelle on a file basis, instead of a directory basis, the
 127following command may be used:
 128
 129    make C=1 CHECK="scripts/coccicheck"
 130
 131To check only newly edited code, use the value 2 for the C flag, i.e.
 132
 133    make C=2 CHECK="scripts/coccicheck"
 134
 135In these modes, which works on a file basis, there is no information
 136about semantic patches displayed, and no commit message proposed.
 137
 138This runs every semantic patch in scripts/coccinelle by default. The
 139COCCI variable may additionally be used to only apply a single
 140semantic patch as shown in the previous section.
 141
 142The "report" mode is the default. You can select another one with the
 143MODE variable explained above.
 144
 145 Additional flags
 146~~~~~~~~~~~~~~~~~~
 147
 148Additional flags can be passed to spatch through the SPFLAGS
 149variable.
 150
 151    make SPFLAGS=--use-glimpse coccicheck
 152    make SPFLAGS=--use-idutils coccicheck
 153
 154See spatch --help to learn more about spatch options.
 155
 156Note that the '--use-glimpse' and '--use-idutils' options
 157require external tools for indexing the code. None of them is
 158thus active by default. However, by indexing the code with
 159one of these tools, and according to the cocci file used,
 160spatch could proceed the entire code base more quickly.
 161
 162 Proposing new semantic patches
 163~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 164
 165New semantic patches can be proposed and submitted by kernel
 166developers. For sake of clarity, they should be organized in the
 167sub-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
 176Example:
 177
 178Running
 179
 180        make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci
 181
 182will execute the following part of the SmPL script.
 183
 184<smpl>
 185@r depends on !context && !patch && (org || report)@
 186expression x;
 187position p;
 188@@
 189
 190 ERR_PTR@p(PTR_ERR(x))
 191
 192@script:python depends on report@
 193p << r.p;
 194x << r.x;
 195@@
 196
 197msg="ERR_CAST can be used with %s" % (x)
 198coccilib.report.print_report(p[0], msg)
 199</smpl>
 200
 201This SmPL excerpt generates entries on the standard output, as
 202illustrated 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
 212When the 'patch' mode is available, it proposes a fix for each problem
 213identified.
 214
 215Example:
 216
 217Running
 218        make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci
 219
 220will execute the following part of the SmPL script.
 221
 222<smpl>
 223@ depends on !context && patch && !org && !report @
 224expression x;
 225@@
 226
 227- ERR_PTR(PTR_ERR(x))
 228+ ERR_CAST(x)
 229</smpl>
 230
 231This SmPL excerpt generates patch hunks on the standard output, as
 232illustrated below:
 233
 234diff -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
 251in a diff-like style.
 252
 253NOTE: 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
 259Example:
 260
 261Running
 262        make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci
 263
 264will execute the following part of the SmPL script.
 265
 266<smpl>
 267@ depends on context && !patch && !org && !report@
 268expression x;
 269@@
 270
 271* ERR_PTR(PTR_ERR(x))
 272</smpl>
 273
 274This SmPL excerpt generates diff hunks on the standard output, as
 275illustrated below:
 276
 277diff -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
 294Example:
 295
 296Running
 297        make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci
 298
 299will execute the following part of the SmPL script.
 300
 301<smpl>
 302@r depends on !context && !patch && (org || report)@
 303expression x;
 304position p;
 305@@
 306
 307 ERR_PTR@p(PTR_ERR(x))
 308
 309@script:python depends on org@
 310p << r.p;
 311x << r.x;
 312@@
 313
 314msg="ERR_CAST can be used with %s" % (x)
 315msg_safe=msg.replace("[","@(").replace("]",")")
 316coccilib.org.print_todo(p[0], msg_safe)
 317</smpl>
 318
 319This SmPL excerpt generates Org entries on the standard output, as
 320illustrated 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]]
 325
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.