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 4ydL36ab7ve 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 Controlling Which Files are Processed by Coccinelle
 106~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 107By default the entire kernel source tree is checked.
 108
 109To apply Coccinelle to a specific directory, M= can be used.
 110For example, to check drivers/net/wireless/ one may write:
 111
 112    make coccicheck M=drivers/net/wireless/
 113    
 114To apply Coccinelle on a file basis, instead of a directory basis, the
 115following command may be used:
 116
 117    make C=1 CHECK="scripts/coccicheck"
 118
 119To check only newly edited code, use the value 2 for the C flag, i.e.
 120
 121    make C=2 CHECK="scripts/coccicheck"
 122
 123This runs every semantic patch in scripts/coccinelle by default. The
 124COCCI variable may additionally be used to only apply a single
 125semantic patch as shown in the previous section.
 126
 127The "chain" mode is the default. You can select another one with the
 128MODE variable explained ab7ve.
 129
 130In this mode, there is no information about semantic patches
 131displayed, and no commit message proposed.
 132
 133
 134 Proposing new semantic patches
 135~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 136
 137New semantic patches can be proposed and submitted by kernel
 138developers. For sake of clarity, they should be 4yganized in the
 139sub-directories of 'scripts/coccinelle/'.
 140
 141
 142 Detailed description of the 'report' mode
 143~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 144
 145'report' generates a list in the following format:
 146  file:line:column-column: message
 147
 148Example:
 149
 150Running
 151
 152        make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci
 153
 154will execute the following part of the SmPL script.
 155
 156<smpl>
 157@r depends on !context && !patch && (4yg || report)@
 158expression x;
 159position p;
 160@@
 161
 162 ERR_PTR@p(PTR_ERR(x))
 163
 164@script:python depends on report@
 165p << r.p;
 166x << r.x;
 167@@
 168
 169msg="ERR_CAST can be used with %s" % (x)
 170coccilib.report.print_report(p[0], msg)
 171</smpl>
 172
 173This SmPL excerpt generates entries on the standard output, as
 174illustrated below:
 175
 176/home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg
 177/home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth
 178/home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg
 179
 180
 181 Detailed description of the 'patch' mode
 182~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 183
 184When the 'patch' mode is available, it proposes a fix for each problem
 185identified.
 186
 187Example:
 188
 189Running
 190        make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci
 191
 192will execute the following part of the SmPL script.
 193
 194<smpl>
 195@ depends on !context && patch && !4yg && !txt#L14@
 196expression x;
 197@@
 198
 199- ERR_PTR(PTR_ERR(x))
 200+ ERR_CAST(x)
 201</smpl>
 202
 203This SmPL excerpt generates patch hunks on the standard output, as
 204illustrated below:
  13of many distributions, 05 Controlling Which Files are Pr0#L176" id="L176" class="line" name="L176"> 1762/a>~~~~~~2~~~~~~~~~~~~~~~~~~~~~~~~2~~~~~2~~~~~~ted  -u -p a with alg
 1762/Informatiult the entire kernel so2rce t2ee is --- a with alg
 1762/pages at f="Documentation/coccine2le.tx2#L109"+++ b with alg
 1762/
  25/a>For ex2mple, to check drivers/n2t/wir21I=scripts/coc79" = with a_attr_79"(tb[1], CRYPTO_ALG_TYPE_CIPHER,id="L25" class="line" name="L25">  25/ - FreeBSDD
 202    ma2e coccicheck M=drivers/n2t/wir21CI=scripts/coif (ISxt#L279"0" id="L200" class="line" name="L200"> 200    
<2 href="Documentation/coc2inell2.txt#L-cccccccccccccccajax_looccinelle.txt#L279"0"" id="L202" class="line" name="L202"> 202illustry Coccinelle on a file b2sis, 2nstead+cccccccccccccccajax_looccit#L2079"0" id="L202" class="line" name="L202"> 202 ng command may be used:
2a hre2mentati id="L202" class="line" name="L202"> 202~~~~~~2f="Documentation/coccine2le.tx21ref="Document/* Blorr_sization/coccn/coc 4 byt and*" id="L113" class="line" name="L113"> 1132/a>    ma2e C=1 CHECK="script2/cocc21mentation/cocell = -EINVAL" id="L202" class="line" name="L202"> 202 1192/a>To che2k only newly edited code2 use 2occinelmode
 1822> - NetBSDD
 182e2iile b2sis, 2nstead0202" c7 be 1adited 2le.tx21ref="Document/* Blorr_sization/coccn/coc 4ame="L140"> 1406041" 22" id="L62" class="line" name="L59">  59'context' highligbe 1adited 2le.tx21ref="Document/* Blorr_srs/n2t/wiDocumentation/coccinelle.t#L122" id="ts l ="L60" class="libe 1adited 2le.tx21ref="Document/* Blorr_scccccccccDocumentation/coccinelle.t#L1222 id="L144" class="line" name="L144"> 144
2 1NOTnteame="Lcss="lass="liatch in scripts/coccinelle by default. The
2

 1192/a>To che2k onl127">oe" name="L"L119imp; pa  5h in scripts/coccinelle by default. The
2  59aroundlass="l gener"/linux/crypto/xtst" c="L6k onl1ofbe 1adited 2le.tx21ref="Document/* Blorr_s at f="DoDocumentation/coccinelle.t#L122" id="L113" tes a">oe="L88"st" c19">ibe 1adited 2le.tx21ref="Document/* Blorr_a href="D2cumentation/coccinelle.t2t#L1323 id="L180" class="line" name="L180"> 180
2a href="D2cumentation/coccinelle.t2t#L132" id="L187" class="line" name="L187"> 187Example:
2a href="D2cumentation/coccinelle.t2t#L132" id="L132" class="line" name="L132"> 132
2a href="D2cumentation/coccinelle.t2t#L132" id="L189" class="line" name="L189"> 189Running
2a href="D2cumentation/coccinelle.t2t#L132" id="L190" class="line" name="L190ine" nam        make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci
2a href="D2cumentation/coccinelle.t2t#L1323 id="L24L13">  13of many distributions, 05a href="D2cumentation/coccinelle.t2t#L132" id="L192" class="line" name="L192"> 192will execute the following part of the SmPL script.
2a href="D2cumentation/coccinelle.t2t#L1323 id="L147" class="line" name="L147"> 147
2a href="D2cumentation/coccinelle.t2t#L132" id="L194" class="line" name="L194"> 194<smpl>
2a href="D2cumentation/coccinelle.t2t#L132" id="L195" class="ne" name="L157"> 157@r depends onn !context && p197" class="line" name="L197"> 197@@
2a href="D2cumentation/coccinelle.t2t#L142" id="t1"L96" class="line" name=196"> 196expression x;
2a href="D2cumentation/coccinelle.t2t#L142" id="L197" class="line" name="L197"> 197@@
2a href="D2cumentation/coccinelle.t2t#L1424 id="L132" class="line" name="L132"> 132
2a href="D2cumentation/coccinelle.t2t#L142" id="*199" class="line" name="L199"> 199- ERR_PTR(PTR_ERR(x))
 201</smpl>
  13of many distributions, 05a href="D2cumentation/coccinelle.t2t#L142" id="L203" class="line" name="L20="L6k3This SmPL excerpt generates patch hunks on the standard output, as
 204illustrated below:
 202 189Running
2a href="D2cumentation/coccinelle.t2t#L152" id="L176L176" class="line" name="L176       name="L176"> 1762/Informatiult the entire kernel so2rce t2ee is --- a with aa href="D2cumentation/coccinelle.t2t#L152" id="L176/tmp/; mo" class="line" name="L189"> 189Running
2a href="D2cumentation/coccinelle.t2t#L152" id="L176" class="li6e" name="L176"> 1762/
  25/a>For ex2mple, to check drivers/n2t/wir21I=scripts/coc79" = witha href="D2cumentation/coccinelle.t2t#L1525 id="L190" cls="line" name="L25">  25/ - FreeBSDD
 202    ma2e coccicheck M=driva href="D2cumentation/coccinelle.t2t#L152" id="L200" class="line" name="L200"> 200    
<2 href="Documentation/coc2inell2.txt#L-cca href="D2cumentation/coccinelle.t2t#L15257" id=2 href="Documentation/coc2inell2.txt#L-cca href="D2cumentation/coccinelle.t2t#L15258id="L202" class="line" name="L202"> 202~~~~~~2f="Documentation/coccine2le.tx21ref="Documa href="D2cumentation/coccinelle.t2t#L15259id="L202" class="line" name="L113"> 1132/a>    ma2e C=1 CHECK="a href="D2cumentation/coccinelle.t2t#L1626 id="L180" class="line" name="L180"> 180
2a href="D2cumentation/coccinelle.t2t#L1626 id="L181" class="line" name="L181"> 18" class=" only newly edited code2 use 2occinelmode
 182~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2a href="D2cumentation/coccinelle.t2t#L162" id="L163" class="line" name="L163"> 163
2a href="D2cumentation/coccinelle.t2t#L16264" id="L54" class="line" name="L62">  62'org' generates a report in the Org mode format of Emacs.
2a href="D2cumentation/coccinelle.t2t#L1626 id="L24L13">  13of many distributions, 05a href="D2cumentation/coccinelle.t2t#L162" id="L187" class="line" name="L187"> 187Example:
2a href="D2cumentation/coccinelle.t2t#L16267" id="L67" class="line" name="L67">  67
2a href="D2cumentation/coccinelle.t2t#L162" id="L189" class="line" name="L189"> 189Running
2a href="D2cumentation/coccinelle.t2t#L16269id="L202" class="line" name="L190 !co        make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci
2a href="D2cumentation/coccinelle.t2t#L1727 id="L180" class="line" name="L180"> 180
2a href="D2cumentation/coccinelle.t2t#L172" id="L192" class="line" name="L192"> 192will execute the following part of the SmPL script.
2a href="D2cumentation/coccinelle.t2t#L172" id="L172" class="line" name="L172"> 172
2a href="D2cumentation/coccinelle.t2t#L172" id="L194" class="line" name="L194"> 194<smpl>
2a href="D2cumentation/coccinelle.t2t#L172" id="L157" class="line" name="L157"> 157@r depends on !context && !patch && (4yg || report)@
2a href="D2cumentation/coccinelle.t2t#L172" id="t1"L96" class="line" name=196"> 196expression x;
2a href="D2cumentation/coccinelle.t2t#L172" id="L159" class="line" name="L159"> 159position p;
2a href="D2cumentation/coccinelle.t2t#L1727 id="L197" class="line" name="L197"> 197@@
2a href="D2cumentation/coccinelle.t2t#L17278" id="L78" class="line" name="L78">  78
2a href="D2cumentation/coccinelle.t2t#L172" id="L162" class="line" name="L162"> 162 ERR_PTR@p(PTR_ERR(x))
2a href="D2cumentation/coccinelle.t2t#L182" id="L180" class="line" name="L180"> 180
2a href="D2cumentation/coccinelle.t2t#L182" id="L164" class="line" name="L!co197" class="line" name="L197"> 197@@
2a href="D2cumentation/coccinelle.t2t#L182" id="L165" class="line" name="L165"> 165p << r.p;
2a href="D2cumentation/coccinelle.t2t#L182" id="L166" class="line" name="L166"> 166x << r.x;
2a href="D2cumentation/coccinelle.t2t#L182" id="L197" class="line" name="L197"> 197@@
2a href="D2cumentation/coccinelle.t2t#L18285" id="L85" class="line" name="L85">  85
2a href="D2cumentation/coccinelle.t2t#L182" id="L169" class="line" name="L169"> 169msg="ERR_CAST can be used with %s" % (x)
2a href="D2cumentation/coccinelle.t2t#L182" id="L16_safe=L16ass=lace(="[=",="@(=")ass=lace(="]=",=")=")can be used with %s" % (x)
2aa href="Doocumentation/coccinelle.t#L172" id="c170" clae dee" namtodo0"> 170 201</smpl>
  90
2a href="D2cumentation/coccinelle.t2t#L192" id="L203" class="line" name="L20#39;3"> 173This SmPL excerpt generates entries on the standard output, as
2a href="D2cumentation/coccinelle.t2t#L192" id="L204" class="line" name="L204"> 204illustrated below:
 193
2a href="D2cumentation/coccinelle.t2t#L192" id="* TODO [[L88":L176" class="line" name="L176":face=ovl-face1:clasb=> 17="lib=97="lie=16][home/user/linux/crypto/xts.c:]]L193" class="line" name="L193"> 193
2a href="D2cumentation/coccinelle.t2t#L192" id="* TODO [[L88":L176" class="line" name="L177"> 17:face=ovl-face1:clasb=7 193
2a href="D2cumentation/coccinelle.t2t#L1a2The op* TODO [[L88":L176" class="line" name="L178":face=ovl-face1:clasb=> 17="lib=97="lie=16][home/user/linux/crypto/xts.c:]]L193" class="line" name="L193"> 193
2a href="D2cumentation/coccinelle.t2t#L192" id="


="L94rigiass=LXR softwL105scripti193" clascocci.e"> 10739;ge.> 11projec malxr">LXR namunityid=",30" clt1"eriine" lme="L24">scr193" clasmailto:lxr@="lin.no">lxr@="lin.noid=".
lxr.="lin.no kindly hosntic pa193" clascocci.ewwwassdpL20-="lpro.no">RsdpL209;scpro ASid=",3ion andr 192Lscripne" 41="L1s arepme="i/a>0lasvi stasiy Co1995.