1*8a28caf0SHeinrich Schuchardt.. Copyright 2010 Nicolas Palix <npalix@diku.dk> 2*8a28caf0SHeinrich Schuchardt.. Copyright 2010 Julia Lawall <julia@diku.dk> 3*8a28caf0SHeinrich Schuchardt.. Copyright 2010 Gilles Muller <Gilles.Muller@lip6.fr> 4*8a28caf0SHeinrich Schuchardt 5*8a28caf0SHeinrich Schuchardt.. highlight:: none 6*8a28caf0SHeinrich Schuchardt 7*8a28caf0SHeinrich SchuchardtCoccinelle 8*8a28caf0SHeinrich Schuchardt========== 9*8a28caf0SHeinrich Schuchardt 10*8a28caf0SHeinrich SchuchardtCoccinelle is a tool for pattern matching and text transformation that has 11*8a28caf0SHeinrich Schuchardtmany uses in kernel development, including the application of complex, 12*8a28caf0SHeinrich Schuchardttree-wide patches and detection of problematic programming patterns. 13*8a28caf0SHeinrich Schuchardt 14*8a28caf0SHeinrich SchuchardtGetting Coccinelle 15*8a28caf0SHeinrich Schuchardt------------------- 16*8a28caf0SHeinrich Schuchardt 17*8a28caf0SHeinrich SchuchardtThe semantic patches included in the kernel use features and options 18*8a28caf0SHeinrich Schuchardtwhich are provided by Coccinelle version 1.0.0-rc11 and above. 19*8a28caf0SHeinrich SchuchardtUsing earlier versions will fail as the option names used by 20*8a28caf0SHeinrich Schuchardtthe Coccinelle files and coccicheck have been updated. 21*8a28caf0SHeinrich Schuchardt 22*8a28caf0SHeinrich SchuchardtCoccinelle is available through the package manager 23*8a28caf0SHeinrich Schuchardtof many distributions, e.g. : 24*8a28caf0SHeinrich Schuchardt 25*8a28caf0SHeinrich Schuchardt - Debian 26*8a28caf0SHeinrich Schuchardt - Fedora 27*8a28caf0SHeinrich Schuchardt - Ubuntu 28*8a28caf0SHeinrich Schuchardt - OpenSUSE 29*8a28caf0SHeinrich Schuchardt - Arch Linux 30*8a28caf0SHeinrich Schuchardt - NetBSD 31*8a28caf0SHeinrich Schuchardt - FreeBSD 32*8a28caf0SHeinrich Schuchardt 33*8a28caf0SHeinrich SchuchardtYou can get the latest version released from the Coccinelle homepage at 34*8a28caf0SHeinrich Schuchardthttp://coccinelle.lip6.fr/ 35*8a28caf0SHeinrich Schuchardt 36*8a28caf0SHeinrich SchuchardtInformation and tips about Coccinelle are also provided on the wiki 37*8a28caf0SHeinrich Schuchardtpages at http://cocci.ekstranet.diku.dk/wiki/doku.php 38*8a28caf0SHeinrich Schuchardt 39*8a28caf0SHeinrich SchuchardtOnce you have it, run the following command:: 40*8a28caf0SHeinrich Schuchardt 41*8a28caf0SHeinrich Schuchardt ./configure 42*8a28caf0SHeinrich Schuchardt make 43*8a28caf0SHeinrich Schuchardt 44*8a28caf0SHeinrich Schuchardtas a regular user, and install it with:: 45*8a28caf0SHeinrich Schuchardt 46*8a28caf0SHeinrich Schuchardt sudo make install 47*8a28caf0SHeinrich Schuchardt 48*8a28caf0SHeinrich SchuchardtSupplemental documentation 49*8a28caf0SHeinrich Schuchardt--------------------------- 50*8a28caf0SHeinrich Schuchardt 51*8a28caf0SHeinrich SchuchardtFor supplemental documentation refer to the wiki: 52*8a28caf0SHeinrich Schuchardt 53*8a28caf0SHeinrich Schuchardthttps://bottest.wiki.kernel.org/coccicheck 54*8a28caf0SHeinrich Schuchardt 55*8a28caf0SHeinrich SchuchardtThe wiki documentation always refers to the linux-next version of the script. 56*8a28caf0SHeinrich Schuchardt 57*8a28caf0SHeinrich SchuchardtUsing Coccinelle on the Linux kernel 58*8a28caf0SHeinrich Schuchardt------------------------------------ 59*8a28caf0SHeinrich Schuchardt 60*8a28caf0SHeinrich SchuchardtA Coccinelle-specific target is defined in the top level 61*8a28caf0SHeinrich SchuchardtMakefile. This target is named ``coccicheck`` and calls the ``coccicheck`` 62*8a28caf0SHeinrich Schuchardtfront-end in the ``scripts`` directory. 63*8a28caf0SHeinrich Schuchardt 64*8a28caf0SHeinrich SchuchardtFour basic modes are defined: ``patch``, ``report``, ``context``, and 65*8a28caf0SHeinrich Schuchardt``org``. The mode to use is specified by setting the MODE variable with 66*8a28caf0SHeinrich Schuchardt``MODE=<mode>``. 67*8a28caf0SHeinrich Schuchardt 68*8a28caf0SHeinrich Schuchardt- ``patch`` proposes a fix, when possible. 69*8a28caf0SHeinrich Schuchardt 70*8a28caf0SHeinrich Schuchardt- ``report`` generates a list in the following format: 71*8a28caf0SHeinrich Schuchardt file:line:column-column: message 72*8a28caf0SHeinrich Schuchardt 73*8a28caf0SHeinrich Schuchardt- ``context`` highlights lines of interest and their context in a 74*8a28caf0SHeinrich Schuchardt diff-like style.Lines of interest are indicated with ``-``. 75*8a28caf0SHeinrich Schuchardt 76*8a28caf0SHeinrich Schuchardt- ``org`` generates a report in the Org mode format of Emacs. 77*8a28caf0SHeinrich Schuchardt 78*8a28caf0SHeinrich SchuchardtNote that not all semantic patches implement all modes. For easy use 79*8a28caf0SHeinrich Schuchardtof Coccinelle, the default mode is "report". 80*8a28caf0SHeinrich Schuchardt 81*8a28caf0SHeinrich SchuchardtTwo other modes provide some common combinations of these modes. 82*8a28caf0SHeinrich Schuchardt 83*8a28caf0SHeinrich Schuchardt- ``chain`` tries the previous modes in the order above until one succeeds. 84*8a28caf0SHeinrich Schuchardt 85*8a28caf0SHeinrich Schuchardt- ``rep+ctxt`` runs successively the report mode and the context mode. 86*8a28caf0SHeinrich Schuchardt It should be used with the C option (described later) 87*8a28caf0SHeinrich Schuchardt which checks the code on a file basis. 88*8a28caf0SHeinrich Schuchardt 89*8a28caf0SHeinrich SchuchardtExamples 90*8a28caf0SHeinrich Schuchardt~~~~~~~~ 91*8a28caf0SHeinrich Schuchardt 92*8a28caf0SHeinrich SchuchardtTo make a report for every semantic patch, run the following command:: 93*8a28caf0SHeinrich Schuchardt 94*8a28caf0SHeinrich Schuchardt make coccicheck MODE=report 95*8a28caf0SHeinrich Schuchardt 96*8a28caf0SHeinrich SchuchardtTo produce patches, run:: 97*8a28caf0SHeinrich Schuchardt 98*8a28caf0SHeinrich Schuchardt make coccicheck MODE=patch 99*8a28caf0SHeinrich Schuchardt 100*8a28caf0SHeinrich Schuchardt 101*8a28caf0SHeinrich SchuchardtThe coccicheck target applies every semantic patch available in the 102*8a28caf0SHeinrich Schuchardtsub-directories of ``scripts/coccinelle`` to the entire Linux kernel. 103*8a28caf0SHeinrich Schuchardt 104*8a28caf0SHeinrich SchuchardtFor each semantic patch, a commit message is proposed. It gives a 105*8a28caf0SHeinrich Schuchardtdescription of the problem being checked by the semantic patch, and 106*8a28caf0SHeinrich Schuchardtincludes a reference to Coccinelle. 107*8a28caf0SHeinrich Schuchardt 108*8a28caf0SHeinrich SchuchardtAs any static code analyzer, Coccinelle produces false 109*8a28caf0SHeinrich Schuchardtpositives. Thus, reports must be carefully checked, and patches 110*8a28caf0SHeinrich Schuchardtreviewed. 111*8a28caf0SHeinrich Schuchardt 112*8a28caf0SHeinrich SchuchardtTo enable verbose messages set the V= variable, for example:: 113*8a28caf0SHeinrich Schuchardt 114*8a28caf0SHeinrich Schuchardt make coccicheck MODE=report V=1 115*8a28caf0SHeinrich Schuchardt 116*8a28caf0SHeinrich SchuchardtCoccinelle parallelization 117*8a28caf0SHeinrich Schuchardt--------------------------- 118*8a28caf0SHeinrich Schuchardt 119*8a28caf0SHeinrich SchuchardtBy default, coccicheck tries to run as parallel as possible. To change 120*8a28caf0SHeinrich Schuchardtthe parallelism, set the J= variable. For example, to run across 4 CPUs:: 121*8a28caf0SHeinrich Schuchardt 122*8a28caf0SHeinrich Schuchardt make coccicheck MODE=report J=4 123*8a28caf0SHeinrich Schuchardt 124*8a28caf0SHeinrich SchuchardtAs of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization, 125*8a28caf0SHeinrich Schuchardtif support for this is detected you will benefit from parmap parallelization. 126*8a28caf0SHeinrich Schuchardt 127*8a28caf0SHeinrich SchuchardtWhen parmap is enabled coccicheck will enable dynamic load balancing by using 128*8a28caf0SHeinrich Schuchardt``--chunksize 1`` argument, this ensures we keep feeding threads with work 129*8a28caf0SHeinrich Schuchardtone by one, so that we avoid the situation where most work gets done by only 130*8a28caf0SHeinrich Schuchardta few threads. With dynamic load balancing, if a thread finishes early we keep 131*8a28caf0SHeinrich Schuchardtfeeding it more work. 132*8a28caf0SHeinrich Schuchardt 133*8a28caf0SHeinrich SchuchardtWhen parmap is enabled, if an error occurs in Coccinelle, this error 134*8a28caf0SHeinrich Schuchardtvalue is propagated back, the return value of the ``make coccicheck`` 135*8a28caf0SHeinrich Schuchardtcaptures this return value. 136*8a28caf0SHeinrich Schuchardt 137*8a28caf0SHeinrich SchuchardtUsing Coccinelle with a single semantic patch 138*8a28caf0SHeinrich Schuchardt--------------------------------------------- 139*8a28caf0SHeinrich Schuchardt 140*8a28caf0SHeinrich SchuchardtThe optional make variable COCCI can be used to check a single 141*8a28caf0SHeinrich Schuchardtsemantic patch. In that case, the variable must be initialized with 142*8a28caf0SHeinrich Schuchardtthe name of the semantic patch to apply. 143*8a28caf0SHeinrich Schuchardt 144*8a28caf0SHeinrich SchuchardtFor instance:: 145*8a28caf0SHeinrich Schuchardt 146*8a28caf0SHeinrich Schuchardt make coccicheck COCCI=<my_SP.cocci> MODE=patch 147*8a28caf0SHeinrich Schuchardt 148*8a28caf0SHeinrich Schuchardtor:: 149*8a28caf0SHeinrich Schuchardt 150*8a28caf0SHeinrich Schuchardt make coccicheck COCCI=<my_SP.cocci> MODE=report 151*8a28caf0SHeinrich Schuchardt 152*8a28caf0SHeinrich Schuchardt 153*8a28caf0SHeinrich SchuchardtControlling Which Files are Processed by Coccinelle 154*8a28caf0SHeinrich Schuchardt--------------------------------------------------- 155*8a28caf0SHeinrich Schuchardt 156*8a28caf0SHeinrich SchuchardtBy default the entire kernel source tree is checked. 157*8a28caf0SHeinrich Schuchardt 158*8a28caf0SHeinrich SchuchardtTo apply Coccinelle to a specific directory, ``M=`` can be used. 159*8a28caf0SHeinrich SchuchardtFor example, to check drivers/net/wireless/ one may write:: 160*8a28caf0SHeinrich Schuchardt 161*8a28caf0SHeinrich Schuchardt make coccicheck M=drivers/net/wireless/ 162*8a28caf0SHeinrich Schuchardt 163*8a28caf0SHeinrich SchuchardtTo apply Coccinelle on a file basis, instead of a directory basis, the 164*8a28caf0SHeinrich Schuchardtfollowing command may be used:: 165*8a28caf0SHeinrich Schuchardt 166*8a28caf0SHeinrich Schuchardt make C=1 CHECK="scripts/coccicheck" 167*8a28caf0SHeinrich Schuchardt 168*8a28caf0SHeinrich SchuchardtTo check only newly edited code, use the value 2 for the C flag, i.e.:: 169*8a28caf0SHeinrich Schuchardt 170*8a28caf0SHeinrich Schuchardt make C=2 CHECK="scripts/coccicheck" 171*8a28caf0SHeinrich Schuchardt 172*8a28caf0SHeinrich SchuchardtIn these modes, which works on a file basis, there is no information 173*8a28caf0SHeinrich Schuchardtabout semantic patches displayed, and no commit message proposed. 174*8a28caf0SHeinrich Schuchardt 175*8a28caf0SHeinrich SchuchardtThis runs every semantic patch in scripts/coccinelle by default. The 176*8a28caf0SHeinrich SchuchardtCOCCI variable may additionally be used to only apply a single 177*8a28caf0SHeinrich Schuchardtsemantic patch as shown in the previous section. 178*8a28caf0SHeinrich Schuchardt 179*8a28caf0SHeinrich SchuchardtThe "report" mode is the default. You can select another one with the 180*8a28caf0SHeinrich SchuchardtMODE variable explained above. 181*8a28caf0SHeinrich Schuchardt 182*8a28caf0SHeinrich SchuchardtDebugging Coccinelle SmPL patches 183*8a28caf0SHeinrich Schuchardt--------------------------------- 184*8a28caf0SHeinrich Schuchardt 185*8a28caf0SHeinrich SchuchardtUsing coccicheck is best as it provides in the spatch command line 186*8a28caf0SHeinrich Schuchardtinclude options matching the options used when we compile the kernel. 187*8a28caf0SHeinrich SchuchardtYou can learn what these options are by using V=1, you could then 188*8a28caf0SHeinrich Schuchardtmanually run Coccinelle with debug options added. 189*8a28caf0SHeinrich Schuchardt 190*8a28caf0SHeinrich SchuchardtAlternatively you can debug running Coccinelle against SmPL patches 191*8a28caf0SHeinrich Schuchardtby asking for stderr to be redirected to stderr, by default stderr 192*8a28caf0SHeinrich Schuchardtis redirected to /dev/null, if you'd like to capture stderr you 193*8a28caf0SHeinrich Schuchardtcan specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For 194*8a28caf0SHeinrich Schuchardtinstance:: 195*8a28caf0SHeinrich Schuchardt 196*8a28caf0SHeinrich Schuchardt rm -f cocci.err 197*8a28caf0SHeinrich Schuchardt make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err 198*8a28caf0SHeinrich Schuchardt cat cocci.err 199*8a28caf0SHeinrich Schuchardt 200*8a28caf0SHeinrich SchuchardtYou can use SPFLAGS to add debugging flags, for instance you may want to 201*8a28caf0SHeinrich Schuchardtadd both --profile --show-trying to SPFLAGS when debugging. For instance 202*8a28caf0SHeinrich Schuchardtyou may want to use:: 203*8a28caf0SHeinrich Schuchardt 204*8a28caf0SHeinrich Schuchardt rm -f err.log 205*8a28caf0SHeinrich Schuchardt export COCCI=scripts/coccinelle/misc/irqf_oneshot.cocci 206*8a28caf0SHeinrich Schuchardt make coccicheck DEBUG_FILE="err.log" MODE=report SPFLAGS="--profile --show-trying" M=./drivers/mfd/arizona-irq.c 207*8a28caf0SHeinrich Schuchardt 208*8a28caf0SHeinrich Schuchardterr.log will now have the profiling information, while stdout will 209*8a28caf0SHeinrich Schuchardtprovide some progress information as Coccinelle moves forward with 210*8a28caf0SHeinrich Schuchardtwork. 211*8a28caf0SHeinrich Schuchardt 212*8a28caf0SHeinrich SchuchardtDEBUG_FILE support is only supported when using coccinelle >= 1.2. 213*8a28caf0SHeinrich Schuchardt 214*8a28caf0SHeinrich Schuchardt.cocciconfig support 215*8a28caf0SHeinrich Schuchardt-------------------- 216*8a28caf0SHeinrich Schuchardt 217*8a28caf0SHeinrich SchuchardtCoccinelle supports reading .cocciconfig for default Coccinelle options that 218*8a28caf0SHeinrich Schuchardtshould be used every time spatch is spawned, the order of precedence for 219*8a28caf0SHeinrich Schuchardtvariables for .cocciconfig is as follows: 220*8a28caf0SHeinrich Schuchardt 221*8a28caf0SHeinrich Schuchardt- Your current user's home directory is processed first 222*8a28caf0SHeinrich Schuchardt- Your directory from which spatch is called is processed next 223*8a28caf0SHeinrich Schuchardt- The directory provided with the --dir option is processed last, if used 224*8a28caf0SHeinrich Schuchardt 225*8a28caf0SHeinrich SchuchardtSince coccicheck runs through make, it naturally runs from the kernel 226*8a28caf0SHeinrich Schuchardtproper dir, as such the second rule above would be implied for picking up a 227*8a28caf0SHeinrich Schuchardt.cocciconfig when using ``make coccicheck``. 228*8a28caf0SHeinrich Schuchardt 229*8a28caf0SHeinrich Schuchardt``make coccicheck`` also supports using M= targets.If you do not supply 230*8a28caf0SHeinrich Schuchardtany M= target, it is assumed you want to target the entire kernel. 231*8a28caf0SHeinrich SchuchardtThe kernel coccicheck script has:: 232*8a28caf0SHeinrich Schuchardt 233*8a28caf0SHeinrich Schuchardt if [ "$KBUILD_EXTMOD" = "" ] ; then 234*8a28caf0SHeinrich Schuchardt OPTIONS="--dir $srctree $COCCIINCLUDE" 235*8a28caf0SHeinrich Schuchardt else 236*8a28caf0SHeinrich Schuchardt OPTIONS="--dir $KBUILD_EXTMOD $COCCIINCLUDE" 237*8a28caf0SHeinrich Schuchardt fi 238*8a28caf0SHeinrich Schuchardt 239*8a28caf0SHeinrich SchuchardtKBUILD_EXTMOD is set when an explicit target with M= is used. For both cases 240*8a28caf0SHeinrich Schuchardtthe spatch --dir argument is used, as such third rule applies when whether M= 241*8a28caf0SHeinrich Schuchardtis used or not, and when M= is used the target directory can have its own 242*8a28caf0SHeinrich Schuchardt.cocciconfig file. When M= is not passed as an argument to coccicheck the 243*8a28caf0SHeinrich Schuchardttarget directory is the same as the directory from where spatch was called. 244*8a28caf0SHeinrich Schuchardt 245*8a28caf0SHeinrich SchuchardtIf not using the kernel's coccicheck target, keep the above precedence 246*8a28caf0SHeinrich Schuchardtorder logic of .cocciconfig reading. If using the kernel's coccicheck target, 247*8a28caf0SHeinrich Schuchardtoverride any of the kernel's .coccicheck's settings using SPFLAGS. 248*8a28caf0SHeinrich Schuchardt 249*8a28caf0SHeinrich SchuchardtWe help Coccinelle when used against Linux with a set of sensible defaults 250*8a28caf0SHeinrich Schuchardtoptions for Linux with our own Linux .cocciconfig. This hints to coccinelle 251*8a28caf0SHeinrich Schuchardtgit can be used for ``git grep`` queries over coccigrep. A timeout of 200 252*8a28caf0SHeinrich Schuchardtseconds should suffice for now. 253*8a28caf0SHeinrich Schuchardt 254*8a28caf0SHeinrich SchuchardtThe options picked up by coccinelle when reading a .cocciconfig do not appear 255*8a28caf0SHeinrich Schuchardtas arguments to spatch processes running on your system, to confirm what 256*8a28caf0SHeinrich Schuchardtoptions will be used by Coccinelle run:: 257*8a28caf0SHeinrich Schuchardt 258*8a28caf0SHeinrich Schuchardt spatch --print-options-only 259*8a28caf0SHeinrich Schuchardt 260*8a28caf0SHeinrich SchuchardtYou can override with your own preferred index option by using SPFLAGS. Take 261*8a28caf0SHeinrich Schuchardtnote that when there are conflicting options Coccinelle takes precedence for 262*8a28caf0SHeinrich Schuchardtthe last options passed. Using .cocciconfig is possible to use idutils, however 263*8a28caf0SHeinrich Schuchardtgiven the order of precedence followed by Coccinelle, since the kernel now 264*8a28caf0SHeinrich Schuchardtcarries its own .cocciconfig, you will need to use SPFLAGS to use idutils if 265*8a28caf0SHeinrich Schuchardtdesired. See below section "Additional flags" for more details on how to use 266*8a28caf0SHeinrich Schuchardtidutils. 267*8a28caf0SHeinrich Schuchardt 268*8a28caf0SHeinrich SchuchardtAdditional flags 269*8a28caf0SHeinrich Schuchardt---------------- 270*8a28caf0SHeinrich Schuchardt 271*8a28caf0SHeinrich SchuchardtAdditional flags can be passed to spatch through the SPFLAGS 272*8a28caf0SHeinrich Schuchardtvariable. This works as Coccinelle respects the last flags 273*8a28caf0SHeinrich Schuchardtgiven to it when options are in conflict. :: 274*8a28caf0SHeinrich Schuchardt 275*8a28caf0SHeinrich Schuchardt make SPFLAGS=--use-glimpse coccicheck 276*8a28caf0SHeinrich Schuchardt 277*8a28caf0SHeinrich SchuchardtCoccinelle supports idutils as well but requires coccinelle >= 1.0.6. 278*8a28caf0SHeinrich SchuchardtWhen no ID file is specified coccinelle assumes your ID database file 279*8a28caf0SHeinrich Schuchardtis in the file .id-utils.index on the top level of the kernel, coccinelle 280*8a28caf0SHeinrich Schuchardtcarries a script scripts/idutils_index.sh which creates the database with:: 281*8a28caf0SHeinrich Schuchardt 282*8a28caf0SHeinrich Schuchardt mkid -i C --output .id-utils.index 283*8a28caf0SHeinrich Schuchardt 284*8a28caf0SHeinrich SchuchardtIf you have another database filename you can also just symlink with this 285*8a28caf0SHeinrich Schuchardtname. :: 286*8a28caf0SHeinrich Schuchardt 287*8a28caf0SHeinrich Schuchardt make SPFLAGS=--use-idutils coccicheck 288*8a28caf0SHeinrich Schuchardt 289*8a28caf0SHeinrich SchuchardtAlternatively you can specify the database filename explicitly, for 290*8a28caf0SHeinrich Schuchardtinstance:: 291*8a28caf0SHeinrich Schuchardt 292*8a28caf0SHeinrich Schuchardt make SPFLAGS="--use-idutils /full-path/to/ID" coccicheck 293*8a28caf0SHeinrich Schuchardt 294*8a28caf0SHeinrich SchuchardtSee ``spatch --help`` to learn more about spatch options. 295*8a28caf0SHeinrich Schuchardt 296*8a28caf0SHeinrich SchuchardtNote that the ``--use-glimpse`` and ``--use-idutils`` options 297*8a28caf0SHeinrich Schuchardtrequire external tools for indexing the code. None of them is 298*8a28caf0SHeinrich Schuchardtthus active by default. However, by indexing the code with 299*8a28caf0SHeinrich Schuchardtone of these tools, and according to the cocci file used, 300*8a28caf0SHeinrich Schuchardtspatch could proceed the entire code base more quickly. 301*8a28caf0SHeinrich Schuchardt 302*8a28caf0SHeinrich SchuchardtSmPL patch specific options 303*8a28caf0SHeinrich Schuchardt--------------------------- 304*8a28caf0SHeinrich Schuchardt 305*8a28caf0SHeinrich SchuchardtSmPL patches can have their own requirements for options passed 306*8a28caf0SHeinrich Schuchardtto Coccinelle. SmPL patch specific options can be provided by 307*8a28caf0SHeinrich Schuchardtproviding them at the top of the SmPL patch, for instance:: 308*8a28caf0SHeinrich Schuchardt 309*8a28caf0SHeinrich Schuchardt // Options: --no-includes --include-headers 310*8a28caf0SHeinrich Schuchardt 311*8a28caf0SHeinrich SchuchardtSmPL patch Coccinelle requirements 312*8a28caf0SHeinrich Schuchardt---------------------------------- 313*8a28caf0SHeinrich Schuchardt 314*8a28caf0SHeinrich SchuchardtAs Coccinelle features get added some more advanced SmPL patches 315*8a28caf0SHeinrich Schuchardtmay require newer versions of Coccinelle. If an SmPL patch requires 316*8a28caf0SHeinrich Schuchardtat least a version of Coccinelle, this can be specified as follows, 317*8a28caf0SHeinrich Schuchardtas an example if requiring at least Coccinelle >= 1.0.5:: 318*8a28caf0SHeinrich Schuchardt 319*8a28caf0SHeinrich Schuchardt // Requires: 1.0.5 320*8a28caf0SHeinrich Schuchardt 321*8a28caf0SHeinrich SchuchardtProposing new semantic patches 322*8a28caf0SHeinrich Schuchardt------------------------------- 323*8a28caf0SHeinrich Schuchardt 324*8a28caf0SHeinrich SchuchardtNew semantic patches can be proposed and submitted by kernel 325*8a28caf0SHeinrich Schuchardtdevelopers. For sake of clarity, they should be organized in the 326*8a28caf0SHeinrich Schuchardtsub-directories of ``scripts/coccinelle/``. 327*8a28caf0SHeinrich Schuchardt 328*8a28caf0SHeinrich Schuchardt 329*8a28caf0SHeinrich SchuchardtDetailed description of the ``report`` mode 330*8a28caf0SHeinrich Schuchardt------------------------------------------- 331*8a28caf0SHeinrich Schuchardt 332*8a28caf0SHeinrich Schuchardt``report`` generates a list in the following format:: 333*8a28caf0SHeinrich Schuchardt 334*8a28caf0SHeinrich Schuchardt file:line:column-column: message 335*8a28caf0SHeinrich Schuchardt 336*8a28caf0SHeinrich SchuchardtExample 337*8a28caf0SHeinrich Schuchardt~~~~~~~ 338*8a28caf0SHeinrich Schuchardt 339*8a28caf0SHeinrich SchuchardtRunning:: 340*8a28caf0SHeinrich Schuchardt 341*8a28caf0SHeinrich Schuchardt make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci 342*8a28caf0SHeinrich Schuchardt 343*8a28caf0SHeinrich Schuchardtwill execute the following part of the SmPL script:: 344*8a28caf0SHeinrich Schuchardt 345*8a28caf0SHeinrich Schuchardt <smpl> 346*8a28caf0SHeinrich Schuchardt @r depends on !context && !patch && (org || report)@ 347*8a28caf0SHeinrich Schuchardt expression x; 348*8a28caf0SHeinrich Schuchardt position p; 349*8a28caf0SHeinrich Schuchardt @@ 350*8a28caf0SHeinrich Schuchardt 351*8a28caf0SHeinrich Schuchardt ERR_PTR@p(PTR_ERR(x)) 352*8a28caf0SHeinrich Schuchardt 353*8a28caf0SHeinrich Schuchardt @script:python depends on report@ 354*8a28caf0SHeinrich Schuchardt p << r.p; 355*8a28caf0SHeinrich Schuchardt x << r.x; 356*8a28caf0SHeinrich Schuchardt @@ 357*8a28caf0SHeinrich Schuchardt 358*8a28caf0SHeinrich Schuchardt msg="ERR_CAST can be used with %s" % (x) 359*8a28caf0SHeinrich Schuchardt coccilib.report.print_report(p[0], msg) 360*8a28caf0SHeinrich Schuchardt </smpl> 361*8a28caf0SHeinrich Schuchardt 362*8a28caf0SHeinrich SchuchardtThis SmPL excerpt generates entries on the standard output, as 363*8a28caf0SHeinrich Schuchardtillustrated below:: 364*8a28caf0SHeinrich Schuchardt 365*8a28caf0SHeinrich Schuchardt /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg 366*8a28caf0SHeinrich Schuchardt /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth 367*8a28caf0SHeinrich Schuchardt /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg 368*8a28caf0SHeinrich Schuchardt 369*8a28caf0SHeinrich Schuchardt 370*8a28caf0SHeinrich SchuchardtDetailed description of the ``patch`` mode 371*8a28caf0SHeinrich Schuchardt------------------------------------------ 372*8a28caf0SHeinrich Schuchardt 373*8a28caf0SHeinrich SchuchardtWhen the ``patch`` mode is available, it proposes a fix for each problem 374*8a28caf0SHeinrich Schuchardtidentified. 375*8a28caf0SHeinrich Schuchardt 376*8a28caf0SHeinrich SchuchardtExample 377*8a28caf0SHeinrich Schuchardt~~~~~~~ 378*8a28caf0SHeinrich Schuchardt 379*8a28caf0SHeinrich SchuchardtRunning:: 380*8a28caf0SHeinrich Schuchardt 381*8a28caf0SHeinrich Schuchardt make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci 382*8a28caf0SHeinrich Schuchardt 383*8a28caf0SHeinrich Schuchardtwill execute the following part of the SmPL script:: 384*8a28caf0SHeinrich Schuchardt 385*8a28caf0SHeinrich Schuchardt <smpl> 386*8a28caf0SHeinrich Schuchardt @ depends on !context && patch && !org && !report @ 387*8a28caf0SHeinrich Schuchardt expression x; 388*8a28caf0SHeinrich Schuchardt @@ 389*8a28caf0SHeinrich Schuchardt 390*8a28caf0SHeinrich Schuchardt - ERR_PTR(PTR_ERR(x)) 391*8a28caf0SHeinrich Schuchardt + ERR_CAST(x) 392*8a28caf0SHeinrich Schuchardt </smpl> 393*8a28caf0SHeinrich Schuchardt 394*8a28caf0SHeinrich SchuchardtThis SmPL excerpt generates patch hunks on the standard output, as 395*8a28caf0SHeinrich Schuchardtillustrated below:: 396*8a28caf0SHeinrich Schuchardt 397*8a28caf0SHeinrich Schuchardt diff -u -p a/crypto/ctr.c b/crypto/ctr.c 398*8a28caf0SHeinrich Schuchardt --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 399*8a28caf0SHeinrich Schuchardt +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 400*8a28caf0SHeinrich Schuchardt @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct 401*8a28caf0SHeinrich Schuchardt alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, 402*8a28caf0SHeinrich Schuchardt CRYPTO_ALG_TYPE_MASK); 403*8a28caf0SHeinrich Schuchardt if (IS_ERR(alg)) 404*8a28caf0SHeinrich Schuchardt - return ERR_PTR(PTR_ERR(alg)); 405*8a28caf0SHeinrich Schuchardt + return ERR_CAST(alg); 406*8a28caf0SHeinrich Schuchardt 407*8a28caf0SHeinrich Schuchardt /* Block size must be >= 4 bytes. */ 408*8a28caf0SHeinrich Schuchardt err = -EINVAL; 409*8a28caf0SHeinrich Schuchardt 410*8a28caf0SHeinrich SchuchardtDetailed description of the ``context`` mode 411*8a28caf0SHeinrich Schuchardt-------------------------------------------- 412*8a28caf0SHeinrich Schuchardt 413*8a28caf0SHeinrich Schuchardt``context`` highlights lines of interest and their context 414*8a28caf0SHeinrich Schuchardtin a diff-like style. 415*8a28caf0SHeinrich Schuchardt 416*8a28caf0SHeinrich Schuchardt **NOTE**: The diff-like output generated is NOT an applicable patch. The 417*8a28caf0SHeinrich Schuchardt intent of the ``context`` mode is to highlight the important lines 418*8a28caf0SHeinrich Schuchardt (annotated with minus, ``-``) and gives some surrounding context 419*8a28caf0SHeinrich Schuchardt lines around. This output can be used with the diff mode of 420*8a28caf0SHeinrich Schuchardt Emacs to review the code. 421*8a28caf0SHeinrich Schuchardt 422*8a28caf0SHeinrich SchuchardtExample 423*8a28caf0SHeinrich Schuchardt~~~~~~~ 424*8a28caf0SHeinrich Schuchardt 425*8a28caf0SHeinrich SchuchardtRunning:: 426*8a28caf0SHeinrich Schuchardt 427*8a28caf0SHeinrich Schuchardt make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci 428*8a28caf0SHeinrich Schuchardt 429*8a28caf0SHeinrich Schuchardtwill execute the following part of the SmPL script:: 430*8a28caf0SHeinrich Schuchardt 431*8a28caf0SHeinrich Schuchardt <smpl> 432*8a28caf0SHeinrich Schuchardt @ depends on context && !patch && !org && !report@ 433*8a28caf0SHeinrich Schuchardt expression x; 434*8a28caf0SHeinrich Schuchardt @@ 435*8a28caf0SHeinrich Schuchardt 436*8a28caf0SHeinrich Schuchardt * ERR_PTR(PTR_ERR(x)) 437*8a28caf0SHeinrich Schuchardt </smpl> 438*8a28caf0SHeinrich Schuchardt 439*8a28caf0SHeinrich SchuchardtThis SmPL excerpt generates diff hunks on the standard output, as 440*8a28caf0SHeinrich Schuchardtillustrated below:: 441*8a28caf0SHeinrich Schuchardt 442*8a28caf0SHeinrich Schuchardt diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing 443*8a28caf0SHeinrich Schuchardt --- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 444*8a28caf0SHeinrich Schuchardt +++ /tmp/nothing 445*8a28caf0SHeinrich Schuchardt @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct 446*8a28caf0SHeinrich Schuchardt alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, 447*8a28caf0SHeinrich Schuchardt CRYPTO_ALG_TYPE_MASK); 448*8a28caf0SHeinrich Schuchardt if (IS_ERR(alg)) 449*8a28caf0SHeinrich Schuchardt - return ERR_PTR(PTR_ERR(alg)); 450*8a28caf0SHeinrich Schuchardt 451*8a28caf0SHeinrich Schuchardt /* Block size must be >= 4 bytes. */ 452*8a28caf0SHeinrich Schuchardt err = -EINVAL; 453*8a28caf0SHeinrich Schuchardt 454*8a28caf0SHeinrich SchuchardtDetailed description of the ``org`` mode 455*8a28caf0SHeinrich Schuchardt---------------------------------------- 456*8a28caf0SHeinrich Schuchardt 457*8a28caf0SHeinrich Schuchardt``org`` generates a report in the Org mode format of Emacs. 458*8a28caf0SHeinrich Schuchardt 459*8a28caf0SHeinrich SchuchardtExample 460*8a28caf0SHeinrich Schuchardt~~~~~~~ 461*8a28caf0SHeinrich Schuchardt 462*8a28caf0SHeinrich SchuchardtRunning:: 463*8a28caf0SHeinrich Schuchardt 464*8a28caf0SHeinrich Schuchardt make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci 465*8a28caf0SHeinrich Schuchardt 466*8a28caf0SHeinrich Schuchardtwill execute the following part of the SmPL script:: 467*8a28caf0SHeinrich Schuchardt 468*8a28caf0SHeinrich Schuchardt <smpl> 469*8a28caf0SHeinrich Schuchardt @r depends on !context && !patch && (org || report)@ 470*8a28caf0SHeinrich Schuchardt expression x; 471*8a28caf0SHeinrich Schuchardt position p; 472*8a28caf0SHeinrich Schuchardt @@ 473*8a28caf0SHeinrich Schuchardt 474*8a28caf0SHeinrich Schuchardt ERR_PTR@p(PTR_ERR(x)) 475*8a28caf0SHeinrich Schuchardt 476*8a28caf0SHeinrich Schuchardt @script:python depends on org@ 477*8a28caf0SHeinrich Schuchardt p << r.p; 478*8a28caf0SHeinrich Schuchardt x << r.x; 479*8a28caf0SHeinrich Schuchardt @@ 480*8a28caf0SHeinrich Schuchardt 481*8a28caf0SHeinrich Schuchardt msg="ERR_CAST can be used with %s" % (x) 482*8a28caf0SHeinrich Schuchardt msg_safe=msg.replace("[","@(").replace("]",")") 483*8a28caf0SHeinrich Schuchardt coccilib.org.print_todo(p[0], msg_safe) 484*8a28caf0SHeinrich Schuchardt </smpl> 485*8a28caf0SHeinrich Schuchardt 486*8a28caf0SHeinrich SchuchardtThis SmPL excerpt generates Org entries on the standard output, as 487*8a28caf0SHeinrich Schuchardtillustrated below:: 488*8a28caf0SHeinrich Schuchardt 489*8a28caf0SHeinrich Schuchardt * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] 490*8a28caf0SHeinrich Schuchardt * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] 491*8a28caf0SHeinrich Schuchardt * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]] 492