User Tools

Site Tools


coccicheck

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
coccicheck [2015/10/22 13:46]
Luis R. Rodriguez
coccicheck [2018/01/17 14:05] (current)
Himanshu Jha [api] updated cocci rules
Line 3: Line 3:
 ===== coccicheck ===== ===== coccicheck =====
  
-'''​coccicheck'''​ is one of the targets of the Linux kernel, this page documents how you can use it, what it provides and how to help extend it. '''​coccicheck'''​ provides a series of semantic patches written in Semantic Patch Language (SmPL) and make use of the [[http://​coccinelle.lip6.fr/​|Coccinelle engine]] to interpret and complete these tests. These tests can help you vet for correctness and avoid certain bugs which have been able to be expressed semantically.+'''​coccicheck'''​ is one of the targets of the Linux kernel, this page documents how you can use it, what it provides and how to help extend it. '''​coccicheck'''​ provides a series of semantic patches written in Semantic Patch Language (SmPL) and makes use of the [[http://​coccinelle.lip6.fr/​|Coccinelle engine]] to interpret and complete these tests. These tests can help you vet for correctness and avoid certain bugs which have been able to be expressed semantically.
  
-If you're a developer you are encouraged to vet for your patch using cocciecheck to ensure you are not introducing issues which are known semantically. If you're a maintainer you are encouraged to be using coccicheck with M=your/​maintained-code-path so you can make use of the learned ​SmPL patches to avoid bugs in your maintained code. How maintainers can use this is explained below. Automatic code bot setups which test patches for inlusion ​upstream are encouraged to consider using 'make coccicheck'​ as well.+If you're a developer you are encouraged to vet your patch using cocciecheck to ensure you are not introducing issues which are known semantically. If you're a maintainer you are encouraged to be using coccicheck with M=your/​maintained-code-path so you can make use of the SmPL patches to avoid known bugs in your maintained code. How maintainers can use this is explained below. Automatic code bot setups which test patches for inclusion ​upstream are encouraged to consider using 'make coccicheck'​ as well.
  
 SmPL patches exist for a few different types of categories, documented below. SmPL patches exist for a few different types of categories, documented below.
Line 11: Line 11:
 ==== Confidence ==== ==== Confidence ====
  
-Eeach SmPL patch has a '''​confidence'''​ tag associated with it, to help highlight how confident the devlelopers of the SmPL patch are that the reports / fixes generated by the SmPL patch will be accurate or relevant. If an SmPL patch has a '''​High'''​ confidence annotated on it, it means that if you use coccicheck with it and it generates a report for a file there is a high degree of confidence that the report should be valid. Likewise if the confidence annotated is '''​Low'''​ you should take good care to review the report/​patch generated and vet for the validity of it before sending it to maintainers.+Eeach SmPL patch has a '''​confidence'''​ tag associated with it, to help highlight how confident the devlelopers of the SmPL patch are that the reports / fixes generated by the SmPL patch will be accurate ​and/or relevant. If an SmPL patch has a '''​High'''​ confidence annotated on it, it means that if you use coccicheck with it and it generates a report for a file there is a high degree of confidence that the report should be valid. Likewise if the confidence annotated is '''​Low'''​ you should take good care to review the report/​patch generated and vet the validity of it before sending it to maintainers.
  
 ==== Modes ==== ==== Modes ====
  
-There are three different modes you can use to use the semantic patches:+There are four different modes you can use to use the semantic patches:
  
-  * report - lets you generate a report - this is the '''​default'''​ mode if one is not specified +  ​* patch - lets you fix the issues found. 
-  * org xxx +  ​* report - lets you generate a report - this is the '''​default'''​ mode if one is not specified. 
-  * patch lets you fix the issues found+  * context ​highlights lines of interest and their context in a diff-like style. Lines of interest are indicated with '​-'​. 
 +  * org generates a report in the Org mode format of Emacs.
  
-You specify the mode want to operate+You specify the mode you want to operate. Note that not all semantic patches implement all modes. For easy use of Coccinelle, the default mode is "​report"​. 
 + 
 +Two other modes provide some common combinations of these modes. 
 + 
 +  * chain - tries the previous modes in the order above until one succeeds. 
 +  * rep+ctxt - runs successively the report mode and the context mode. It should be used with the C option (described later) which checks the code on a file basis.
  
 ==== Run tests ==== ==== Run tests ====
Line 30: Line 36:
 make coccicheck MODE=report make coccicheck MODE=report
 </​code>​ </​code>​
 +
 +To produce patches for the entire kernel, run:
 +
 +<code bash>
 +make coccicheck MODE=patch
 +</​code>​
 +
 +For each semantic patch, a commit message is proposed. ​ It gives a description of the problem being checked by the semantic patch, and includes a reference to Coccinelle.
 +
 +As any static code analyzer, Coccinelle produces false positives. Thus, reports must be carefully checked, and patches reviewed.
 +
 +==== Maintainer work ====
  
 If you are a maintainer you may want to use M=your/​maintained-path/​ to limit the scope to only the files you maintain. For instance the following will generate a report for all files in drivers/​net/​ only. If you are a maintainer you may want to use M=your/​maintained-path/​ to limit the scope to only the files you maintain. For instance the following will generate a report for all files in drivers/​net/​ only.
Line 42: Line 60:
  
 <code bash> <code bash>
-export ​COCCI=scripts/​coccinelle/​locks/​double_lock.cocci +make coccicheck ​COCCI=scripts/​coccinelle/​locks/​double_lock.cocci MODE=report
-make coccicheck ​MODE=report+
 </​code>​ </​code>​
  
-===== Types of tests ====+or 
 + 
 +<code bash> 
 +make coccicheck COCCI=scripts/​coccinelle/​locks/​double_lock.cocci MODE=patch 
 +</​code>​ 
 + 
 +===== Controlling Which Files are Processed by Coccinelle ===== 
 + 
 +By default the entire kernel source tree is checked. To apply Coccinelle to a specific directory, M= can be used. For example, to check drivers/​net/​wireless/​ one may write: 
 + 
 +<code bash> 
 +make coccicheck MODE=report M=drivers/​net/​wireless/​ 
 +</​code>​ 
 + 
 +To apply Coccinelle on a file basis, instead of a directory basis, the following command may be used: 
 + 
 +<code bash> 
 +make C=1 CHECK="​scripts/​coccicheck"​ 
 +</​code>​ 
 + 
 +To check only newly edited code, use the value 2 for the C flag, i.e. 
 + 
 +<code bash> 
 +make C=2 CHECK="​scripts/​coccicheck"​ 
 +</​code>​ 
 + 
 +In these modes, which work on a file basis, there is no information about semantic patches displayed, and no commit message proposed. 
 + 
 +This runs every semantic patch in scripts/​coccinelle by default. The COCCI variable may additionally be used to only apply a single semantic patch as shown in the previous section.  
 + 
 +The "​report"​ mode is the default. You can select another one with the MODE variable explained above. 
 + 
 +===== Additional flags ===== 
 + 
 +Additional flags can be passed to spatch through the SPFLAGS variable. 
 + 
 +<code bash> 
 +make SPFLAGS=--use-idutils coccicheck 
 +</​code>​ 
 + 
 +See spatch --help to learn more about spatch options. 
 + 
 +===== Proposing new semantic patches ====== 
 + 
 +New semantic patches can be proposed and submitted by kernel developers. For sake of clarity, they should be organized in the sub-directories of '​scripts/​coccinelle/'​. 
 + 
 +===== Types of tests =====
  
 Below we document each type of test category which as been devised. Below we document each type of test category which as been devised.
Line 60: Line 123:
 Remove casting the values returned by memory allocation functions like kmalloc, kzalloc, kmem_cache_alloc,​ kmem_cache_zalloc etc. This makes an effort to find cases of casting of values returned by kmalloc, kzalloc, kcalloc, kmem_cache_alloc,​ kmem_cache_zalloc,​ kmem_cache_alloc_node,​ kmalloc_node and kzalloc_node and removes the casting as it is not required. The result in the patch case may need some reformatting. Remove casting the values returned by memory allocation functions like kmalloc, kzalloc, kmem_cache_alloc,​ kmem_cache_zalloc etc. This makes an effort to find cases of casting of values returned by kmalloc, kzalloc, kcalloc, kmem_cache_alloc,​ kmem_cache_zalloc,​ kmem_cache_alloc_node,​ kmalloc_node and kzalloc_node and removes the casting as it is not required. The result in the patch case may need some reformatting.
  
-=== kzalloc-simple.cocci ===+=== zalloc-simple.cocci ===
  
-scripts/​coccinelle/​api/​alloc/​kzalloc-simple.cocci+scripts/​coccinelle/​api/​alloc/​zalloc-simple.cocci
  
-Use kzalloc ​rather than kmalloc ​followed by memset with 0. This considers some simple cases that are common and easy to validate. Note in particular that there are no ...s in the rule, so all of the matched code has to be contiguous.+Use zeroing memory allocator function ​rather than allocator ​followed by memset with 0. This considers some simple cases that are common and easy to validate. Note in particular that there are no ...s in the rule, so all of the matched code has to be contiguous.
  
 ==== free ==== ==== free ====
  
-Avoid freeing bugs+Avoid freeing bugs.
  
 ==== iterator ==== ==== iterator ====
  
-Help vet for correctness when using kernel iterators+Help vet for correctness when using kernel iterators.
  
 ==== locks ==== ==== locks ====
  
-Vet for correct locking behaviour and avoid bugs+Vet for correct locking behaviour and avoid bugs.
  
 ==== misc ==== ==== misc ====
Line 84: Line 147:
 ==== null ==== ==== null ====
  
-Avoid null bugs+Avoid null bugs.
  
 ==== tests ==== ==== tests ====
Line 92: Line 155:
 ===== Who runs these tests ===== ===== Who runs these tests =====
  
-Linux kernel maintainers are encouraged to make use of the cocciecheck ​to vet for issues on their tree. This can be used to help review quality of patches before they get merged into your tree as well.+Linux kernel maintainers are encouraged to make use of the coccicheck ​to vet for issues on their tree. This can be used to help review quality of patches before they get merged into your tree as well.
  
-These days coccicheck is run every now and then by Julia Lawall, false possitives ​are reviewed (in particular cocci files where confidence is annotated as low), and then once issues are confirmed patches typically are sent to maintainers.+These days coccicheck is run every now and then by Julia Lawall, false positives ​are reviewed (in particular cocci files where confidence is annotated as low), and then once issues are confirmed patches typically are sent to maintainers.
  
-Average developers can and should use coccicheck as well but care should be taken to ensure the '''​Confidence'''​ tag is reviewed and proper ​dilligence ​is done before sending any reports / fixes to kernel maintainers.+Average developers can and should use coccicheck as well but care should be taken to ensure the '''​Confidence'''​ tag is reviewed and proper ​diligence ​is done before sending any reports / fixes to kernel maintainers.
  
 It seems the zero day bot test infrastructure also makes use of 'make coccicheck'​ --- this section needs to be extended to document in what capacity this is done, how often, etc. It seems the zero day bot test infrastructure also makes use of 'make coccicheck'​ --- this section needs to be extended to document in what capacity this is done, how often, etc.
Line 102: Line 165:
 ===== How often are these tests run ===== ===== How often are these tests run =====
  
-The point of merging these SmPL patches upstream was to enable ​develoeprs ​and maintainers vet for code themselves. Ideally developers would run 'make coccicheck M=path/​to-their-code/'​ prior to submitting a patch upstream, and maintainers would use it regularly, perhaps after applying new patches, to avoid introducing new issues.+The point of merging these SmPL patches upstream was to enable ​developers ​and maintainers ​to vet code themselves. Ideally developers would run 'make coccicheck M=path/​to-their-code/'​ prior to submitting a patch upstream, and maintainers would use it regularly, perhaps after applying new patches, to avoid introducing new issues.
  
-Time permitting Julia will also run these tests on her own when possible as linux-next moves on. There is no specific regular interval in which these tests are run. The zero day bot tests infrasctructure ​also seems to use 'make coccicheck'​ -- but this section should be extended to document this.+Time permitting Julia will also run these tests on her own when possible as linux-next moves on. There is no specific regular interval in which these tests are run. The zero day bot test infrastructure ​also seems to use 'make coccicheck'​ -- but this section should be extended to document this.
coccicheck.1445521570.txt.gz · Last modified: 2015/10/22 13:46 by Luis R. Rodriguez