Documentation/dev-tools/coccinelle.rst

12 Coccinelle is a tool for pattern matching and text transformation that has
14 tree-wide patches and detection of problematic programming patterns.
17 ------------------
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.
22 the Coccinelle files and coccicheck have been updated.
27  - Debian
28  - Fedora
29  - Ubuntu
30  - OpenSUSE
31  - Arch Linux
32  - NetBSD
33  - FreeBSD
35 Some distribution packages are obsolete and it is recommended
49 as a regular user, and install it with::
53 More detailed installation instructions to build from source can be
59 --------------------------
65 The wiki documentation always refers to the linux-next version of the script.
69 https://coccinelle.gitlabpages.inria.fr/website/docs/main_grammar.html
72 ------------------------------------
74 A Coccinelle-specific target is defined in the top level
75 Makefile. This target is named ``coccicheck`` and calls the ``coccicheck``
76 front-end in the ``scripts`` directory.
78 Four basic modes are defined: ``patch``, ``report``, ``context``, and
82 - ``patch`` proposes a fix, when possible.
84 - ``report`` generates a list in the following format:
85   file:line:column-column: message
87 - ``context`` highlights lines of interest and their context in a
88   diff-like style. Lines of interest are indicated with ``-``.
90 - ``org`` generates a report in the Org mode format of Emacs.
97 - ``chain`` tries the previous modes in the order above until one succeeds.
99 - ``rep+ctxt`` runs successively the report mode and the context mode.
116 sub-directories of ``scripts/coccinelle`` to the entire Linux kernel.
119 description of the problem being checked by the semantic patch, and
123 positives. Thus, reports must be carefully checked, and patches
131 --------------------------
142 ``--chunksize 1`` argument. This ensures we keep feeding threads with work
148 value is propagated back, and the return value of the ``make coccicheck``
152 ---------------------------------------------
168 ---------------------------------------------------
194 about semantic patches displayed, and no commit message proposed.
204 ---------------------------------
217     rm -f cocci.err
222 add both ``--profile --show-trying`` to SPFLAGS when debugging. For example
225     rm -f err.log
227 … make coccicheck DEBUG_FILE="err.log" MODE=report SPFLAGS="--profile --show-trying" M=./drivers/mfd
237 Currently, DEBUG_FILE support is only available to check folders, and
243 --------------------
249 - Your current user's home directory is processed first
250 - Your directory from which spatch is called is processed next
251 - The directory provided with the ``--dir`` option is processed last, if used
262         OPTIONS="--dir $srctree $COCCIINCLUDE"
264         OPTIONS="--dir $KBUILD_EXTMOD $COCCIINCLUDE"
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
286       spatch --print-options-only
297 ----------------
303     make SPFLAGS=--use-glimpse coccicheck
307 is in the file .id-utils.index on the top level of the kernel. Coccinelle
310     mkid -i C --output .id-utils.index
315     make SPFLAGS=--use-idutils coccicheck
320     make SPFLAGS="--use-idutils /full-path/to/ID" coccicheck
322 See ``spatch --help`` to learn more about spatch options.
324 Note that the ``--use-glimpse`` and ``--use-idutils`` options
325 require external tools for indexing the code. None of them is
327 one of these tools, and according to the cocci file used,
331 ---------------------------
334 to Coccinelle. SmPL patch-specific options can be provided by
337 	// Options: --no-includes --include-headers
340 ----------------------------------
350 ------------------------------
352 New semantic patches can be proposed and submitted by kernel
354 sub-directories of ``scripts/coccinelle/``.
358 -------------------------------------------
362   file:line:column-column: message
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
399 ------------------------------------------
418     - ERR_PTR(PTR_ERR(x))
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
432     -		return ERR_PTR(PTR_ERR(alg));
436  	err = -EINVAL;
439 --------------------------------------------
441 ``context`` highlights lines of interest and their context
442 in a diff-like style.
444       **NOTE**: The diff-like output generated is NOT an applicable patch. The
446       (annotated with minus, ``-``) and gives some surrounding context
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
473     @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct
477     -		return ERR_PTR(PTR_ERR(alg));
480  	err = -EINVAL;
483 ----------------------------------------
517 …* TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST c…
518 …* TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CA…
519 …* TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST c…