About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / coccinelle.txt




Custom Search

Based on kernel version 3.9. Page generated on 2013-05-02 22:55 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 the 'virtual rule'
10	feature which was introduced in Coccinelle version 0.1.11.
11	
12	Coccinelle (>=0.2.0) is available through the package manager
13	of many distributions, e.g. :
14	
15	 - Debian (>=squeeze)
16	 - Fedora (>=13)
17	 - Ubuntu (>=10.04 Lucid Lynx)
18	 - OpenSUSE
19	 - Arch Linux
20	 - NetBSD
21	 - FreeBSD
22	
23	
24	You can get the latest version released from the Coccinelle homepage at
25	http://coccinelle.lip6.fr/
26	
27	Information and tips about Coccinelle are also provided on the wiki
28	pages at http://cocci.ekstranet.diku.dk/wiki/doku.php
29	
30	Once you have it, run the following command:
31	
32	     	./configure
33	        make
34	
35	as a regular user, and install it with
36	
37	        sudo make install
38	
39	The semantic patches in the kernel will work best with Coccinelle version
40	0.2.4 or later.  Using earlier versions may incur some parse errors in the
41	semantic patch code, but any results that are obtained should still be
42	correct.
43	
44	 Using Coccinelle on the Linux kernel
45	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
46	
47	A Coccinelle-specific target is defined in the top level
48	Makefile. This target is named 'coccicheck' and calls the 'coccicheck'
49	front-end in the 'scripts' directory.
50	
51	Four modes are defined: patch, report, context, and org. The mode to
52	use is specified by setting the MODE variable with 'MODE=<mode>'.
53	
54	'patch' proposes a fix, when possible.
55	
56	'report' generates a list in the following format:
57	  file:line:column-column: message
58	
59	'context' highlights lines of interest and their context in a
60	diff-like style.Lines of interest are indicated with '-'.
61	
62	'org' generates a report in the Org mode format of Emacs.
63	
64	Note that not all semantic patches implement all modes. For easy use
65	of Coccinelle, the default mode is "chain" which tries the previous
66	modes in the order above until one succeeds.
67	
68	To make a report for every semantic patch, run the following command:
69	
70		make coccicheck MODE=report
71	
72	NB: The 'report' mode is the default one.
73	
74	To produce patches, run:
75	
76		make coccicheck MODE=patch
77	
78	
79	The coccicheck target applies every semantic patch available in the
80	sub-directories of 'scripts/coccinelle' to the entire Linux kernel.
81	
82	For each semantic patch, a commit message is proposed.  It gives a
83	description of the problem being checked by the semantic patch, and
84	includes a reference to Coccinelle.
85	
86	As any static code analyzer, Coccinelle produces false
87	positives. Thus, reports must be carefully checked, and patches
88	reviewed.
89	
90	To enable verbose messages set the V= variable, for example:
91	
92	   make coccicheck MODE=report V=1
93	
94	
95	 Using Coccinelle with a single semantic patch
96	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
97	
98	The optional make variable COCCI can be used to check a single
99	semantic patch. In that case, the variable must be initialized with
100	the name of the semantic patch to apply.
101	
102	For instance:
103	
104		make coccicheck COCCI=<my_SP.cocci> MODE=patch
105	or
106		make coccicheck COCCI=<my_SP.cocci> MODE=report
107	
108	
109	 Controlling Which Files are Processed by Coccinelle
110	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
111	By default the entire kernel source tree is checked.
112	
113	To apply Coccinelle to a specific directory, M= can be used.
114	For example, to check drivers/net/wireless/ one may write:
115	
116	    make coccicheck M=drivers/net/wireless/
117	    
118	To apply Coccinelle on a file basis, instead of a directory basis, the
119	following command may be used:
120	
121	    make C=1 CHECK="scripts/coccicheck"
122	
123	To check only newly edited code, use the value 2 for the C flag, i.e.
124	
125	    make C=2 CHECK="scripts/coccicheck"
126	
127	This runs every semantic patch in scripts/coccinelle by default. The
128	COCCI variable may additionally be used to only apply a single
129	semantic patch as shown in the previous section.
130	
131	The "chain" mode is the default. You can select another one with the
132	MODE variable explained above.
133	
134	In this mode, there is no information about semantic patches
135	displayed, and no commit message proposed.
136	
137	
138	 Proposing new semantic patches
139	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
140	
141	New semantic patches can be proposed and submitted by kernel
142	developers. For sake of clarity, they should be organized in the
143	sub-directories of 'scripts/coccinelle/'.
144	
145	
146	 Detailed description of the 'report' mode
147	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
148	
149	'report' generates a list in the following format:
150	  file:line:column-column: message
151	
152	Example:
153	
154	Running
155	
156		make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci
157	
158	will execute the following part of the SmPL script.
159	
160	<smpl>
161	@r depends on !context && !patch && (org || report)@
162	expression x;
163	position p;
164	@@
165	
166	 ERR_PTR@p(PTR_ERR(x))
167	
168	@script:python depends on report@
169	p << r.p;
170	x << r.x;
171	@@
172	
173	msg="ERR_CAST can be used with %s" % (x)
174	coccilib.report.print_report(p[0], msg)
175	</smpl>
176	
177	This SmPL excerpt generates entries on the standard output, as
178	illustrated below:
179	
180	/home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg
181	/home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth
182	/home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg
183	
184	
185	 Detailed description of the 'patch' mode
186	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
187	
188	When the 'patch' mode is available, it proposes a fix for each problem
189	identified.
190	
191	Example:
192	
193	Running
194		make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci
195	
196	will execute the following part of the SmPL script.
197	
198	<smpl>
199	@ depends on !context && patch && !org && !report @
200	expression x;
201	@@
202	
203	- ERR_PTR(PTR_ERR(x))
204	+ ERR_CAST(x)
205	</smpl>
206	
207	This SmPL excerpt generates patch hunks on the standard output, as
208	illustrated below:
209	
210	diff -u -p a/crypto/ctr.c b/crypto/ctr.c
211	--- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200
212	+++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200
213	@@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct
214	 	alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,
215	 				  CRYPTO_ALG_TYPE_MASK);
216	 	if (IS_ERR(alg))
217	-		return ERR_PTR(PTR_ERR(alg));
218	+		return ERR_CAST(alg);
219	 
220	 	/* Block size must be >= 4 bytes. */
221	 	err = -EINVAL;
222	
223	 Detailed description of the 'context' mode
224	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
225	
226	'context' highlights lines of interest and their context
227	in a diff-like style.
228	
229	NOTE: The diff-like output generated is NOT an applicable patch. The
230	      intent of the 'context' mode is to highlight the important lines
231	      (annotated with minus, '-') and gives some surrounding context
232	      lines around. This output can be used with the diff mode of
233	      Emacs to review the code.
234	
235	Example:
236	
237	Running
238		make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci
239	
240	will execute the following part of the SmPL script.
241	
242	<smpl>
243	@ depends on context && !patch && !org && !report@
244	expression x;
245	@@
246	
247	* ERR_PTR(PTR_ERR(x))
248	</smpl>
249	
250	This SmPL excerpt generates diff hunks on the standard output, as
251	illustrated below:
252	
253	diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing
254	--- /home/user/linux/crypto/ctr.c	2010-05-26 10:49:38.000000000 +0200
255	+++ /tmp/nothing
256	@@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct
257	 	alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,
258	 				  CRYPTO_ALG_TYPE_MASK);
259	 	if (IS_ERR(alg))
260	-		return ERR_PTR(PTR_ERR(alg));
261	 
262	 	/* Block size must be >= 4 bytes. */
263	 	err = -EINVAL;
264	
265	 Detailed description of the 'org' mode
266	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
267	
268	'org' generates a report in the Org mode format of Emacs.
269	
270	Example:
271	
272	Running
273		make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci
274	
275	will execute the following part of the SmPL script.
276	
277	<smpl>
278	@r depends on !context && !patch && (org || report)@
279	expression x;
280	position p;
281	@@
282	
283	 ERR_PTR@p(PTR_ERR(x))
284	
285	@script:python depends on org@
286	p << r.p;
287	x << r.x;
288	@@
289	
290	msg="ERR_CAST can be used with %s" % (x)
291	msg_safe=msg.replace("[","@(").replace("]",")")
292	coccilib.org.print_todo(p[0], msg_safe)
293	</smpl>
294	
295	This SmPL excerpt generates Org entries on the standard output, as
296	illustrated below:
297	
298	* TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]]
299	* TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]]
300	* 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
Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.