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 Once you have it, run the following command:
  28
  29         ./configure
  30         make
  31
  32 as a regular user, and install it with
  33
  34         sudo make install
  35
  36
  37  Using Coccinelle on the Linux kernel
  38 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  39
  40 A Coccinelle-specific target is defined in the top level
  41 Makefile. This target is named 'coccicheck' and calls the 'coccicheck'
  42 front-end in the 'scripts' directory.
  43
  44 Four modes are defined: report, patch, context, and org. The mode to
  45 use is specified by setting the MODE variable with 'MODE=<mode>'.
  46
  47 'report' generates a list in the following format:
  48   file:line:column-column: message
  49
  50 'patch' proposes a fix, when possible.
  51
  52 'context' highlights lines of interest and their context in a
  53 diff-like style.Lines of interest are indicated with '-'.
  54
  55 'org' generates a report in the Org mode format of Emacs.
  56
  57 Note that not all semantic patches implement all modes.
  58
  59 To make a report for every semantic patch, run the following command:
  60
  61         make coccicheck MODE=report
  62
  63 NB: The 'report' mode is the default one.
  64
  65 To produce patches, run:
  66
  67         make coccicheck MODE=patch
  68
  69
  70 The coccicheck target applies every semantic patch available in the
  71 subdirectories of 'scripts/coccinelle' to the entire Linux kernel.
  72
  73 For each semantic patch, a changelog message is proposed.  It gives a
  74 description of the problem being checked by the semantic patch, and
  75 includes a reference to Coccinelle.
  76
  77 As any static code analyzer, Coccinelle produces false
  78 positives. Thus, reports must be carefully checked, and patches
  79 reviewed.
  80
  81
  82  Using Coccinelle with a single semantic patch
  83 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  84
  85 The optional make variable COCCI can be used to check a single
  86 semantic patch. In that case, the variable must be initialized with
  87 the name of the semantic patch to apply.
  88
  89 For instance:
  90
  91         make coccicheck COCCI=<my_SP.cocci> MODE=patch
  92 or
  93         make coccicheck COCCI=<my_SP.cocci> MODE=report
  94
  95
  96  Proposing new semantic patches
  97 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  98
  99 New semantic patches can be proposed and submitted by kernel
 100 developers. For sake of clarity, they should be organized in the
 101 subdirectories of 'scripts/coccinelle/'.
 102
 103
 104  Detailed description of the 'report' mode
 105 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 106
 107 'report' generates a list in the following format:
 108   file:line:column-column: message
 109
 110 Example:
 111
 112 Running
 113
 114         make coccicheck MODE=report COCCI=scripts/coccinelle/err_cast.cocci
 115
 116 will execute the following part of the SmPL script.
 117
 118 <smpl>
 119 @r depends on !context && !patch && (org || report)@
 120 expression x;
 121 position p;
 122 @@
 123
 124  ERR_PTR@p(PTR_ERR(x))
 125
 126 @script:python depends on report@
 127 p << r.p;
 128 x << r.x;
 129 @@
 130
 131 msg="ERR_CAST can be used with %s" % (x)
 132 coccilib.report.print_report(p[0], msg)
 133 </smpl>
 134
 135 This SmPL excerpt generates entries on the standard output, as
 136 illustrated below:
 137
 138 /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg
 139 /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth
 140 /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg
 141
 142
 143  Detailed description of the 'patch' mode
 144 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 145
 146 When the 'patch' mode is available, it proposes a fix for each problem
 147 identified.
 148
 149 Example:
 150
 151 Running
 152         make coccicheck MODE=patch COCCI=scripts/coccinelle/err_cast.cocci
 153
 154 will execute the following part of the SmPL script.
 155
 156 <smpl>
 157 @ depends on !context && patch && !org && !report @
 158 expression x;
 159 @@
 160
 161 - ERR_PTR(PTR_ERR(x))
 162 + ERR_CAST(x)
 163 </smpl>
 164
 165 This SmPL excerpt generates patch hunks on the standard output, as
 166 illustrated below:
 167
 168 diff -u -p a/crypto/ctr.c b/crypto/ctr.c
 169 --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200
 170 +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200
 171 @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct
 172         alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,
 173                                   CRYPTO_ALG_TYPE_MASK);
 174         if (IS_ERR(alg))
 175 -               return ERR_PTR(PTR_ERR(alg));
 176 +               return ERR_CAST(alg);
 177
 178         /* Block size must be >= 4 bytes. */
 179         err = -EINVAL;
 180
 181  Detailed description of the 'context' mode
 182 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 183
 184 'context' highlights lines of interest and their context
 185 in a diff-like style.
 186
 187 NOTE: The diff-like output generated is NOT an applicable patch. The
 188       intent of the 'context' mode is to highlight the important lines
 189       (annotated with minus, '-') and gives some surrounding context
 190       lines around. This output can be used with the diff mode of
 191       Emacs to review the code.
 192
 193 Example:
 194
 195 Running
 196         make coccicheck MODE=context COCCI=scripts/coccinelle/err_cast.cocci
 197
 198 will execute the following part of the SmPL script.
 199
 200 <smpl>
 201 @ depends on context && !patch && !org && !report@
 202 expression x;
 203 @@
 204
 205 * ERR_PTR(PTR_ERR(x))
 206 </smpl>
 207
 208 This SmPL excerpt generates diff hunks on the standard output, as
 209 illustrated below:
 210
 211 diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing
 212 --- /home/user/linux/crypto/ctr.c       2010-05-26 10:49:38.000000000 +0200
 213 +++ /tmp/nothing
 214 @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct
 215         alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,
 216                                   CRYPTO_ALG_TYPE_MASK);
 217         if (IS_ERR(alg))
 218 -               return ERR_PTR(PTR_ERR(alg));
 219
 220         /* Block size must be >= 4 bytes. */
 221         err = -EINVAL;
 222
 223  Detailed description of the 'org' mode
 224 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 225
 226 'org' generates a report in the Org mode format of Emacs.
 227
 228 Example:
 229
 230 Running
 231         make coccicheck MODE=org COCCI=scripts/coccinelle/err_cast.cocci
 232
 233 will execute the following part of the SmPL script.
 234
 235 <smpl>
 236 @r depends on !context && !patch && (org || report)@
 237 expression x;
 238 position p;
 239 @@
 240
 241  ERR_PTR@p(PTR_ERR(x))
 242
 243 @script:python depends on org@
 244 p << r.p;
 245 x << r.x;
 246 @@
 247
 248 msg="ERR_CAST can be used with %s" % (x)
 249 msg_safe=msg.replace("[","@(").replace("]",")")
 250 coccilib.org.print_todo(p[0], msg_safe)
 251 </smpl>
 252
 253 This SmPL excerpt generates Org entries on the standard output, as
 254 illustrated below:
 255
 256 * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]]
 257 * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]]
 258 * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]]