[PATCH 3/3] misra: deviate MISRA C Rule 5.5 for ARM SMMU fault handlers

[Dmytro Prokopchuk1 <dmytro_prokopchuk1@xxxxxxxx>]

MISRA C Rule 5.5 states: "Identifiers shall be distinct from macro
names".

Update ECLAIR configuration to deviate intentional identifier and
macro name clashes by specifying the macros that should be ignored.
This includes 'arm_smmu_global_fault' and 'arm_smmu_context_fault',
where the original ARM SMMU handler returns irqreturn_t, while the
same-named macro redirects later uses to a Xen wrapper with the
void interrupt-handler signature expected by Xen 'request_irq()'.

Update deviations.rst and rules.rst accordingly.

Signed-off-by: Dmytro Prokopchuk <dmytro_prokopchuk1@xxxxxxxx>
---
 automation/eclair_analysis/ECLAIR/deviations.ecl | 6 ++++++
 docs/misra/deviations.rst                        | 7 +++++++
 docs/misra/rules.rst                             | 4 ++++
 3 files changed, 17 insertions(+)

diff --git a/automation/eclair_analysis/ECLAIR/deviations.ecl 
b/automation/eclair_analysis/ECLAIR/deviations.ecl
index 7aa64796ba..419a23ce8e 100644
--- a/automation/eclair_analysis/ECLAIR/deviations.ecl
+++ b/automation/eclair_analysis/ECLAIR/deviations.ecl
@@ -144,6 +144,12 @@ ARM SMMU driver calls by reordering the handler and flags 
arguments."
 
-config=MC3A2.R5.5,ignored_macros+="name(request_irq)&&loc(file(^xen/drivers/passthrough/arm/smmu\\.c$))"
 -doc_end
 
+-doc_begin="Clashes between ARM SMMU fault handler functions and macro names 
in 'xen/drivers/passthrough/arm/smmu.c' are deliberate.
+The original ARM SMMU handler returns irqreturn_t, while the macro redirects 
later uses to a Xen wrapper with the
+void interrupt-handler signature expected by Xen 'request_irq()'."
+-config=MC3A2.R5.5,ignored_macros+="name(arm_smmu_global_fault||arm_smmu_context_fault)&&loc(file(^xen/drivers/passthrough/arm/smmu\\.c$))"
+-doc_end
+
 -doc_begin="The type \"ret_t\" is deliberately defined multiple times,
 depending on the guest."
 -config=MC3A2.R5.6,reports+={deliberate,"any_area(any_loc(text(^.*ret_t.*$)))"}
diff --git a/docs/misra/deviations.rst b/docs/misra/deviations.rst
index 01f141b73f..15c88b82f4 100644
--- a/docs/misra/deviations.rst
+++ b/docs/misra/deviations.rst
@@ -192,6 +192,13 @@ Deviations related to MISRA C:2012 Rules:
        reordering the handler and flags arguments.
      - ECLAIR has been configured to ignore this macro.
 
+   * - R5.5
+     - Clashes between the ARM SMMU fault handler functions and macro names are
+       intentional. The original ARM SMMU handler returns irqreturn_t, while
+       the macro redirects later uses to a Xen wrapper with the void
+       interrupt-handler signature expected by Xen 'request_irq()'.
+     - ECLAIR has been configured to ignore these macros.
+
    * - R5.6
      - The type ret_t is deliberately defined multiple times depending on the
        type of guest to service.
diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
index 097c20432e..88d2c5fa7c 100644
--- a/docs/misra/rules.rst
+++ b/docs/misra/rules.rst
@@ -230,6 +230,10 @@ maintainers if you want to suggest a change.
        the macro is a local compatibility wrapper that adapts ARM SMMU driver
        call to Xen's request_irq() argument order.
 
+       Clashes between ARM SMMU fault handler functions and macro names are
+       allowed because the macros redirect ARM SMMU driver uses to a Xen 
interrupt
+       wrapper with the handler signature expected by request_irq().
+
    * - `Rule 5.6 
<https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_06.c>`_
      - Required
      - A typedef name shall be a unique identifier
-- 
2.43.0