michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: add parasoft tool section to the coding guidelines page

Browse source 
Recently we started to use Parasoft Codescan Static Analysis tool
to fix MISRA violations and align code to follow our Coding Guidelines.
I started fixing violations, and adding suppression tages to fix
false-positive findings. Developers started to ask me, what I'm doing
here and where is the documentation page about that.

Add a new section describing violations fixing process using Parasoft
tool.

Signed-off-by: Maksim Masalski <maksim.masalski@intel.com>
This commit is contained in:
Maksim Masalski 2021-07-13 11:19:30 +08:00 • committed by Christopher Friedt
commit 843ea97eac
1 changed files with 99 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

99
doc/contribute/coding_guidelines/index.rst
View file

@ -952,3 +952,102 @@ Related GitHub Issues and Pull Requests are tagged with the `Inclusive Language
.. _Bluetooth Appropriate Language Mapping Tables: https://btprodspecificationrefs.blob.core.windows.net/language-mapping/Appropriate_Language_Mapping_Table.pdf
.. _OSHWA Resolution to Redefine SPI Signal Names: https://www.oshwa.org/a-resolution-to-redefine-spi-signal-names/
.. _Zephyr issue 27033: https://github.com/zephyrproject-rtos/zephyr/issues/27033
Parasoft Codescan Tool
**********************
Parasoft Codescan is an official static code analysis tool used by the Zephyr
project. It is used to automate compliance with a range of coding and security
standards.
The tool is currently set to the MISRA-C:2012 Coding Standard because the Zephyr
:ref:`coding_guidelines` are based on that standard.
It is used together with the Coverity Scan tool to achieve the best code health
and precision in bug findings.
Violations fixing process
=========================
Step 1
Any Zephyr Project member, company or a developer can request access
to the Parasoft reporting centre if they wish to get involved in fixing
violations by submitting issues.
Step 2
A developer starts to review violations.
Step 3
A developer submits a Github PR with the fix. Commit messages should follow
the same guidelines as other PRs in the Zephyr project. Please add a comment
that your fix was found by a static coding scanning tool.
Developers should follow and refer to the Zephyr :ref:`coding_guidelines`
as basic rules for coding. These rules are based on the MISRA-C standard.
Below you can find an example of a recommended commit message::
lib: os: add braces to 'if' statements
An 'if' (expression) construct shall be followed by a compound statement.
Add braces to improve readability and maintainability.
Found as a coding guideline violation (Rule 15.6) by static
coding scanning tool.
Signed-off-by: Johnny Developer <johnny.developer@company.com>
Step 4
If a violation is a false positive, the developer should mark it for the Codescan
tool just like they would do for the Coverity tool.
The developer should also add a comment to the code explaining that
the violation raised by the static code analysis tool should be considered a
false positive.
Step 5
If the developer has found a real violation that the community decided to ignore,
the developer must submit a PR with a suppression tag
and a comment explaining why the violation has been deviated.
The template structure of the comment and tag in the code should be::
/* Explain why that part of the code doesn't follow the standard,
* explain why it is a deliberate deviation from the standard.
* Don't refer to the Parasoft tool here, just mention that static code
* analysis tool raised a violation in the line below.
*/
code_line_with_a_violation /* parasoft-suppress Rule ID */
Below you can find an example of a recommended commit message::
testsuite: suppress usage of setjmp in a testcode (rule 21.4)
According to the Rule 21.4 the standard header file <setjmp.h> shall not
be used. We will suppress this violation because it is in
test code. Tag suppresses reporting of the violation for the
line where the violation is located.
This is a deliberate deviation.
Found as a coding guideline violation (Rule 21.4) by static coding
scanning tool.
Signed-off-by: Johnny Developer <johnny.developer@company.com>
The example below demonstrates how deviations can be suppressed in the code::
/* Static code analysis tool can raise a violation that the standard
* header <setjmp.h> shall not be used.
* Since this violation is in test code, we will suppress it.
* Deliberate deviation.
*/
#include <setjmp.h> /* parasoft-suppress MISRAC2012-RULE_21_4-a MISRAC2012-RULE_21_4-b */
This variant above suppresses item ``MISRAC2012-RULE_21_4-a`` and ``MISRAC2012-RULE_21_4-b``
on the line with "setjump" header include. You can add as many rules to suppress you want -
just make sure to keep the Parasoft tag on one line and separate rules with a space.
To read more about suppressing findings in the Parasoft tool, refer to the
official Parasoft `documentation`_
.. _documentation: https://docs.parasoft.com/display/CPPTEST1031/Suppressing+Findings
Step 6
After a PR is submitted, the developer should add the ``Coding guidelines``
and ``MISRA-C`` Github labels so their PR can be easily tracked by maintainers.
If you have any concerns about what your PR should look like, you can search
on Github using those tags and refer to similar PRs that have already been merged.