About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / coccinelle.txt


Based on kernel version 4.8. Page generated on 2016-10-06 23:10 EST.

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


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog