[v2,1/2] docs/misra: introduce rules.rst

Commit Message

Stefano Stabellini June 1, 2022, 1:44 a.m. UTC

From: Stefano Stabellini <[e-mail]>

Introduce a list of MISRA C rules that apply to the Xen hypervisor. The
list is in RST format.

Specify that rules deviations need to be documented. Introduce a
documentation tag for in-code comments to mark them as deviations. Also
mention that other documentation mechanisms are work-in-progress.

Add a mention of the new list to CODING_STYLE.

Signed-off-by: Stefano Stabellini <[e-mail]>
Signed-off-by: Bertrand Marquis <[e-mail]>
---

Note that I don't feel strongly about the deviations format. At this
stage anything is OK in my view. We'll need to improve it as we go along
and as we start to integrate better with MISRA C checkers. That said,
certainly an in-code comment with a special tag is a safe bet in terms
of tools integration (easy to parse, easy to convert.) We'll need other
mechanisms too and that's why I kept the sentence about "Other
documentation mechanisms are work-in-progress."

Changes in v2:
- clarify that deviations are permitted
- introduce an in-code tag for deviations
- improve the document format, make it proper reStructuredText
- improve commit message
---
 CODING_STYLE         |   6 +++
 docs/index.rst       |  12 +++++
 docs/misra/rules.rst | 123 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 141 insertions(+)
 create mode 100644 docs/misra/rules.rst

Comments

Julien Grall June 1, 2022, 5:18 p.m. UTC | #1

Hi Stefano,

On 01/06/2022 02:44, Stefano Stabellini wrote:
> From: Stefano Stabellini <[e-mail]>
> 
> Introduce a list of MISRA C rules that apply to the Xen hypervisor. The
> list is in RST format.
> 
> Specify that rules deviations need to be documented. Introduce a
> documentation tag for in-code comments to mark them as deviations. Also
> mention that other documentation mechanisms are work-in-progress.
> 
> Add a mention of the new list to CODING_STYLE.
> 
> Signed-off-by: Stefano Stabellini <[e-mail]>
> Signed-off-by: Bertrand Marquis <[e-mail]>

Acked-by: Julien Grall <[e-mail]>

Cheers,

Patch

diff --git a/CODING_STYLE b/CODING_STYLE
index 9f50d9cec4..3386ee1d90 100644
--- a/CODING_STYLE
+++ b/CODING_STYLE
@@ -14,6 +14,12 @@  explicitly (e.g. tools/libxl/CODING_STYLE) but often implicitly (Linux
 coding style is fairly common). In general you should copy the style
 of the surrounding code. If you are unsure please ask.
 
+MISRA C
+-------
+
+The Xen Hypervisor follows some MISRA C coding rules. See
+docs/misra/rules.rst for details.
+
 Indentation
 -----------
 
diff --git a/docs/index.rst b/docs/index.rst
index b75487a05d..2c47cfa999 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -53,6 +53,18 @@  kind of development environment.
    hypervisor-guide/index
 
 
+MISRA C coding guidelines
+-------------------------
+
+MISRA C rules and directive to be used as coding guidelines when writing
+Xen hypervisor code.
+
+.. toctree::
+   :maxdepth: 2
+
+   misra/rules
+
+
 Miscellanea
 -----------
 
diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
new file mode 100644
index 0000000000..7d6a9fe063
--- /dev/null
+++ b/docs/misra/rules.rst
@@ -0,0 +1,123 @@ 
+.. SPDX-License-Identifier: CC-BY-4.0
+
+MISRA C rules for Xen
+=====================
+
+.. note::
+
+   **IMPORTANT** All MISRA C rules, text, and examples are copyrighted
+   by the MISRA Consortium Limited and used with permission.
+
+   Please refer to https://www.misra.org.uk/ to obtain a copy of MISRA
+   C, or for licensing options for other use of the rules.
+
+The following is the list of MISRA C rules that apply to the Xen
+hypervisor.
+
+It is possible that in specific circumstances it is best not to follow a
+rule because it is not possible or because the alternative leads to
+better code quality. Those cases are called "deviations". They are
+permissible as long as they are documented as an in-code comment using
+the following format::
+
+    /*
+     * MISRA_DEV: Rule ID
+     * Justification text.
+     */
+
+Other documentation mechanisms are work-in-progress.
+
+The existing codebase is not 100% compliant with the rules. Some of the
+violations are meant to be documented as deviations, while some others
+should be fixed. Both compliance and documenting deviations on the
+existing codebase are work-in-progress.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Dir number
+     - Severity
+     - Summary
+     - Notes
+
+   * - `Dir 2.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_02_01.c>`_
+     - Required
+     - All source files shall compile without any compilation errors
+     -
+
+   * - `Dir 4.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_07.c>`_
+     - Required
+     - If a function returns error information then that error
+       information shall be tested
+     -
+
+   * - `Dir 4.10 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_10.c>`_
+     - Required
+     - Precautions shall be taken in order to prevent the contents of a
+       header file being included more than once
+     -
+
+   * - `Dir 4.14 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_14.c>`_
+     - Required
+     - The validity of values received from external sources shall be
+       checked
+     -
+
+.. list-table::
+   :header-rows: 1
+
+   * - Rule number
+     - Severity
+     - Summary
+     - Notes
+
+   * - `Rule 1.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_01_03.c>`_
+     - Required
+     - There shall be no occurrence of undefined or critical unspecified
+       behaviour
+     -
+
+   * - `Rule 3.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_03_02.c>`_
+     - Required
+     - Line-splicing shall not be used in // comments
+     -
+
+   * - `Rule 6.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_06_02.c>`_
+     - Required
+     - Single-bit named bit fields shall not be of a signed type
+     -
+
+   * - `Rule 8.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_01.c>`_
+     - Required
+     - Types shall be explicitly specified
+     -
+
+   * - `Rule 8.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_04.c>`_
+     - Required
+     - A compatible declaration shall be visible when an object or
+       function with external linkage is defined
+     -
+
+   * - `Rule 8.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_05_2.c>`_
+     - Required
+     - An external object or function shall be declared once in one and only one file
+     -
+
+   * - `Rule 8.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_06_2.c>`_
+     - Required
+     - An identifier with external linkage shall have exactly one
+       external definition
+     - Declarations without definitions are allowed (specifically when
+       the definition is compiled-out or optimized-out by the compiler)
+
+   * - `Rule 8.8 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_08.c>`_
+     - Required
+     - The static storage class specifier shall be used in all
+       declarations of objects and functions that have internal linkage
+     -
+
+   * - `Rule 8.12 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_12.c>`_
+     - Required
+     - Within an enumerator list the value of an implicitly-specified
+       enumeration constant shall be unique
+     -