From 4b08435f586e3f605fdc13f7cb38484f37ad42e9 Mon Sep 17 00:00:00 2001 From: Stefano Stabellini Date: Tue, 31 May 2022 18:44:01 -0700 Subject: [PATCH] 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 Signed-off-by: Bertrand Marquis Acked-by: Julien Grall --- CODING_STYLE | 6 +++ docs/index.rst | 12 +++++ docs/misra/rules.rst | 123 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 141 insertions(+) create mode 100644 docs/misra/rules.rst 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 `_ + - Required + - All source files shall compile without any compilation errors + - + + * - `Dir 4.7 `_ + - Required + - If a function returns error information then that error + information shall be tested + - + + * - `Dir 4.10 `_ + - Required + - Precautions shall be taken in order to prevent the contents of a + header file being included more than once + - + + * - `Dir 4.14 `_ + - 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 `_ + - Required + - There shall be no occurrence of undefined or critical unspecified + behaviour + - + + * - `Rule 3.2 `_ + - Required + - Line-splicing shall not be used in // comments + - + + * - `Rule 6.2 `_ + - Required + - Single-bit named bit fields shall not be of a signed type + - + + * - `Rule 8.1 `_ + - Required + - Types shall be explicitly specified + - + + * - `Rule 8.4 `_ + - Required + - A compatible declaration shall be visible when an object or + function with external linkage is defined + - + + * - `Rule 8.5 `_ + - Required + - An external object or function shall be declared once in one and only one file + - + + * - `Rule 8.6 `_ + - 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 `_ + - Required + - The static storage class specifier shall be used in all + declarations of objects and functions that have internal linkage + - + + * - `Rule 8.12 `_ + - Required + - Within an enumerator list the value of an implicitly-specified + enumeration constant shall be unique + - -- 2.30.2