docs(tools/cppcheck): add application note on cppcheck
Add application note on cppcheck.
Change-Id: If5dbdfc5bad2d59f6fb617f2d98ba3e7a1fb1bef
Signed-off-by: Shruti Gupta <shruti.gupta@arm.com>
diff --git a/docs/getting_started/getting-started.rst b/docs/getting_started/getting-started.rst
index 87c003d..b8c8f87 100644
--- a/docs/getting_started/getting-started.rst
+++ b/docs/getting_started/getting-started.rst
@@ -32,6 +32,8 @@
Tool & Dependency overview
##########################
+.. _tool_dependencies:
+
The following tools are required to obtain and build |RMM|:
.. csv-table:: Tool dependencies
@@ -51,7 +53,7 @@
"docutils",">v2.38.0","Documentation"
"gcovr",">=v4.2","Tools(Coverage analysis)"
"CBMC",">=5.84.0","Tools(CBMC analysis)"
- "CPPcheck",">=1.90","Tools(CPPcheck)"
+ "CPPcheck",">=2.13.4","Tools(CPPcheck)"
.. _getting_started_toolchain:
@@ -216,15 +218,9 @@
The installation of Cppcheck is an optional step. This is required only
if using the Cppcheck static analysis.
-Follow the public documentation to install Cppcheck either from the official
-website https://cppcheck.sourceforge.io/ or from the official github
-https://github.com/danmar/cppcheck/
-
-If you own a valid copy of a MISRA rules file:
-
-.. code-block:: bash
-
- cp -a <path to the misra rules file>/<file name> ${RMM_SOURCE_DIR}/tools/cppcheck/misra.rules
+The recommended version of Cppcheck is indicated :ref:`above<tool_dependencies>`.
+See :ref:`Cppcheck Application Note` for installation steps and details
+on how to use it within RMM build system.
############
Install CBMC
diff --git a/docs/resources/application-notes/cppcheck.rst b/docs/resources/application-notes/cppcheck.rst
new file mode 100644
index 0000000..b860a47
--- /dev/null
+++ b/docs/resources/application-notes/cppcheck.rst
@@ -0,0 +1,128 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+.. SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
+
+*************************
+Cppcheck Application Note
+*************************
+
+Cppcheck is an open source static analysis tool for C/C++. In addition to
+various static analysis, it also has an addon to verify compliance with MISRA
+C 2012. Please refer to `Cppcheck Project Page`_ for details on Cppcheck.
+
+Cppcheck can be run standalone or along with MISRA addon from within the RMM
+build system. TF-RMM aims to have 0 outstanding errors with the recommended
+Cppcheck version mentioned :ref:`here<tool_dependencies>`.
+
+Installing Cppcheck
+===================
+
+Cppcheck can be installed directly from various package managers or built from
+source. However installing from package manager can get you an outdated
+version.
+
+For building from source, please refer to `Cppcheck GitHub`_ for downloading
+recommended version and build guidelines. Once Cppcheck is built, add both
+Cppcheck bin folder and Cppcheck-htmlreport folder to PATH. The latter
+is used to convert Cppcheck XML output into user friendly html report.
+
+.. code-block:: bash
+
+ export PATH=$cppcheck_root/build/bin:$cppcheck_root/htmlreport:$PATH
+ cppcheck --version
+
+The Cppcheck version should report the recommended version.
+
+Invoking Cppcheck rule within TF-RMM build system
+=================================================
+
+If you own a valid copy of a MISRA rules file, copy the file to the below
+location as it will give a more descriptive error message on detecting MISRA
+errors.
+
+.. code-block:: bash
+
+ cp -a <path to the misra rules file>/<file name> ${RMM_SOURCE_DIR}/tools/cppcheck/misra.rules
+
+To invoke the standard Cppcheck static analysis build rule on TF-RMM, run the
+`cppcheck` build target after TF-RMM configuration :
+
+.. code-block:: bash
+
+ cd $rmm_root
+ cmake -DRMM_CONFIG=fvp_defcfg -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+ cmake --build build -- cppcheck
+
+The `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON` generates a compile_commands.json
+file containing the exact compiler calls for all translation units of the
+project in machine-readable form.
+
+The successful execution of the build target will generate `cppcheck.xml`
+in `build/tools/cppcheck` folder.
+
+To invoke the Cppcheck static analysis with MISRA addon, run the
+`cppcheck-misra` build target:
+
+.. code-block:: bash
+
+ cd $rmm_root
+ cmake -DRMM_CONFIG=fvp_defcfg -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+ cmake --build build -- cppcheck-misra
+
+This will generate `cppcheck_misra.xml` in `build/tools/cppcheck` folder.
+
+Generating the Cppcheck HTML report
+===================================
+
+To generate html report in current directory after the Cppcheck build target
+has executed, run `cppcheck-htmlreport` tool with the genenerated xml file as
+input. For example, after the `cppcheck-misra` build target has completed,
+use the below cmd line to generate the html report :
+
+.. code-block:: bash
+
+ cppcheck-htmlreport --file=./build/tools/cppcheck/cppcheck_misra.xml --report-dir=test --source-dir=.
+
+The output will be generated in the specified `report-dir` and, for the above
+command, the html report can be found at `./test/index.html`.
+
+Cppcheck Error Suppression
+==========================
+
+TF-RMM as a project has decided to suppress some rules because either the rule
+is not found to be useful for the project or there are too many false positives
+generated by the rule. The global suppression rules are specified via
+`suppressions.txt` file present in `tools/cppcheck` directory.
+
+If more suppressions need to be added for Cppcheck, it can be done by adding it
+to the suppression rules file. For example, to skip `ext` folder from Cppcheck
+analysis, add the following line to the file :
+
+.. code-block:: bash
+
+ *:*/ext/*
+
+Suppression can be added inline to code as a comment. For example, to suppress
+the `uninitvar` rule on a particular line, add the following comment above the
+line :
+
+.. code-block:: C
+
+ /* cppcheck-suppress uninitvar */
+
+Multiple rules can be disabled via this method, as shown in example below :
+
+.. code-block:: C
+
+ /* cppcheck-suppress [arrayIndexOutOfBounds, uninitvar] */
+
+If a certain rule needs to be suppressed for a block of code, the block
+suppression format can be used as shown in example below:
+
+.. code-block:: C
+
+ /* cppcheck-suppress-begin uninitvar*/
+ block_of_code;
+ /* cppcheck-suppress-end uninitvar*/
+
+.. _Cppcheck Project Page: https://cppcheck.sourceforge.io/
+.. _Cppcheck GitHub: https://github.com/danmar/cppcheck
diff --git a/docs/resources/application-notes/index.rst b/docs/resources/application-notes/index.rst
index 535e96f..d2ebbe9 100644
--- a/docs/resources/application-notes/index.rst
+++ b/docs/resources/application-notes/index.rst
@@ -8,3 +8,4 @@
:caption: Contents
cbmc
+ cppcheck