Why do you need the MISRA Compliance report and how to generate one in PVS-Studio?
- What is MISRA Compliance?
- Ways to achieve MISRA Compliance
- MISRA Compliance report generation in PVS-Studio
- Additional resources:
If you are strongly interested in MISRA and would like to understand whether your project meets one of the MISRA association's standards, there is a solution. Its name is MISRA Compliance. PVS-Studio has recently learned how to generate the MISRA Compliance report. This article describes how you can use this feature. This can make somebody's life better.
What is MISRA Compliance?
MISRA Compliance is a standard that allows you to understand whether your project conforms to the MISRA C/C++ standards, its deviations, and re-categorizations. MISRA Compliance can be applied to all MISRA association standards, but in this article, we'll review its use with the MISRA C 2012 standard.
The MISRA C 2012 guidelines recognize that in some cases compliance is unjustified or even impossible. All deviations from the rules must be documented. However, after that, it may become difficult to understand whether a program conforms to this standard. Here's where the MISRA Compliance standard is helpful.
Ways to achieve MISRA Compliance
The main goal is to understand whether your project complies with MISRA C 2012. To do this, we must obtain the GCS (Guideline Compliance Summary). The GCS includes an entry for each guideline, and records the level of compliance with it, as permitted by its MISRA category. Simply put, we need to display the rule's number, the rule's category, and information about whether code complies with it. Here is an example of what this should look like:
By default, the rule's number and category are taken from the standard. However, MISRA Compliance allows you to change (re-categorize) the level of guidelines, although this is not necessary. Each specific user does this for each specific project according to GRP (Guideline Re-categorization Plan). GRP is a set of acceptable shifts from one level to the other. The table below demonstrates this:
To make it easier for you to understand, let me give you an example. Suppose we have the 1.1 rule whose level is Required. According to the table, we can raise the warning level to Mandatory or leave it as-is (green cells). At the same time lowering the level to Advisory or Disapplied is not allowed (red cells).
Based on the resulting categories, you can specify rule compliance. Possible compliance variants for MISRA categories look like this:
You can use this table to determine whether your project complies with the MISRA C 2012 standard. Specifically, if your project hits the red zone (see the table above) at least once, that means your project does not comply with the standard.
To make this simpler, let's take rule 1.1 that has the standard value of the category equal to Required. If you look at the table, you can see that acceptable compliance values for Required are Compliance or Deviations (I'll talk more about the meaning of these statuses later). This means that if your project complies with rule 1.1, or if it complies with this rule with some deviations - everything is fine and you can go to the next rule. If you get at least one hit in Violations or Disapplied, then the project does not comply with MISRA C 2012. If all rules have acceptable values only, congratulations! Your project complies with the MISRA C 2012 standard. If you have a hit in the red zone (the table above), you do not comply with the standard.
That's mostly everything there is to know about how the MISRA Compliance report is generated.
MISRA Compliance report generation in PVS-Studio
In order to generate the report, use the PlogConverter.exe or the plog-converter utilities on Windows and Unix respectively. These utilities are also available as part of PVS-Studio distributions. As I am writing this article, PVS-Studio can produce a compliance report only for the MISRA C 2012 standard. All features described above will also be available starting with PVS-Studio 7.15 or request a beta-version.
To generate the MISRA Compliance report, you need to run the analysis. To learn how to do this on Windows - click here, on Unix - here. It's important that you turn on all MISRA-related diagnostics. Otherwise, you would be voluntarily reducing MISRA coverage. Use the analysis documentation, whose links I provided earlier, to check that you have all MISRA-related rules enabled.
Then use one of the report conversion utilities. Here is an example of how to run PlogConverter.exe:
"C:\Program Files (x86)\PVS-Studio\PlogConverter.exe" "path_to_report_file" \ -t MisraCompliance -o "path_to_MISRA_report" --grp "path_to_grp.txt"
And below is a sample command for plog-converter:
plog-converter "path_to_report_file" -t misra_compliance \ -o "path_to_MISRA_report" --grp "path_to_grp.txt"
The report you get is an html page that is conveniently formatted for printing. Here is what a report looks like, when a project does not comply with MISRA C 2012:
And this is what a report looks like when a project complies with MISRA C 2012:
Let's take a closer look at the columns:
- Guideline contains rule and directive numbers from the MISRA C standard;
- Category shows the category that a rule or a directive indicated in the guideline column has;
- Recategorication contains a category a rule or a directive has after it's been re-categorized according to GRP;
- Compliance contains information about the checked code's compliance with a rule or directive. If a value is red, this means your code does not comply with the MISRA C 2012 standard.
In our case, GRP is a txt file. Below is an example of a file with acceptable deviations:
Rule 2.1 = Mandatory Rule 8.13 = Required Directive 4.3 = Mandatory Rule 2.6 = Disapplied
If this file contains a category down-shift, the utility will issue an error message and will not generate the report. The only exception is the Advisory category that can deviate to Disapplied. Just in case, this is the categories' order, from the most important to the least important:
The compliance states of the code checked mean the following:
- Compliant - the project has not deviations from this rule;
- Deviations - deviations from a rule were found and documented. The number of approved deviations is shown in the parentheses. You can ask the utility to ignore a specific warning. To do this, mark it as a false alarm;
- Violations - there is at least one rule deviation that has not been documented. The number of such deviations is indicated in parentheses. If a project contains both rule Violations and Deviations, both states will be displayed;
- Disapplied - the category is disabled and is not to be taken into account in any way. Applicable only to the Advisory categories;
- Not Supported - the analyzer does not support this rule. At the moment when I am writing this article, PVS-Studio covers 60% of the MISRA C 2012 standard. But we do not stop here. By the end of this year, we plan to increase MISRA coverage up to 85%. You can read about our current progress with MISRA here.
The most important thing in all of this - you get the Guideline Compliance report that shows whether your project complies or does not comply with the MISRA C 2012 standard. The MISRA C 2012 standard - compliant code meets the following conditions:
- All Mandatory rules have the Compliant status;
- All Required rules have the Compliant and/or Deviations status;
- Advisory rules have any status;
- Disapplied rules are ignored.
Go ahead and try our new report! If you have any difficulties, problems or feedback - write to our support.