1.. SPDX-License-Identifier: BSD-3-Clause
2.. SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
3
4*************************
5Cppcheck Application Note
6*************************
7
8Cppcheck is an open source static analysis tool for C/C++. In addition to
9various static analysis, it also has an addon to verify compliance with MISRA
10C 2012. Please refer to `Cppcheck Project Page`_ for details on Cppcheck.
11
12Cppcheck can be run standalone or along with MISRA addon from within the RMM
13build system. TF-RMM aims to have 0 outstanding errors with the recommended
14Cppcheck version mentioned in :ref:`tool_dependencies`.
15
16Installing Cppcheck
17===================
18
19Cppcheck can be installed directly from various package managers or built from
20source. However installing from package manager can get you an outdated
21version.
22
23For building from source, please refer to `Cppcheck GitHub`_ for downloading
24recommended version and build guidelines. Once Cppcheck is built, add both
25Cppcheck binary folder and Cppcheck-htmlreport folder to PATH. The latter
26is used to convert Cppcheck XML output into user friendly html report.
27Asssuming that `build` is the output folder for Cppcheck build:
28
29.. code-block:: bash
30
31    export PATH=$cppcheck_root/build/bin:$cppcheck_root/htmlreport:$PATH
32    cppcheck --version
33
34The Cppcheck version should report the recommended version.
35
36Invoking Cppcheck rule within TF-RMM build system
37=================================================
38
39If you own a valid copy of a MISRA rules file, copy the file to the below
40location as it will give a more descriptive error message on detecting MISRA
41errors.
42
43.. code-block:: bash
44
45    cp -a <path to the misra rules file>/<file name> ${RMM_SOURCE_DIR}/tools/cppcheck/misra.rules
46
47To invoke the standard Cppcheck static analysis build rule on TF-RMM, run the
48`cppcheck` build target after TF-RMM configuration :
49
50.. code-block:: bash
51
52    cd $rmm_root
53    cmake -DRMM_CONFIG=fvp_defcfg -S . -B build  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
54    cmake --build build -- cppcheck
55
56The `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON` generates a compile_commands.json
57file containing the exact compiler calls for all translation units of the
58project in machine-readable form.
59
60The successful execution of the build target will generate `cppcheck.xml`
61in `build/tools/cppcheck` folder.
62
63To invoke the Cppcheck static analysis with MISRA addon, run the
64`cppcheck-misra` build target:
65
66.. code-block:: bash
67
68    cd $rmm_root
69    cmake -DRMM_CONFIG=fvp_defcfg -S . -B build  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
70    cmake --build build -- cppcheck-misra
71
72This will generate `cppcheck_misra.xml` in `build/tools/cppcheck` folder.
73
74If the above generated xml contains error tags detected by Cppcheck and
75if the installed version of Cppcheck matches or exceeds the recommended
76version mentioned in :ref:`tool_dependencies`, the build fails and prints
77the error count. However, if the installed version is less than the
78recommended version, a warning is generated and the output is not parsed
79for errors.
80
81Generating the Cppcheck HTML report
82===================================
83
84To generate html report in current directory after the Cppcheck build target
85has executed, run `cppcheck-htmlreport` tool with the genenerated xml file as
86input. For example, after the `cppcheck-misra` build target has completed,
87use the below cmd line to generate the html report :
88
89.. code-block:: bash
90
91    cppcheck-htmlreport --file=./build/tools/cppcheck/cppcheck_misra.xml --report-dir=test --source-dir=.
92
93The output will be generated in the specified `report-dir` and, for the above
94command, the html report can be found at `./test/index.html`.
95
96Cppcheck Error Suppression
97==========================
98
99TF-RMM as a project has decided to suppress some rules because either the rule
100is not found to be useful for the project or there are too many false positives
101generated by the rule. The global suppression rules are specified via
102`suppressions.txt` file present in `tools/cppcheck` directory.
103
104If more suppressions need to be added for Cppcheck, it can be done by adding it
105to the suppression rules file. For example, to skip `ext` folder from Cppcheck
106analysis, add the following line to the file :
107
108.. code-block:: bash
109
110        *:*/ext/*
111
112Suppression can be added inline to code as a comment. For example, to suppress
113the `uninitvar` rule on a particular line, add the following comment above the
114line :
115
116.. code-block:: C
117
118    /* cppcheck-suppress uninitvar */
119
120Multiple rules can be disabled via this method, as shown in example below :
121
122.. code-block:: C
123
124    /* cppcheck-suppress [arrayIndexOutOfBounds, uninitvar] */
125
126If a certain rule needs to be suppressed for a block of code, the block
127suppression format can be used as shown in example below:
128
129.. code-block:: C
130
131    /* cppcheck-suppress-begin uninitvar */
132    block_of_code;
133    /* cppcheck-suppress-end uninitvar */
134
135.. _Cppcheck Project Page: https://cppcheck.sourceforge.io/
136.. _Cppcheck GitHub: https://github.com/danmar/cppcheck
137