docs: Add cross references in userguide
This patch adds necessary cross references to CBMC and Cppcheck
application note from build examples and getting started guides.
The contribution guide is also enhanced to add notes about static
analysis as part of the contribution workflow.
Some minor corrections are also made in the cppcheck application
note.
Signed-off-by: Soby Mathew <soby.mathew@arm.com>
Change-Id: I67fe84b154f14dd49152862b5bdd4402ddb88881
diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst
index ecb32c1..03fa3c1 100644
--- a/docs/getting_started/build-options.rst
+++ b/docs/getting_started/build-options.rst
@@ -100,19 +100,25 @@
8. Perform a Cppcheck static analysis:
+Refer to :ref:`Cppcheck Application Note` for details on installing and running cppcheck
+static analysis.
+
.. code-block:: bash
cmake -DRMM_CONFIG=fvp_defcfg -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
cmake --build ${RMM_BUILD_DIR} -- cppcheck
- cat ${BUILD_DIR}/tools/cppcheck/cppcheck.xml
+ cat ${RMM_BUILD_DIR}/tools/cppcheck/cppcheck.xml
9. Perform a Cppcheck static analysis with MISRA:
+Refer to :ref:`Cppcheck Application Note` for details on installing and running cppcheck
+static analysis.
+
.. code-block:: bash
cmake -DRMM_CONFIG=fvp_defcfg -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
cmake --build ${RMM_BUILD_DIR} -- cppcheck-misra
- cat ${BUILD_DIR}/tools/cppcheck/cppcheck_misra.xml
+ cat ${RMM_BUILD_DIR}/tools/cppcheck/cppcheck_misra.xml
10. Perform a checkpatch analysis:
@@ -244,6 +250,8 @@
cmake -DRMM_CONFIG=host_defcfg -DHOST_VARIANT=host_cbmc -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
cmake --build ${RMM_BUILD_DIR} -- cbmc-coverage cbmc-analysis cbmc-assert
+Refer to :ref:`CBMC` Application Note for details on installing and running CBMC.
+
.. _build_options_table:
###################
diff --git a/docs/getting_started/getting-started.rst b/docs/getting_started/getting-started.rst
index b8c8f87..367b1d6 100644
--- a/docs/getting_started/getting-started.rst
+++ b/docs/getting_started/getting-started.rst
@@ -1,6 +1,8 @@
.. SPDX-License-Identifier: BSD-3-Clause
.. SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
+.. _getting_started:
+
#############
Prerequisite
#############
@@ -28,12 +30,12 @@
arm64/AArch64 Ubuntu and other Linux distributions should also work fine,
provided that the necessary tools and libraries can be installed.
+.. _tool_dependencies:
+
##########################
Tool & Dependency overview
##########################
-.. _tool_dependencies:
-
The following tools are required to obtain and build |RMM|:
.. csv-table:: Tool dependencies
@@ -53,7 +55,7 @@
"docutils",">v2.38.0","Documentation"
"gcovr",">=v4.2","Tools(Coverage analysis)"
"CBMC",">=5.84.0","Tools(CBMC analysis)"
- "CPPcheck",">=2.13.4","Tools(CPPcheck)"
+ "Cppcheck",">=2.13.4","Tools(Cppcheck)"
.. _getting_started_toolchain:
@@ -159,7 +161,7 @@
On Ubuntu, ``gcovr`` tool can be installed in two different ways:
-Using the pagckage manager:
+Using the package manager:
.. code-block:: bash
@@ -209,6 +211,9 @@
You can read more about Git hooks in the *githooks* page of the `Git hooks
documentation`_.
+General contribution guidelines for contributors can be found in
+:ref:`Contributor's Guide`.
+
#################################
Install Cppcheck and dependencies
#################################
@@ -218,7 +223,7 @@
The installation of Cppcheck is an optional step. This is required only
if using the Cppcheck static analysis.
-The recommended version of Cppcheck is indicated :ref:`above<tool_dependencies>`.
+The recommended version of Cppcheck is indicated in :ref:`tool_dependencies`.
See :ref:`Cppcheck Application Note` for installation steps and details
on how to use it within RMM build system.
@@ -235,6 +240,23 @@
website https://www.cprover.org/cbmc/ or from the official github
https://github.com/diffblue/cbmc
+Refer to :ref:`CBMC` Application Notes for details on installation and
+running CBMC analysis on TF-RMM sources.
+
+##################
+Install Clang-tidy
+##################
+
+Clang-tidy is included in LLVM release package. It can also be installed via
+package manager :
+
+.. code-block:: bash
+
+ sudo apt-get install clang-tidy
+
+Note that the ``RMM_TOOLCHAIN`` needs to be set to `llvm` to run clang-tidy
+build targets from RMM build system.
+
###########################
Performing an Initial Build
###########################
diff --git a/docs/process/contributing.rst b/docs/process/contributing.rst
index 4667f07..b9fa3d6 100644
--- a/docs/process/contributing.rst
+++ b/docs/process/contributing.rst
@@ -48,8 +48,16 @@
- Follow the :ref:`Coding Standard`.
- - Use the static checks as shown in :ref:`build_options_examples` to perform
- checks like checkpatch, checkspdx, header files include order etc.
+- Use the static checks as shown in :ref:`build_options_examples` to perform
+ checks like checkpatch, checkspdx, header files include order, clang-tidy,
+ cppcheck etc. A sample static analysis command line is given below, assuming
+ the tools have been setup as per instruction in :ref:`getting_started`.
+
+ .. code-block:: bash
+
+ cd $rmm_root
+ cmake -DRMM_CONFIG=fvp_defcfg -S . -B build -DRMM_TOOLCHAIN=llvm -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+ cmake --build build -- checkpatch checkspdx-patch checkincludes-patch clang-tidy-patch cppcheck-misra
- Where appropriate, please update the documentation.
@@ -64,9 +72,6 @@
- Please test your changes and add suitable tests in the available test
frameworks for any new functionality.
-- Ensure that all CI automated tests pass. Failures should be fixed. They
- might block a patch, depending on how critical they are.
-
Submitting Changes
==================
diff --git a/docs/resources/application-notes/cppcheck.rst b/docs/resources/application-notes/cppcheck.rst
index b860a47..13647b6 100644
--- a/docs/resources/application-notes/cppcheck.rst
+++ b/docs/resources/application-notes/cppcheck.rst
@@ -11,7 +11,7 @@
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>`.
+Cppcheck version mentioned in :ref:`tool_dependencies`.
Installing Cppcheck
===================
@@ -22,8 +22,9 @@
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
+Cppcheck binary folder and Cppcheck-htmlreport folder to PATH. The latter
is used to convert Cppcheck XML output into user friendly html report.
+Asssuming that `build` is the output folder for Cppcheck build:
.. code-block:: bash
@@ -120,9 +121,9 @@
.. code-block:: C
- /* cppcheck-suppress-begin uninitvar*/
+ /* cppcheck-suppress-begin uninitvar */
block_of_code;
- /* cppcheck-suppress-end uninitvar*/
+ /* cppcheck-suppress-end uninitvar */
.. _Cppcheck Project Page: https://cppcheck.sourceforge.io/
.. _Cppcheck GitHub: https://github.com/danmar/cppcheck