[xen staging] docs/misra: introduce rules.rst

[patchbot@xxxxxxx]

commit 4b08435f586e3f605fdc13f7cb38484f37ad42e9
Author:     Stefano Stabellini <stefano.stabellini@xxxxxxxxxx>
AuthorDate: Tue May 31 18:44:01 2022 -0700
Commit:     Stefano Stabellini <stefano.stabellini@xxxxxxxxxx>
CommitDate: Tue Jun 7 17:43:47 2022 -0700

    docs/misra: introduce rules.rst
    
    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 <stefano.stabellini@xxxxxxxxxx>
    Signed-off-by: Bertrand Marquis <bertrand.marquis@xxxxxxx>
    Acked-by: Julien Grall <jgrall@xxxxxxxxxx>
---
 CODING_STYLE         |   6 +++
 docs/index.rst       |  12 +++++
 docs/misra/rules.rst | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 141 insertions(+)

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
+     -
--
generated by git-patchbot for /home/xen/git/xen.git#staging