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