diff options
Diffstat (limited to 'Documentation/dev-tools/coccinelle.rst')
| -rw-r--r-- | Documentation/dev-tools/coccinelle.rst | 80 |
1 files changed, 47 insertions, 33 deletions
diff --git a/Documentation/dev-tools/coccinelle.rst b/Documentation/dev-tools/coccinelle.rst index 00a3409b0c28..535ce126fb4f 100644 --- a/Documentation/dev-tools/coccinelle.rst +++ b/Documentation/dev-tools/coccinelle.rst @@ -14,7 +14,7 @@ many uses in kernel development, including the application of complex, tree-wide patches and detection of problematic programming patterns. Getting Coccinelle -------------------- +------------------ The semantic patches included in the kernel use features and options which are provided by Coccinelle version 1.0.0-rc11 and above. @@ -56,7 +56,7 @@ found at: https://github.com/coccinelle/coccinelle/blob/master/install.txt Supplemental documentation ---------------------------- +-------------------------- For supplemental documentation refer to the wiki: @@ -66,7 +66,7 @@ The wiki documentation always refers to the linux-next version of the script. For Semantic Patch Language(SmPL) grammar documentation refer to: -http://coccinelle.lip6.fr/documentation.php +https://coccinelle.gitlabpages.inria.fr/website/docs/main_grammar.html Using Coccinelle on the Linux kernel ------------------------------------ @@ -85,7 +85,7 @@ Four basic modes are defined: ``patch``, ``report``, ``context``, and file:line:column-column: message - ``context`` highlights lines of interest and their context in a - diff-like style.Lines of interest are indicated with ``-``. + diff-like style. Lines of interest are indicated with ``-``. - ``org`` generates a report in the Org mode format of Emacs. @@ -119,7 +119,7 @@ For each semantic patch, a commit message is proposed. It gives a description of the problem being checked by the semantic patch, and includes a reference to Coccinelle. -As any static code analyzer, Coccinelle produces false +As with any static code analyzer, Coccinelle produces false positives. Thus, reports must be carefully checked, and patches reviewed. @@ -128,25 +128,25 @@ To enable verbose messages set the V= variable, for example:: make coccicheck MODE=report V=1 Coccinelle parallelization ---------------------------- +-------------------------- By default, coccicheck tries to run as parallel as possible. To change the parallelism, set the J= variable. For example, to run across 4 CPUs:: make coccicheck MODE=report J=4 -As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization, +As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization; if support for this is detected you will benefit from parmap parallelization. When parmap is enabled coccicheck will enable dynamic load balancing by using -``--chunksize 1`` argument, this ensures we keep feeding threads with work +``--chunksize 1`` argument. This ensures we keep feeding threads with work one by one, so that we avoid the situation where most work gets done by only a few threads. With dynamic load balancing, if a thread finishes early we keep feeding it more work. When parmap is enabled, if an error occurs in Coccinelle, this error -value is propagated back, the return value of the ``make coccicheck`` -captures this return value. +value is propagated back, and the return value of the ``make coccicheck`` +command captures this return value. Using Coccinelle with a single semantic patch --------------------------------------------- @@ -175,15 +175,22 @@ For example, to check drivers/net/wireless/ one may write:: make coccicheck M=drivers/net/wireless/ To apply Coccinelle on a file basis, instead of a directory basis, the -following command may be used:: +C variable is used by the makefile to select which files to work with. +This variable can be used to run scripts for the entire kernel, a +specific directory, or for a single file. + +For example, to check drivers/bluetooth/bfusb.c, the value 1 is +passed to the C variable to check files that make considers +need to be compiled.:: - make C=1 CHECK="scripts/coccicheck" + make C=1 CHECK=scripts/coccicheck drivers/bluetooth/bfusb.o -To check only newly edited code, use the value 2 for the C flag, i.e.:: +The value 2 is passed to the C variable to check files regardless of +whether they need to be compiled or not.:: - make C=2 CHECK="scripts/coccicheck" + make C=2 CHECK=scripts/coccicheck drivers/bluetooth/bfusb.o -In these modes, which works on a file basis, there is no information +In these modes, which work on a file basis, there is no information about semantic patches displayed, and no commit message proposed. This runs every semantic patch in scripts/coccinelle by default. The @@ -198,12 +205,12 @@ Debugging Coccinelle SmPL patches Using coccicheck is best as it provides in the spatch command line include options matching the options used when we compile the kernel. -You can learn what these options are by using V=1, you could then +You can learn what these options are by using V=1; you could then manually run Coccinelle with debug options added. Alternatively you can debug running Coccinelle against SmPL patches -by asking for stderr to be redirected to stderr, by default stderr -is redirected to /dev/null, if you'd like to capture stderr you +by asking for stderr to be redirected to stderr. By default stderr +is redirected to /dev/null; if you'd like to capture stderr you can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For instance:: @@ -211,33 +218,40 @@ instance:: make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err cat cocci.err -You can use SPFLAGS to add debugging flags, for instance you may want to -add both --profile --show-trying to SPFLAGS when debugging. For instance +You can use SPFLAGS to add debugging flags; for instance you may want to +add both ``--profile --show-trying`` to SPFLAGS when debugging. For example you may want to use:: rm -f err.log export COCCI=scripts/coccinelle/misc/irqf_oneshot.cocci - make coccicheck DEBUG_FILE="err.log" MODE=report SPFLAGS="--profile --show-trying" M=./drivers/mfd/arizona-irq.c + make coccicheck DEBUG_FILE="err.log" MODE=report SPFLAGS="--profile --show-trying" M=./drivers/mfd err.log will now have the profiling information, while stdout will provide some progress information as Coccinelle moves forward with work. +NOTE: + DEBUG_FILE support is only supported when using coccinelle >= 1.0.2. +Currently, DEBUG_FILE support is only available to check folders, and +not single files. This is because checking a single file requires spatch +to be called twice leading to DEBUG_FILE being set both times to the same value, +giving rise to an error. + .cocciconfig support -------------------- Coccinelle supports reading .cocciconfig for default Coccinelle options that -should be used every time spatch is spawned, the order of precedence for +should be used every time spatch is spawned. The order of precedence for variables for .cocciconfig is as follows: - Your current user's home directory is processed first - Your directory from which spatch is called is processed next -- The directory provided with the --dir option is processed last, if used +- The directory provided with the ``--dir`` option is processed last, if used Since coccicheck runs through make, it naturally runs from the kernel -proper dir, as such the second rule above would be implied for picking up a +proper dir; as such the second rule above would be implied for picking up a .cocciconfig when using ``make coccicheck``. ``make coccicheck`` also supports using M= targets. If you do not supply @@ -251,8 +265,8 @@ The kernel coccicheck script has:: fi KBUILD_EXTMOD is set when an explicit target with M= is used. For both cases -the spatch --dir argument is used, as such third rule applies when whether M= -is used or not, and when M= is used the target directory can have its own +the spatch ``--dir`` argument is used, as such third rule applies when whether +M= is used or not, and when M= is used the target directory can have its own .cocciconfig file. When M= is not passed as an argument to coccicheck the target directory is the same as the directory from where spatch was called. @@ -260,13 +274,13 @@ If not using the kernel's coccicheck target, keep the above precedence order logic of .cocciconfig reading. If using the kernel's coccicheck target, override any of the kernel's .coccicheck's settings using SPFLAGS. -We help Coccinelle when used against Linux with a set of sensible defaults +We help Coccinelle when used against Linux with a set of sensible default options for Linux with our own Linux .cocciconfig. This hints to coccinelle -git can be used for ``git grep`` queries over coccigrep. A timeout of 200 +that git can be used for ``git grep`` queries over coccigrep. A timeout of 200 seconds should suffice for now. The options picked up by coccinelle when reading a .cocciconfig do not appear -as arguments to spatch processes running on your system, to confirm what +as arguments to spatch processes running on your system. To confirm what options will be used by Coccinelle run:: spatch --print-options-only @@ -290,7 +304,7 @@ given to it when options are in conflict. :: Coccinelle supports idutils as well but requires coccinelle >= 1.0.6. When no ID file is specified coccinelle assumes your ID database file -is in the file .id-utils.index on the top level of the kernel, coccinelle +is in the file .id-utils.index on the top level of the kernel. Coccinelle carries a script scripts/idutils_index.sh which creates the database with:: mkid -i C --output .id-utils.index @@ -317,7 +331,7 @@ SmPL patch specific options --------------------------- SmPL patches can have their own requirements for options passed -to Coccinelle. SmPL patch specific options can be provided by +to Coccinelle. SmPL patch-specific options can be provided by providing them at the top of the SmPL patch, for instance:: // Options: --no-includes --include-headers @@ -327,13 +341,13 @@ SmPL patch Coccinelle requirements As Coccinelle features get added some more advanced SmPL patches may require newer versions of Coccinelle. If an SmPL patch requires -at least a version of Coccinelle, this can be specified as follows, +a minimum version of Coccinelle, this can be specified as follows, as an example if requiring at least Coccinelle >= 1.0.5:: // Requires: 1.0.5 Proposing new semantic patches -------------------------------- +------------------------------ New semantic patches can be proposed and submitted by kernel developers. For sake of clarity, they should be organized in the |