[XEN PATCH v2] automation/eclair_analysis: deviate certain macros for Rule 20.12

[XEN PATCH v2] automation/eclair_analysis: deviate certain macros for Rule 20.12

[Nicola Vetrini]

Certain macros are allowed to violate the Rule, since their meaning and
intended use is well-known to all Xen developers.

Variadic macros that rely on the GCC extension for removing a trailing
comma when token pasting the variable argument are similarly
well-understood and therefore allowed.

No functional change.

Signed-off-by: Nicola Vetrini <nicola.vetrini@bugseng.com>
---
Changes in v2:
- Restrict deviation for GENERATE_CASE to vcpreg.c.
- Improve deviation justifications.
---
 .../eclair_analysis/ECLAIR/deviations.ecl     | 20 +++++++++++++++++
 docs/misra/deviations.rst                     | 22 +++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/automation/eclair_analysis/ECLAIR/deviations.ecl b/automation/eclair_analysis/ECLAIR/deviations.ecl
index fd32ff8a9cae..04cb41e16a50 100644
--- a/automation/eclair_analysis/ECLAIR/deviations.ecl
+++ b/automation/eclair_analysis/ECLAIR/deviations.ecl
@@ -387,6 +387,26 @@ in assignments."
 {safe, "left_right(^[(,\\[]$,^[),\\]]$)"}
 -doc_end
 
+-doc_begin="Uses of variadic macros that have one of their arguments defined as
+a macro and used within the body for both ordinary parameter expansion and as an
+operand to the # or ## operators have a behavior that is well-understood and
+deliberate."
+-config=MC3R1.R20.12,macros+={deliberate, "variadic()"}
+-doc_end
+
+-doc_begin="Uses of a macro parameter for ordinary expansion and as an operand
+to the # or ## operators within the following macros are deliberate, to provide
+useful diagnostic messages to the user."
+-config=MC3R1.R20.12,macros+={deliberate, "name(ASSERT||BUILD_BUG_ON||BUILD_BUG_ON_ZERO)"}
+-doc_end
+
+-doc_begin="The helper macro GENERATE_CASE may use a macro parameter for ordinary
+expansion and token pasting to improve readability. Only instances where this
+leads to a violation of the Rule are deviated."
+-file_tag+={deliberate_generate_case, "^xen/arch/arm/vcpreg\\.c$"}
+-config=MC3R1.R20.12,macros+={deliberate, "name(GENERATE_CASE)&&loc(file(deliberate_generate_case))"}
+-doc_end
+
 #
 # General
 #
diff --git a/docs/misra/deviations.rst b/docs/misra/deviations.rst
index 123c78e20a01..84da637ef888 100644
--- a/docs/misra/deviations.rst
+++ b/docs/misra/deviations.rst
@@ -330,6 +330,28 @@ Deviations related to MISRA C:2012 Rules:
        (4) as lhs in assignments.
      - Tagged as `safe` for ECLAIR.
 
+   * - R20.12
+     - Variadic macros that use token pasting often employ the gcc extension
+       `ext_paste_comma`, as detailed in `C-language-toolchain.rst`, which is
+       not easily replaceable; macros that in addition perform regular argument
+       expansion on the same argument subject to the # or ## operators violate
+       the Rule if the argument is a macro. 
+     - Tagged as `deliberate` for ECLAIR.
+
+   * - R20.12
+     - Macros that are used for runtime or build-time assertions contain
+       deliberate uses of an argument as both a regular argument and a
+       stringification token, to provide useful diagnostic messages.
+     - Tagged as `deliberate` for ECLAIR.
+
+   * - R20.12
+     - GENERATE_CASE is a local helper macro that allows some selected switch
+       statements to be more compact and readable. As such, the risk of
+       developer confusion in using such macro is deemed negligible. This
+       construct is deviated only in Translation Units that present a violation
+       of the Rule due to uses of this macro.
+     - Tagged as `deliberate` for ECLAIR.
+
 Other deviations:
 -----------------
 
-- 
2.34.1

Re: [XEN PATCH v2] automation/eclair_analysis: deviate certain macros for Rule 20.12

[Nicola Vetrini]

On 2024-02-15 14:06, Nicola Vetrini wrote:
> Certain macros are allowed to violate the Rule, since their meaning and
> intended use is well-known to all Xen developers.
> 
> Variadic macros that rely on the GCC extension for removing a trailing
> comma when token pasting the variable argument are similarly
> well-understood and therefore allowed.
> 
> No functional change.
> 
> Signed-off-by: Nicola Vetrini <nicola.vetrini@bugseng.com>
> ---
> Changes in v2:
> - Restrict deviation for GENERATE_CASE to vcpreg.c.
> - Improve deviation justifications.
> ---
>  .../eclair_analysis/ECLAIR/deviations.ecl     | 20 +++++++++++++++++
>  docs/misra/deviations.rst                     | 22 +++++++++++++++++++
>  2 files changed, 42 insertions(+)
> 

Ping?

