About Me
I'm a researcher at Inria, in Paris France. I develop the tool Coccinelle, which allows easy matching and transformation of C code. Coccinelle has been designed with the goal of contributing to Linux development, but it can also be used on other C code.
Please write to me directly if you would like to apply to the Coccinelle Outreachy project.
Overview
This page is organized into two parts. The first part is about learning to use Coccinelle. The second part has some small tasks that are relevant for the documentation project. If you are interested in working on the Coccinelle project, you should do some work from both parts.
For the Coccinelle part, it would be a good idea to start with the first challenge problem, to check that you know how to use the tool properly. The remaining challenge problems can be done in any order. It is not obligatory to do all of them. You may find other things that can be done with Coccinelle. Sources of inspiration may be the results of checkpatch and patches that have been applied to the kernel in the past. Any kind of problem that occurs over and over might be amenable to being solved with Coccinelle.
These challenge problems may apply to many files in the kernel. Pick a few files, and send patches for those. Once they have been accepted, consider moving on to another challenge problem. You will get a better understanding of Coccinelle if you use it for many different things than if you use it do one thing over and over.
There are many examples of uses of Coccinelle, in previous patches, in the kernel source tree in the scripts/coccinelle directory, and at coccinellery. If you use a script that is already in the Linux kernel, you don't need to include the script in your commit log, but rather something like Generated-by: scripts/coccinelle/misc/badty.cocci
Tutorial
A tutorial for Coccinelle is available here. These are slides that are intended to be presented, but they may be understandable independently of the presentation. Please note that the tutorial focuses on the source code of Linux 3.2, and so the patches created in doing the exercises of the tutorial are not suitable for submission to the ooutreachy-kernel mailing list. Doing the tutorial also does not count as a contribution to the project.
Coccinelle challenge problem 1
Consider the following function, from drivers/staging/most/hdm-dim2/dim2_sysfs.c (Note that this file no longer exists. If you want to experiment with this code, just create a new .c file containing this function definition.)
static ssize_t bus_kobj_attr_store(struct kobject *kobj, struct attribute *attr,
const char *buf, size_t count)
{
ssize_t ret;
struct medialb_bus *bus =
container_of(kobj, struct medialb_bus, kobj_group);
struct bus_attr *xattr = container_of(attr, struct bus_attr, attr);
if (!xattr->store)
return -EIO;
ret = xattr->store(bus, buf, count);
return ret;
}In this function, the last two lines could be compressed into one, as:
static ssize_t bus_kobj_attr_store(struct kobject *kobj, struct attribute *attr,
const char *buf, size_t count)
{
ssize_t ret;
struct medialb_bus *bus =
container_of(kobj, struct medialb_bus, kobj_group);
struct bus_attr *xattr = container_of(attr, struct bus_attr, attr);
if (!xattr->store)
return -EIO;
return xattr->store(bus, buf, count);
}The following semantic patch makes this change:
@@
local idexpression ret;
expression e;
@@
-ret =
+return
e;
-return ret;Do the following:
- Download and install Coccinelle. If you are using Linux, it should be available in your package manager. Any recent version is fine to start
with, but you may need to get the most recent version, which is 1.0.4. This is available on the Coccinelle webpage (coccinelle.lip6.fr) and on github.
- Download staging-testing
- Save the above semantic patch in a file ret.cocci
Run Coccinelle on ret.cocci and staging-testing, ie spatch --sp-file ret.cocci --no-includes --dir {your staging-testing path}/drivers/staging > ret.out. This may take some time.
Do you find the result satisfactory? If so, submit some patches. If not, let us know!
Your code may now declare some variables that are never used. Remove them before submitting your patch.
If you do submit a patch based on the use of Coccinelle, please mention Coccinelle in your patch, and the semantic patch that you used.
What happens in the above semantic patch if you replace local idexpression by identifier or expression? Try these extra variants and see if there are any differences in the results.
Coccinelle challenge problem 2
Parentheses are not needed around the right hand side of an assignment, like in value = (FLASH_CMD_STATUS_REG_READ << 24);. Write a semantic patch to remove these parentheses.
One could consider that parentheses might be useful in the case of eg rising = (dir == IIO_EV_DIR_RISING); because there could be a confusion between the different kinds of =. Extend your semantic patch using a disjunction so that it does not report on such cases.
Other kinds of code do not need parentheses, such as a->b in &(a->b), function arguments, and the argument of return.
Coccinelle challenge problem 3
Some functions return NULL as a return value on failure. NULL can be tested for as !x, NULL == x, or x == NULL. When NULL represents failure, eg of an allocation, !x is commonly used. The following are some functions that commonly follow this strategy:
kmalloc devm_kzalloc kmalloc_array devm_ioremap usb_alloc_urb alloc_netdev dev_alloc_skb
Write a semantic patch to clean up the tests on the results of one or more of these functions.
Coccinelle challenge problem 4
Kmalloc and variants normally produce a backtrace when there is not enough memory, so it is not necessary to print an error message that provides only this information. Write a semantic patch that removes such print statements. Note that doing so may results in an if that has only one statement in a branch, so the surrounding braces should also be removed in this case
Hint: A metavariable declared as constant char[] c; matches any string constant.
Coccinelle challenge problem 5
The Linux kernel coding style guidelines discourage the use of typedefs for struct types. There are several opportunities for using Coccinelle here.
You can write a semantic patch to find such typedefs. Typedefs are often found in header files. To be sure that Coccinelle looks at all available header files, use the argument --include-headers. Note also that the name set by a typedef matches a metavariable of type type.
- If you find such a typedef, to remove it, you need to adjust all the uses. This can be done using a semantic patch.
- You can also fully automate the process. Note that the name of a typedef typically ends in _t and thus that name is not directly suitable as a name for the struct type. You will need to use python code to remove the _t. The file coccinelle/demos/pythontococci.cocci can help in doing this, as it shows how to declare a variable in python code and then use it in pattern matching code.
By default, Coccinelle only works on .c files, including only .h files that have the same name as the .c file. Typedefs, however are likely to be in .h files. You can try the argument --all-includes, to try to include the .h files in the treatment of each .c file. That will make it possible to update both the typedef and its uses. To work on the .h files individually, you can use the option --include-headers. In that case you will have to update the uses of the types separately, by hand or with another semantic patch.
Coccinelle challenge problem 6
The file include/linux/list.h contains many functions and macros for manipulating lists. For example, when some expression l points into a list, ie has type struct list_head *, then list_entry(l, type, member) can be used to access the current list element, rather than using container_of. Make a semantic patch to use list_entry when possible. When you find a change opportunity, consider whether some other nearby code could also be reimplemented to use a list operator.
Hint: A metavariable declares as struct list_head *l; will only match an expression of type struct list_head *.
Coccinelle challenge problem 7
list_for_each is a macro that iterates over the elements of a (doubly linked) list. list_entry is a function that takes as argument a list pointer and returns the structure that is pointed to. list_for_each_entry is a macro that iterates over the structures in the list, rather than exposing the list spine.
Often a list is only used for its entries, and thus list_for_each_entry can be used instead of the composition of list_for_each and list_entry.
An exmple of the transformation is as follows (commit 711584ea4c8ce):
- list_for_each(p, &hci_cb_list) {
- struct hci_cb *cb = list_entry(p, struct hci_cb, list);
+ list_for_each_entry(cb, &hci_cb_list, list) {
if (cb->security_cfm)
cb->security_cfm(conn, status, encrypt);
}An criterion for the transformation is that p should not be used in the loop body.
Note that in this example, the variable holding the result of list_entry is only defined inside the loop in the old code. Since that variable is moved up into the loop header, its declaration has to be moved up as well. At the same time, the variable p is no longer used inside the loop, and is indeed no longer used in the function at all, and thus its declaration can be dropped completely. You can automate as much of this as you like.
There are currently few opportunities for this transformation in staging drivers.
Coccinelle challenge problem 8
Sometimes a variable is declared and at the same time initialized to the result of calling some function, and thus function does some simple task, such as accessing a structure field. If the value of this function call doesn't change, the variable can be used rather than calling the function again. Write a semantic patch to detect, and potentially correct, these issues.
Other Coccinelle challenge problems
You can also try the Coccinelle challenge problems from round 8, Coccinelle challenge problems from round 9, and Coccinelle challenge problems from round 10.
Contact info
Email: <Julia.Lawall AT lip6 DOT fr>
My IRC handle is jlawall.
Questions about using Coccinelle should go to the Coccinelle mailing list: <cocci AT systeme DOT lip6 DOT fr>