Commit | Line | Data |
---|---|---|
4b9033a3 JC |
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> | |
e228b1e6 | 4 | |
4b9033a3 | 5 | .. highlight:: none |
e228b1e6 | 6 | |
f77af637 FV |
7 | .. _devtools_coccinelle: |
8 | ||
4b9033a3 JC |
9 | Coccinelle |
10 | ========== | |
11 | ||
12 | Coccinelle is a tool for pattern matching and text transformation that has | |
13 | many uses in kernel development, including the application of complex, | |
14 | tree-wide patches and detection of problematic programming patterns. | |
15 | ||
16 | Getting Coccinelle | |
cc8246de | 17 | ------------------ |
e228b1e6 | 18 | |
ec97946e NP |
19 | The semantic patches included in the kernel use features and options |
20 | which are provided by Coccinelle version 1.0.0-rc11 and above. | |
21 | Using earlier versions will fail as the option names used by | |
22 | the Coccinelle files and coccicheck have been updated. | |
e228b1e6 | 23 | |
ec97946e | 24 | Coccinelle is available through the package manager |
e228b1e6 NP |
25 | of many distributions, e.g. : |
26 | ||
ec97946e NP |
27 | - Debian |
28 | - Fedora | |
29 | - Ubuntu | |
e228b1e6 NP |
30 | - OpenSUSE |
31 | - Arch Linux | |
32 | - NetBSD | |
33 | - FreeBSD | |
34 | ||
9eff4a2e HJ |
35 | Some distribution packages are obsolete and it is recommended |
36 | to use the latest version released from the Coccinelle homepage at | |
e228b1e6 NP |
37 | http://coccinelle.lip6.fr/ |
38 | ||
9eff4a2e | 39 | Or from Github at: |
e228b1e6 | 40 | |
9eff4a2e HJ |
41 | https://github.com/coccinelle/coccinelle |
42 | ||
43 | Once you have it, run the following commands:: | |
44 | ||
45 | ./autogen | |
46 | ./configure | |
e228b1e6 NP |
47 | make |
48 | ||
4b9033a3 | 49 | as a regular user, and install it with:: |
e228b1e6 NP |
50 | |
51 | sudo make install | |
52 | ||
9eff4a2e HJ |
53 | More detailed installation instructions to build from source can be |
54 | found at: | |
55 | ||
56 | https://github.com/coccinelle/coccinelle/blob/master/install.txt | |
57 | ||
4b9033a3 | 58 | Supplemental documentation |
cc8246de | 59 | -------------------------- |
c100d537 LR |
60 | |
61 | For supplemental documentation refer to the wiki: | |
62 | ||
63 | https://bottest.wiki.kernel.org/coccicheck | |
64 | ||
65 | The wiki documentation always refers to the linux-next version of the script. | |
66 | ||
9eff4a2e HJ |
67 | For Semantic Patch Language(SmPL) grammar documentation refer to: |
68 | ||
87444fdc | 69 | https://coccinelle.gitlabpages.inria.fr/website/docs/main_grammar.html |
9eff4a2e | 70 | |
4b9033a3 JC |
71 | Using Coccinelle on the Linux kernel |
72 | ------------------------------------ | |
e228b1e6 NP |
73 | |
74 | A Coccinelle-specific target is defined in the top level | |
4b9033a3 JC |
75 | Makefile. This target is named ``coccicheck`` and calls the ``coccicheck`` |
76 | front-end in the ``scripts`` directory. | |
e228b1e6 | 77 | |
4b9033a3 JC |
78 | Four basic modes are defined: ``patch``, ``report``, ``context``, and |
79 | ``org``. The mode to use is specified by setting the MODE variable with | |
80 | ``MODE=<mode>``. | |
e228b1e6 | 81 | |
4b9033a3 | 82 | - ``patch`` proposes a fix, when possible. |
32af0898 | 83 | |
4b9033a3 | 84 | - ``report`` generates a list in the following format: |
e228b1e6 NP |
85 | file:line:column-column: message |
86 | ||
4b9033a3 | 87 | - ``context`` highlights lines of interest and their context in a |
7d087d02 | 88 | diff-like style. Lines of interest are indicated with ``-``. |
e228b1e6 | 89 | |
4b9033a3 | 90 | - ``org`` generates a report in the Org mode format of Emacs. |
e228b1e6 | 91 | |
32af0898 | 92 | Note that not all semantic patches implement all modes. For easy use |
78a95b9b | 93 | of Coccinelle, the default mode is "report". |
e228b1e6 | 94 | |
78a95b9b | 95 | Two other modes provide some common combinations of these modes. |
e228b1e6 | 96 | |
4b9033a3 JC |
97 | - ``chain`` tries the previous modes in the order above until one succeeds. |
98 | ||
99 | - ``rep+ctxt`` runs successively the report mode and the context mode. | |
100 | It should be used with the C option (described later) | |
101 | which checks the code on a file basis. | |
e228b1e6 | 102 | |
4b9033a3 JC |
103 | Examples |
104 | ~~~~~~~~ | |
e228b1e6 | 105 | |
4b9033a3 | 106 | To make a report for every semantic patch, run the following command:: |
e228b1e6 | 107 | |
78a95b9b NP |
108 | make coccicheck MODE=report |
109 | ||
4b9033a3 | 110 | To produce patches, run:: |
78a95b9b NP |
111 | |
112 | make coccicheck MODE=patch | |
e228b1e6 NP |
113 | |
114 | ||
115 | The coccicheck target applies every semantic patch available in the | |
4b9033a3 | 116 | sub-directories of ``scripts/coccinelle`` to the entire Linux kernel. |
e228b1e6 | 117 | |
32af0898 | 118 | For each semantic patch, a commit message is proposed. It gives a |
e228b1e6 NP |
119 | description of the problem being checked by the semantic patch, and |
120 | includes a reference to Coccinelle. | |
121 | ||
7d087d02 | 122 | As with any static code analyzer, Coccinelle produces false |
e228b1e6 NP |
123 | positives. Thus, reports must be carefully checked, and patches |
124 | reviewed. | |
125 | ||
4b9033a3 | 126 | To enable verbose messages set the V= variable, for example:: |
26e56720 BS |
127 | |
128 | make coccicheck MODE=report V=1 | |
129 | ||
4b9033a3 | 130 | Coccinelle parallelization |
cc8246de | 131 | -------------------------- |
c930a1b2 | 132 | |
90d06a46 | 133 | By default, coccicheck tries to run as parallel as possible. To change |
4b9033a3 | 134 | the parallelism, set the J= variable. For example, to run across 4 CPUs:: |
90d06a46 KC |
135 | |
136 | make coccicheck MODE=report J=4 | |
137 | ||
7d087d02 | 138 | As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization; |
c930a1b2 LR |
139 | if support for this is detected you will benefit from parmap parallelization. |
140 | ||
141 | When parmap is enabled coccicheck will enable dynamic load balancing by using | |
7d087d02 | 142 | ``--chunksize 1`` argument. This ensures we keep feeding threads with work |
c930a1b2 LR |
143 | one by one, so that we avoid the situation where most work gets done by only |
144 | a few threads. With dynamic load balancing, if a thread finishes early we keep | |
145 | feeding it more work. | |
146 | ||
147 | When parmap is enabled, if an error occurs in Coccinelle, this error | |
7d087d02 RD |
148 | value is propagated back, and the return value of the ``make coccicheck`` |
149 | command captures this return value. | |
e228b1e6 | 150 | |
4b9033a3 JC |
151 | Using Coccinelle with a single semantic patch |
152 | --------------------------------------------- | |
e228b1e6 NP |
153 | |
154 | The optional make variable COCCI can be used to check a single | |
155 | semantic patch. In that case, the variable must be initialized with | |
156 | the name of the semantic patch to apply. | |
157 | ||
4b9033a3 | 158 | For instance:: |
e228b1e6 NP |
159 | |
160 | make coccicheck COCCI=<my_SP.cocci> MODE=patch | |
4b9033a3 JC |
161 | |
162 | or:: | |
163 | ||
e228b1e6 NP |
164 | make coccicheck COCCI=<my_SP.cocci> MODE=report |
165 | ||
166 | ||
4b9033a3 JC |
167 | Controlling Which Files are Processed by Coccinelle |
168 | --------------------------------------------------- | |
169 | ||
f95ab209 GD |
170 | By default the entire kernel source tree is checked. |
171 | ||
4b9033a3 JC |
172 | To apply Coccinelle to a specific directory, ``M=`` can be used. |
173 | For example, to check drivers/net/wireless/ one may write:: | |
32af0898 | 174 | |
f95ab209 | 175 | make coccicheck M=drivers/net/wireless/ |
ed621cc4 | 176 | |
32af0898 | 177 | To apply Coccinelle on a file basis, instead of a directory basis, the |
a5019c7f SP |
178 | C variable is used by the makefile to select which files to work with. |
179 | This variable can be used to run scripts for the entire kernel, a | |
180 | specific directory, or for a single file. | |
32af0898 | 181 | |
a5019c7f SP |
182 | For example, to check drivers/bluetooth/bfusb.c, the value 1 is |
183 | passed to the C variable to check files that make considers | |
184 | need to be compiled.:: | |
32af0898 | 185 | |
a5019c7f | 186 | make C=1 CHECK=scripts/coccicheck drivers/bluetooth/bfusb.o |
32af0898 | 187 | |
a5019c7f SP |
188 | The value 2 is passed to the C variable to check files regardless of |
189 | whether they need to be compiled or not.:: | |
190 | ||
191 | make C=2 CHECK=scripts/coccicheck drivers/bluetooth/bfusb.o | |
32af0898 | 192 | |
7d087d02 | 193 | In these modes, which work on a file basis, there is no information |
78a95b9b NP |
194 | about semantic patches displayed, and no commit message proposed. |
195 | ||
32af0898 NP |
196 | This runs every semantic patch in scripts/coccinelle by default. The |
197 | COCCI variable may additionally be used to only apply a single | |
198 | semantic patch as shown in the previous section. | |
199 | ||
78a95b9b | 200 | The "report" mode is the default. You can select another one with the |
32af0898 NP |
201 | MODE variable explained above. |
202 | ||
4b9033a3 JC |
203 | Debugging Coccinelle SmPL patches |
204 | --------------------------------- | |
be1fa900 LR |
205 | |
206 | Using coccicheck is best as it provides in the spatch command line | |
207 | include options matching the options used when we compile the kernel. | |
7d087d02 | 208 | You can learn what these options are by using V=1; you could then |
be1fa900 LR |
209 | manually run Coccinelle with debug options added. |
210 | ||
211 | Alternatively you can debug running Coccinelle against SmPL patches | |
7d087d02 RD |
212 | by asking for stderr to be redirected to stderr. By default stderr |
213 | is redirected to /dev/null; if you'd like to capture stderr you | |
4b9033a3 JC |
214 | can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For |
215 | instance:: | |
be1fa900 LR |
216 | |
217 | rm -f cocci.err | |
218 | make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err | |
219 | cat cocci.err | |
220 | ||
7d087d02 | 221 | You can use SPFLAGS to add debugging flags; for instance you may want to |
19a12613 | 222 | add both ``--profile --show-trying`` to SPFLAGS when debugging. For example |
4b9033a3 | 223 | you may want to use:: |
5c384dba LR |
224 | |
225 | rm -f err.log | |
226 | export COCCI=scripts/coccinelle/misc/irqf_oneshot.cocci | |
27b03cf1 | 227 | make coccicheck DEBUG_FILE="err.log" MODE=report SPFLAGS="--profile --show-trying" M=./drivers/mfd |
5c384dba LR |
228 | |
229 | err.log will now have the profiling information, while stdout will | |
230 | provide some progress information as Coccinelle moves forward with | |
231 | work. | |
232 | ||
27b03cf1 SP |
233 | NOTE: |
234 | ||
4845688d | 235 | DEBUG_FILE support is only supported when using coccinelle >= 1.0.2. |
be1fa900 | 236 | |
27b03cf1 SP |
237 | Currently, DEBUG_FILE support is only available to check folders, and |
238 | not single files. This is because checking a single file requires spatch | |
239 | to be called twice leading to DEBUG_FILE being set both times to the same value, | |
240 | giving rise to an error. | |
241 | ||
4b9033a3 JC |
242 | .cocciconfig support |
243 | -------------------- | |
dd951fc1 LR |
244 | |
245 | Coccinelle supports reading .cocciconfig for default Coccinelle options that | |
7d087d02 | 246 | should be used every time spatch is spawned. The order of precedence for |
dd951fc1 LR |
247 | variables for .cocciconfig is as follows: |
248 | ||
4b9033a3 JC |
249 | - Your current user's home directory is processed first |
250 | - Your directory from which spatch is called is processed next | |
19a12613 | 251 | - The directory provided with the ``--dir`` option is processed last, if used |
dd951fc1 LR |
252 | |
253 | Since coccicheck runs through make, it naturally runs from the kernel | |
7d087d02 | 254 | proper dir; as such the second rule above would be implied for picking up a |
4b9033a3 | 255 | .cocciconfig when using ``make coccicheck``. |
dd951fc1 | 256 | |
9eff4a2e | 257 | ``make coccicheck`` also supports using M= targets. If you do not supply |
dd951fc1 | 258 | any M= target, it is assumed you want to target the entire kernel. |
4b9033a3 | 259 | The kernel coccicheck script has:: |
dd951fc1 LR |
260 | |
261 | if [ "$KBUILD_EXTMOD" = "" ] ; then | |
262 | OPTIONS="--dir $srctree $COCCIINCLUDE" | |
263 | else | |
264 | OPTIONS="--dir $KBUILD_EXTMOD $COCCIINCLUDE" | |
265 | fi | |
266 | ||
267 | KBUILD_EXTMOD is set when an explicit target with M= is used. For both cases | |
19a12613 JN |
268 | the spatch ``--dir`` argument is used, as such third rule applies when whether |
269 | M= is used or not, and when M= is used the target directory can have its own | |
dd951fc1 LR |
270 | .cocciconfig file. When M= is not passed as an argument to coccicheck the |
271 | target directory is the same as the directory from where spatch was called. | |
272 | ||
273 | If not using the kernel's coccicheck target, keep the above precedence | |
274 | order logic of .cocciconfig reading. If using the kernel's coccicheck target, | |
275 | override any of the kernel's .coccicheck's settings using SPFLAGS. | |
276 | ||
7d087d02 | 277 | We help Coccinelle when used against Linux with a set of sensible default |
dd951fc1 | 278 | options for Linux with our own Linux .cocciconfig. This hints to coccinelle |
7d087d02 | 279 | that git can be used for ``git grep`` queries over coccigrep. A timeout of 200 |
dd951fc1 LR |
280 | seconds should suffice for now. |
281 | ||
282 | The options picked up by coccinelle when reading a .cocciconfig do not appear | |
7d087d02 | 283 | as arguments to spatch processes running on your system. To confirm what |
4b9033a3 | 284 | options will be used by Coccinelle run:: |
dd951fc1 LR |
285 | |
286 | spatch --print-options-only | |
287 | ||
288 | You can override with your own preferred index option by using SPFLAGS. Take | |
289 | note that when there are conflicting options Coccinelle takes precedence for | |
290 | the last options passed. Using .cocciconfig is possible to use idutils, however | |
291 | given the order of precedence followed by Coccinelle, since the kernel now | |
292 | carries its own .cocciconfig, you will need to use SPFLAGS to use idutils if | |
293 | desired. See below section "Additional flags" for more details on how to use | |
294 | idutils. | |
295 | ||
4b9033a3 JC |
296 | Additional flags |
297 | ---------------- | |
ed621cc4 NP |
298 | |
299 | Additional flags can be passed to spatch through the SPFLAGS | |
8e826ad5 | 300 | variable. This works as Coccinelle respects the last flags |
4b9033a3 | 301 | given to it when options are in conflict. :: |
ed621cc4 | 302 | |
78a95b9b | 303 | make SPFLAGS=--use-glimpse coccicheck |
dd951fc1 LR |
304 | |
305 | Coccinelle supports idutils as well but requires coccinelle >= 1.0.6. | |
306 | When no ID file is specified coccinelle assumes your ID database file | |
7d087d02 | 307 | is in the file .id-utils.index on the top level of the kernel. Coccinelle |
4b9033a3 | 308 | carries a script scripts/idutils_index.sh which creates the database with:: |
dd951fc1 LR |
309 | |
310 | mkid -i C --output .id-utils.index | |
311 | ||
312 | If you have another database filename you can also just symlink with this | |
4b9033a3 | 313 | name. :: |
dd951fc1 | 314 | |
78a95b9b | 315 | make SPFLAGS=--use-idutils coccicheck |
ed621cc4 | 316 | |
dd951fc1 | 317 | Alternatively you can specify the database filename explicitly, for |
4b9033a3 | 318 | instance:: |
dd951fc1 LR |
319 | |
320 | make SPFLAGS="--use-idutils /full-path/to/ID" coccicheck | |
321 | ||
4b9033a3 | 322 | See ``spatch --help`` to learn more about spatch options. |
32af0898 | 323 | |
4b9033a3 | 324 | Note that the ``--use-glimpse`` and ``--use-idutils`` options |
78a95b9b NP |
325 | require external tools for indexing the code. None of them is |
326 | thus active by default. However, by indexing the code with | |
327 | one of these tools, and according to the cocci file used, | |
328 | spatch could proceed the entire code base more quickly. | |
329 | ||
4b9033a3 JC |
330 | SmPL patch specific options |
331 | --------------------------- | |
a9e064c0 LR |
332 | |
333 | SmPL patches can have their own requirements for options passed | |
7d087d02 | 334 | to Coccinelle. SmPL patch-specific options can be provided by |
4b9033a3 | 335 | providing them at the top of the SmPL patch, for instance:: |
a9e064c0 | 336 | |
4b9033a3 | 337 | // Options: --no-includes --include-headers |
a9e064c0 | 338 | |
4b9033a3 JC |
339 | SmPL patch Coccinelle requirements |
340 | ---------------------------------- | |
a9e064c0 LR |
341 | |
342 | As Coccinelle features get added some more advanced SmPL patches | |
343 | may require newer versions of Coccinelle. If an SmPL patch requires | |
7d087d02 | 344 | a minimum version of Coccinelle, this can be specified as follows, |
4b9033a3 | 345 | as an example if requiring at least Coccinelle >= 1.0.5:: |
a9e064c0 | 346 | |
4b9033a3 | 347 | // Requires: 1.0.5 |
a9e064c0 | 348 | |
4b9033a3 | 349 | Proposing new semantic patches |
cc8246de | 350 | ------------------------------ |
e228b1e6 NP |
351 | |
352 | New semantic patches can be proposed and submitted by kernel | |
353 | developers. For sake of clarity, they should be organized in the | |
4b9033a3 | 354 | sub-directories of ``scripts/coccinelle/``. |
e228b1e6 NP |
355 | |
356 | ||
4b9033a3 JC |
357 | Detailed description of the ``report`` mode |
358 | ------------------------------------------- | |
359 | ||
360 | ``report`` generates a list in the following format:: | |
e228b1e6 | 361 | |
e228b1e6 NP |
362 | file:line:column-column: message |
363 | ||
4b9033a3 JC |
364 | Example |
365 | ~~~~~~~ | |
e228b1e6 | 366 | |
4b9033a3 | 367 | Running:: |
e228b1e6 | 368 | |
9dcf7990 | 369 | make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 | 370 | |
4b9033a3 | 371 | will execute the following part of the SmPL script:: |
e228b1e6 | 372 | |
4b9033a3 JC |
373 | <smpl> |
374 | @r depends on !context && !patch && (org || report)@ | |
375 | expression x; | |
376 | position p; | |
377 | @@ | |
e228b1e6 | 378 | |
4b9033a3 | 379 | ERR_PTR@p(PTR_ERR(x)) |
e228b1e6 | 380 | |
4b9033a3 JC |
381 | @script:python depends on report@ |
382 | p << r.p; | |
383 | x << r.x; | |
384 | @@ | |
e228b1e6 | 385 | |
4b9033a3 JC |
386 | msg="ERR_CAST can be used with %s" % (x) |
387 | coccilib.report.print_report(p[0], msg) | |
388 | </smpl> | |
e228b1e6 NP |
389 | |
390 | This SmPL excerpt generates entries on the standard output, as | |
4b9033a3 | 391 | illustrated below:: |
e228b1e6 | 392 | |
4b9033a3 JC |
393 | /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg |
394 | /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth | |
395 | /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg | |
e228b1e6 NP |
396 | |
397 | ||
4b9033a3 JC |
398 | Detailed description of the ``patch`` mode |
399 | ------------------------------------------ | |
e228b1e6 | 400 | |
4b9033a3 | 401 | When the ``patch`` mode is available, it proposes a fix for each problem |
e228b1e6 NP |
402 | identified. |
403 | ||
4b9033a3 JC |
404 | Example |
405 | ~~~~~~~ | |
406 | ||
407 | Running:: | |
e228b1e6 | 408 | |
9dcf7990 | 409 | make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 | 410 | |
4b9033a3 | 411 | will execute the following part of the SmPL script:: |
e228b1e6 | 412 | |
4b9033a3 JC |
413 | <smpl> |
414 | @ depends on !context && patch && !org && !report @ | |
415 | expression x; | |
416 | @@ | |
e228b1e6 | 417 | |
4b9033a3 JC |
418 | - ERR_PTR(PTR_ERR(x)) |
419 | + ERR_CAST(x) | |
420 | </smpl> | |
e228b1e6 NP |
421 | |
422 | This SmPL excerpt generates patch hunks on the standard output, as | |
4b9033a3 | 423 | illustrated below:: |
e228b1e6 | 424 | |
4b9033a3 JC |
425 | diff -u -p a/crypto/ctr.c b/crypto/ctr.c |
426 | --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 | |
427 | +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 | |
428 | @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct | |
e228b1e6 NP |
429 | alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, |
430 | CRYPTO_ALG_TYPE_MASK); | |
431 | if (IS_ERR(alg)) | |
4b9033a3 JC |
432 | - return ERR_PTR(PTR_ERR(alg)); |
433 | + return ERR_CAST(alg); | |
434 | ||
e228b1e6 NP |
435 | /* Block size must be >= 4 bytes. */ |
436 | err = -EINVAL; | |
437 | ||
4b9033a3 JC |
438 | Detailed description of the ``context`` mode |
439 | -------------------------------------------- | |
e228b1e6 | 440 | |
4b9033a3 | 441 | ``context`` highlights lines of interest and their context |
e228b1e6 NP |
442 | in a diff-like style. |
443 | ||
4b9033a3 JC |
444 | **NOTE**: The diff-like output generated is NOT an applicable patch. The |
445 | intent of the ``context`` mode is to highlight the important lines | |
446 | (annotated with minus, ``-``) and gives some surrounding context | |
e228b1e6 NP |
447 | lines around. This output can be used with the diff mode of |
448 | Emacs to review the code. | |
449 | ||
4b9033a3 JC |
450 | Example |
451 | ~~~~~~~ | |
452 | ||
453 | Running:: | |
e228b1e6 | 454 | |
9dcf7990 | 455 | make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 | 456 | |
4b9033a3 | 457 | will execute the following part of the SmPL script:: |
e228b1e6 | 458 | |
4b9033a3 JC |
459 | <smpl> |
460 | @ depends on context && !patch && !org && !report@ | |
461 | expression x; | |
462 | @@ | |
e228b1e6 | 463 | |
4b9033a3 JC |
464 | * ERR_PTR(PTR_ERR(x)) |
465 | </smpl> | |
e228b1e6 NP |
466 | |
467 | This SmPL excerpt generates diff hunks on the standard output, as | |
4b9033a3 | 468 | illustrated below:: |
e228b1e6 | 469 | |
4b9033a3 JC |
470 | diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing |
471 | --- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 | |
472 | +++ /tmp/nothing | |
473 | @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct | |
e228b1e6 NP |
474 | alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, |
475 | CRYPTO_ALG_TYPE_MASK); | |
476 | if (IS_ERR(alg)) | |
4b9033a3 JC |
477 | - return ERR_PTR(PTR_ERR(alg)); |
478 | ||
e228b1e6 NP |
479 | /* Block size must be >= 4 bytes. */ |
480 | err = -EINVAL; | |
481 | ||
4b9033a3 JC |
482 | Detailed description of the ``org`` mode |
483 | ---------------------------------------- | |
484 | ||
485 | ``org`` generates a report in the Org mode format of Emacs. | |
e228b1e6 | 486 | |
4b9033a3 JC |
487 | Example |
488 | ~~~~~~~ | |
e228b1e6 | 489 | |
4b9033a3 | 490 | Running:: |
e228b1e6 | 491 | |
9dcf7990 | 492 | make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci |
e228b1e6 | 493 | |
4b9033a3 | 494 | will execute the following part of the SmPL script:: |
e228b1e6 | 495 | |
4b9033a3 JC |
496 | <smpl> |
497 | @r depends on !context && !patch && (org || report)@ | |
498 | expression x; | |
499 | position p; | |
500 | @@ | |
e228b1e6 | 501 | |
4b9033a3 | 502 | ERR_PTR@p(PTR_ERR(x)) |
e228b1e6 | 503 | |
4b9033a3 JC |
504 | @script:python depends on org@ |
505 | p << r.p; | |
506 | x << r.x; | |
507 | @@ | |
e228b1e6 | 508 | |
4b9033a3 JC |
509 | msg="ERR_CAST can be used with %s" % (x) |
510 | msg_safe=msg.replace("[","@(").replace("]",")") | |
511 | coccilib.org.print_todo(p[0], msg_safe) | |
512 | </smpl> | |
e228b1e6 NP |
513 | |
514 | This SmPL excerpt generates Org entries on the standard output, as | |
4b9033a3 | 515 | illustrated below:: |
e228b1e6 | 516 | |
4b9033a3 JC |
517 | * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] |
518 | * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] | |
519 | * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]] |