-- 
Nicola Vetrini, BSc
Software Engineer, BUGSENG srl (https://bugseng.com)

Re: [XEN PATCH v2] automation/eclair_analysis: deviate certain macros for Rule 20.12

[Stefano Stabellini]

On Thu, 15 Feb 2024, Nicola Vetrini wrote:
> Certain macros are allowed to violate the Rule, since their meaning and
> intended use is well-known to all Xen developers.
> 
> Variadic macros that rely on the GCC extension for removing a trailing
> comma when token pasting the variable argument are similarly
> well-understood and therefore allowed.
> 
> No functional change.
> 
> Signed-off-by: Nicola Vetrini <nicola.vetrini@bugseng.com>

Reviewed-by: Stefano Stabellini <sstabellini@kernel.org>



> ---
> Changes in v2:
> - Restrict deviation for GENERATE_CASE to vcpreg.c.
> - Improve deviation justifications.
> ---
>  .../eclair_analysis/ECLAIR/deviations.ecl     | 20 +++++++++++++++++
>  docs/misra/deviations.rst                     | 22 +++++++++++++++++++
>  2 files changed, 42 insertions(+)
> 
> diff --git a/automation/eclair_analysis/ECLAIR/deviations.ecl b/automation/eclair_analysis/ECLAIR/deviations.ecl
> index fd32ff8a9cae..04cb41e16a50 100644
> --- a/automation/eclair_analysis/ECLAIR/deviations.ecl
> +++ b/automation/eclair_analysis/ECLAIR/deviations.ecl
> @@ -387,6 +387,26 @@ in assignments."
>  {safe, "left_right(^[(,\\[]$,^[),\\]]$)"}
>  -doc_end
>  
> +-doc_begin="Uses of variadic macros that have one of their arguments defined as
> +a macro and used within the body for both ordinary parameter expansion and as an
> +operand to the # or ## operators have a behavior that is well-understood and
> +deliberate."
> +-config=MC3R1.R20.12,macros+={deliberate, "variadic()"}
> +-doc_end
> +
> +-doc_begin="Uses of a macro parameter for ordinary expansion and as an operand
> +to the # or ## operators within the following macros are deliberate, to provide
> +useful diagnostic messages to the user."
> +-config=MC3R1.R20.12,macros+={deliberate, "name(ASSERT||BUILD_BUG_ON||BUILD_BUG_ON_ZERO)"}
> +-doc_end
> +
> +-doc_begin="The helper macro GENERATE_CASE may use a macro parameter for ordinary
> +expansion and token pasting to improve readability. Only instances where this
> +leads to a violation of the Rule are deviated."
> +-file_tag+={deliberate_generate_case, "^xen/arch/arm/vcpreg\\.c$"}
> +-config=MC3R1.R20.12,macros+={deliberate, "name(GENERATE_CASE)&&loc(file(deliberate_generate_case))"}
> +-doc_end
> +
>  #
>  # General
>  #
> diff --git a/docs/misra/deviations.rst b/docs/misra/deviations.rst
> index 123c78e20a01..84da637ef888 100644
> --- a/docs/misra/deviations.rst
> +++ b/docs/misra/deviations.rst
> @@ -330,6 +330,28 @@ Deviations related to MISRA C:2012 Rules:
>         (4) as lhs in assignments.
>       - Tagged as `safe` for ECLAIR.
>  
> +   * - R20.12
> +     - Variadic macros that use token pasting often employ the gcc extension
> +       `ext_paste_comma`, as detailed in `C-language-toolchain.rst`, which is
> +       not easily replaceable; macros that in addition perform regular argument
> +       expansion on the same argument subject to the # or ## operators violate
> +       the Rule if the argument is a macro. 
> +     - Tagged as `deliberate` for ECLAIR.
> +
> +   * - R20.12
> +     - Macros that are used for runtime or build-time assertions contain
> +       deliberate uses of an argument as both a regular argument and a
> +       stringification token, to provide useful diagnostic messages.
> +     - Tagged as `deliberate` for ECLAIR.
> +
> +   * - R20.12
> +     - GENERATE_CASE is a local helper macro that allows some selected switch
> +       statements to be more compact and readable. As such, the risk of
> +       developer confusion in using such macro is deemed negligible. This
> +       construct is deviated only in Translation Units that present a violation
> +       of the Rule due to uses of this macro.
> +     - Tagged as `deliberate` for ECLAIR.
> +
>  Other deviations:
>  -----------------
>  
> -- 
> 2.34.1
> 

Re: [XEN PATCH v2] automation/eclair_analysis: deviate certain macros for Rule 20.12

[Nicola Vetrini]

On 2024-02-15 14:06, Nicola Vetrini wrote:
> Certain macros are allowed to violate the Rule, since their meaning and
> intended use is well-known to all Xen developers.
> 
> Variadic macros that rely on the GCC extension for removing a trailing
> comma when token pasting the variable argument are similarly
> well-understood and therefore allowed.
> 
> No functional change.
> 
> Signed-off-by: Nicola Vetrini <nicola.vetrini@bugseng.com>
> ---
> Changes in v2:
> - Restrict deviation for GENERATE_CASE to vcpreg.c.
> - Improve deviation justifications.
> ---
>  .../eclair_analysis/ECLAIR/deviations.ecl     | 20 +++++++++++++++++
>  docs/misra/deviations.rst                     | 22 +++++++++++++++++++
>  2 files changed, 42 insertions(+)
> 

Hi,

this patch has an R-by from Stefano. Is there something preventing this 
from being committed?

-- 
Nicola Vetrini, BSc
Software Engineer, BUGSENG srl (https://bugseng.com)