docs/contributing/standards/misra.rst

################
MISRA-C Standard
################

************
Introduction
************

The project checks for MISRA-C violations and cautions in the code base by running the Eclair
MISRA-C compliance tool as part of our CI process. The results for the daily job can be found at
`TF-M Eclair daily CI pipeline`_.

The project, is not fully MISRA-C compliant. However, it aims to be MISRA-C-friendly by:

    - Avoiding the introduction mandatory MISRA-C violations and cautions.
    - Running regular checks on the code base.
    - Analysing and documenting violations and cautions prompted by the Eclair MISRA-C static
      analyser. This can be useful for downstream consumer looking for MISRA-C compliance.

While the project's intention is to keep violations and cautions to a minimum, it will not block new
features, bug fixes, or improvements even if they introduce difficult-to-resolve cautions or
violations. Currently, the project is not equipped with necessary fast-feedback-loop tooling to
inform contributors about the MISRA-C violations/cautions they introduce. The project welcomes
suggestions and contributions to better align with the MISRA-C standard.

.. Note::
   In this document, `Caution` refers to a `caution report` generated by Eclair MISRA-C static
   analyser.

***************
Update schedule
***************

The analysis table for mandatory rules will be updated with every release. Currently, the table is
up-to-date for release v2.2.0.

************************************************************
Assessment of mandatory MISRA-C rules violation and cautions
************************************************************

The following table presents an analysis of the violations and cautions of mandatory MISRA-C:2012
rules report by Eclair.

The reported violations cannot be easily resolved with the current code structure and are discussed
further in the table. The project is not actively prioritizing their resolution; however, as
mentioned earlier, it welcomes suggestions and contributions from the community.

The community should proactively address any cautions that can be reasonably resolved. However, if
resolving a caution does not positively affect code quality and readability, it may be safely
ignored.

+------------------------+-------------+------------------------+-------------------------+
|MISRA-C rule Mandatory  |Error Type   |Rule definition         |Explanation              |
+========================+=============+========================+=========================+
|Rule 9.1                |Caution      |The value of an object  |Cautions are due to the  |
|                        |             |with automatic storage  |objects not being        |
|                        |             |duration shall not be   |explicitly initialised   |
|                        |             |read before it has been |during declaration. In   |
|                        |             |set                     |some of the cases the    |
|                        |             |                        |address of the object    |
|                        |             |                        |is passed to a function  |
|                        |             |                        |to retrieve required     |
|                        |             |                        |value which gives the    |
|                        |             |                        |appearance that the      |
|                        |             |                        |object is used           |
|                        |             |                        |uninitialized.           |
+------------------------+-------------+------------------------+-------------------------+
|Rule 17.4               |Violation    |All exit paths from a   |All violations are       |
|                        |             |function with non-void  |exactly the same case    |
|                        |             |return type shall have  |of having a naked        |
|                        |             |an explicit 'return'    |function with no C       |
|                        |             |statement with an       |return statement. This   |
|                        |             |expression              |cannot be resolved due   |
|                        |             |                        |to the body of the       |
|                        |             |                        |function being written   |
|                        |             |                        |in assembly.             |
+------------------------+-------------+------------------------+-------------------------+
|Rule 21.17              |Caution      |Use of the string       |Currently seen with      |
|                        |             |handling functions from |`tfm_arch_init_context`. |
|                        |             |`<string.h>` shall not  |It is used to clear the  |
|                        |             |result in accesses      |memory (stack) to be     |
|                        |             |beyond the bounds of the|used to store program    |
|                        |             |objects referenced by   |context (as part of the  |
|                        |             |their pointer parameters|context                  |
|                        |             |                        |initialisation).         |
|                        |             |                        |Remember, stack grows    |
|                        |             |                        |downwards - hence,       |
|                        |             |                        |pointer is decremented   |
|                        |             |                        |in the implementation.   |
+------------------------+-------------+------------------------+-------------------------+
|Rule 21.18              |Caution      |The `size_t` argument   |Functions in TF-M use    |
|                        |             |passed to any function  |`<string.h>` functions   |
|                        |             |in `<string.h>` shall   |with buffers/objects     |
|                        |             |have an appropriate     |passed in by the         |
|                        |             |value                   |caller. The functions    |
|                        |             |                        |suspected by Eclair have |
|                        |             |                        |been double checked for  |
|                        |             |                        |verifying size of        |
|                        |             |                        |buffer/object before     |
|                        |             |                        |using them.              |
+------------------------+-------------+------------------------+-------------------------+

*****************************************************
List of required MISRA-C rules violation and cautions
*****************************************************

The list of required  MISRA-C rules violations can be found in \
`TF-M Eclair daily CI pipeline`_ -> Last Successful Artefacts -> \
index.html -> Report by issue strictness (Mandatory/Required/Advisory) (violations)

.. _TF-M Eclair daily CI pipeline: https://ci.trustedfirmware.org/view/TF-M/job/tf-m-eclair-daily/

--------------

*SPDX-License-Identifier: BSD-3-Clause*

*SPDX-FileCopyrightText: Copyright The TrustedFirmware-M Contributors*