About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / coccinelle.txt




Custom Search

Based on kernel version 3.3. Page generated on 2012-03-23 21:25 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	
91	 Using Coccinelle with a single semantic patch
92	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
93	
94	The optional make variable COCCI can be used to check a single
95	semantic patch. In that case, the variable must be initialized with
96	the name of the semantic patch to apply.
97	
98	For instance:
99	
100		make coccicheck COCCI=<my_SP.cocci> MODE=patch
101	or
102		make coccicheck COCCI=<my_SP.cocci> MODE=report
103	
104	
105	 Controlling Which Files are Processed by Coccinelle
106	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
107	By default the entire kernel source tree is checked.
108	
109	To apply Coccinelle to a specific directory, M= can be used.
110	For example, to check drivers/net/wireless/ one may write:
111	
112	    make coccicheck M=drivers/net/wireless/
113	    
114	To apply Coccinelle on a file basis, instead of a directory basis, the
115	following command may be used:
116	
117	    make C=1 CHECK="scripts/coccicheck"
118	
119	To check only newly edited code, use the value 2 for the C flag, i.e.
120	
121	    make C=2 CHECK="scripts/coccicheck"
122	
123	This runs every semantic patch in scripts/coccinelle by default. The
124	COCCI variable may additionally be used to only apply a single
125	semantic patch as shown in the previous section.
126	
127	The "chain" mode is the default. You can select another one with the
128	MODE variable explained above.
129	
130	In this mode, there is no information about semantic patches
131	displayed, and no commit message proposed.
132	
133	
134	 Proposing new semantic patches
135	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
136	
137	New semantic patches can be proposed and submitted by kernel
138	developers. For sake of clarity, they should be organized in the
139	sub-directories of 'scripts/coccinelle/'.
140	
141	
142	 Detailed description of the 'report' mode
143	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
144	
145	'report' generates a list in the following format:
146	  file:line:column-column: message
147	
148	Example:
149	
150	Running
151	
152		make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci
153	
154	will execute the following part of the SmPL script.
155	
156	<smpl>
157	@r depends on !context && !patch && (org || report)@
158	expression x;
159	position p;
160	@@
161	
162	 ERR_PTR@p(PTR_ERR(x))
163	
164	@script:python depends on report@
165	p << r.p;
166	x << r.x;
167	@@
168	
169	msg="ERR_CAST can be used with %s" % (x)
170	coccilib.report.print_report(p[0], msg)
171	</smpl>
172	
173	This SmPL excerpt generates entries on the standard output, as
174	illustrated below:
175	
176	/home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg
177	/home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth
178	/home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg
179	
180	
181	 Detailed description of the 'patch' mode
182	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
183	
184	When the 'patch' mode is available, it proposes a fix for each problem
185	identified.
186	
187	Example:
188	
189	Running
190		make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci
191	
192	will execute the following part of the SmPL script.
193	
194	<smpl>
195	@ depends on !context && patch && !org && !report @
196	expression x;
197	@@
198	
199	- ERR_PTR(PTR_ERR(x))
200	+ ERR_CAST(x)
201	</smpl>
202	
203	This SmPL excerpt generates patch hunks on the standard output, as
204	illustrated below:
205	
206	diff -u -p a/crypto/ctr.c b/crypto/ctr.c
207	--- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200
208	+++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200
209	@@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct
210	 	alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,
211	 				  CRYPTO_ALG_TYPE_MASK);
212	 	if (IS_ERR(alg))
213	-		return ERR_PTR(PTR_ERR(alg));
214	+		return ERR_CAST(alg);
215	 
216	 	/* Block size must be >= 4 bytes. */
217	 	err = -EINVAL;
218	
219	 Detailed description of the 'context' mode
220	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
221	
222	'context' highlights lines of interest and their context
223	in a diff-like style.
224	
225	NOTE: The diff-like output generated is NOT an applicable patch. The
226	      intent of the 'context' mode is to highlight the important lines
227	      (annotated with minus, '-') and gives some surrounding context
228	      lines around. This output can be used with the diff mode of
229	      Emacs to review the code.
230	
231	Example:
232	
233	Running
234		make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci
235	
236	will execute the following part of the SmPL script.
237	
238	<smpl>
239	@ depends on context && !patch && !org && !report@
240	expression x;
241	@@
242	
243	* ERR_PTR(PTR_ERR(x))
244	</smpl>
245	
246	This SmPL excerpt generates diff hunks on the standard output, as
247	illustrated below:
248	
249	diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing
250	--- /home/user/linux/crypto/ctr.c	2010-05-26 10:49:38.000000000 +0200
251	+++ /tmp/nothing
252	@@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct
253	 	alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,
254	 				  CRYPTO_ALG_TYPE_MASK);
255	 	if (IS_ERR(alg))
256	-		return ERR_PTR(PTR_ERR(alg));
257	 
258	 	/* Block size must be >= 4 bytes. */
259	 	err = -EINVAL;
260	
261	 Detailed description of the 'org' mode
262	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
263	
264	'org' generates a report in the Org mode format of Emacs.
265	
266	Example:
267	
268	Running
269		make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci
270	
271	will execute the following part of the SmPL script.
272	
273	<smpl>
274	@r depends on !context && !patch && (org || report)@
275	expression x;
276	position p;
277	@@
278	
279	 ERR_PTR@p(PTR_ERR(x))
280	
281	@script:python depends on org@
282	p << r.p;
283	x << r.x;
284	@@
285	
286	msg="ERR_CAST can be used with %s" % (x)
287	msg_safe=msg.replace("[","@(").replace("]",")")
288	coccilib.org.print_todo(p[0], msg_safe)
289	</smpl>
290	
291	This SmPL excerpt generates Org entries on the standard output, as
292	illustrated below:
293	
294	* TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]]
295	* TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]]
296	* 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.