5 This section presents a range of examples. Each
6 example is presented along with some C code to which it is
7 applied. The description explains the rules and the matching process.
9 \subsection{Function renaming
}
11 One of the primary goals of Coccinelle is to perform software
12 evolution. For instance, Coccinelle could be used to perform function
13 renaming. In the following example, every occurrence of a call to the
14 function
\texttt{foo
} is replaced by a call to the
15 function
\texttt{bar
}.\\
18 Before & Semantic patch & After \\
19 \begin{minipage
}[t
]{.3\linewidth}
40 \begin{minipage
}[t
]{.3\linewidth}
41 \begin{lstlisting
}[language=Cocci
]
52 \begin{minipage
}[t
]{.3\linewidth}
75 \subsection{Removing a function argument
}
77 Another important kind of evolution is the introduction or deletion of a
78 function argument. In the following example, the rule
\texttt{rule1
} looks
79 for definitions of functions having return type
\texttt{irqreturn
\_t} and
80 two parameters. A second
\emph{anonymous
} rule then looks for calls to the
81 previously matched functions that have three arguments. The third argument
82 is then removed to correspond to the new function prototype.\\
85 \begin{lstlisting
}[language=Cocci,name=arg
]
88 identifier irq, dev_id;
92 static irqreturn_t fn (int irq, void *dev_id)
99 expression E1, E2, E3;
111 \texttt{drivers/atm/firestream.c
} at line
1653 before transformation\\
112 \begin{lstlisting
}[language=PatchC
]
113 static void fs_poll (unsigned long data)
115 struct fs_dev *dev = (struct fs_dev *) data;
117 @- fs_irq (
0, dev, NULL);
118 dev->timer.expires = jiffies + FS_POLL_FREQ;
119 add_timer (&dev->timer);
126 \texttt{drivers/atm/firestream.c
} at line
1653 after transformation\\
127 \begin{lstlisting
}[language=PatchC
]
128 static void fs_poll (unsigned long data)
130 struct fs_dev *dev = (struct fs_dev *) data;
133 dev->timer.expires = jiffies + FS_POLL_FREQ;
134 add_timer (&dev->timer);
140 \subsection{Introduction of a macro
}
142 To avoid code duplication or error prone code, the kernel provides
143 macros such as
\texttt{BUG
\_ON},
\texttt{DIV
\_ROUND\_UP} and
144 \texttt{FIELD
\_SIZE}. In these cases, the semantic patches look for
145 the old code pattern and replace it by the new code.\\
147 A semantic patch to introduce uses of the
\texttt{DIV
\_ROUND\_UP} macro
148 looks for the corresponding expression,
\emph{i.e.
}, $(n + d -
1) /
149 d$. When some code is matched, the metavariables
\texttt{n
} and
\texttt{d
}
150 are bound to their corresponding expressions. Finally, Coccinelle rewrites
151 the code with the
\texttt{DIV
\_ROUND\_UP} macro using the values bound to
152 \texttt{n
} and
\texttt{d
}, as illustrated in the patch that follows.\\
155 Semantic patch to introduce uses of the
\texttt{DIV
\_ROUND\_UP} macro\\
156 \begin{lstlisting
}[language=Cocci,name=divround
]
160 #include <linux/kernel.h>
162 @M@ depends on haskernel @
167 @-- (((n) + (d)) -
1) / (d))
168 @++ DIV_ROUND_UP(n,d)
170 @-- (((n) + ((d) -
1)) / (d))
171 @++ DIV_ROUND_UP(n,d)
179 Example of a generated patch hunk\\
180 \begin{lstlisting
}[language=PatchC
]
181 @---- a/drivers/atm/horizon.c
182 @++++ b/drivers/atm/horizon.c
183 @M@@ -
698,
7 +
698,
7 @@ got_it:
185 *bits = (div<<CLOCK_SELECT_SHIFT) | (pre-
1);
187 @-- *actual = (br + (pre<<div) -
1) / (pre<<div);
188 @++ *actual = DIV_ROUND_UP(br, pre<<div);
189 PRINTD (DBG_QOS, "actual rate:
%u", *actual);
197 The
\texttt{BUG
\_ON} macro makes a assertion about the value of an
198 expression. However, because some parts of the kernel define
199 \texttt{BUG
\_ON} to be the empty statement when debugging is not wanted,
200 care must be taken when the asserted expression may have some side-effects,
201 as is the case of a function call. Thus, we create a rule introducing
202 \texttt{BUG
\_ON} only in the case when the asserted expression does not
203 perform a function call.
205 On particular piece of code that has the form of a function call is a use
206 of
\texttt{unlikely
}, which informs the compiler that a particular
207 expression is unlikely to be true. In this case, because
\texttt{unlikely
}
208 does not perform any side effects, it is safe to use
\texttt{BUG
\_ON}. The
209 second rule takes care of this case. It furthermore disables the
210 isomorphism that allows a call to
\texttt{unlikely
} be replaced with its
211 argument, as then the second rule would be the same as the first one.\\
214 \begin{lstlisting
}[language=Cocci,name=bugon
]
220 if (<+... f(...) ...+>)
{ BUG();
}
222 @-- if (E)
{ BUG();
}
226 @M@ disable unlikely @
231 if (<+... f(...) ...+>)
{ BUG();
}
233 @-- if (unlikely(E))
{ BUG();
}
239 For instance, using the semantic patch above, Coccinelle generates
240 patches like the following one.
243 \begin{lstlisting
}[language=PatchC
]
244 @---- a/fs/ext3/balloc.c
245 @++++ b/fs/ext3/balloc.c
246 @M@@ -
232,
8 +
232,
7 @@ restart:
249 printk("Window map complete.
\n");
254 #define rsv_window_dump(root, verbose) \
255 __rsv_window_dump((root), (verbose), __FUNCTION__)
260 \subsection{Look for
\texttt{NULL
} dereference
}
262 This SmPL match looks for
\texttt{NULL
} dereferences. Once an
263 expression has been compared to
\texttt{NULL
}, a dereference to this
264 expression is prohibited unless the pointer variable is reassigned.\\
272 printk ("Error
%s", foo->here);
285 \begin{lstlisting
}[language=Cocci
]
294 ... when != if (E == NULL) S1 else S2
309 \begin{lstlisting
}[language=PatchC
]
312 @- printk ("Error
%s", foo->here);
321 \subsection{Reference counter: the of
\_xxx API
}
323 Coccinelle can embed Python code. Python code is used inside special
324 SmPL rule annotated with
\texttt{script:python
}. Python rules inherit
325 metavariables, such as identifier or token positions, from other SmPL
326 rules. The inherited metavariables can then be manipulated by Python
329 The following semantic match looks for a call to the
330 \texttt{of
\_find\_node\_by\_name} function. This call increments a
331 counter which must be decremented to release the resource. Then, when
332 there is no call to
\texttt{of
\_node\_put}, no new assignment to the
333 \texttt{device
\_node} variable
\texttt{n
} and a
\texttt{return
}
334 statement is reached, a bug is detected and the position
\texttt{p1
}
335 and
\texttt{p2
} are initialized. As the Python only depends on the
336 positions
\texttt{p1
} and
\texttt{p2
}, it is evaluated. In the
337 following case, some emacs Org mode data are produced. This example
338 illustrates the various fields that can be accessed in the Python code from
342 \begin{lstlisting
}[language=Cocci,breaklines=true
]
344 local idexpression struct device_node *n;
351 if (!(n@p1 = of_find_node_by_name(...))) S1
353 n@p1 = of_find_node_by_name(...)
355 <... when != of_node_put(n)
356 when != if (...)
{ <+... of_node_put(n) ...+>
}
357 when != true !n || ...
377 print "* TODO
[[view:
%s::face=ovl-face1::linb=%s::colb=%s::cole=%s][inc. counter:%s::%s]]" % (p1[0].file,p1[0].line,p1[0].column,p1[0].column_end,p1[0].file,p1[0].line)
378 print "
[[view:
%s::face=ovl-face2::linb=%s::colb=%s::cole=%s][return]]" % (p2[0].file,p2[0].line,p2[0].column,p2[0].column_end)
385 Lines
13 to
17 list a variety of constructs that should not appear
386 between a call to
\texttt{of
\_find\_node\_by\_name} and a buggy return
387 site. Examples are a call to
\texttt{of
\_node\_put} (line
13) and a
388 transition into the then branch of a conditional testing whether
389 \texttt{n
} is
\texttt{NULL
} (line
15). Any number of conditionals
390 testing whether
\texttt{n
} is
\texttt{NULL
} are allowed as indicated
391 by the use of a nest
\texttt{<...~~...>
} to describe the path between
392 the call to
\texttt{of
\_find\_node\_by\_name}, the return and the
393 conditional in the pattern on line
18.\\
395 The previously semantic match has been used to generate the following
396 lines. They may be edited using the emacs Org mode to navigate in the code
397 from a site to another.
399 \begin{lstlisting
}[language=,breaklines=true
]
400 * TODO
[[view:/linux-next/arch/powerpc/platforms/pseries/setup.c::face=ovl-face1::linb=
236::colb=
18::cole=
20][inc. counter:/linux-next/arch/powerpc/platforms/pseries/setup.c::
236]]
401 [[view:/linux-next/arch/powerpc/platforms/pseries/setup.c::face=ovl-face2::linb=
250::colb=
3::cole=
9][return
]]
402 * TODO
[[view:/linux-next/arch/powerpc/platforms/pseries/setup.c::face=ovl-face1::linb=
236::colb=
18::cole=
20][inc. counter:/linux-next/arch/powerpc/platforms/pseries/setup.c::
236]]
403 [[view:/linux-next/arch/powerpc/platforms/pseries/setup.c::face=ovl-face2::linb=
245::colb=
3::cole=
9][return
]]
406 Note~: Coccinelle provides some predefined Python functions,
407 \emph{i.e.
},
\texttt{cocci.print
\_main},
\texttt{cocci.print
\_sec} and
408 \texttt{cocci.print
\_secs}. One could alternatively write the following
409 SmPL rule instead of the previously presented one.
412 \begin{lstlisting
}[language=Cocci
]
419 cocci.print_sec(p2,"return")
423 The function
\texttt{cocci.print
\_secs} is used when there is several
424 positions which are matched by a single position variable and that
425 every matched position should be printed.
427 Any metavariable could be inherited in the Python code. However,
428 accessible fields are not currently equally supported among them.
431 \subsection{Filtering identifiers, declarers or iterators with regular expression
}
433 If you consider the following SmPL file which uses the regexp functionality to
434 filter the identifiers that contain, begin or end by
\texttt{foo
},
436 \begin{tabular
}{c@
{\hspace{2cm
}}c
}
437 \begin{lstlisting
}[language=Cocci, name=Regexp
]
447 print "Identifier:
%s" % x
451 identifier foo ~= ".*foo";
458 print "Contains foo:
%s" % x
462 \begin{lstlisting
}[language=Cocci,name=Regexp
]
465 identifier foo ~= ".*foo$";
473 print "Ends by foo:
%s" % x
477 identifier foo ~= "^foo";
484 print "Begins by foo:
%s" % x
488 and the following C program, on the left, which defines the functions
489 \texttt{foo
},
\texttt{bar
},
\texttt{foobar
},
\texttt{barfoobar
} and
490 \texttt{barfoo
}, you will get the result on the right.
492 \begin{tabular
}{c@
{\hspace{2cm
}}c
}
494 int foo ()
{ return
0;
}
495 int bar ()
{ return
0;
}
496 int foobar ()
{ return
0;
}
497 int barfoobar ()
{ return
0;
}
498 int barfoo ()
{ return
0;
}
505 Identifier: barfoobar
509 Contains foo: barfoobar
514 Begins by foo: foobar
518 % \begin{tabular}{ccc}
519 % Before & Semantic patch & After \\
520 % \begin{minipage}[t]{.3\linewidth}
525 % \begin{minipage}[t]{.3\linewidth}
526 % \begin{lstlisting}[language=Cocci]
530 % \begin{minipage}[t]{.3\linewidth}
538 %%% TeX-master: "main_grammar"
541 %%% ispell-local-dictionary: "american"